cli-builder

CLI 构建器

将 CLI 视为工具与 Agent 之间的契约。契约包括命令名称、--help、标志、输出架构、退出代码、stderr 和预览。将此文件作为工作流；仅在需要专门指导时加载链接的参考资料。

适用场景

• 构建一个供 Agent 发现和调用的新 CLI。
• 重构提示词、含糊的命令、不利于解析器处理的输出或错误的成功代码。
• 添加或审查 --json、--dry-run、--yes、幂等性或延迟身份验证。

工作流

1. 发现真实契约

为每项服务定义一个 CLI（共享供应商身份验证的服务除外）。在编写代码前检查真实的非健康检查读取端点，验证实际的身份验证标头和响应形状，并记录命令树和失败场景。不要仅根据 API 文档臆造标志。对于 HTTP 客户端，请阅读Python API 客户端模式。

本地封装和文件系统流水线请选择 Bash。涉及 HTTP、JSON、身份验证状态或三级命令树时请选择 Python。

2. 构建可预测的界面

采用统一的动词／资源命名约定。每条命令都应为非交互式、由标志驱动、拒绝未知标志，并提供包含具体示例的实用子命令帮助。常规输出应便于人阅读，同时支持 --json，提供稳定且经过整理的架构、规范化类型、确定性排序，并且不向 stdout 输出其他内容。诊断信息发送到 stderr，并返回真实准确的非零退出代码。

对于任何状态变更，都应在获取数据或执行变更前实现 --dry-run，并要求通过明确的 --yes／--force 门槛授权破坏性操作。对创建、更新和删除操作进行防护，确保重复运行安全。身份验证必须延迟执行：没有凭据时，--help 和安全的试运行也应正常工作。

对于链式试运行、第三方 JSON、依赖版本的行为和文本匹配，请使用高级模式。如果本地 Shell 封装更合适，请使用 Bash 脚手架。

3. 验证契约

运行语法检查、每条命令的 --help，解析每个 --json 响应，检查缺失参数和未知标志，确认错误信息输出到 stderr，在没有凭据时执行试运行，并证明第二次相同的运行不会产生任何操作。针对在线服务，测试一次真实的身份验证读取，并对每项变更执行试运行。使用 Agent 就绪检查清单进行最终审查。

4. 封装和维护

保持入口技能简洁，并将条件性细节放入参考资料。封装应说明 CLI 的用途、设置方式、常用命令、输出含义和注意事项，而不是重复列出每个标志。请参阅技能封装示例。实际使用后，记录失败情况，并使用改进周期确定修复优先级。

核心契约

• --help 是可发现的架构，并包含示例。
• --json 仅在 stdout 上输出可解析内容；错误具有稳定的机器可读代码。
• --dry-run 描述确切的预期变更，且不执行写入或前置条件查询。
• 变更操作需经明确授权、具备幂等性，并报告有意义的状态。
• 退出状态应区分成功、用法错误和运行时错误。

不适用场景

不要将此技能用于一次性的交互式人工命令、GUI／TUI 或 Web UI 设计、对话式 Agent 工具或 MCP 服务。有关工具边界的选择，请阅读 MCP 与 CLI 决策指南；常规 API 契约设计请转至 api-design-and-evolution。

References

• Python API client
• Advanced patterns
• Agent-readiness checklist
• Skill wrapper example
• MCP vs CLI
• Improvement cycle
• Bash scaffold