CLI-Anything 这个名字我第一次写进仓库时旁边同事还开玩笑说这口气有点大。但用了大半年之后我反而觉得这个定语还不够大——因为Anything恰好点中了命令行工具治理里最痛的软肋什么都能做什么都做得没法统一。过去几年我一共维护过三个内部系统。数据回刷工具是用 Python argparse 写的CI 发布脚本是 Shell 拼的运营查询接口则拿 curl 包了一套伪命令行。每个都能跑但凑在一起就像三个人用三种口音讲同一件事参数风格、错误输出、退出码全不一样监控告警一来先得凭经验判断是哪个系统在咳嗽。CLI-Anything 就是在这个背景下立项的一个配置驱动的通用命令行构建框架不管底层是脚本、是接口还是工作流只要在一份 YAML 配置里声明清楚就能得到一条参数规范、输出统一、开箱即用的标准命令。这篇分享会把整个框架的思路、配置细节、坑位地图和个人体会讲透。还在被又双叒要写一个 CLI折磨的人或者正打算把散装运维脚本收拢成规范命令的团队内容可能比较对味。1. CLI-Anything 是什么从又要写一个 CLI说起1.1 一个真实的痛点场景先说我自己踩出来的痛点。我们组三个内部系统表面看都有自己的命令行入口但切换成本特别高。数据回刷工具传错参数时直接甩一段 Python traceback 到终端发布脚本遇到失败就静默exit 1连一行错误说明都没有curl 那个伪命令则把后端接口的 JSON 错误信息原样铺在屏幕上。这三个系统凑在一起最糟糕的是没法自动化串联。我想写一个流水线脚本按顺序执行检查配额 - 回刷数据 - 发送通知光是解析三种输出格式就够写一堆正则。而且每个命令的帮助信息还要分别维护发版节奏不同步文档经常跟实际行为对不上。这种碎片化状态持续了两个月直到有一次线上回刷任务因为参数搞混导致重跑了一整天我才下决心把入口治理提上日程。把三条命令的底层逻辑拆开看本质上全是同样四步读参数、调业务逻辑、格式化输出、设置退出码。既然共性这么明显那抽一层公共的壳子就是水到渠成的事。CLI-Anything 的第一版就是在那个周末写的功能很简单先把参数校验和 JSON 输出统一掉效果立竿见影。1.2 定位与设计目标CLI-Anything 的定位用一句话就能说清它是一个配置驱动的通用命令行构建框架不限定底层语言不绑定操作系统把把一个可调用的东西变成一条标准命令这件事简化成写一段 YAML 配置的工作量。设计目标我总结为四条。第一声明式定义命令。命令名、参数、说明、执行方式全部写在配置里业务方不需要学习框架 API。第二统一运行时行为。help 输出、参数校验、退出码、日志格式这些横向能力由框架接管各系统不再各自为政。第三程序友好。既能给人交互使用也能被脚本和 CI 直接调用输出格式支持 human 和 json 两种。第四可扩展。内置插件机制允许在命令执行的几个关键节点挂上自己的逻辑。这四条目标不是拍脑袋定的每条都能对应到前面说的具体痛点声明式对应不要再写解析代码统一运行时对应不要再各报各的错程序友好对应流水线里能可靠对接可扩展对应别把框架变成新的束缚。一个工具如果只是把问题换了个形式那它就不值得存在这是我给 CLI-Anything 定的底线。1.3 与现有 CLI 框架的差异很多人第一反应是Node 有 CommanderPython 有 ClickGo 有 Cobra为什么还要再造一个轮子这个问题我内部分享时被问过不下十次。Commander、Click 这类库解决的是单个命令行程序的开发体验问题它们帮你把参数解析、子命令分发这些样板代码封装成 API但每个工具最终仍然是一个独立应用有自己的构建方式、依赖和发布物。CLI-Anything 的视角不一样它不关心你的业务代码是谁写的只要求你声明我有这条命令参数是这些执行时去跑这个脚本或调这个地址剩下由框架统一处理。它更像一个面向多个脚本和服务的命令总线而不是某个应用的开发库。这个差异决定了使用姿势完全不同用 Commander 是开发一个工具用 CLI-Anything 是治理一批入口。维度Commander/Click/Cobra 这类库CLI-Anything关注点单个 CLI 程序的开发体验多个脚本/服务/流程的统一封装接入成本需要调用框架 API 编写代码写配置并指向已有逻辑多命令统一程度每个程序自己负责全局统一 help、日志、校验运维友好度依赖各程序自身实现内置 json 输出与退出码约定可观测性自行埋点插件化统一采集这个表格不是想说明孰优孰劣而是划清适用边界。如果团队只有一个工具要写直接用 Commander 或 Click 会更顺手如果已经有一堆脚本和服务它们各自为政让你很难受那 CLI-Anything 这类治理型框架才真正对症。2. 核心架构拆解一切皆命令2.1 配置驱动的命令注册机制CLI-Anything 的心脏是项目根目录下的commands.yaml配置文件框架启动时递归扫描这个文件把里面声明的每条命令都注册进命令表同时自动生成help和--help输出。一个最小命令定义是这样的version: 1.0 commands: ping: description: 检查服务是否存活 run: type: exec cmd: curl -s -o /dev/null -w %{http_code} https://api.example.com/health outputs: - human - json这个定义只回答了四个问题命令叫什么、干什么、怎么执行、输出怎么处理。框架拿到这四条信息后命令注册、参数解析、退出码映射、帮助文本生成全部自动完成。我刻意把配置字段控制得很薄就是为了防止配置文件本身变成一个新的维护负担。命令多了以后一个文件塞不下是必然的。所以配置里支持imports指令按领域拆文件imports: - commands/deploy.yml - commands/query.yml base: version: 1.0我这边给团队定的惯例是一个子文件对应一个子系统文件内部只读命令放上面、写操作放下面。这样 code review 时扫一眼文件结构就能判断一次改动的影响面是只读还是可能改变状态。命令名也有命名规范统一用小写加连字符比如batch-run、quota-check不允许驼峰因为驼峰在大小写不敏感的文件系统上换台机器就可能变成两条命令。2.2 参数解析与自动验证参数是命令行最容易翻车的环节CLI-Anything 把这块拿到框架层统一处理。参数列表挂在命令节点下的args字段commands: batch-run: description: 批量执行数据回刷 args: - name: jobId required: true type: string desc: 任务ID多个用逗号分隔 - name: --parallel type: int default: 2 desc: 并行数 - name: --dry-run type: bool default: false desc: 只打印将执行的操作 run: type: script file: scripts/batch_run.sh outputs: - human - json解析规则采用 Posix 风格位置参数在前--option后置短选项-p能自动映射到--parallel。框架在真正执行业务逻辑之前会先做一轮完整校验必填项缺失直接报错类型不匹配给出精确提示未知参数也不会静默忽略而是给一条警告。比如运行cli run batch-run不带必填的jobId输出是这样$ cli run batch-run Error: missing required argument jobId Usage: cli run batch-run jobId [--parallel N] [--dry-run]这套统一校验带来的额外收益是不同命令的报错格式完全一致了脚本和 CI 抓取错误信息时不用再兼容 N 种正则。支持的类型包括 string、int、float、bool、enum、list其中enum用来限定有限取值list支持逗号分隔。类型定义不要贪多我实际用下来80% 的场景就是 string、int、bool 和 enum 四种够用且有约束力比提供一堆花哨类型更有价值。2.3 插件系统与能力扩展CLI-Anything 不打算框死所有场景从 0.9 版本开始引入插件机制。插件是一个实现了特定接口的模块能在命令执行的几个关键节点挂上钩子beforeCommand、afterCommand、beforeOutput、afterOutput。一个计数插件只有几行export const metricsHook { beforeCommand(ctx) { ctx.startedAt Date.now(); }, afterCommand(ctx) { console.log(duration_ms${Date.now() - ctx.startedAt}); } };我们实际应用的一个插件是耗时上报。CI 每天跑几百次命令有些偶尔慢一两秒不采集数据根本发现不了。插件在beforeCommand打时间戳afterCommand计算耗时打到本地 metrics 端口Prometheus 抓取完事。插件文件用插件配置声明plugins: metrics: hook: beforeCommand/afterCommand module: ./metrics-hook.js插件规范里最有约束力的一条是插件内禁止修改命令的上下文数据只能读取和增加元信息。这条约束是在一次生产事故之后补上的细节放到 4.4 节细说。插件机制的价值在于框架不需要预判所有场景只提供控制流把观察点留给生态。这样既能保持核心稳定又能让有特殊需求的团队自我武装。3. 实操把一堆散装脚本变成统一 CLI3.1 场景设定与工作流梳理这一节用一次真实做过的迁移来演示。假设你手上有一个数据仓库里面有三个脚本backup_to_s3.sh、notify.py、check_quota.py。旧的调用方式分别是./backup_to_s3.sh --bucket>commands: backup: description: 将指定目录备份到对象存储 args: - name: --bucket required: true type: string desc: 存储桶名 - name: --env type: enum values: [dev, staging, prod] default: dev run: type: script file: ../scripts/backup_to_s3.sh argsMap: --bucket: --bucket --env: --env outputs: - human - jsonnotify.yml和quota.yml的结构类似只是指向不同的脚本和参数commands: notify: description: 发送通知消息 args: - name: --to required: true type: string desc: 接收人 - name: --msg required: true type: string desc: 消息内容 run: type: script file: ../scripts/notify.py argsMap: --to: --to --msg: --msg outputs: - human - json迁移完成后新命令统一成cli backup --bucket>{ command: backup, exitCode: 0, durationMs: 3421, stdout: backup done, 128MB, stderr: }流水线里解析这个结构比匹配自由文本可靠得多。这里有个细节argsMap里如果旧脚本用的是位置参数$1、$2可以在argsMap里写成$1: --bucket这样的映射框架会自动按声明顺序把参数拼到脚本调用末尾。3.3 自定义输出格式与错误处理内置的human输出适合给人看json适合给程序看但总有需要第三种格式的场景。CLI-Anything 允许为每条命令声明自定义输出渲染器实现一个函数即可。比如quota-check原来的输出是Disk usage: 82.3%, threshold: 60%人看着不直观监控程序也不好解析。我给它接了一个自定义渲染器把脚本输出里的百分比抽出来转成带status字段的对象export const quotaRenderer { type: quota, render(output) { const m output.match(/([\d.])%/g).map(Number); const usage m[0], threshold m[1]; return { usage, threshold, status: usage threshold ? warn : ok }; } };错误处理方面框架有个全局约定命令执行成功退出码为 0业务失败按错误等级用 1通用错误、2参数错误、3依赖缺失。这个分级必须跟团队成员宣贯到位否则大家还是会随手exit 1分级就失去意义。我在 CI 的 lint 模板里加了一条检查凡是脚本里出现裸exit 1的提示改成语义化退出码。约定如果只写在文档里约等于没有约定要让工具替你守住。4. 常见问题与排查技巧实录4.1 命令注册不上help 里看不到这大概是使用频率最高的问题。现象是配置文件里明明写了命令但cli help不显示执行时提示command not found。我的排查路径固定三步第一步看配置文件有没有被imports加载漏写 import 是第一大来源第二步确认命令名没有和内置命令help、version冲突框架会预留这两个名字自定义命令叫version会被拒第三步检查 YAML 缩进和字段名最常犯的是把commands写成了command导致整棵命令树静默为空。有个可以抄走的验证命令cli debug config。它会把经过 import 合并后的完整配置树原样打出来只要这个输出里没有你期望的命令问题一定出在配置本身不用怀疑运行时。我排查过的最离谱一例是有人把配置文件放到了.gitignore目录下本地跑得通CI 里命令表却是空的这种环境差异用debug config一眼就能看穿。4.2 参数解析的各种坑第一个坑是脚本参数转发。run.type: script模式下如果旧脚本用的是$1、$2这种位置参数而不是--namevalue必须在argsMap里显式写清楚映射。我最初偷懒没写结果框架把--bucket原样传给脚本脚本里$1拿到的是字符串--bucket排查了很久才发现。第二个坑是enum枚举校验的大小写敏感--env Prod在values: [dev, staging, prod]时直接判失败。第三个坑是 bool 参数的写法Posix 风格里--dry-run true会被拒绝必须写成--dry-run或--dry-runfalse。把这些坑整理成自查表贴在内部文档里能省下大量重复答疑时间现象原因解决脚本收到--bucket而不是值argsMap 没配或配错检查 argsMap 位置参数映射enum 校验失败大小写不匹配统一用小写或标注取值严格bool 参数带 true 被拒格式不符合 Posix 规范用--flagfalse或裸 flag位置参数数量不对旧脚本参数顺序变化对照 argsMap 声明顺序检查4.3 CI/CD 集成时的注意事项接进 CI 是收益最明显、也最容易埋雷的环节。收益在于统一了命令入口流水线里原来分散的 shell 指令缩成一行cli deploy --env staging埋雷在于很多人忽略非交互模式这个隐藏前提。CLI-Anything 在环境变量CItrue时自动切换非交互模式任何需要用户确认的提示按是处理同时关掉颜色输出避免 CI 日志出现乱码。这个机制的设计初衷很直接本地人工操作和流水线自动执行的期望完全不同同一条命令必须同时适配两种场景。实际使用中容易漏的细节是环境变量覆盖参数的优先级。框架的规定是显式参数 环境变量 配置文件默认值。也就是说命令里写了--env prod但 CI 全局定义了ENVstaging最终生效的仍然是命令行显式参数。这个优先级建议用大字在团队文档里标出来因为环境变量往往是看不见的全局状态被它悄悄改掉参数是最难排查的问题类型。我们曾遇到线下任务跑到了 staging 环境最后查出来是 CI 上一级的公共环境变量带了ENVstaging覆盖了配置默认值而命令行恰恰没写这个参数。4.4 插件踩坑不能修改上下文前面反复提只读上下文不加修改这条规矩来自一次真实事故。早期有个按环境打标签的插件实现里直接改了命令上下文里的env字段想着下游步骤不用再手动处理。结果插件被执行了两次第二次执行时把环境从prod又改成了插件的默认值。当天晚上跑了一个发布任务后面所有环境标签都和真实环境对不上排查花了整整一个下午。那次之后我把这条约束从口头约定升级成运行时强校验插件对上下文的修改直接抛异常。现在插件想影响行为只能通过添加元信息由命令的运行器决定要不要使用。设计原则一句话框架提供控制流插件提供观察点两者不要互相越界。这条原则写进了开发规范的第一页也是我给所有接入团队讲的第一个千万别踩的雷。5. 使用心得与后续扩展方向CLI-Anything 我实际维护和使用了差不多一年最大感受是统一入口带来的隐性收益远大于首屏那点配置量。原来三套脚本、三份文档、三种报错格式新同事上手平均要一两天现在一条cli help能解决 80% 的问题。命令从分散到收敛看着是形式上的变化实际上把团队协作的摩擦也一起降下来了。如果你打算在自己的项目里试用我的建议是不要一上来就全量迁移。先挑一两个非核心的命令接进来跑通一条流水线感受一下 help 输出、参数校验、json 输出这些横向能力再逐步扩大范围。千万别一开始就接那些依赖复杂、历史包袱最重的命令否则排查成本会冲淡对框架的好感。我自己就是这么过来的三个月时间从第一条命令做到全量收敛踩过的坑都在前面几节里了。后续我在规划几个扩展方向定时执行能力让声明出来的命令可以直接挂 cron权限检查钩子把团队里谁能在生产环境执行写操作的规则下沉到框架层灰度发布插件把一个部署命令拆成按比例分批执行。这些功能做出来后CLI-Anything 就不仅仅是一个命令封装工具慢慢会变成一个轻量级的运维编排底座。能不能走通等实践一段时间再回来分享。
