public

OpenCLI 深度调研

从 CLI 版 OpenAPI 的定位、生态进展、争议点到企业采用建议的完整研究笔记

OpenCLI 深度调研

研究日期：2026-03-26

一句话判断

OpenCLI 的方向很对：它试图把 CLI 的命令、参数、退出码和示例变成机器可读契约，让文档生成、自动化集成和 MCP bridge 有统一上游。

但截至 2026-03-26，它仍更像一个有明确势能的 draft，而不是已经定型的行业标准。

项目定位

OpenCLI 由 spectreconsole/open-cli 推进，定位是“CLI 的 OpenAPI”：

给 CLI 提供标准、语言无关的描述格式
让人和机器都能在不阅读源码的情况下理解 CLI 接口
为文档、客户端、补全、变更检测、MCP / agent bridge 提供统一输入

官方规范页列出的用途包括：

生成文档
生成客户端
生成自动化工具和 MCP server
检测 CLI API breaking changes
生成 shell completion

已知进展

2025-07-07：作者发布介绍文章 Introducing OpenCLI
2025-10-04：规范 changelog 仍在补 default values 等细节，说明 draft 仍在演进
2025-10-10：Spectre.Console.Cli 0.52.0 发布，加入 OpenCLI 导出能力
2026-02：社区讨论 steering group，希望吸引更多 CLI framework maintainer 参与治理

它为什么值得关注

把 CLI 从“只能给人看 help 文本”升级成“可被程序消费的契约层”
和 MCP 的连接非常自然：OpenCLI 很适合作为 tool schema 的上游描述
对多语言 CLI 团队特别有价值：可以把文档、门户、自动化、回归检测统一起来
对内部平台团队尤其友好：把一堆自建 CLI 做成可治理的产品接口

当前主要风险

1. 发现机制尚未收敛

社区仍在讨论到底应该怎样从一个 CLI 中稳定发现 OpenCLI 描述，例如 --help-opencli 还是版本化 flag。这个问题不解决，不同实现之间就很难真正互通。

相关讨论：https://github.com/spectreconsole/open-cli/discussions/46

2. 根命令建模还在争论

关于 Document 与 root command 的关系，讨论仍在继续。这个设计会直接影响解析器、生成器和兼容层的复杂度。

相关讨论：https://github.com/spectreconsole/open-cli/discussions/70

3. 类型系统边界未完全定稿

是否尽量贴近 JSON Schema，还是保留 CLI 特有类型（例如 file、directory），仍有明显分歧。这会影响跨语言工具链的一致性。

4. 生态开始萌芽，但还没完全兼容

Rust 已有 opencli crate，.NET 侧已有 OpenCLI → MCP 的尝试，oclif 社区也在讨论 plugin。积极信号很明显，但也意味着现在不同实现可能形成方言。

适合采用的场景

同时控制 producer 和 consumer 的内部平台团队
希望把 CLI 文档、MCP bridge、版本检测统一起来的研发基础设施团队
正在用 Spectre.Console.Cli 或愿意为现有 CLI 补导出层的团队

暂不建议重仓的场景

需要面向外部生态承诺长期兼容的公共标准接口
依赖多个第三方实现无缝互通、且不能接受方言风险的场景
对版本稳定性、治理成熟度要求很高的基础协议层

Reallier 的采用建议

我们更推荐把 OpenCLI 当成三层结构里的中间层：

CLI 本身是事实接口
OpenCLI 是机器可读描述层
MCP / 文档门户 / SDK / 自动补全是下游消费层

这种做法的好处是：

上游只维护一份契约
下游可以分别演进
即使 OpenCLI 后续调整，也能通过适配层控制风险

实施路径建议

第一步：盘点现有 CLI 命令面、参数命名和退出码
第二步：先为一个高价值 CLI 生成 OpenCLI 描述
第三步：把它接到文档生成和 breaking change 检测
第四步：再考虑 OpenCLI → MCP 的桥接自动化
第五步：最后再做跨团队推广

主要来源