📦 Agent Native Design — 代理本地设计

agent-native-design 目的 本技能帮助分析、设计和重构命令行工具，以便可靠地同时为人类、AI 代理和编排系统提供服务。它不是仅仅使用 CLI 的技能，而是设计和审查 CLI 作为代理原生接口的技能。该技能关注四个目标： 使 CLI 行为对于 AI 代理可预测。 使 CLI 输出对于人类可读和可恢复。 使 CLI 执行对于系统和编排器可管理。 定义从身份验证到错误路由的完整交互循环。

何时使用此技能 使用此技能时，用户希望： 评估现有的 CLI 是否为代理友好 重新设计 CLI 以更好地支持 AI 代理 将 API 或 SDK 转换为代理原生 CLI 审查帮助输出、模式设计、退出代码或 JSON 契约 设计 dry-run、auth 委托或安全边界 从模式生成 CLI 技能、文档或接口约定 将面向人类的 CLI 重构为面向机器的 定义 CLI 应如何与代理运行时交互

典型提示包括： “审查此 CLI 并告诉我它是否为代理原生。” “为此 API 设计一个 CLI，以便 AI 代理可以可靠地使用它。” “重构此工具，以便 stdout 对机器可读且对代理更安全。” “帮助我定义模式自省、dry-run 和退出代码语义。”

何时不使用此技能 当用户只希望： 运行特定命令的帮助 CLI 安装帮助 与接口设计无关的 shell 故障排除 通用 Linux 或终端教程 与工具无关的代理规划或内存设计 没有任何 CLI/工具层的 API 业务逻辑审查

核心模型 代理原生 CLI 必须同时为三个受众提供服务。

• 人类需求：可读输出、友好错误消息、入门指导。

通道：stderr、可选 --format 表格、在适当情况下交互式 TUI。

• AI 代理需求：结构化数据、稳定契约、自描述。

通道：stdout 作为 JSON、稳定退出代码、模式自省、dry-run 预览、生成技能/文档。

• 系统/编排器需求：委托身份验证、进程管理、确定性错误路由。

通道：环境变量、退出代码、dry-run 模式、稳定命令语义。

基础契约 通道 主要受众 stdout 机器和代理 stderr 人类 退出代码 系统和编排器

此技能教授如何使 CLI 成为代理的第一类接口。 生产代理（Claude Code、Cursor、Gemini CLI）通常将 CLI 与 MCP 服务器配对 — CLI 用于状态更改和本地/可脚本工作，MCP 用于多租户 SaaS 和每用户身份验证。 当设计需要 MCP 侧时，请参阅 references/hybrid-mcp-cli.md 以获取决策矩阵和 CLI/MCP 权衡背后的基准数据。

完整交互循环 阶段 步骤 描述

• 引导 1 人类/系统获取身份验证令牌或凭据
• 引导 2 设置可信环境变量：令牌、配置文件、安全模式
• 发现 3 代理加载技能或命令摘要
• 发现 4 代理查询模式/帮助以获取参数
• 规划 5 代理使用 --dry-run 预览请求形状
• 执行 6 代理执行带有验证输入
• 解释 7 代理解析结构化结果
• 恢复 8 代理使用退出代码 + 错误对象重试、重新身份验证、修复或升级

不支持每个阶段的 CLI 从代理的角度来看是不完整的。

七原则 这些是承重的。每个原则至少有一个评判标准和至少一个支持示例。 原则 0. 一个 CLI，三个受众 CLI 必须同时为人类、代理和系统提供服务。仅服务一个受众的设计是不完整的。 原则 1. 结构化输出是接口 stdout 应该始终可解析和稳定。成功和失败都是结构化 JSON。 CLI 必须自己决定哪个受众正在阅读：在启动时检测是否为 TTY，否则默认为 JSON，当为 TTY 时默认为人类可读。 NO_COLOR 和显式 --format json|表格 标志覆盖自动检测。 代理不应该记得传递 --format json — 如果他们必须这样做，他们会忘记，并且运行将默默地产生不可解析的散文。 信封和错误契约：references/design-patterns.md#output-envelopes。 原则 2. 信任是有方向的 CLI 参数本身并不值得信任 —— 它们可能来自于幻觉或提示注入的代理。 由人类或系统设置的环境级配置更值得信任。 代理选择在有界面内执行什么操作；人类定义允许它操作的位置和方式。 原则 3. CLI 必须自我描述 CLI 必须自我描述到足以使代理能够在不阅读外部 README 文件的情况下使用它。 自我描述必须是渐进的，而不是急切的：顶级 --help 列出资源；资源帮助列出操作；操作帮助列出标志；一个单独的模式自省...