AI 原生命令行界面

ai-native-cli
分类编程
作者Agentic Awesome Skills 社区
许可MIT
评分4.90/5
使用3.9K

Agent 友好型 CLI 规范 v0.1

在构建或修改 CLI 工具时，请遵循以下规则，以确保 AI Agent 能够安全且可靠地使用。

概述

这是一套构建 AI 原生 CLI 工具的全面设计规范。它定义了分布在三个认证级别（Agent-Friendly, Agent-Ready, Agent-Native）中的 98 条规则，并根据优先级（P0/P1/P2）进行了划分。该规范涵盖了结构化 JSON 输出、错误处理、输入契约、安全护栏、退出码、自描述，以及通过内置 issue 系统实现的反馈循环。

适用场景

  • 构建 AI Agent 将要调用的新 CLI 工具时
  • 将现有 CLI 重构为 Agent 友好型时
  • 为自动化流水线设计命令行界面时
  • 审计 CLI 工具是否符合 Agent 安全标准时

核心哲学

1. Agent 优先 —— 默认输出为 JSON；人类友好模式需通过 --human 开启
2. 不信任 Agent —— 对所有输入的验证级别应等同于公共 API
3. 故障闭锁 (Fail-Closed) —— 当验证逻辑本身出错时，默认拒绝执行
4. 可验证性 —— 每条规则的编写方式都必须支持自动化检查

分层模型

本规范采用两个正交轴线：

  • 层级 (Layer) 决定部署范围：core (核心), recommended (推荐), ecosystem (生态)
  • 优先级 (Priority) 决定严重程度：P0, P1, P2

层级用于迁移和认证：

  • core —— 执行契约：JSON、错误、退出码、stdout/stderr、安全性
  • recommended —— 更好的机器 UX：自描述、显式模式、更丰富的 Schema
  • ecosystem —— Agent 原生集成：agent/ 目录、skills、issue、内联上下文

认证级别与层级对应关系：

  • Agent-Friendly —— 通过所有 core 规则
  • Agent-Ready —— 通过所有 core + recommended 规则
  • Agent-Native —— 通过所有层级的规则

工作原理

第一步：输出模式

默认模式为 Agent 模式 (JSON)。使用显式标志进行切换：

bash
$ mycli list              # 默认 = JSON 输出 (Agent 模式)
$ mycli list --human      # 人类友好：带颜色、表格、格式化
$ mycli list --agent      # 显式 Agent 模式 (必要时覆盖配置)
  • 默认 (无标志) —— 向 stdout 输出 JSON。Agent 无需添加任何标志。
  • --human —— 人类友好格式（颜色、表格、进度条）。
  • --agent —— 显式 JSON 模式（当环境/配置覆盖了默认设置时很有用）。

第二步：agent/ 目录约定

每个 CLI 工具必须在项目根目录下拥有一个 agent/ 目录。这是该工具面向 AI Agent 的身份标识和行为契约。

code
agent/
  brief.md          # 一段话简介：我是谁，我能做什么
  rules/            # 行为约束 (自动注册)
    trigger.md      # Agent 何时应使用此工具
    workflow.md     # 分步使用流程
    writeback.md    # 如何写回反馈
  skills/           # 扩展能力 (自动注册)
    getting-started.md

第三步：四个级别的自描述

1. --brief (名片，注入到 Agent 配置中)
2. 每条命令的响应 (始终开启的上下文：数据 + 规则 + 技能 + issue)
3. --help (完整的自描述：简介 + 命令...)
(需求 + 规则 + 技能 + 问题)
4. skills \<name\> (针对特定技能的按需深度解析)

认证要求

每个级别包含之前所有级别的规则。
优先级标签：[P0] = 缺失则 Agent 崩溃，[P1] = Agent 可运行但效果差，[P2] = 锦上添花。

Level 1: Agent-Friendly (核心 -- 20 条规则)

目标：CLI 是一个稳定、可调用的 API。Agent 可以调用、解析并处理错误。

输出 (Output) -- 默认为 JSON，模式稳定

  • [P0] O1: 默认输出为 JSON，无需 --json 标志

  • [P0] O2: JSON 必须通过 jq . 验证

  • [P0] O3: 同一版本内 JSON schema 严禁变更

错误 (Error) -- 结构化，输出至 stderr，绝非交互式

  • [P0] E1: 错误 $\rightarrow$ {"error":true, "code":"...", "message":"...", "suggestion":"..."} 输出至 stderr

  • [P0] E4: 错误包含机器可读的 code (例如 MISSING_REQUIRED)

  • [P0] E5: 错误包含人类可读的 message

  • [P0] E7: 发生错误时，绝不能进入交互模式 $\rightarrow$ 立即退出

  • [P0] E8: 错误代码即 API 契约 $\rightarrow$ 跨版本严禁重命名

退出码 (Exit Code) -- 可预测的失败信号

  • [P0] X3: 参数/用法错误必须退出码为 2

  • [P0] X9: 失败必须返回非零退出码 $\rightarrow$ 绝不能在 stdout 报告错误的同时返回 0

可组合性 (Composability) -- 干净的管道语义

  • [P0] C1: stdout 仅用于数据

  • [P0] C2: 日志、进度、警告仅输出至 stderr

输入 (Input) -- 坏输入快速失败

  • [P1] I4: 缺失必要参数 $\rightarrow$ 结构化错误，绝无交互式提示

  • [P1] I5: 类型不匹配 $\rightarrow$ 退出码 2 + 结构化错误

安全性 (Safety) -- 防止 Agent 误操作

  • [P1] S1: 破坏性操作需要 --yes 确认

  • [P1] S4: 拒绝 ../../ 路径遍历和控制字符

护栏 (Guardrails) -- 运行时输入保护

  • [P1] G1: 拒绝未知标志，退出码 2

  • [P1] G2: 检测参数中的 API 密钥/令牌模式并拒绝执行

  • [P1] G3: 拒绝敏感文件路径 (*.env, *.key, *.pem)

  • [P1] G8: 拒绝参数中的 Shell 元字符 (; | && $())

Level 2: Agent-Ready (推荐 -- 59 条规则)

目标：CLI 具有自描述性、命名规范且对管道友好。Agent 能发现能力并链式调用命令，无需试错。

自描述 (Self-Description) -- Agent 发现 CLI 能做什么

  • [P1] D1: --help 输出包含 commands[] 的结构化 JSON

  • [P1] D3: Schema 包含必要字段 (help, commands)

  • [P1] D4: 所有参数均有类型声明

  • [P1] D7: 参数标注为必填/可选

  • [P1] D9: 每个命令均有描述

  • [P1] D11: --help 输出包含 help, rules, skills, commands 的 JSON

  • [P1] D15: --brief 输出 agent/brief.md 内容

  • [P1] D16: 默认 JSON (Agent 模式)，--human 用于人类友好模式

  • [P2] D2/D5/D6/D8/D10: 单个命令帮助、枚举、默认值、输出 schema、版本

输入 (Input) -- 无歧义的调用约定

  • [P1] I1: 所有标志使用 --long-name 格式

  • [P1] I2: 无位置参数歧义

  • [P2] I3/I6/I7: --json-input，布尔值 --no-X，数组参数

错误 (Error)

  • [P1] E6: 错误包含 suggestion 字段

  • [P2] E2/E3: 错误输出至 stderr，错误 JSON 有效

安全性 (Safety)

  • [P1] S8: 针对外部输入的 --sanitize 标志

  • [P2] S2/S3/S5/S6/S7: 默认拒绝、--dry-run、无自动更新、破坏性标记

退出码 (Exit Code)

  • [P1] X1: 0 = 成功

  • [P2] X2/X4-X8: 1=通用错误, 10=认证, 11=权限, 20=未找到, 30=冲突

可组合性 (Composability)

  • [P1] C6: 管道模式下无交互式提示

  • [P2] C3/C4/C5/C7: 管道友好, --quiet, 管道 ch

主干，幂等性

命名 -- 可预测的标志（flag）约定

  • [P1] N4：保留标志 (--agent, --human, --brief, --help, --version, --yes, --dry-run, --quiet, --fields)

  • [P2] N1/N2/N3/N5/N6：命名一致，使用 kebab-case，最多 3 层，--version 遵循 semver 语义化版本

护栏 (Guardrails)

  • [P1] I8/I9：无隐式状态，非交互式认证

  • [P1] G6/G9：前置条件检查，故障闭锁 (fail-closed)

  • [P2] G4/G5/G7：权限分级，PII 脱敏，批处理限制

#### 保留标志

| 标志 | 语义 | 备注 |
|------|-----------|-------|
| --agent | JSON 输出 (默认) | 显式覆盖 |
| --human | 易读输出 | 包含颜色、表格、格式化 |
| --brief | 单段身份描述 | 用于同步至 agent 配置 |
| --help | 完整的自描述 JSON | 包含 brief + 命令 + 规则 + 技能 + issue |
| --version | Semver 版本字符串 | |
| --yes | 确认破坏性操作 | 删除/销毁操作必填 |
| --dry-run | 预览而不执行 | |
| --quiet | 抑制 stderr 输出 | |
| --fields | 过滤输出字段 | 节省 token |

第 3 级：Agent 原生 (+ 生态系统 -- 19 条规则)

目标：CLI 具备身份、行为契约、技能系统和反馈闭环。Agent 可以学习该工具，扩展其用途并报告问题 —— 实现完整的闭环协作。

Agent 目录 -- 工具身份与行为契约

  • [P1] D12：存在 agent/brief.md

  • [P1] D13：agent/rules/ 包含 trigger.md, workflow.md, writeback.md

  • [P1] D17：agent/rules/*.md 包含 YAML frontmatter (name, description)

  • [P1] D18：agent/skills/*.md 包含 YAML frontmatter (name, description)

  • [P2] D14：agent/skills/ 目录 + skills 子命令

响应结构 -- 每次调用均包含内联上下文

  • [P1] R1：每个响应包含 rules[] (来自 agent/rules/ 的全部内容)

  • [P1] R2：每个响应包含 skills[] (名称 + 描述 + 命令)

  • [P1] R3：每个响应包含 issue (反馈指南)

元数据 (Meta) -- 项目级集成

  • [P2] M1：项目根目录包含 AGENTS.md

  • [P2] M2：可选的 MCP 工具 schema 导出

  • [P2] M3：CHANGELOG.md 标记破坏性变更

反馈 -- 内置 issue 系统

  • [P2] F1：issue 子命令 (create/list/show)

  • [P2] F2：结构化提交，包含 version/context/exit_code

  • [P2] F3：分类：bug / requirement / suggestion / bad-output

  • [P2] F4：Issue 本地存储，不依赖外部服务

  • [P2] F5：issue list / issue show <id> 可查询

  • [P2] F6：Issue 具有状态追踪 (open/in-progress/resolved/closed)

  • [P2] F7：Issue JSON 包含所有必填字段 (id, type, status, message, created_at, updated_at)

  • [P2] F8：所有 Issue 均有 status 字段

示例

示例 1：JSON 输出 (Agent 模式)

bash
$ mycli list
{"result": [{"id": 1, "title": "Buy milk", "status": "todo"}], "rules": [...], "skills": [...], "issue": "..."}

示例 2：结构化错误

json
{
  "error": true,
  "code": "AUTH_EXPIRED",
  "message": "Access token expired 2 hours ago",
  "suggestion": "Run 'mycli auth refresh' to get a new token"
}

示例 3：退出码表

code
0   success         10  auth failed       20  resource not found
1   general error   11  permission denied 30  conflict/precondition
2   param/usage error

快速实现清单

按层级实现 —— 每个阶段完成后即可获得下一级认证。

阶段 1：Agent 友好 (核心)
1. 默认输出为 JSON —— 无需 --json 标志
2. 错误处理器：{ error, code, mes
sage, suggestion } 到 stderr
3. 退出码：0 成功，2 参数错误，1 通用错误
4. stdout = 仅数据，stderr = 仅日志
5. 参数缺失 $\rightarrow$ 结构化错误（绝不进入交互模式）
6. 破坏性操作需使用 --yes 保护
7. 安全护栏：拒绝密钥、路径遍历、Shell 元字符

第二阶段：Agent 适配（推荐）
8. --help 返回结构化 JSON（help, commands[], rules[], skills[]）
9. --brief 读取并输出 agent/brief.md 内容
10. --human 标志切换至人类友好格式
11. 保留标志：--agent, --version, --dry-run, --quiet, --fields
12. 退出码：20 未找到，30 冲突，10 认证失败，11 权限不足

第三阶段：Agent 原生（+ 生态）
13. 创建 agent/ 目录：brief.md, rules/trigger.md, rules/workflow.md, rules/writeback.md
14. 每个命令响应均附加：rules[] + skills[] + issue
15. skills 子命令：列出所有 / 显示单个完整内容
16. issue 子命令用于反馈（创建/列出/显示/关闭/状态转移）
17. 项目根目录放置 AGENTS.md

最佳实践

  • 建议： 默认使用 JSON 输出，使 Agent 无需添加标志
  • 建议： 在每个错误响应中包含 suggestion 字段
  • 建议： 使用三级认证模型进行渐进式采用
  • 建议： 将 agent/brief.md 限制在一段以内，以提高 Token 效率
  • 避免： 错误时进入交互模式 —— 应当立即退出
  • 避免： 在同一版本内更改 JSON 架构或错误码
  • 避免： 将日志或进度信息输出到 stdout —— 仅使用 stderr
  • 避免： 静默接受未知标志 —— 应以退出码 2 拒绝

常见陷阱

  • 问题： CLI 默认输出人类可读文本，导致 Agent 解析失败
解决方案： 将 JSON 设为默认输出格式；为人类友好模式添加 --human 标志
  • 问题： 错误通过 stdout 报告且退出码为 0
解决方案： 失败时始终返回非零退出码，并将结构化错误 JSON 写入 stderr
  • 问题： CLI 在输入缺失时进行交互式提示
解决方案： 返回带有 suggestion 字段的结构化错误并立即退出

相关技能

  • @cli-best-practices - 通用 CLI 设计模式（本技能专注于 AI Agent 兼容性）

附加资源

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出视为环境特定验证、测试或专家评审的替代方案。
  • 如果缺失必要输入、权限、安全边界或成功标准，请停止并请求澄清。