agent-aware-cli

面向 Agent 的 CLI 设计指南

在构建或改进命令行界面（CLI）时，请遵循这些架构和设计最佳实践，确保它既能服务于人类操作员（提供丰富的 TUI），也能服务于 AI Agent（提供确定性、机器可读的输出）。

核心原则

1. 双重体验范式（DX 和 AX） 此 CLI 必须设计为“双模式”界面，将人类和 AI Agent 都视为一等用户。

   • DX（开发者体验）：面向人工操作人员的人体工学设计。强调易发现性、丰富的 TUI（例如 Bubbletea、Lipgloss）、语义化着色和直观的别名。
   • AX（Agent 体验）：面向自主 AI Agent 的人体工学设计。强调确定性、严格的机器可读输出模式（例如 --json）、无头身份验证、积极的数据范围控制（限制／过滤），以及变更安全性（--dry-run）。
   • 环境变量覆盖：遵循 NO_COLOR 和 [APP]_NO_TUI 环境变量，自动回退到非交互、无样式模式。

2. 支持无头环境的身份验证

   • Agent 无法完成交互式的浏览器 OAuth 流程。CLI 必须支持无头身份验证方式（服务账号、通过 ENV 变量传入 API 密钥、--token 标志），或者立即失败，并提供清晰、机器可读的错误，指示人工操作人员先手动完成身份验证。

3. 合理的默认值和积极过滤

   • 切勿向 stdout 输出未分页或未经筛选的列表。默认采用合理的限制（例如，前 10 个项目）。提供丰富的过滤标志（例如 --status、--mine、--limit），以便 Agent 精确查询所需内容，避免耗尽其令牌上下文。

4. 变更安全性（--dry-run）

   • 对于会创建、更新或删除外部状态的命令，请实现 --dry-run 标志。这样自主 Agent 就能在执行破坏性操作前测试参数映射，并在本地验证生成的载荷。

5. 保护上下文窗口

   • Agent 的上下文窗口有限。主动截断大块文本，将关键操作项排在前面，并默认屏蔽原始凭据，以防凭据泄露。
   • 提供可选的详细输出（例如 --full 或 --verbose），供明确请求未经筛选数据的 Agent 或人类使用。

6. 可执行的主动错误提示

   • 不要只报告失败，还要提供准确的修复步骤。
   • 在 stderr 中插入可直接复制粘贴的终端命令（例如：Hint: run 'app init' to create a database）。这样自主 Agent 就能解析错误并顺畅地自行纠正。

7. 委托状态管理

   • 编排复杂工作流时，避免在 CLI 内维护长期运行的状态循环。
   • 使用无状态任务标识符模式（--task <ID>、--ref <ID>）。将 ID 传回后端服务，由后端维护令牌上下文窗口和对话历史。

8. 外置 Agent 指令

   • 在仓库根目录添加 AGENTS.md 或 GEMINI.md 文件，说明供 AI 开发者使用的工具用法、工作流和规范。
   • 提供符合 agentskills.io 规范的 skills/ 目录，其中包含用于复杂子命令的 SKILL.md 文件。

9. API 发现与渐进式易用性

   • 基于大型 Google/REST API 构建 CLI 时，分析其发现文档（例如 https://youtube.googleapis.com/$discovery/rest?version=v3），以了解资源、方法、查询参数和必需 OAuth 范围的准确且严格的映射关系。
   • 考虑直接根据发现文档自动生成基础命令，以确保覆盖 100% 的 API。
   • 不过，原始 REST 映射对人类来说往往不够易用。必须在原始生成的命令之上添加“便捷封装”或“提示”。例如，用户请求“列出某个用户的视频”时，CLI 应能智能地抽象掉需要两次 API 调用的事实（一次将句柄解析为频道 ID，另一次获取播放列表），并通过单个 channel videos @user 命令完成操作。

使用 Go（Cobra 和 Viper）实现

在 Go 中实现 CLI 时，使用 Cobra 进行命令路由，使用 Viper 管理配置。

Cobra 实践

• 结构化的可发现性：使用 Cobra 的 GroupID 对命令进行分类（例如 Task Management、Information），避免根帮助输出变成“文字墙”。
• 文档的三大支柱：为每个命令填写以下字段：
  • Short：5 到 10 个词的摘要，以动作动词开头，便于快速浏览。
  • Long：详细说明它的功能、用途，以及与其他命令的区别。
  • Example：提供 3 到 5 个具体、可复制粘贴的示例，展示常见的标志组合。
• 快速失败钩子：在执行繁重逻辑之前，通过 PersistentPreRun 钩子验证配置和连接状态。

Viper 与配置实践

• 遵循 XDG 规范：按照 XDG Base Directory Specification 存放配置文件（例如 ~/.config/app/config.yaml）。
• 智能回退优先级：使用 Viper 确保值按以下一致顺序解析： Command Line Flag > Environment Variable > Config File > Default Value
• 密钥管理：绝不让 API 密钥泄露到 Shell 历史记录中。密钥优先使用环境变量，而不是 CLI 标志。

视觉信息设计（面向人类）

优化 CLI 的可读性时，可借鉴 Tufte 风格的原则，尽量降低认知负担：

• 最大化数据墨水比：尽量减少装饰性边框等非必要“墨水”。使用留白和位置作为传达层级的主要手段。
• 可靠的 UI 格式化：应用终端样式（例如使用 lipgloss）之前，务必先对原始字符串应用填充和宽度限制。否则，不可见的 ANSI 转义码可能会破坏 fmt.Printf 表格的对齐。
• ANSI 对齐陷阱：在 Go 中构建 TUI 表格时，如果传入包含不可见 ANSI 颜色码的字符串，text/tabwriter 或 fmt.Printf 等原生工具会导致对齐错乱。必须先将字符串填充到固定宽度，再应用颜色包装器；也可以使用 lipgloss.Table 之类的稳健布局引擎。
• 语义化颜色标记：使用具有明确功能的颜色，而不是仅具审美效果的颜色：
  • Accent（蓝色）：导航标记、标题、分组标题。
  • Command（灰色／浅灰色）：命令名称和标志等扫描目标。
  • Pass（绿色）：成功状态和已完成的任务。
  • Warn（橙色／黄色）：临时或待处理状态、警告。
  • Fail（红色）：错误和被拒绝的状态。
  • Muted（深灰色）：弱化元数据、类型或默认值。
  • ID（青绿色／薄荷绿）：唯一标识符。
• 颜色降级：确保将输出管道传入文件、调用 --json 或存在 NO_COLOR 时，颜色都能平稳降级。

Agent 的强制实施清单

生成或更新 CLI 命令时，MUST 确保在首次提交中实现以下所有内容。不要把 UI/UX 当作事后才考虑的事情：

• 双重体验（DX/AX）：命令是否支持 --json 标志，或遵循 NO_COLOR/[APP]_NO_TUI？
• 无头身份验证：Agent 能否自主运行此命令，而不会卡在基于浏览器的 OAuth 提示上？
• 数据范围控制：如果返回列表，是否设置了合理的默认限制和筛选标志（例如 --limit、--status）？
• 变更安全性：如果命令会更改状态，是否包含 --dry-run 标志以保障 Agent 安全？
• 错误提示：错误是否会向 stderr 输出可执行、可复制粘贴的终端命令？
• XDG 合规性：配置是否通过 XDG 基础目录规范处理（例如 ~/.config/app/config.yaml），而不是使用本地 .env 文件？
• 三大要素：Cobra 命令定义中的 Short、Long 和 Example 字段是否都已完整填写？
• 易发现性：命令是否已分配到合理的 GroupID？
• 语义化颜色：面向用户的输出是否使用语义颜色令牌（例如 Lipgloss）进行格式化？
• 对齐安全性：如果在表格中使用原始 ANSI 颜色，是否在添加颜色代码前应用字符串填充，以防止对齐错乱？
• 帮助格式：是否重写了 Cobra 默认的 SetUsageTemplate，以便为帮助输出本身应用语义颜色（例如将标题设为蓝色）？