接手团队内部工具链维护的第一周我光是把七个分散的脚本拿出来对齐参数格式就花了整整两天。有人用 argparse有人用 click还有人直接拿$1拼逻辑。难受的还不只是格式不统一——新脚本加进来的时候几乎每个人都在重新发明轮子重复实现--help、参数校验、错误码、日志级别。CLI-Anything 就是在这个背景下冒出来的想法能不能把做一个命令行工具这件事抽象成一份声明式配置让任何脚本、任何 API、任何工作流都能在统一规则下变成一套标准 CLI真正做到anything。这篇文章会完整拆解这个项目的设计思路和实现过程核心的配置即程序机制、把老旧 HTTP API 包装成规范命令行工具的真实案例、从能跑到好用的细节打磨以及插件化扩展和踩坑记录。如果你平时经常写内部工具、自动化脚本或者维护过多个互相之间毫无章法的命令行程序这篇应该能给你一些可直接抄作业的参考。1. 被重复造轮子逼出来的想法CLI 脚手架为什么值得被标准化先说说痛点到底在哪。命令行工具的生态其实已经很成熟了Python 系有 argparse、click、typerNode 系有 commander、yargsGo 系有 cobra、kong。每一个单独拿出来都挺好用但落到一个团队、一个长期维护的项目群里面问题就变了每个工具用不同的库、不同的参数风格、不同的报错方式维护者要么忍受碎片化要么花大力气统一。我当时的处境是内部系统有二十多个自动化任务有的直接是 shell 脚本有的是 Python 写的定时任务有的要调用内部 API 再格式化输出。每个任务的入口参数、日志输出、退出码约定都不一致。上线一个新任务光是把输入参数怎么解析、错误怎么反馈这些样板代码写一遍就得大半天而且写出来的东西没法复用。真正促使我动手做 CLI-Anything 的是一次线上故障。一个维护了很久的部署脚本突然跑挂了排查下来不是脚本逻辑错了而是它解析参数的方式和别人不一样——别的工具都接受--envprod这种长选项写法这个脚本只认位置参数$2操作手册里也写得含糊不清。那次事故之后我意识到CLI 的体验问题本质上是一个工程规范问题不是某个脚本单点能解决的。1.1 为什么不做成又一个解析库最初我确实考虑过直接选一个解析库写进团队规范里比如强制大家用 click。但调研了一圈发现库层面的规范约束力很弱新人来了不一定遵守存量脚本不会主动迁移而且每个库的 help 风格、校验机制、错误处理差异依然存在。更关键的是很多内部工具根本不缺一个更好的参数解析库缺的是从业务函数到完整 CLI 程序的那一整段胶水代码——帮助文档、参数校验、配置读取、日志级别、环境变量注入、shell 补全。这些事务性的工作高度重复跟业务逻辑本身没有关系。既然这样与其让大家重复写不如把它变成自动生成的东西。1.2 生成器加运行时混合架构的选择所以 CLI-Anything 的定位很明确它不是一个解析库而是一个CLI 脚手架生成器加轻量运行时。用户用一份声明式配置描述这个命令长什么样参数、选项、执行逻辑、输入输出工具负责把它编译成一套完整可执行的命令行程序同时保留一个精简的运行时来加载业务逻辑。这个架构参考了市面上一众 CLI 框架的通用做法声明式配置负责描述意图代码生成负责产出样板运行时负责执行。为什么不用纯运行时解释因为生成出来的程序可以打成一个自包含目录单独部署到任何机器上不依赖生成器本体而且对使用者来说生成出来的代码是可读、可改、可 audit 的不会变成黑盒。2. 核心机制一份 manifest 跑遍所有场景的配置即程序CLI-Anything 的入口文件叫manifest.yaml它描述一个 CLI 程序的全部元信息命令名、简介、版本、参数、选项、执行器、钩子。整个系统的设计哲学可以浓缩成一句话配置即程序。你不需要手写 main 函数不需要写 if/else 分支去处理参数只描述这个命令收什么、做什么、吐什么其余交给引擎。2.1 manifest 长什么样以下面这个查询天气的命令为例这是最简单的一类场景——执行一个本地脚本并传参command: weather description: 查询任意城市的实时天气 version: 0.3.0 arguments: city: type: string required: true help: 城市名称如 beijing、shanghai options: units: type: choice choices: [metric, imperial] default: metric help: 温度单位默认公制 verbose: type: flag short: v help: 输出详细日志 adapter: type: exec command: scripts/fetch_weather.py args_template: {{city}} --units {{units}}这份配置说明命令叫weather必须接收一个位置参数city可选的--units参数只能在两个值里二选一-v/--verbose是布尔开关真正干活的是后面的scripts/fetch_weather.py。CLI-Anything 的生成器读这份 YAML 后会产出一个标准化的入口程序。用户看到的帮助文本、参数解析、校验逻辑、退出码处理都是自动生成的。不同命令的 manifest 即使内容完全不同产出的交互风格也完全一致这就从根源上解决了之前那种参数风格七零八落的问题。2.2 为什么选 YAML 而不是 JSON 或 TOML这是一个被问过很多次的问题。选 YAML 有几个实际考量一是 YAML 支持注释manifest 里可以把每个参数的取值范围、业务含义写清楚这份配置本身就能当文档用二是多行字符串写起来自然描述复杂的默认值或模版不费劲三是团队里大部分工程师都熟悉它运维配置、CI 管道里到处是 YAML认知成本低。当然 YAML 也有坑比如缩进错误不易排查、某些值会被自动类型转换。但生成器会做 schema 校验一旦字段类型不对、缺少必填项会在生成阶段就报错而不是等你跑起来才爆。实践中我把 manifest 的 schema 定义得非常严格command只能是合法标识符arguments和options不能重名adapter.type必须在已注册的适配器列表里。严格 schema 是配置文件能当程序用的前提。2.3 运行时怎么理解这份配置生成出来的程序启动后运行时会做四件事解析参数、校验输入、规范化数据、分发执行。解析参数这步生成器其实已经根据 manifest 把解析代码写死了运行时只是执行。校验发生在解析的同时——类型不对、必填缺失、枚举值不合法都会被拦在业务逻辑执行之前。规范化数据是个容易忽略但很实用的环节。比如--unitsmetric这种选项在 YAML 里是字符串到了执行器那里weather 脚本期望的可能是整数枚举。manifest 里可以配置transform字段做映射甚至写一段内联表达式把输入转成执行器想要的形态。分发执行则是适配器的活儿。执行器拿到标准化后的参数按照适配器类型去调脚本、调 API、调容器再把结果收回来统一处理。这层抽象是整个Anything的核心具体展开放在第 5 节。3. 实战把一个没人维护的 HTTP API 包装成规范 CLI 的完整过程理论讲再多不如看一个贯穿到底的例子。团队里有个历史悠久的内部系统对外暴露了一组 REST API没有 SDK文档也停留在三年前。其中一个接口是查询构建任务的当前状态另一个接口是触发重建。业务方经常要在排查问题时手动 curl每次都要记 token、记参数、还要肉眼解析 JSON。用 CLI-Anything 包装这个 API整个过程大约花了四十分钟产出是一个叫buildctl的命令行工具同事不需要懂 HTTP 细节就能用。3.1 把 API 描述成 manifest两个接口GET /api/v1/builds/{id}查询状态POST /api/v1/builds/{id}/rebuild触发重建。自然映射成两个子命令buildctl status id和buildctl rebuild id。manifest 的写法如下command: buildctl description: 构建任务的查询与重建工具 version: 1.0.0 options: server: type: string default: https://build.internal.example.com help: API 服务地址一般不用改 env: BUILDCTL_SERVER api_token: type: string secret: true help: 访问令牌也可通过 BUILDCTL_TOKEN 环境变量传入 env: BUILDCTL_TOKEN subcommands: status: description: 查询构建任务状态 arguments: id: type: string required: true help: 构建任务 ID adapter: type: http method: GET endpoint: {{server}}/api/v1/builds/{{id}} headers: Authorization: Bearer {{api_token}} output: json rebuild: description: 触发一次构建重建 arguments: id: type: string required: true help: 构建任务 ID adapter: type: http method: POST endpoint: {{server}}/api/v1/builds/{{id}}/rebuild headers: Authorization: Bearer {{api_token}} output: table这里有几个设计细节值得解释。API token 配置了secret: true生成器会把它从帮助文本、调试日志、错误提示里全面屏蔽。用户在 shell 里敲--api_tokenxxx会出现在 history 里所以更推荐用环境变量BUILDCTL_TOKEN传入。运行时会优先读命令行参数其次读环境变量最后读配置文件这个优先级顺序是 CLI 工具领域的通用约定我也沿用了。输出格式分了两种。status返回 JSON因为要保留完整字段供脚本消费rebuild输出表格因为人看的是这次触发成没成功、新任务号是多少。适配器内部做了响应解析状态码 2xx 正常输出4xx 映射成使用错误5xx 映射成运行时错误并附上响应体里的错误信息。3.2 生成后的使用效果生成出来的buildctl自带完整的--help说明子命令各自有独立的帮助文本。同事排查问题时只需要buildctl status 48293输出会被格式化不再是一坨 JSON。必要的时候还可以接-v看到底层的 HTTP 请求细节方便定位 API 侧的问题。值得注意的是这个工具也继承了 CLI-Anything 的退出码约定0 代表成功1 代表执行时错误2 代表参数用法错误3 代表配置错误。这样它在 CI 脚本里可以放心地被判断成败不用解析 stderr 文本。围绕退出码、补全、交互体验的细节是下面一节的重点。4. 从能跑到好用错误码、补全脚本和交互细节的打磨生成器跑通只是第一步。CLI 工具的价值在日复一日的使用中体现而使用体验往往藏在细节里。这一节聊聊我在 CLI-Anything 里打磨得最多的几个点。4.1 退出码与错误信息的规范很多内部脚本的退出码是乱来的有的直接exit 1有的exit -1本质是 255有的干脆不设置。CLI-Anything 强制统一为四段式约定退出码含义触发场景0成功正常执行完毕1运行时错误脚本崩溃、API 5xx、网络不通2用法错误参数缺失、类型不对、枚举值非法3配置错误manifest 校验失败、配置文件不存在、密钥缺失错误信息统一写到 stderr格式固定为[error] 简短描述加提示可能的解决方案。这个错误信息要带建议的习惯是从 Go 的错误处理哲学里借鉴来的光告诉用户不对没用要告诉他怎么改对。比如参数校验失败时输出不只是invalid value而是[error] --units 的值只能是 metric 或 imperial当前收到 celsius [error] 提示在 buildctl.status --help 中查看 --units 的完整说明这在内部工具的日常使用里省了太多的来回沟通。4.2 补全脚本不是锦上添花我见过很多 CLI 工具不提供 shell 补全内部工具尤其如此。但实际用起来补全对效率的提升非常大——不是少敲几个字母的问题而是减少记忆负担。一个命令有哪些子命令、哪些参数、参数有哪些可选值全靠大脑记是不现实的。CLI-Anything 的生成器支持从 manifest 直接产出 bash、zsh、fish 三种 shell 的补全脚本。参数名、枚举值、子命令名全部从 manifest 提取不需要额外维护一份补全定义。安装方式也很简单生成工具时带--completions bash /usr/share/bash-completion/completions/buildctl即可。做补全时有个细节HTTP adapter 的场景里某些参数值来自远端 API比如构建任务 ID 列表。补全脚本没法实时请求 API我就在 manifest 里支持了completions.command字段允许指定一个本地命令来动态生成候选项满足这类高级需求。4.3 TTY 感知与交互式提醒终端工具的另一个细节是分清交互与非交互场景。CLI-Anything 在输出上做到了 TTY 感知标准输出重定向到文件或管道时自动去掉 ANSI 颜色只有在真正的终端里才展示彩色和进度条。NO_COLOR环境变量也是被尊重的这在 CI 日志里特别重要——带颜色转义的日志传到日志系统里就是一堆乱码。还有一个我比较得意的设计当必填参数缺失时如果检测到当前是交互式 TTY会提示用户输入而不是直接报错如果非交互比如在 CI 里就直接以退出码 2 失败并明确指出缺少哪个参数。这个行为模仿了现代 CLI 工具该省事时省事该严格时严格的普遍做法。4.4 日志级别与进度展示manifest 里可以声明verbose风格的选项是否内置。CLI-Anything 默认注入-v显示 INFO 级日志、-vv显示 DEBUG 级日志、-q安静模式只输出关键结果。日志统一走 stderrstdout 永远只留主输出这样buildctl status 48293 | jq .result才不会被日志污染。耗时较长的任务比如触发重建后等待完成会显示进度条但进度条只在 TTY 下出现。进度信息的实现我特意要求不能用第三方进度库因为诊断时进度条到底在干什么很难追溯最终用了一套简单的阶段标记加时间戳方案非 TTY 下直接输出[3/5] 等待构建完成...这种纯文本行。5. 插件化扩展如何让 CLI-Anything 适配任意私有协议前面提到的adapter.type: exec和adapter.type: http其实是两个内建适配器。CLI-Anything 真正的野心在Anything这个词上——它要能对接一切执行形态。为此我设计了一套非常薄的插件接口任何团队私有协议都可以在半小时内接入。5.1 适配器接口只有三个方法适配器本质上是一个 Python 模块暴露三个钩子parse把 manifest 和标准化参数转成执行动作、execute执行动作并拿到原始结果、format把原始结果转成用户可读的输出。以 HTTP 适配器为例parse负责用 Jinja2 渲染 endpoint 和 headersexecute用 httpx 发请求并处理超时、重试、错误码映射format把 JSON 转成表格或原始输出。整个结构非常简单# adapter_demo/simple_mq_adapter.py class SimpleMQAdapter: name simple_mq def parse(self, ctx): return { queue: ctx.args[queue], message: ctx.args[text], priority: ctx.options.get(priority, normal), } def execute(self, action): return mq_client.publish(action[queue], action[message], action[priority]) def format(self, raw, output_mode): if output_mode json: return json.dumps(raw, ensure_asciiFalse) return f已发送到队列 {raw[queue]}消息ID {raw[message_id]}插件只需要放到约定的目录比如~/.cli-anything/adapters/或项目内的adapters/目录生成器会自动发现并注册。manifest 里写adapter.type: simple_mq就能直接用。5.2 钩子机制解决执行前后要做额外动作的需求很多真实场景不只是一个动作比如调用 API 之前要刷新 token执行脚本之前要检查依赖。CLI-Anything 提供了hooks段hooks: before: - command: scripts/refresh_token.py args_template: {{api_token}} after: - command: scripts/notify.py args_template: {{status}}钩子可以串任意命令也可以调用其他 adapter。这套机制和 CI 工具里的前后置脚本一个思路但它跑在本地命令执行前所有钩子共享同一个上下文字典钩子产生的输出可以注入到主执行器的参数里。比如刷新 token 那个钩子会把新 token 写回上下文主 HTTP 请求就能直接用上。5.3 插件发现的细节与安全性插件放目录、自动发现听起来很美好但有个安全点必须处理自动发现的插件等于任意代码执行。所以 CLI-Anything 对非内建适配器做了一个限制使用插件前需要显式声明信任生成器会提示该适配器来自非官方路径是否信任并把信任记录写到用户级配置文件里。这个设计参考了现代包管理器普遍采用的首次使用需确认机制不算首创但确实能挡掉不小心的攻击面。6. 若干坑位记录与我的最终取舍最后写几个真实踩过的坑。CLI-Anything 前后迭代了快一年凡是能在文档里查到的方案我都不想重复说这里挑几个最容易被忽视、又最影响实际体验的问题。6.1 生成代码与运行时解释的边界第一版我倾向全量生成——把解析代码、帮助文本、校验逻辑全部生成到目标目录好处是产物完全独立。但很快发现一个问题manifest 一变整个目录都要重新生成代码 diff 一片混乱审计困难。后来改成生成薄壳加运行时解释生成器只产出入口脚本和编译后的 manifest解析逻辑统一走运行时库。这样改 manifest 后 diff 很小运行时升级也能直接给所有已部署的工具打补丁。产品形态上这是正确的取舍宁可让产物多一个运行时依赖也不要每一次小改动都通篇重生成。6.2 Windows 兼容性比想象中恶心内部工具有一部分同事在 Windows 上跑Git Bash 环境这里全是细节exec适配器执行外部命令时路径分隔符、.py脚本解释器的选择、CRLF 与 LF 的混用稍微不注意就会翻车。我最终的策略是能少依赖 shell 就少依赖exec适配器默认用 Python 的subprocess以列表形式传参不做字符串拼接所有外部脚本统一在 manifest 里声明解释器避免依赖系统默认关联。Windows 的另一个坑是 stdout 编码。很多脚本在 Windows 控制台输出 GBK 编码文本被日志系统收集后显示乱码。处理方式是运行时统一以 UTF-8 作为输出编码遇到无法解码的字节流时做替换而不是抛异常。这个小改动让上海同事那边的日志终于能看懂了。6.3 子进程输出缓冲导致的日志迟到exec适配器最初直接调用外部脚本脚本的 stdout 和 stderr 混在一起输出看似正常但一旦脚本阻塞日志会积压到最后一次性喷出来。排查了半天才发现是子进程的管道缓冲问题——外部程序检测到 stdout 不是 TTY 时会启用块缓冲而不是行缓冲。解决方案是给exec适配器加了一个stdbuf兼容层Linux 下用stdbuf -oL强制行缓冲其他平台退化为不设置同时把 stdout 和 stderr 分成两条管道独立读取。这个坑非常隐蔽如果没有在真实的长任务里观察根本不会暴露。6.4 什么情况不建议用 CLI-Anything说了这么多也得泼点冷水。CLI-Anything 适合的是命令结构清楚、参数规则明确、主要工作是调用现有能力的工具典型如内部 API 客户端、运维脚本封装、CI 辅助命令。它不太适合高度交互式的终端应用比如那种要画全屏菜单的工具也不适合对性能极致敏感的超高频小命令——启动一个 Python 运行时毕竟有固定开销一次调用几十毫秒的性能敏感场景直接用 C 或 Go 写更合适。这也不算缺陷更准确的说是定位清晰。我做这个项目的初衷就是消灭重复的 CLI 脚手架让团队的内部工具收敛成一套统一交互风格这件事的收益远远大于那点运行时开销。最后分享一个踩过多次坑后沉淀下来的习惯manifest 一定要放进版本库并且从生成产物里反解出 manifest 的版本号。因为生成工具是分散部署的线上跑着的是老版本产物你改完 manifest 之后根本不知道哪台机器还跑着旧逻辑。给 manifest 加一个generated_from字段记录生成时的 git commit排查问题的时候能少掉一半头发。我实际维护中靠这个字段定位过至少三次因为改完没重新生成导致的诡异故障。CLI-Anything 本身终归是个工具真正让工具链变得可靠的是这一层工程纪律。