给“CLI 的 OpenAPI”当第一个外部贡献者：一次 AI 协作的开源实践

先说人话：这个项目是什么

你让 AI 帮你干活的时候，它最后大概率要去敲命令行。问题是：命令行是写给人看的。--help 输出的是散文，AI 想知道”这个命令危不危险、会不会删东西、要不要先登录”，只能靠猜。

CLI Schema 想解决的就是这个：给命令行程序定一个开放的 JSON 描述规范。CLI 作者随程序发布一份 schema 文档，里面写清楚命令树、参数、默认值，以及最关键的安全语义——这个命令是不是破坏性的、需不需要人工确认、哪个参数是”跳过确认”（比如 --yes)、哪个是”空跑一遍看看”（比如 --dry-run)。AI agent 在执行之前就知道后果，而不是事后猜。

类比很直接：CLI 的 OpenAPI。OpenAPI 让机器理解 HTTP 接口，CLI Schema 让机器理解命令行。

有人一定会问：不是有 MCP 了吗？不冲突。MCP 是让 agent 调用新工具服务的协议；CLI Schema 是让 agent 理解现存几十万个 CLI 的描述格式——那些工具永远不会有人给它们包一层 MCP。

我为什么一头扎进去

我自己一直在做 AI agent 操作命令行相关的工具（比如用 pexpect 自动化交互式 CLI 的 skill)。“agent 猜参数”这个痛点是我每天撞墙的墙。六月底我在 GitHub 上瞎逛时发现了这个规范——当时它上线不到两个月，0 star、0 fork、只有作者一个贡献者。

但读完 spec 我判断它设计得很认真，举两个例子：

• 双发现机制。运行 mytool __schema 直接输出文档；或者在二进制旁边放一个 <binary>.cli-schema.json 文件。后者意味着不用启动进程就能读懂一个 CLI——对沙箱环境里跑的 agent 来说这是刚需。
• 安全语义是一等公民，不是事后补丁。destructive、requiresConfirmation、confirmationSkip、dryRun 都是规范里的正式字段。

规范本身是 CC0（公共领域），作者是 Elastic 官方 .NET 客户端的长期负责人 Martijn Laarman。东西好、没人用、作者靠谱——这就是值得下注的早期项目。

我用 AI 参与了哪些开发

我先后做了两块工作，都是和 AI（Claude）结对完成的：

1. Python SDK(cli-schema-typer)。 六月底我在规范仓库的 issue #6 里提议做 Python 集成，然后搭出了原型：给现有 Typer/Click 写的 CLI 加一个保留的 __schema 元命令，从框架元数据里自动导出命令树和参数。有个坑很快就露出来了：给只有一个命令的 Typer 应用加子命令会改变它的调用形状，所以 Typer 集成得用入口包装器拦截 mytool __schema，而不是真的注册子命令。

2. 给官方 JS SDK 补发现机制(PR #3)。 七月上旬作者自己建了 cli-schema-js 仓库，做了 Commander 集成——但它只能生成文档，CLI 本身没法被发现。我把 Python 侧踩过的坑平移过去，提交了 __schema 元命令的 argv 拦截实现和 sidecar 文件写入器，顺带把 README 里”注册隐藏子命令”的旧配方替换掉并说明了原因。

AI 在其中干的活：读 spec 全文、读对方代码、写实现和测试、跑构建和 lint、起草 issue 回复和 PR 描述、甚至后续的推广投稿。我干的活：所有需要判断力的决策——要不要押注这个项目、包怎么命名、PR 做哪个切口、什么时候不适合打扰作者。这个分工很顺：执行归 AI，品味归人。

和一位低频在线的作者打交道

这部分可能是对别的开源参与者最有用的经验。作者人很好、回复也热情，但他有自己的全职工作，上线频率很低——我的仓库转移请求挂在半空快两周了。

我学到的几条：

把请求压缩成对方的一次点击。 不要发”我们讨论一下治理结构吧”这种开放式问题，而是发”建一个空仓库 cli-schema/py 并把我设为 maintainer，或者我发起 transfer 你点接受——二选一，都是一次操作”。作者上线一次，就能解锁你所有的事。

不要让治理阻塞代码。 规范是 CC0 的，__schema 约定是公开的，我在自己账号下继续开发完全合规。org 托管只是品牌问题，代码先行，治理追上即可。

用作品换权限，而不是用请求。 想要 collaborator 权限，最好的方式是先交一个高质量的 PR。合 PR 的门槛远低于仓库治理操作，而且第一个 PR 落地后开口要权限，成功率完全不同。

作者的行动比他的话新。 我们在 issue 里约定仓库叫 cli-schema/typer，但他第二天建的是 cli-schema-js 单语言 monorepo——事实约定已经变了，跟着他最新的代码走，不要抱着旧的口头约定不放。

现状：值得参与，但别当成熟工具

诚实地说：这还是 Draft 阶段的规范，v1 没冻结，可能有破坏性变更；整个项目 0 star，JS SDK 刚有第一个外部 PR（我的）。命令行描述规范这条路是有坟场的——Fig 的 autocomplete spec 被亚马逊收购后消亡，是最近的前车之鉴。

但规范类项目的冷启动就是这样：llms.txt 刚提出时同样零采用，靠的是早期相信它的人把它推过临界点。如果你也做 AI agent 相关的开发，觉得这个方向值得存在，现在参与进去的边际影响最大——规范还没定型，一个外部贡献者的声音此时最有分量。

• 规范与官网：github.com/cli-schema/cli-schema · cli-schema.org
• 官方 JS SDK:github.com/cli-schema/cli-schema-js
• 我的 PR:cli-schema-js#3（发现机制）
• 起点：issue #6(Python SDK 提案）