agent-native-design

agent-native-design

用途

此技能可帮助分析、设计和重构命令行工具，使其能够同时可靠地服务于人类、AI Agent和编排系统。

这不是一项单纯用于 使用 CLI 的技能，而是一项用于将 CLI 设计和审查为Agent 原生接口的技能。

此技能聚焦于四个目标：

1. 让 AI Agent 能够预测 CLI 的行为。
2. 让 CLI 输出便于人类阅读和恢复。
3. 让系统和编排器能够管理 CLI 执行。
4. 定义从身份验证到错误路由的完整交互闭环。

---

何时使用此技能

当用户希望：

• 评估现有 CLI 是否便于 Agent 使用
• 重新设计 CLI，以更好地支持 AI Agent
• 将 API 或 SDK 转换为 Agent 原生 CLI
• 审查帮助输出、架构设计、退出代码或 JSON 契约
• 设计试运行、身份验证委派或安全边界
• 根据架构生成 CLI 技能、文档或接口约定
• 将面向人类的 CLI 重构为便于机器使用的 CLI
• 定义 CLI 应如何与 Agent 运行时交互

典型提示包括：

• “审查这个 CLI，告诉我它是否是 Agent 原生的。”
• “为这个 API 设计一个 AI Agent 能够可靠使用的 CLI。”
• “重构这个工具，让 stdout 可供机器读取，并且对 Agent 更安全。”
• “帮我定义架构内省、试运行和退出代码语义。”

何时不使用此技能

当用户仅希望：

• 获得运行特定命令的帮助
• 获得 CLI 安装帮助
• 排查与接口设计无关的 shell 问题
• 学习通用 Linux 或终端教程
• 设计与工具无关的 Agent 规划或记忆
• 审查不涉及 CLI/工具层的 API 业务逻辑

---

核心模型

Agent 原生 CLI 必须同时服务于三类受众。

1. 人类

需求：易读的输出、友好的错误消息、入门指导。 渠道：stderr、可选的 --format table，以及适用时的交互式 TUI。

2. AI Agent

需求：结构化数据、稳定的契约、自我描述能力。 渠道：作为 JSON 的 stdout、稳定的退出代码、架构内省、试运行预览、生成的技能/文档。

3. 系统 / 编排器

需求：委派身份验证、进程管理、确定性的错误路由。 渠道：环境变量、退出代码、试运行模式、稳定的命令语义。

基础契约

渠道	主要受众
stdout	机器和 Agent
stderr	人类
exit codes	系统和编排器

此技能将介绍如何让 CLI 成为 Agent 的一流接口。生产环境中的 Agent（Claude Code、Cursor、Gemini CLI）通常会将 CLI 与 MCP 服务搭配使用——CLI 用于状态变更和本地/脚本化工作，MCP 用于多租户 SaaS 和按用户身份验证。如果设计还需要 MCP 端，请参阅 references/hybrid-mcp-cli.md，了解决策矩阵以及 CLI/MCP 权衡背后的基准数据。

---

完整交互闭环

阶段	步骤	描述
0. 引导	1	人类/系统获取身份验证令牌或凭据
0. 引导	2	设置可信环境变量：令牌、配置文件、安全模式
1. 发现	3	Agent 加载技能或命令摘要
1. 发现	4	Agent 查询架构/帮助信息以了解参数
2. 规划	5	Agent 使用 --dry-run 预览请求结构
3. 执行	6	Agent 使用经过验证的输入执行命令
4. 解析	7	Agent 解析结构化结果
5. 恢复	8	Agent 使用退出代码和错误对象进行重试、重新身份验证、修复或升级处理

从 Agent 的角度来看，不支持所有阶段的 CLI 都是不完整的。

---

七项原则

这些原则至关重要。每项原则至少有一条评估标准和一个示例作为依据。

原则 0. 一个 CLI，三类受众

CLI 必须同时服务于人类、Agent 和系统。只服务于其中一类受众的设计是不完整的。

原则 1. 结构化输出就是接口

stdout 应始终可解析且稳定。成功和失败都应输出结构化 JSON。CLI 必须自行判断由哪类受众读取：启动时检测 stdout 是否为 TTY；不是时默认输出 JSON，是时默认输出人类可读的内容。NO_COLOR 和显式的 --format json|table 标志会覆盖自动检测。Agent 不应需要记住传入 --format json——如果需要，它们就会忘记，运行结果也会悄然变成无法解析的散文。信封和错误契约：references/design-patterns.md#output-envelopes。

原则 2. 信任具有方向性

CLI 参数并非天然可信——它们可能来自产生幻觉或遭受提示词注入的 Agent。由人类或系统设置的环境级配置更可信。Agent 在有限范围内选择做什么；人类定义允许它在哪里以及如何操作。

原则 3. CLI 必须能自我说明

CLI 必须具备足够的自我说明能力，让 Agent 无需阅读外部 README 文件即可使用。自我说明必须是渐进式的，而非一次性全部展开：顶层 --help 列出资源；资源帮助列出操作；操作帮助列出标志；单独的 schema <resource.action> 命令返回完整的类型化架构。拥有数百条命令的 CLI 如果在首次 --help 中倾倒所有信息，就会让每次 Agent 调用都承担这些令牌开销。参见 references/design-patterns.md#help-design 和 references/examples.md 中的示例 2 和 5。

原则 4. 通过分级可见性保障安全

读取命令应易于发现；修改命令应带有明确警告；破坏性命令应从技能中隐藏，或单独设置门禁。分级表和理由：references/design-patterns.md#safety-design。分级是必要条件，但并非充分条件——它属于提示词侧的防御，审批疲劳会迅速削弱其效果。假设 Agent 运行时还会在操作系统层面（文件系统、网络、进程）对 CLI 进行沙箱隔离，并设计破坏性命令，使其在该沙箱内默认拒绝执行。

原则 5. 在边界处验证，而非在中间验证

输入应在 CLI 入口处验证一次。内部代码处理经过验证、类型化且可信的结构。验证函数应集中管理，并针对通过和拒绝两种情况进行测试。

原则 6. 架构是唯一事实来源

如果存在架构，所有内容都应由它派生：CLI 命令结构、验证规则、帮助文本、生成的文档、生成的技能、类型定义、试运行契约。架构绝不能手动重复编写。架构还必须包含自身的版本和弃用信号，并在每个响应的 meta 块中呈现，以便缓存了旧视图的 Agent 能检测到变化并重新发现，而不是悄然调用已移除的方法。完整的版本控制契约和示例：references/design-patterns.md#schema-versioning。

原则 7. 身份验证必须可委托

身份验证应通过由人类或系统管理的流程获取和刷新。Agent 使用凭证，但绝不负责管理身份验证生命周期。首选机制：环境变量、配置文件、操作系统钥匙串集成、外部刷新的令牌。标准模式：references/examples.md 示例 3。

---

标准审查工作流

步骤 1. 对输入进行分类

判断用户提供的是：现有 CLI、待封装的 API、概念设计、部分接口，还是故障案例。

第 2 步：梳理三类受众

**人类：**输出是否易于阅读？错误是否易于理解？是否支持新手上手？

**Agent：**标准输出是否为稳定的 JSON？CLI 能否描述自身？是否支持架构内省和试运行？

**系统：**身份验证是否可委托？退出代码是否稳定？能否确定性地路由故障？

第 3 步：检查交互循环

检查 CLI 是否支持：引导、发现、参数理解、预览、执行、解析、恢复。

第 4 步：使用评估标准为 CLI 评分，再映射回原则

使用包含 14 项标准的评估表为 CLI 评分。完整评估表位于 references/rubric.md。七项原则中的每一项至少都有一条评估表项目作为依据，因此评分与原则之间的映射是完整的：P0 → 三类受众支持、非交互式操作；P1 → 标准输出契约、标准错误分离、幂等重试、错误可恢复性；P2 → 信任边界；P3 → 自我描述（帮助）、试运行；P4 → 安全等级；P5 → 边界验证；P6 → 架构内省；P7 → 身份验证委托。然后针对每项原则，结合证据、风险和建议进行总结。完整的评审检查清单位于 references/checklists.md。

机器验证基线。 如果待评审的 CLI 已安装且可运行，请在应用评估表前运行 anc audit <command> --output json（agentnative 检查工具，包含 8 项 RFC 2119 原则）。anc 会探测已发布二进制文件的行为：非交互式操作、--output json 的有效性、架构可发现性、帮助信息／版本信息、退出代码、NO_COLOR 和试运行。请自行评估仅由评估表涵盖的维度——当前没有检查工具能够衡量信任方向性（P2）、边界验证（P5）、安全等级（P4）、身份验证委托（P7）或架构版本漂移（P6）。如果 CLI 无法安装或 anc 不可用，请仅使用评估表；如果两者都可用，请在评估表评分旁一并报告 anc 评分卡。

第 5 步：制定重构计划

• P0 必须修复
• P1 应改进
• P2 长期增强

---

默认输出格式

1. 总体结论

说明 CLI 是 原生支持 Agent、部分原生支持 Agent，还是尚未原生支持 Agent。

2. 三类受众契约评审

评估对人类、Agent、系统的支持情况。

3. 交互循环覆盖情况

评估各个阶段：身份验证引导 → 环境设置 → 技能／帮助发现 → 架构内省 → 试运行 → 执行 → 解析与恢复。

4. 评估表评分 + 七项原则评审

先报告包含 14 项标准的评估表评分，再按以下格式总结七项原则：状态 · 证据 · 问题 · 建议。

5. 主要风险

总结设计缺陷：仅提供人类可读的输出、JSON 不稳定、缺少架构内省、过度开放破坏性命令、身份验证与 Agent 耦合、退出代码含义模糊。

6. 重构计划

按优先级列出建议，并从 references/examples.md 中选取示例。

---

此技能应避免提出的建议

• 仅将面向人类的可读文本作为输出契约
• 基本命令发现必须依赖 README
• 架构与验证规则相互脱节
• 主要通过 Agent 生成的参数提供身份验证信息
• 默认开放破坏性操作
• CLI 行为依赖未文档化的约定
• 错误仅以文本形式呈现，无法通过机器路由
• 重试时无法保持幂等的变更命令
• 确认提示没有 --yes 绕过选项，也没有感知 TTY 的回退机制
• 在顶层 --help 中急切输出完整架构——在循环中调用 CLI 的 Agent 每次调用都会承担这项开销；应采用渐进式信息披露。关于 token 成本的说明见 references/hybrid-mcp-cli.md。

---

参考文件

按需加载——这些文件在需要之前不会出现在 Agent 的上下文中：

文件	阅读时机
references/examples.md	向用户展示良好的信封、错误、试运行、批处理响应或反模式时
references/rubric.md	生成 CLI 评审的评分部分时
references/checklists.md	与用户一起逐项检查 CLI 审核清单，或检查新设计是否合理时
references/design-patterns.md	编写有关信封、退出代码、幂等性、非交互模式、长时间运行的命令、架构版本控制、区域设置/时间的契约时
references/hybrid-mcp-cli.md	决定使用 CLI、MCP 还是两者兼用，或引用支持 CLI 效率观点的基准数据时
references/testing.md	向用户说明如何验证 CLI 是否真正遵守契约（信封形状、幂等性重放、TTY 行为、架构漂移、试运行安全性、区域设置确定性）时——当设计评审的重点转向“如何让它长期保持 Agent 原生？”时加载此文件
references/citations.md	引用建议所依据的主要来源时

---

一句话概述

此技能可帮助将 CLI 打造成值得信赖的执行接口，供人类、AI Agent 和系统使用，并具备结构化输出、自我描述、委托式身份验证、安全边界和完整的交互循环。