SuperAPI AI 工具集

agent-native-design

编程与开发

查看项目

更新于 10-15 16:43

技能介绍

用途:该技能用于分析、设计和重构命令行工具,使其同时可靠地服务人类、AI 智能体和编排系统。它不是教如何使用 CLI,而是把 CLI 当作智能体原生接口来设计与评审。

主要能力:围绕四个目标展开——让 CLI 行为对智能体可预测、让输出对人类可读可恢复、让执行对系统与编排器可管理、定义从认证到错误路由的完整交互循环。核心模型要求 CLI 同时服务三类受众:人类(可读输出、友好错误、引导)、AI 智能体(结构化数据、稳定契约、自描述)、系统/编排器(委托认证、进程管理、确定性错误路由)。基础契约是 stdout 面向机器与智能体、stderr 面向人类、退出码面向系统。

七项原则:一个 CLI 服务三类受众;结构化输出即接口(stdout 始终可解析,成功与失败均为结构化 JSON,启动时检测 TTY 自动选择格式,NO_COLOR 与 --format json|table 可覆盖);信任具有方向性(CLI 参数不被默认信任,环境级配置更可信);CLI 必须自描述(渐进式披露,顶层 --help 列资源,资源帮助列动作,动作帮助列标志,schema 返回完整类型);通过分级可见性实现安全(读命令易发现,变更命令带警告,破坏性命令隐藏或单独门控);在边界而非中间校验;schema 是唯一事实来源(命令结构、校验、帮助、文档、类型、dry-run 契约均由其派生,并携带版本与弃用信号);认证必须可委托(由人类/系统管理流程获取与刷新,智能体只使用凭证)。

使用方式:标准评审流程为——分类输入(现有 CLI、待包装 API、概念设计、部分接口或失败案例);映射三类受众;检查交互循环(引导、发现、参数理解、预览、执行、解析、恢复);用 14 项评分表打分并映射回七项原则;产出重构计划(P0 必须修复、P1 应改进、P2 长期增强)。当 CLI 已安装可运行时,可先运行 anc audit <command> --output json 做机器验证基线,再应用评分表;不可安装或 anc 不可用时仅用评分表。

适用场景:评估现有 CLI 是否对智能体友好、重新设计以更好支持智能体、将 API 或 SDK 转为智能体原生 CLI、评审帮助输出/schema/退出码/JSON 契约、设计 dry-run 与认证委托与安全边界、从 schema 生成 CLI 技能与文档、将面向人类的 CLI 重构为面向机器的 CLI。

限制:不适用于仅需运行某条命令、安装帮助、与接口设计无关的 shell 排障、通用 Linux 教程、与工具无关的智能体规划或记忆设计、无 CLI 层的 API 业务逻辑评审。应避免推荐:仅以人类可读文本作为输出契约、基本命令发现依赖 README、schema 与校验漂移、认证主要靠智能体生成参数、默认暴露破坏性操作、依赖未文档化约定、错误仅文本不可机器路由、重试下非幂等的变更命令、无 --yes 逃生与 TTY 感知回退的确认提示、顶层 --help 中急切倾倒 schema。参考文件按需加载,包括 examples、rubric、checklists、design-patterns、hybrid-mcp-cli、testing、citations。