agentic-cli-design

Agent CLI 设计

概述

Agent CLI 设计是一种设计理念：不把 CLI 视为“供人们在终端中操作的工具”，而是将其视为 大模型/Agent 可以安全、可靠、可重复调用的协议/API。

成功标准是，Agent 能够操作 CLI：

• 不会困惑（选项明确）
• 不会造成破坏（默认安全）
• 不会陷入停滞（非交互，并采用超时/重试策略）
• 能够重复操作（幂等，允许重新执行）
• 能够自我修复（可观测，可自我描述）

本技能提供了一个全面的框架，用于设计和评估供 Agent 使用的 CLI 工具。

核心定义

Agent CLI 设计 = 使 CLI 能够在非交互、重复、易出错的环境中安全、可靠地执行命令的设计原则。

我们不再针对人的“使用感受”进行优化，而是针对 机器的读取、决策、重新执行和恢复能力进行优化。

7 项原则

P1. 机器可读（主要输出格式）

机器可读的输出是主要接口，而非人类可读的文本。

• 提供 --json / --output json|yaml|text，作为一等选项
• 严格分离：stdout=结果 / stderr=日志与进度（绝不混用）
• 错误也应采用结构化格式（优先使用 JSON）
• 保持架构稳定（通过 schemaVersion 管理不兼容变更）

适用场景：每条 CLI 命令都应支持结构化输出。

P2. 默认非交互

交互式提示不应是默认行为。

• 不要假定存在交互式提示
• 提供 --yes / --force / --no-confirm / --non-interactive 标志
• 必须能够在无 TTY 的环境（CI、作业运行器）中成功完成

适用场景：任何可能提示用户输入的命令。

P3. 幂等且可重放

同一命令重复运行时，应安全且结果一致。

• 发送/创建操作接受 dedupe-key / client-request-id
• “已存在”行为可配置：--if-exists skip|update|error
• 检索使用显式分页：--limit --cursor --all

适用场景：任何写入操作或数据检索命令。

P4. 默认安全

破坏性操作需要明确确认。

• 破坏性操作支持 --dry-run / --confirm <id>
• 删除操作需要 --force 或类似选项（默认防止意外操作）
• 将权限/作用域降至最低；权限不足时返回“后续步骤”

适用场景：任何修改或删除数据的命令。

P5. 可观测且可调试

操作必须可追踪、可调试。

• 提供 --verbose / --debug / --log-format json
• 接受 --trace-id 作为关联 ID
• 退出码应分类，以支持自动恢复：
  • 0：成功
  • 2：参数无效
  • 3：身份验证/权限问题
  • 4：可重试（速率限制、暂时性错误）

适用场景：所有命令都应支持可观测性标志。

P6. 高效利用上下文

尽量减少大模型 Agent 的 Token/上下文消耗。

• --fields/--select（投影）
• --output ndjson（流式输出）
• 默认返回摘要；通过 get/--include-* 显式获取详情
• 提供丰富的服务端过滤功能（since/until/query/type...）

适用场景：返回大型数据集或详细信息的命令。

P7. 可自省（自描述 CLI）

CLI 本身可以以机器可读格式输出其规范。

MCP 工具具有架构定义，但 CLI 往往是黑箱。解决方案：由 CLI 输出自身规范。

• commands --json（列出命令和参数）
• schema --command ... --output json-schema（每个命令的 JSON Schema）
• --help --json（示例、退出代码、错误词汇表）
• install-skills（从 <project dir>/skills 输出／安装 CLI 自身的 Agent 技能）
• --output json 顶层固定字段：
  • schemaVersion、type、ok

建议的 install-skills 行为：

• 安装 CLI 自身的用法技能，而非任意第三方技能
• 从 <project dir>/skills 读取技能源文件
• 默认目标目录：./.agents/skills
• install-skills --global：~/.agents/skills
• install-skills --claude：./.claude/skills
• install-skills --claude --global：~/.claude/skills

适用场景：需要让 Agent 能够发现并自行理解文档的 CLI。

参考文档

此技能包含按主题整理的详细参考资料：

references/principles.md

详细说明 7 项原则，包含具体示例、实现指导和最佳实践。

适用场景：需要深入理解特定原则或查看实现示例时。

references/scorecard.md

用于根据 7 项原则审查 CLI 设计的完整检查清单。每项原则都有具体的评估复选框。

适用场景：审查现有 CLI 是否便于 Agent 使用，或验证新的 CLI 设计时。

references/templates.md

以下内容的具体模板：

• JSON 响应格式（成功／失败）
• 退出代码约定
• 自省命令模式
• 身份验证状态响应

适用场景：实现 JSON 输出、错误处理或自描述等具体功能时。

references/anti-patterns.md

破坏 Agent 兼容性的常见失败模式，包括：

• 混用 stdout/stderr
• JSON Schema 不一致
• 默认采用交互式行为
• 不安全的破坏性操作
• 上下文膨胀
• 仅支持浏览器的身份验证

适用场景：排查 Agent 故障或避免常见陷阱时。

快速入门

设计新的 CLI

1. 查看上文的 7 项原则
2. 使用 references/scorecard.md 作为设计检查清单
3. 采用 references/templates.md 中的模式进行实现
4. 避免 references/anti-patterns.md 中的模式

审查现有 CLI

1. 根据 references/scorecard.md 逐项检查
2. 找出原则覆盖方面的不足
3. 查看 references/anti-patterns.md 中列出的现存问题
4. 根据 Agent 使用场景确定修复优先级

创建 Agent 技能

为 CLI 工具创建 Agent 技能时，请包含：

• 特定任务的操作指南（最精简的命令序列）
• 安全护栏（试运行 → 确认 → 执行模式）
• 输入／输出类型（典型的成功／失败 JSON）
• 错误恢复流程（速率限制、auth_required 等）
• 推荐的默认选项（--json/--non-interactive/--limit）
• install-skills 流程，让 CLI 能从 <project dir>/skills 安装自身技能

身份验证注意事项

对于 OAuth／无头身份验证：

• 首选 设备授权授权（RFC 8628）
• 提供 auth status --json，供 Agent 检查前提条件
• 支持 auth export / auth import，用于无头环境迁移
• 在 --non-interactive 模式下：返回错误和后续步骤（不要提示用户）

身份验证响应格式请参阅 references/templates.md。

为你的 CLI 评分

每项原则可评为 0／1／2 分，便于比较：

• 0：未实现
• 1：部分实现
• 2：完全实现

最高分：14 分（2 分 × 7 项原则）

详细评分标准请参阅 references/scorecard.md。

相关概念

• MCP（模型上下文协议）：提供带有架构的工具定义；Agentic CLI Design 让独立 CLI 同样易于发现
• Agent Skills：文档层，用于教会 Agent 安全使用 CLI 的模式
• 基础设施即代码：遵循幂等性和声明式原则
• 12-Factor Apps：遵循配置和可观测性原则

实际示例

体现这些原则的优秀 CLI：

• GitHub CLI（gh）：出色的 --json 支持和非交互式标志
• kubectl：强大的幂等性、声明式 apply 和 dry-run 支持
• AWS CLI：全面的 --output json、分页和筛选功能

何时使用此技能

在以下情况下使用此技能：

1. 设计新的 CLI，用于 Agent／自动化
2. 改进现有 CLI，使其更适合 Agent 使用
3. 为 CLI 工具创建 Agent Skill
4. 调试 Agent 使用 CLI 工具时的故障
5. 审查 CLI 设计，确保其可用于生产环境
6. 为 Agent 工作流选择 CLI 工具

何时不应使用此技能

以下情况使用此技能可能有些大材小用：

• 个人使用的一次性脚本
• 仅供人类交互使用的 CLI
• 不打算用于生产环境的原型
• 工作流本身具有交互性的工具（文本编辑器、REPL）

延伸阅读

• references/principles.md - 深入了解各项原则
• references/scorecard.md - 评估清单
• references/templates.md - 实现模板
• references/anti-patterns.md - 应避免的做法