---

name: ai-native-cli description: "包含 98 条规则的设计规范，用于构建 AI 智能体可安全使用的 CLI 工具。涵盖结构化 JSON 输出、错误处理、输入契约、安全护栏、退出码和智能体自描述。" risk: safe source: https://github.com/ChaosRealmsAI/agent-cli-spec date_added: "2026-03-15"

智能体友好 CLI 规范 v0.1

构建或修改 CLI 工具时，遵循这些规则使其对 AI 智能体安全可靠。

概述

一个全面的设计规范，用于构建 AI 原生 CLI 工具。定义了跨三个认证级别（智能体友好、智能体就绪、智能体原生）的 98 条规则，带优先级要求（P0/P1/P2）。规范涵盖结构化 JSON 输出、错误处理、输入契约、安全护栏、退出码、自描述和通过内置 issue 系统的反馈循环。

何时使用此技能

• 构建 AI 智能体将调用的新 CLI 工具时
• 改造现有 CLI 使其对智能体友好时
• 为自动化管道设计命令行接口时
• 审计 CLI 工具是否符合智能体安全标准时

核心理念

1. 智能体优先 -- 默认输出是 JSON；人类友好格式通过 --human 选择加入
2. 智能体不可信 -- 以与公共 API 相同的级别验证所有输入
3. 失败即关闭 -- 当验证逻辑本身出错时，默认拒绝
4. 可验证 -- 每条规则都可以被自动检查

层级模型

此规范使用两个正交轴：

• 层级回答部署范围：core、recommended、ecosystem
• 优先级回答严重性：P0、P1、P2

认证映射到层级：

• 智能体友好 -- 所有 core 规则通过
• 智能体就绪 -- 所有 core + recommended 规则通过
• 智能体原生 -- 所有层级通过

工作原理

步骤 1：输出模式

默认是智能体模式（JSON）。显式标志切换：

$ mycli list              # 默认 = JSON 输出（智能体模式）
$ mycli list --human      # 人类友好：彩色、表格、格式化
$ mycli list --agent      # 显式智能体模式（需要时覆盖配置）

• 默认（无标志） -- JSON 到 stdout。智能体永远不需要添加标志。
• --human -- 人类友好格式（颜色、表格、进度条）
• --agent -- 显式 JSON 模式（当环境/配置覆盖默认时有用）

步骤 2：agent/ 目录约定

每个 CLI 工具必须在项目根目录有一个 agent/ 目录。这是工具对 AI 智能体的身份和行为契约。

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

步骤 3：四级自描述

1. --brief（名片，注入智能体配置）
2. 每个命令响应（始终在线上下文：数据 + 规则 + 技能 + issue）
3. --help（完整自描述：brief + 命令 + 规则 + 技能 + issue）
4. skills <name>（按需深入特定技能）

认证要求

每个级别包含前一级别的所有规则。 优先级标签 [P0]=没有它智能体会崩溃，[P1]=智能体能工作但体验差，[P2]=锦上添花。

级别 1：智能体友好（core -- 20 条规则）

目标：CLI 是稳定的可调用 API。智能体可以调用、解析和处理错误。

输出 -- 默认是 JSON，稳定 schema

• [P0] O1：默认输出是 JSON。不需要 --json 标志
• [P0] O2：JSON 必须通过 jq . 验证
• [P0] O3：JSON schema 在同一版本内不得更改

错误 -- 结构化，到 stderr，永不交互

• [P0] E1：错误 -> {"error":true, "code":"...", "message":"...", "suggestion":"..."} 到 stderr
• [P0] E4：错误有机器可读的 code（如 MISSING_REQUIRED）
• [P0] E5：错误有人类可读的 message
• [P0] E7：出错时，永不进入交互模式——立即退出
• [P0] E8：错误码是 API 契约——跨版本不得重命名

退出码 -- 可预测的失败信号

• [P0] X3：参数/用法错误必须退出 2
• [P0] X9：失败必须非零退出——永不退出 0 然后在 stdout 报告错误

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

• [P0] C1：stdout 仅用于数据
• [P0] C2：日志、进度、警告仅到 stderr

输入 -- 对错误输入快速失败

• [P1] I4：缺少必需参数 -> 结构化错误，永不交互提示