每天早晨到工位我都要在终端里敲一串固定的命令git status看代码状态、docker ps看容器死活、curl一下本地的健康检查接口、再df看下磁盘还剩多少。日复一日肌肉记忆倒是练出来了但这些命令之间没有任何关联每换一台机器、每换一个项目这套流程就得重新脑补一遍。后来我把这套操作固化成了一个叫 CLI-Anything 的工具核心思路就一句话把日常那些零散的终端操作收敛成一个个有名字、有参数、有配置的命令想用的时候直接敲名字就行。CLI-Anything 不是一个具体框架的绑定而是一种命令行工具箱的设计思路解决的核心问题是碎片化操作的统一入口。它不太挑语言也不太挑平台适合所有重度依赖终端的开发者、运维和数据分析师。这篇文章我会完整拆一遍这个工具的架构设计、配置规范、实操流程和我在落地过程中踩过的坑尽量做到你读完就能在自己的机器上搭一套出来。1. 项目设计与整体思路为什么需要命令行全家桶1.1 从分散到统一CLI-Anything 要解决的真正问题每个基础设施工具都有自己的 CLIgit 有 git 的语法docker 有 docker 的语法kubectl 有 kubectl 的参数规范mysql 客户端有自己的连接选项。你在终端里记的不是一套命令而是五六套互不兼容的命令语法。真正的痛点还不只是记忆负担而是业务场景无法被这些散装命令直接表达。举个例子我想把服务发到测试环境中途涉及构建、跑测试、打镜像、推送镜像、登录服务器、拉镜像、重启容器这一整套操作横跨至少五个工具。在没有统一封装的情况下你需要手动执行八九条命令中间任何一步失败都得从头定位。CLI-Anything 的思路是把这些跨工具的操作重构成一个有名字、可复用的上层命令你可以把它想成一个调度大脑它不替代底层工具而是帮你把底层工具的调用编排好。这和电视遥控器的逻辑很像。遥控器没有替代电视机、机顶盒和音响但它把我要看电影这件事封装成了一个按键背后替你做了输入源切换、音量调节、开机唤醒。CLI-Anything 干的就是这活儿它把我要发版我要晨检我要同步数据封装成一个命令背后替你调度 git、docker、ssh、curl 这些真正干活的工具。1.2 架构选型为什么选择子命令聚合 插件扩展模式设计 CLI-Anything 时我对比过几种方案。最粗暴的是写一堆 Shell 脚本按功能命名放在 ~/bin 里但这有个问题脚本之间相互调用困难、参数解析全靠手工、输出格式五花八门而且随着脚本增多管理成本直线上升。还有一种思路是引入完整的工作流引擎比如 GitHub Actions 或 Jenkins Pipeline但这套东西太重了本地开发场景根本不需要那么多 runner、artifact、sandbox 的概念。最终我选了子命令聚合 插件扩展的轻量架构。核心可执行文件只负责四件事解析子命令、加载配置、按顺序执行步骤、格式化输出。具体的操作逻辑全部分布到插件或者外部脚本里。这样做的好处有三个第一核心代码量很小维护成本低第二新增能力不需要改核心逻辑写个插件挂载进去就行第三每个插件可以独立测试出问题了不会拖垮整个系统。架构上我把它拆成了五个模块。入口调度器接收命令行参数解析出要运行哪个子命令、携带什么选项。配置加载器读取 YAML 或 TOML 配置文件把命令定义、变量、钩子加载到内存。插件注册表扫描指定目录下的插件文件维护插件名到执行逻辑的映射。执行引擎按顺序执行命令步骤捕获每个步骤的输出和退出码遇到错误可以中断也可以继续。输出格式化器统一处理颜色、缩进、进度提示让所有命令的输出风格保持一致。提示模块划分不必一步到位。我一开始只写了入口调度器和执行引擎配置加载器是用了两周之后才加的插件机制更是后来才补上的。设计时心里有蓝图但落地可以循序渐进。这套架构的另一个关键决策是声明式配置优先于命令式代码。也就是说编排什么样的工作流尽量写在配置文件里而不是散落在代码的 if/else 里。为什么因为命令的编排本质上是业务逻辑业务逻辑会频繁变化——今天要多加一个健康检查明天要换一个部署目标。如果这些变化都要改代码、重新编译、重新发布那这个工具的实用性就大打折扣了。声明式配置让我改一个 YAML 文件就能生效改完还能用 git 管理起来出问题能回滚。2. 核心配置与命令体系拆解2.1 配置文件设计用一份 YAML 管理所有工作流配置是 CLI-Anything 的心脏。我用的格式是 YAML选它不是因为功能最强而是因为它可读性好、注释友好、和 GitHub Actions、GitLab CI 的语法习惯一脉相承团队协作时沟通成本低。先看一份我实际在用的配置文件麻雀虽小五脏俱全。# ~/.cli-anything/config.yaml project: myapp version: 1.2.0 variables: REGISTRY: registry.example.com DEPLOY_HOST: deploy10.0.0.8 HEALTH_URL: http://localhost:8080/healthz commands: morning-check: description: 晨检git 状态 服务健康 磁盘余量 steps: - run: git status --short - run: curl -sf ${HEALTH_URL} echo healthy - run: df -h | head -5 deploy: description: 一键构建、打包、发布到测试环境 steps: - name: 构建二进制 run: go build -o ./bin/app . - name: 自检版本 run: ./bin/app --version - name: 打镜像 run: docker build -t ${REGISTRY}/myapp:${TAG} . - name: 推送镜像 run: docker push ${REGISTRY}/myapp:${TAG} - name: 远程更新 run: ssh ${DEPLOY_HOST} docker pull ${REGISTRY}/myapp:${TAG} docker restart myapp hooks: before-command: - run: echo 开始执行命令 after-failure: - run: echo 命令执行失败这份配置里有几个字段值得展开说说。project 和 version标识项目和相关配置版本version 主要用来做配置迁移。我升级配置格式时加载器会根据 version 字段决定是否执行迁移逻辑。不要小看这个字段没有它改了字段名之后老配置文件全部静默失效排查起来非常痛苦。variables全局变量区。变量可以在 steps 里通过${VAR_NAME}引用。注意这里的变量不仅仅是简单的替换加载器会做层级化解析——先加载默认值再加载用户配置覆盖值最后加载环境变量值。也就是说我在命令行里设置了环境变量TAGv1.2.0deploy 命令里的${TAG}就会用环境变量的值等于提供了一种运行时注入参数的方式。commands.steps每个步骤本质上还是一个命令调用。我给每个步骤加了可选的name字段执行时日志会打印[步骤名] 正在执行这样出错时能快速定位是哪个环节挂了。hooks钩子机制。支持 before-command、after-success、after-failure 三个时机点。这个功能非常实用比如我可以在每次执行任何命令之前自动拉取最新配置或者在失败时往日志中心上报一条记录。配置文件的价值还体现在版本管理上。我的整个~/.cli-anything/目录是初始化成 git 仓库的配置变更、插件更新全都有 commit 记录。有一次我把某个步骤的镜像标签写错了导致线上发布了错误版本回滚时直接git revert配置一分钟内恢复。2.2 命令命名与参数规范让每个命令都像原生内置子命令的设计规范是 CLI-Anything 体验好不好的分水岭。命令名我用了一个简单规则动词开头名词补充不超过三个词。比如morning-check、init-project、sync-db你看到名字就知道这命令干嘛的。尽量避免util、misc、test1这种不知道在说什么的名字。参数设计参考了 GNU 风格短参数用一个横杠加一个字母长参数用双横杠加单词。每个子命令都支持统一的全局参数这些参数由入口调度器解析不劳烦插件各自处理。参数短参说明示例--dry-run无只打印将要执行的步骤不真正执行anything run deploy --dry-run--verbose-v输出每个步骤的完整原始输出anything run deploy -v--skip无跳过指定步骤多个步骤用逗号分隔anything run deploy --skip build,test--only无只执行指定步骤anything run deploy --only 推送镜像--json无以 JSON 格式输出结果适合对接自动化anything list --json--timeout无每个步骤的超时时间单位秒anything run sync-db --timeout 60--dry-run是我用得最多的参数。因为编排一个跨工具的命令时最怕的就是不理解每一步的影响范围直接在真实环境里跑出大事。dry-run 模式会把每一步将要执行的命令原样打印出来但不会真的调用外部进程相当于提前预演一遍。这个参数救过我起码三次有两次是发现自己拼错了目标主机的 IP。关于参数命名我还有一个经验不要设计含义模糊的多功能选项。比如--force到底强制的是一步还是全程不同命令里语义还不一样用起来全靠猜。我后来把这类参数拆成了更明确的--skip-if-exists、--no-input这类命名虽然命令长一点但歧义少很多。2.3 变量展开的优先级与陷阱变量展开顺序上踩过一次坑得专门提一下。我的加载器设计了一套三级优先的变量来源优先级从高到低是进程环境变量、用户配置文件中的variables、内置默认值。设计上很简单但使用时容易忽略一个细节在同一个步骤里变量引用解析发生在命令真正执行之前。举个例子如果我在配置里写run: sh deploy.sh ${TAG}而环境变量里正好没有TAG那 YAML 里TAG会被解析为空字符串实际执行的是sh deploy.sh参数直接丢了。后来我加了一个校验规则解析步骤之前先扫描所有${VAR}引用如果有未定义变量直接报错并列出缺失变量名而不是闷头执行一个残缺的命令。这个校验规则非常有用它把很多隐性错误提前暴露在 dry-run 阶段。3. 实操从零搭建你自己的 CLI-Anything3.1 安装与初始化两条命令进入可用状态我不太喜欢那种动辄几十个依赖、装完还要配环境变量的工具。CLI-Anything 的安装刻意做得很轻。核心二进制分发有两种方式一种是 Go 写的版本直接go install另一种是 Node 写的版本用 npm 全局安装两者互不影响选一条路就行。# 方式一Go 版本 go install github.com/yourself/cli-anythinglatest # 方式二Node 版本 npm install -g cli-anything # 初始化配置目录 anything initanything init会创建~/.cli-anything/目录里面生成一个默认的 config.yaml、一个 plugins 目录、一个 logs 目录。默认配置里带了两三个示例命令方便你做冒烟测试。初始化完成之后可以先用anything list看一下命令列表确认安装没问题。提示如果你在团队里使用强烈建议把生成的配置目录纳入团队 git 仓库然后让每个人anything init之后执行anything sync拉取共享配置。这样团队的命令规范、部署流程都能保持一致新同事入职配置环境的时间能从半天压缩到十分钟。3.2 手写第一个自定义命令晨检流程我建议你在动手前先想明白一个问题你最想封装的高频操作是什么找一个最简单的场景练手而不是一上来就试着把发布流程全自动化。我第一次写配置文件时第一个命令就是晨检因为它几乎没有危险操作即使写错了最多就是打印几行错误信息。来看完整做法。第一步在 config.yaml 的commands节点下新增一个morning-check定义包含三个步骤git 状态、服务健康检查、磁盘使用率。commands: morning-check: description: 晨检git 状态 服务健康 磁盘余量 steps: - run: git status --short - run: curl -sf ${HEALTH_URL} echo healthy - run: df -h | head -5第二步执行 dry-run 验证。anything run morning-check --dry-run正常输出应该是这样[步骤 1/3] 执行: git status --short [步骤 2/3] 执行: curl -sf ${HEALTH_URL} echo healthy [步骤 3/3] 执行: df -h | head -5如果这里看到了什么奇怪的引号丢失、变量被错误展开立刻回头检查 YAML 的引号嵌套。常见的坑是在 YAML 里需要整个命令作为字符串保存所以run:的值要记得用引号包住否则会被解析成不合法格式。第三步真正执行。anything run morning-check执行的时候执行引擎会逐条启动子进程捕获 stdout 和 stderr前缀加上步骤序号实时打印。如果某一步的退出码不是 0默认行为是中断后续步骤并在日志里标记失败位置。这就是上面提到过的 fail-fast 策略。对于晨检这种只读操作如果 git status 失败后续的 curl 和 df 大概率也不会正常快速中断能省下不少等待时间。3.3 对接外部工具一键发版命令的完整实现晨检算是热身真正体现 CLI-Anything 价值的是多工具协同的命令。我拿 deploy 命令当例子拆解一下。deploy 命令的完整流程是构建二进制、自检版本、构建 Docker 镜像、推送到私有仓库、SSH 上服务器拉镜像并重启容器。这五步如果手动操作每步少说 30 秒中间还容易输错镜像标签。封装之后变成一条命令。配置代码前面已经给过了这里重点说几个执行引擎层面的设计细节。每个步骤默认在项目根目录下执行。也就是说如果我在某个项目的目录里运行anything run deploy那go build、docker build都是以当前目录为工作目录执行的。这样设计的直觉是把 CLI-Anything 当成一个项目意识的助手它知道自己在哪个项目里自然知道构建上下文在哪。步骤之间是顺序执行还是并行执行我的设计是默认顺序执行。因为发布流程里推送镜像必须在构建之后远程重启必须在推送之后天然就是有向无环图。并行执行看着效率高但一旦引入共享文件、共享端口排查问题的时间远超节省的执行时间。只有一些真正互相独立且耗时的步骤比如同时备份多个数据库我会用并行的方式处理。执行中的超时控制也很关键。curl 卡住了、ssh 连不上、docker pull 大镜像慢得像蜗牛如果没有超时机制一个步骤能挂半小时。我给每个步骤设置了默认 120 秒超时如果步骤执行超时执行引擎会杀掉整个进程组把超时作为失败原因记录下来。对于网络操作频繁的步骤我单独加长超时时间比如 docker pull 可以放宽到 300 秒。# 实际发版时我通常会这样操作 anything run deploy --dry-run --verbose # 确认无误后使用环境变量注入版本号 TAGv2.3.1 anything run deploy实际执行的输出大概是这样的[步骤 1/5: 构建二进制] 开始执行 go build -o ./bin/app . [步骤 1/5: 构建二进制] 完成 (2.1s) [步骤 2/5: 自检版本] 开始执行 ./bin/app --version myapp version 2.3.1 [步骤 2/5: 自检版本] 完成 (0.1s) [步骤 3/5: 打镜像] 开始执行 docker build -t registry.example.com/myapp:v2.3.1 . ... 省略镜像层输出 ... [步骤 3/5: 打镜像] 完成 (15.8s) [步骤 4/5: 推送镜像] 开始执行 docker push registry.example.com/myapp:v2.3.1 [步骤 4/5: 推送镜像] 完成 (12.3s) [步骤 5/5: 远程更新] 开始执行 ssh deploy10.0.0.8 docker pull registry.example.com/myapp:v2.3.1 docker restart myapp [步骤 5/5: 远程更新] 完成 (4.7s) deploy 命令执行成功总耗时 35.0s这个命令已经是团队内部的标配了。有个后端同事说他最满意的不是少敲了几条命令而是每条命令的输出都有统一的时间戳、步骤名和耗时出了事能立刻定位是哪一步慢、哪一步挂。3.4 插件扩展不用改核心代码也能加能力CLI-Anything 的名字里带着Anything这份野心主要靠插件机制支撑。插件本质上是一段独立脚本导出自己的命令定义然后被主程序加载。我定义了一个极简的插件协议目前支持 Shell 脚本和 Node.js 模块两种形式。插件放在~/.cli-anything/plugins/目录下文件名以.sh或.js结尾。以 Shell 插件为例一个插件文件里只需要声明PLUGIN_NAME和PLUGIN_COMMANDS两个变量主程序启动时会扫描这个目录把声明过的命令合并进命令列表。#!/usr/bin/env bash # 文件位置: ~/.cli-anything/plugins/notify.sh PLUGIN_NAMEnotify PLUGIN_COMMANDSsend plugin_notify_send() { local channel$1 local message$2 # 这里调用团队内部的通知服务 API curl -sf -X POST https://notify.example.com/${channel} \ -d text${message} }这个插件的核心逻辑就一个把文本消息发送到指定频道。它有plugin_notify_send这个函数函数名有规律——plugin_{插件名}_{命令名}主程序执行时会在插件上下文中调用这个函数并传入解析好的参数。这样一个插件就提供了一条notify send命令。插件机制带来的自由度非常大。我之前写过一个db-backup插件把 mysqldump、压缩、上传对象存储、清理过期备份整个流程封装起来团队里任何人备份数据库都只需执行anything run db-backup --env prod不用再关心 mysqldump 的参数语法和对象存储的密钥配置。但插件也不是越多越好。插件多了启动时扫描时间会变长而且插件之间的依赖关系会变得混乱。我现在的原则是高频的、稳定的操作放进核心配置低频的、可变的扩展写成插件。晨检、发版这种几乎每天用的放核心给某个临时项目写的专用同步脚本放插件用完就删。4. 常见问题、踩坑实录与排查技巧4.1 环境变量消失了非交互式 Shell 的陷阱这是我被问得最多的问题。现象是在终端里明明export TAGv1.0了配置里的${TAG}却展开为空。我明明设了环境变量这句话我听了不下十遍。原因几乎都出在 Shell 的加载机制上。当你执行anything run deploy时主程序是以子进程的方式启动外部命令的这个子进程继承的是主程序的环境变量而不是你在.zshrc或.bashrc里设置的那些。如果你的 Shell 配置是在非交互模式下没有加载的主程序根本看不到那些变量。排查路径固定三步。先确认环境变量在当前 Shell 是否存在echo $TAG。如果存在第二步用anything run some-command -v打开 verbose 模式看实际传给子进程的环境变量里有没有 TAG。第三步如果 verbose 模式看不到检查一下是不是用了 sudo 或者其它会重置环境的方式执行命令。提示我最终的解决方案是标准化了变量注入方式。业务相关的变量不依赖环境变量而是统一维护在配置文件里只有临时变化的变量比如版本号、目标环境才用环境变量注入。创建配置时约定配置文件里的变量叫variables环境变量仅在运行时覆盖两边不要出现同名但不同义的变量否则排查起来非常头疼。4.2 中文乱码与输出格式异常另一个常见问题是命令输出里的中文变成了乱码。这通常不是 CLI-Anything 的问题而是外部命令的输出编码没有被正确识别。我的执行引擎在捕获子进程输出时默认按 UTF-8 解码但有些老旧的系统工具默认输出 GBK 编码导致乱码。处理方案是给执行引擎增加一个--encoding参数按需指定子进程输出的编码格式。虽然按需指定听起来繁琐但在对接遗留系统时真的能救命。另一个小细节是 Windows 环境下命令输出末尾会带\r\n而不是\n这个也会导致日志里出现奇怪的^M字符。处理办法是在展示之前统一做一次换行符归一化把\r\n转成\n。4.3 步骤莫名其妙的失败引号与转义的隐形杀手还有一个容易让人抓狂的情况配置里写得好好的命令在终端里手动执行能成功但通过 CLI-Anything 执行就报错。排查到最后八成是引号和转义出了问题。YAML 里的字符串在传给 Shell 执行时会经过多层解析。比如run: ssh host echo hello echo world这行 YAML 加载后变成字符串ssh host echo hello echo world再传给/bin/sh -c执行。问题出在如果命令本身还包含$、反引号、转义字符这些符号会在 Shell 解析时被再次解释导致行为和预期不一致。我后来在配置里约定了一个规范配置里的命令字符串不传复杂 Shell 语法。复杂的逻辑一律下沉到独立脚本文件配置里只写调用脚本的命令。比如我要做拉取远程数据库并导入本地我不会写一长串管道加变量拼接而是写一个scripts/sync-db.sh脚本配置里只写run: bash scripts/sync-db.sh ${ENV}。这样既避免了多层转义的坑又方便单独测试脚本逻辑。4.4 Shell 补全与别名CLI-Anything 的价值之一是统一入口但如果每次都要敲全命令名体验就大打折扣了。我实现了子命令的自动补全脚本支持 bash 和 zsh。安装补全脚本的步骤很简单anything completion bash ~/.cli-anything/completion.bash echo source ~/.cli-anything/completion.bash ~/.bashrc # zsh 用户 anything completion zsh ~/.cli-anything/completion.zsh echo source ~/.cli-anything/completion.zsh ~/.zshrc补全之后敲anything run depTab就能自动补出deploy再敲--Tab能列出全局参数。这个功能是用完就回不去的强烈建议安装。另外我常用的一个技巧是在 Shell 配置文件里给高频命令设置别名。alias ckanything run morning-check alias depanything run deploy alias syncanything run sync-db这里提醒一句别名不要和子命令名冲突否则容易精神分裂。我一开始给anything run morning-check起了个别名叫mc结果团队新同事不知道mc是什么查了半天才发现在是别名。后来统一规则别名全部用人类可读的短单词ck、dep、sync避免无意义缩写。4.5 执行过程中的性能问题步骤多了以后可能会遇到执行慢的问题。除了外部命令本身的耗时还有一个常被忽略的消耗每个步骤都是独立拉起一个子进程这个进程的启动开销虽然只有毫秒级但如果有上百个步骤累计也有几百毫秒。更重要的是如果步骤内部又调用了大量外部工具比如 grep、awk、sed 的组合性能瓶颈会非常明显。优化思路有两个。一个方向是减少不必要的步骤拆分把多个简单操作合并到一个脚本里执行降低进程拉起的次数另一个方向是在执行引擎里支持步骤级别的并行标记允许把没有依赖关系的步骤并发执行。这两个方向我都在实际项目里用过效果都不错但记住性能优化的前提是可观测性。先开 verbose 模式看清楚每步耗时再决定怎么优化别凭感觉做并行化。5. 工具选型与周边生态语言与体验的取舍5.1 用什么语言写 CLIGo、Rust、Node 还是 PythonCLI-Anything 的核心二进制在不同阶段换过两种语言实现。这个选型问题对其他想自己写命令行工具的人也有参考价值我直接给一张对比表。维度GoRustNode.jsPython二进制分发单个静态二进制部署简单单个静态二进制体积略大依赖 Node 运行时依赖 Python 解释器启动速度极快约 10ms 级极快中等约 80ms 级较慢约 100ms 级开发效率高标准库覆盖广中学习曲线陡高生态丰富高写起来最快生态与库优秀的 cobra/viperclap/serde 很强commander/yargsclick/typer并发执行goroutine 很顺手tokio 强大但复杂异步回调心智负担重多进程方案较繁琐我自己最终留在 Go 版本上主要是看中它的单二进制分发和接近零的启动延迟。CLI 工具的使用频率极高每次敲命令都希望它像原生指令一样瞬间响应哪怕多 100 毫秒的延迟高频使用时也会觉得拖沓。如果你主要做数据分析、机器学习方向工具和 Python 生态绑定很深那用 Python 实现也许更合适。5.2 体验优化温度色输出与进度反馈命令行工具的体验不只是功能正确还包括输出是否直观、操作是否有反馈。我用三个原则优化了 CLI-Anything 的交互体验。第一颜色传达语义。错误信息用红色警告用黄色成功的步骤摘要用绿色普通日志用默认色。这些颜色只在终端支持时启用输出管道重定向到文件时会自动关闭 ANSI 码避免日志文件里混入乱码。第二大步骤给出明确的进度信号。docker build 这类命令默认输出就很多很杂用户很难分辨卡在哪一层。CLI-Anything 会把长输出的最后几行实时打印同时显示累计耗时。用户看到的信息永远是最新状态不会淹没在刷屏的输出里。第三重要的操作要有确认交互。破坏性操作比如删除备份、重置数据库执行前默认会弹出确认提示只有加上--yes参数才会跳过确认。这个确认机制为团队避免过至少两次灾难性操作。5.3 和现有工具的生态整合CLI-Anything 不是要替代已有的工具链而是做它们的粘合剂。它和 git 的关系是编排而不替代——diff、log、commit 这些单点操作还是用 git 原生命令但涉及把当前分支推到开发环境这种跨 git 和 ssh 的复合操作就会封装成命令。同样的原则适用于 Docker、kubectl、数据库客户端。和 CI/CD 系统的关系也是一样。本地执行用 CLI-AnythingCI 流水线里也可以直接调用它。我见过有人在 GitHub Actions 里跑anything run test --env ci命令本身和本地是一致的只是参数不同。这种本地和流水线共用一套命令的方式能显著减少本地能跑但 CI 挂了这类环境差异问题。最后分享一点个人体会玩 CLI-Anything 时间久了我最大的感受是命令是壳配置是肉脚本是魂。核心二进制只是提供一个稳定可靠的外壳真正让工具融入日常的是那些经过反复打磨的配置文件和插件脚本。如果你也想搭一套我的建议是先别急着设计一大堆命令从你明天早上要做的第一件事开始——看看它涉及哪几个工具、哪几步操作、哪些参数是变化的然后把它们编译成一条命令。用上两天觉得顺手了再增加下一条。等到某天你发现新同事入职一天就能独立完成发版或者你换了一台新电脑十分钟内恢复了所有工作流你就会明白这个工具真正省下的不只是敲命令的时间而是你从繁琐细节中腾出来的注意力。
每天早晨到工位我都要在终端里敲一串固定的命令git status看代码状态、docker ps看容器死活、curl一下本地的健康检查接口、再df看下磁盘还剩多少。日复一日肌肉记忆倒是练出来了但这些命令之间没有任何关联每换一台机器、每换一个项目这套流程就得重新脑补一遍。后来我把这套操作固化成了一个叫 CLI-Anything 的工具核心思路就一句话把日常那些零散的终端操作收敛成一个个有名字、有参数、有配置的命令想用的时候直接敲名字就行。CLI-Anything 不是一个具体框架的绑定而是一种命令行工具箱的设计思路解决的核心问题是碎片化操作的统一入口。它不太挑语言也不太挑平台适合所有重度依赖终端的开发者、运维和数据分析师。这篇文章我会完整拆一遍这个工具的架构设计、配置规范、实操流程和我在落地过程中踩过的坑尽量做到你读完就能在自己的机器上搭一套出来。1. 项目设计与整体思路为什么需要命令行全家桶1.1 从分散到统一CLI-Anything 要解决的真正问题每个基础设施工具都有自己的 CLIgit 有 git 的语法docker 有 docker 的语法kubectl 有 kubectl 的参数规范mysql 客户端有自己的连接选项。你在终端里记的不是一套命令而是五六套互不兼容的命令语法。真正的痛点还不只是记忆负担而是业务场景无法被这些散装命令直接表达。举个例子我想把服务发到测试环境中途涉及构建、跑测试、打镜像、推送镜像、登录服务器、拉镜像、重启容器这一整套操作横跨至少五个工具。在没有统一封装的情况下你需要手动执行八九条命令中间任何一步失败都得从头定位。CLI-Anything 的思路是把这些跨工具的操作重构成一个有名字、可复用的上层命令你可以把它想成一个调度大脑它不替代底层工具而是帮你把底层工具的调用编排好。这和电视遥控器的逻辑很像。遥控器没有替代电视机、机顶盒和音响但它把我要看电影这件事封装成了一个按键背后替你做了输入源切换、音量调节、开机唤醒。CLI-Anything 干的就是这活儿它把我要发版我要晨检我要同步数据封装成一个命令背后替你调度 git、docker、ssh、curl 这些真正干活的工具。1.2 架构选型为什么选择子命令聚合 插件扩展模式设计 CLI-Anything 时我对比过几种方案。最粗暴的是写一堆 Shell 脚本按功能命名放在 ~/bin 里但这有个问题脚本之间相互调用困难、参数解析全靠手工、输出格式五花八门而且随着脚本增多管理成本直线上升。还有一种思路是引入完整的工作流引擎比如 GitHub Actions 或 Jenkins Pipeline但这套东西太重了本地开发场景根本不需要那么多 runner、artifact、sandbox 的概念。最终我选了子命令聚合 插件扩展的轻量架构。核心可执行文件只负责四件事解析子命令、加载配置、按顺序执行步骤、格式化输出。具体的操作逻辑全部分布到插件或者外部脚本里。这样做的好处有三个第一核心代码量很小维护成本低第二新增能力不需要改核心逻辑写个插件挂载进去就行第三每个插件可以独立测试出问题了不会拖垮整个系统。架构上我把它拆成了五个模块。入口调度器接收命令行参数解析出要运行哪个子命令、携带什么选项。配置加载器读取 YAML 或 TOML 配置文件把命令定义、变量、钩子加载到内存。插件注册表扫描指定目录下的插件文件维护插件名到执行逻辑的映射。执行引擎按顺序执行命令步骤捕获每个步骤的输出和退出码遇到错误可以中断也可以继续。输出格式化器统一处理颜色、缩进、进度提示让所有命令的输出风格保持一致。提示模块划分不必一步到位。我一开始只写了入口调度器和执行引擎配置加载器是用了两周之后才加的插件机制更是后来才补上的。设计时心里有蓝图但落地可以循序渐进。这套架构的另一个关键决策是声明式配置优先于命令式代码。也就是说编排什么样的工作流尽量写在配置文件里而不是散落在代码的 if/else 里。为什么因为命令的编排本质上是业务逻辑业务逻辑会频繁变化——今天要多加一个健康检查明天要换一个部署目标。如果这些变化都要改代码、重新编译、重新发布那这个工具的实用性就大打折扣了。声明式配置让我改一个 YAML 文件就能生效改完还能用 git 管理起来出问题能回滚。2. 核心配置与命令体系拆解2.1 配置文件设计用一份 YAML 管理所有工作流配置是 CLI-Anything 的心脏。我用的格式是 YAML选它不是因为功能最强而是因为它可读性好、注释友好、和 GitHub Actions、GitLab CI 的语法习惯一脉相承团队协作时沟通成本低。先看一份我实际在用的配置文件麻雀虽小五脏俱全。# ~/.cli-anything/config.yaml project: myapp version: 1.2.0 variables: REGISTRY: registry.example.com DEPLOY_HOST: deploy10.0.0.8 HEALTH_URL: http://localhost:8080/healthz commands: morning-check: description: 晨检git 状态 服务健康 磁盘余量 steps: - run: git status --short - run: curl -sf ${HEALTH_URL} echo healthy - run: df -h | head -5 deploy: description: 一键构建、打包、发布到测试环境 steps: - name: 构建二进制 run: go build -o ./bin/app . - name: 自检版本 run: ./bin/app --version - name: 打镜像 run: docker build -t ${REGISTRY}/myapp:${TAG} . - name: 推送镜像 run: docker push ${REGISTRY}/myapp:${TAG} - name: 远程更新 run: ssh ${DEPLOY_HOST} docker pull ${REGISTRY}/myapp:${TAG} docker restart myapp hooks: before-command: - run: echo 开始执行命令 after-failure: - run: echo 命令执行失败这份配置里有几个字段值得展开说说。project 和 version标识项目和相关配置版本version 主要用来做配置迁移。我升级配置格式时加载器会根据 version 字段决定是否执行迁移逻辑。不要小看这个字段没有它改了字段名之后老配置文件全部静默失效排查起来非常痛苦。variables全局变量区。变量可以在 steps 里通过${VAR_NAME}引用。注意这里的变量不仅仅是简单的替换加载器会做层级化解析——先加载默认值再加载用户配置覆盖值最后加载环境变量值。也就是说我在命令行里设置了环境变量TAGv1.2.0deploy 命令里的${TAG}就会用环境变量的值等于提供了一种运行时注入参数的方式。commands.steps每个步骤本质上还是一个命令调用。我给每个步骤加了可选的name字段执行时日志会打印[步骤名] 正在执行这样出错时能快速定位是哪个环节挂了。hooks钩子机制。支持 before-command、after-success、after-failure 三个时机点。这个功能非常实用比如我可以在每次执行任何命令之前自动拉取最新配置或者在失败时往日志中心上报一条记录。配置文件的价值还体现在版本管理上。我的整个~/.cli-anything/目录是初始化成 git 仓库的配置变更、插件更新全都有 commit 记录。有一次我把某个步骤的镜像标签写错了导致线上发布了错误版本回滚时直接git revert配置一分钟内恢复。2.2 命令命名与参数规范让每个命令都像原生内置子命令的设计规范是 CLI-Anything 体验好不好的分水岭。命令名我用了一个简单规则动词开头名词补充不超过三个词。比如morning-check、init-project、sync-db你看到名字就知道这命令干嘛的。尽量避免util、misc、test1这种不知道在说什么的名字。参数设计参考了 GNU 风格短参数用一个横杠加一个字母长参数用双横杠加单词。每个子命令都支持统一的全局参数这些参数由入口调度器解析不劳烦插件各自处理。参数短参说明示例--dry-run无只打印将要执行的步骤不真正执行anything run deploy --dry-run--verbose-v输出每个步骤的完整原始输出anything run deploy -v--skip无跳过指定步骤多个步骤用逗号分隔anything run deploy --skip build,test--only无只执行指定步骤anything run deploy --only 推送镜像--json无以 JSON 格式输出结果适合对接自动化anything list --json--timeout无每个步骤的超时时间单位秒anything run sync-db --timeout 60--dry-run是我用得最多的参数。因为编排一个跨工具的命令时最怕的就是不理解每一步的影响范围直接在真实环境里跑出大事。dry-run 模式会把每一步将要执行的命令原样打印出来但不会真的调用外部进程相当于提前预演一遍。这个参数救过我起码三次有两次是发现自己拼错了目标主机的 IP。关于参数命名我还有一个经验不要设计含义模糊的多功能选项。比如--force到底强制的是一步还是全程不同命令里语义还不一样用起来全靠猜。我后来把这类参数拆成了更明确的--skip-if-exists、--no-input这类命名虽然命令长一点但歧义少很多。2.3 变量展开的优先级与陷阱变量展开顺序上踩过一次坑得专门提一下。我的加载器设计了一套三级优先的变量来源优先级从高到低是进程环境变量、用户配置文件中的variables、内置默认值。设计上很简单但使用时容易忽略一个细节在同一个步骤里变量引用解析发生在命令真正执行之前。举个例子如果我在配置里写run: sh deploy.sh ${TAG}而环境变量里正好没有TAG那 YAML 里TAG会被解析为空字符串实际执行的是sh deploy.sh参数直接丢了。后来我加了一个校验规则解析步骤之前先扫描所有${VAR}引用如果有未定义变量直接报错并列出缺失变量名而不是闷头执行一个残缺的命令。这个校验规则非常有用它把很多隐性错误提前暴露在 dry-run 阶段。3. 实操从零搭建你自己的 CLI-Anything3.1 安装与初始化两条命令进入可用状态我不太喜欢那种动辄几十个依赖、装完还要配环境变量的工具。CLI-Anything 的安装刻意做得很轻。核心二进制分发有两种方式一种是 Go 写的版本直接go install另一种是 Node 写的版本用 npm 全局安装两者互不影响选一条路就行。# 方式一Go 版本 go install github.com/yourself/cli-anythinglatest # 方式二Node 版本 npm install -g cli-anything # 初始化配置目录 anything initanything init会创建~/.cli-anything/目录里面生成一个默认的 config.yaml、一个 plugins 目录、一个 logs 目录。默认配置里带了两三个示例命令方便你做冒烟测试。初始化完成之后可以先用anything list看一下命令列表确认安装没问题。提示如果你在团队里使用强烈建议把生成的配置目录纳入团队 git 仓库然后让每个人anything init之后执行anything sync拉取共享配置。这样团队的命令规范、部署流程都能保持一致新同事入职配置环境的时间能从半天压缩到十分钟。3.2 手写第一个自定义命令晨检流程我建议你在动手前先想明白一个问题你最想封装的高频操作是什么找一个最简单的场景练手而不是一上来就试着把发布流程全自动化。我第一次写配置文件时第一个命令就是晨检因为它几乎没有危险操作即使写错了最多就是打印几行错误信息。来看完整做法。第一步在 config.yaml 的commands节点下新增一个morning-check定义包含三个步骤git 状态、服务健康检查、磁盘使用率。commands: morning-check: description: 晨检git 状态 服务健康 磁盘余量 steps: - run: git status --short - run: curl -sf ${HEALTH_URL} echo healthy - run: df -h | head -5第二步执行 dry-run 验证。anything run morning-check --dry-run正常输出应该是这样[步骤 1/3] 执行: git status --short [步骤 2/3] 执行: curl -sf ${HEALTH_URL} echo healthy [步骤 3/3] 执行: df -h | head -5如果这里看到了什么奇怪的引号丢失、变量被错误展开立刻回头检查 YAML 的引号嵌套。常见的坑是在 YAML 里需要整个命令作为字符串保存所以run:的值要记得用引号包住否则会被解析成不合法格式。第三步真正执行。anything run morning-check执行的时候执行引擎会逐条启动子进程捕获 stdout 和 stderr前缀加上步骤序号实时打印。如果某一步的退出码不是 0默认行为是中断后续步骤并在日志里标记失败位置。这就是上面提到过的 fail-fast 策略。对于晨检这种只读操作如果 git status 失败后续的 curl 和 df 大概率也不会正常快速中断能省下不少等待时间。3.3 对接外部工具一键发版命令的完整实现晨检算是热身真正体现 CLI-Anything 价值的是多工具协同的命令。我拿 deploy 命令当例子拆解一下。deploy 命令的完整流程是构建二进制、自检版本、构建 Docker 镜像、推送到私有仓库、SSH 上服务器拉镜像并重启容器。这五步如果手动操作每步少说 30 秒中间还容易输错镜像标签。封装之后变成一条命令。配置代码前面已经给过了这里重点说几个执行引擎层面的设计细节。每个步骤默认在项目根目录下执行。也就是说如果我在某个项目的目录里运行anything run deploy那go build、docker build都是以当前目录为工作目录执行的。这样设计的直觉是把 CLI-Anything 当成一个项目意识的助手它知道自己在哪个项目里自然知道构建上下文在哪。步骤之间是顺序执行还是并行执行我的设计是默认顺序执行。因为发布流程里推送镜像必须在构建之后远程重启必须在推送之后天然就是有向无环图。并行执行看着效率高但一旦引入共享文件、共享端口排查问题的时间远超节省的执行时间。只有一些真正互相独立且耗时的步骤比如同时备份多个数据库我会用并行的方式处理。执行中的超时控制也很关键。curl 卡住了、ssh 连不上、docker pull 大镜像慢得像蜗牛如果没有超时机制一个步骤能挂半小时。我给每个步骤设置了默认 120 秒超时如果步骤执行超时执行引擎会杀掉整个进程组把超时作为失败原因记录下来。对于网络操作频繁的步骤我单独加长超时时间比如 docker pull 可以放宽到 300 秒。# 实际发版时我通常会这样操作 anything run deploy --dry-run --verbose # 确认无误后使用环境变量注入版本号 TAGv2.3.1 anything run deploy实际执行的输出大概是这样的[步骤 1/5: 构建二进制] 开始执行 go build -o ./bin/app . [步骤 1/5: 构建二进制] 完成 (2.1s) [步骤 2/5: 自检版本] 开始执行 ./bin/app --version myapp version 2.3.1 [步骤 2/5: 自检版本] 完成 (0.1s) [步骤 3/5: 打镜像] 开始执行 docker build -t registry.example.com/myapp:v2.3.1 . ... 省略镜像层输出 ... [步骤 3/5: 打镜像] 完成 (15.8s) [步骤 4/5: 推送镜像] 开始执行 docker push registry.example.com/myapp:v2.3.1 [步骤 4/5: 推送镜像] 完成 (12.3s) [步骤 5/5: 远程更新] 开始执行 ssh deploy10.0.0.8 docker pull registry.example.com/myapp:v2.3.1 docker restart myapp [步骤 5/5: 远程更新] 完成 (4.7s) deploy 命令执行成功总耗时 35.0s这个命令已经是团队内部的标配了。有个后端同事说他最满意的不是少敲了几条命令而是每条命令的输出都有统一的时间戳、步骤名和耗时出了事能立刻定位是哪一步慢、哪一步挂。3.4 插件扩展不用改核心代码也能加能力CLI-Anything 的名字里带着Anything这份野心主要靠插件机制支撑。插件本质上是一段独立脚本导出自己的命令定义然后被主程序加载。我定义了一个极简的插件协议目前支持 Shell 脚本和 Node.js 模块两种形式。插件放在~/.cli-anything/plugins/目录下文件名以.sh或.js结尾。以 Shell 插件为例一个插件文件里只需要声明PLUGIN_NAME和PLUGIN_COMMANDS两个变量主程序启动时会扫描这个目录把声明过的命令合并进命令列表。#!/usr/bin/env bash # 文件位置: ~/.cli-anything/plugins/notify.sh PLUGIN_NAMEnotify PLUGIN_COMMANDSsend plugin_notify_send() { local channel$1 local message$2 # 这里调用团队内部的通知服务 API curl -sf -X POST https://notify.example.com/${channel} \ -d text${message} }这个插件的核心逻辑就一个把文本消息发送到指定频道。它有plugin_notify_send这个函数函数名有规律——plugin_{插件名}_{命令名}主程序执行时会在插件上下文中调用这个函数并传入解析好的参数。这样一个插件就提供了一条notify send命令。插件机制带来的自由度非常大。我之前写过一个db-backup插件把 mysqldump、压缩、上传对象存储、清理过期备份整个流程封装起来团队里任何人备份数据库都只需执行anything run db-backup --env prod不用再关心 mysqldump 的参数语法和对象存储的密钥配置。但插件也不是越多越好。插件多了启动时扫描时间会变长而且插件之间的依赖关系会变得混乱。我现在的原则是高频的、稳定的操作放进核心配置低频的、可变的扩展写成插件。晨检、发版这种几乎每天用的放核心给某个临时项目写的专用同步脚本放插件用完就删。4. 常见问题、踩坑实录与排查技巧4.1 环境变量消失了非交互式 Shell 的陷阱这是我被问得最多的问题。现象是在终端里明明export TAGv1.0了配置里的${TAG}却展开为空。我明明设了环境变量这句话我听了不下十遍。原因几乎都出在 Shell 的加载机制上。当你执行anything run deploy时主程序是以子进程的方式启动外部命令的这个子进程继承的是主程序的环境变量而不是你在.zshrc或.bashrc里设置的那些。如果你的 Shell 配置是在非交互模式下没有加载的主程序根本看不到那些变量。排查路径固定三步。先确认环境变量在当前 Shell 是否存在echo $TAG。如果存在第二步用anything run some-command -v打开 verbose 模式看实际传给子进程的环境变量里有没有 TAG。第三步如果 verbose 模式看不到检查一下是不是用了 sudo 或者其它会重置环境的方式执行命令。提示我最终的解决方案是标准化了变量注入方式。业务相关的变量不依赖环境变量而是统一维护在配置文件里只有临时变化的变量比如版本号、目标环境才用环境变量注入。创建配置时约定配置文件里的变量叫variables环境变量仅在运行时覆盖两边不要出现同名但不同义的变量否则排查起来非常头疼。4.2 中文乱码与输出格式异常另一个常见问题是命令输出里的中文变成了乱码。这通常不是 CLI-Anything 的问题而是外部命令的输出编码没有被正确识别。我的执行引擎在捕获子进程输出时默认按 UTF-8 解码但有些老旧的系统工具默认输出 GBK 编码导致乱码。处理方案是给执行引擎增加一个--encoding参数按需指定子进程输出的编码格式。虽然按需指定听起来繁琐但在对接遗留系统时真的能救命。另一个小细节是 Windows 环境下命令输出末尾会带\r\n而不是\n这个也会导致日志里出现奇怪的^M字符。处理办法是在展示之前统一做一次换行符归一化把\r\n转成\n。4.3 步骤莫名其妙的失败引号与转义的隐形杀手还有一个容易让人抓狂的情况配置里写得好好的命令在终端里手动执行能成功但通过 CLI-Anything 执行就报错。排查到最后八成是引号和转义出了问题。YAML 里的字符串在传给 Shell 执行时会经过多层解析。比如run: ssh host echo hello echo world这行 YAML 加载后变成字符串ssh host echo hello echo world再传给/bin/sh -c执行。问题出在如果命令本身还包含$、反引号、转义字符这些符号会在 Shell 解析时被再次解释导致行为和预期不一致。我后来在配置里约定了一个规范配置里的命令字符串不传复杂 Shell 语法。复杂的逻辑一律下沉到独立脚本文件配置里只写调用脚本的命令。比如我要做拉取远程数据库并导入本地我不会写一长串管道加变量拼接而是写一个scripts/sync-db.sh脚本配置里只写run: bash scripts/sync-db.sh ${ENV}。这样既避免了多层转义的坑又方便单独测试脚本逻辑。4.4 Shell 补全与别名CLI-Anything 的价值之一是统一入口但如果每次都要敲全命令名体验就大打折扣了。我实现了子命令的自动补全脚本支持 bash 和 zsh。安装补全脚本的步骤很简单anything completion bash ~/.cli-anything/completion.bash echo source ~/.cli-anything/completion.bash ~/.bashrc # zsh 用户 anything completion zsh ~/.cli-anything/completion.zsh echo source ~/.cli-anything/completion.zsh ~/.zshrc补全之后敲anything run depTab就能自动补出deploy再敲--Tab能列出全局参数。这个功能是用完就回不去的强烈建议安装。另外我常用的一个技巧是在 Shell 配置文件里给高频命令设置别名。alias ckanything run morning-check alias depanything run deploy alias syncanything run sync-db这里提醒一句别名不要和子命令名冲突否则容易精神分裂。我一开始给anything run morning-check起了个别名叫mc结果团队新同事不知道mc是什么查了半天才发现在是别名。后来统一规则别名全部用人类可读的短单词ck、dep、sync避免无意义缩写。4.5 执行过程中的性能问题步骤多了以后可能会遇到执行慢的问题。除了外部命令本身的耗时还有一个常被忽略的消耗每个步骤都是独立拉起一个子进程这个进程的启动开销虽然只有毫秒级但如果有上百个步骤累计也有几百毫秒。更重要的是如果步骤内部又调用了大量外部工具比如 grep、awk、sed 的组合性能瓶颈会非常明显。优化思路有两个。一个方向是减少不必要的步骤拆分把多个简单操作合并到一个脚本里执行降低进程拉起的次数另一个方向是在执行引擎里支持步骤级别的并行标记允许把没有依赖关系的步骤并发执行。这两个方向我都在实际项目里用过效果都不错但记住性能优化的前提是可观测性。先开 verbose 模式看清楚每步耗时再决定怎么优化别凭感觉做并行化。5. 工具选型与周边生态语言与体验的取舍5.1 用什么语言写 CLIGo、Rust、Node 还是 PythonCLI-Anything 的核心二进制在不同阶段换过两种语言实现。这个选型问题对其他想自己写命令行工具的人也有参考价值我直接给一张对比表。维度GoRustNode.jsPython二进制分发单个静态二进制部署简单单个静态二进制体积略大依赖 Node 运行时依赖 Python 解释器启动速度极快约 10ms 级极快中等约 80ms 级较慢约 100ms 级开发效率高标准库覆盖广中学习曲线陡高生态丰富高写起来最快生态与库优秀的 cobra/viperclap/serde 很强commander/yargsclick/typer并发执行goroutine 很顺手tokio 强大但复杂异步回调心智负担重多进程方案较繁琐我自己最终留在 Go 版本上主要是看中它的单二进制分发和接近零的启动延迟。CLI 工具的使用频率极高每次敲命令都希望它像原生指令一样瞬间响应哪怕多 100 毫秒的延迟高频使用时也会觉得拖沓。如果你主要做数据分析、机器学习方向工具和 Python 生态绑定很深那用 Python 实现也许更合适。5.2 体验优化温度色输出与进度反馈命令行工具的体验不只是功能正确还包括输出是否直观、操作是否有反馈。我用三个原则优化了 CLI-Anything 的交互体验。第一颜色传达语义。错误信息用红色警告用黄色成功的步骤摘要用绿色普通日志用默认色。这些颜色只在终端支持时启用输出管道重定向到文件时会自动关闭 ANSI 码避免日志文件里混入乱码。第二大步骤给出明确的进度信号。docker build 这类命令默认输出就很多很杂用户很难分辨卡在哪一层。CLI-Anything 会把长输出的最后几行实时打印同时显示累计耗时。用户看到的信息永远是最新状态不会淹没在刷屏的输出里。第三重要的操作要有确认交互。破坏性操作比如删除备份、重置数据库执行前默认会弹出确认提示只有加上--yes参数才会跳过确认。这个确认机制为团队避免过至少两次灾难性操作。5.3 和现有工具的生态整合CLI-Anything 不是要替代已有的工具链而是做它们的粘合剂。它和 git 的关系是编排而不替代——diff、log、commit 这些单点操作还是用 git 原生命令但涉及把当前分支推到开发环境这种跨 git 和 ssh 的复合操作就会封装成命令。同样的原则适用于 Docker、kubectl、数据库客户端。和 CI/CD 系统的关系也是一样。本地执行用 CLI-AnythingCI 流水线里也可以直接调用它。我见过有人在 GitHub Actions 里跑anything run test --env ci命令本身和本地是一致的只是参数不同。这种本地和流水线共用一套命令的方式能显著减少本地能跑但 CI 挂了这类环境差异问题。最后分享一点个人体会玩 CLI-Anything 时间久了我最大的感受是命令是壳配置是肉脚本是魂。核心二进制只是提供一个稳定可靠的外壳真正让工具融入日常的是那些经过反复打磨的配置文件和插件脚本。如果你也想搭一套我的建议是先别急着设计一大堆命令从你明天早上要做的第一件事开始——看看它涉及哪几个工具、哪几步操作、哪些参数是变化的然后把它们编译成一条命令。用上两天觉得顺手了再增加下一条。等到某天你发现新同事入职一天就能独立完成发版或者你换了一台新电脑十分钟内恢复了所有工作流你就会明白这个工具真正省下的不只是敲命令的时间而是你从繁琐细节中腾出来的注意力。
