SuperAPI AI 工具集

cli-for-agents

智能体与模型

查看项目

更新于 10-16 03:46

技能介绍

用途:本技能给出面向 AI 智能体与脚本(而非人类交互输入)的命令行界面设计与评审规范,可用于新建 CLI 时按规则设计,或评审现有 CLI 的无头可用性回归。核心判断是:面向人类的 CLI 常阻塞智能体,例如交互式提示、一次性输出庞大文档、帮助文本缺少可直接复制的示例、错误信息不含修复方式、没有 dry-run 模式。

主要能力:共 45 条规则,分 8 类并按影响范围排序。非交互运行(CRITICAL):输入优先用标志表达,提示仅作 TTY 回退;先检测 isatty();用标志选择替代方向键菜单;支持 --no-input;不用定时提示或按键屏;不阻塞 stdin。帮助文本(HIGH):每个 --help 含可复制示例、每个子命令独立 --help、零参数时显示帮助、顶层帮助作为导航索引、列出长短标志形式、建议下一步。错误信息(HIGH):缺必填项快速退出、给出具体修复、错误写入 stderr、不同失败用不同非零退出码、附正确调用示例、默认不打印堆栈(留给 --debug)。破坏性操作安全(HIGH):提供 --dry-run、--yes/--force、不可逆操作需输入资源名确认、--no-input 时不提示、目标已消失仍成功退出、面向崩溃恢复设计多步命令。输入处理(HIGH):用 - 表示 stdin/stdout、优先具名标志、密钥经 stdin 或文件传入、常用标志支持环境变量回退、缺标志不回退到提示。输出格式:提供 --json、大结果集用 NDJSON 流式输出、以 --limit 与 --all 控制默认输出量、成功时返回可链式使用的值、尊重 NO_COLOR 与非 TTY、避免仅靠装饰性输出表达状态、每行一条记录。幂等与重试:重复执行安全、创建类命令在目标已存在时跳过、跳过与执行返回相同结构、优先“确保状态”语义、接受用户提供的名称而非自动生成 ID。命令结构:采用一致的资源-动词形式、标志位置无关、避免未知子命令的兜底处理、使用标准标志名(--help、--version、--verbose、--quiet)。

使用方式:新建时从 CRITICAL 往下逐条应用;评审时按优先级清单逐项检查,例如用 --no-input 或 </dev/null 调用各子命令看是否挂起,检查顶层帮助是否只列子命令,看每个子命令帮助是否以可运行示例结尾,检查错误是否说明需加哪个标志,验证 exit code 是否区分用法错误、运行失败与瞬时失败,确认破坏性命令都有 dry-run 与确认绕过,以及成功输出是否返回 deploy_id 等可继续使用的标识。

适用场景与限制:适用于编写 --help、设计标志与子命令、编写错误信息与退出码、添加破坏性操作、在交互提示与纯标志输入间取舍、以及评审现有 CLI。资料未提供具体版本、代码示例内容、安装步骤或收费信息。