agent-friendly-clilisted

# 面向 Agent 的 CLI 工具开发 ## 定位 这个 skill 管**跨语言的 CLI 契约设计与验收**：命令怎么分、输出怎么给、退出码怎么排、非交互怎么处理、怎么避坑、怎么验收。语言层面的实现细节（如 Go 的 cobra/flag、Python 的 argparse）交给对应语言级 skill，本 skill 不重复。 核心目标一句话：让 CLI 对 Agent **低 token、低歧义、低风险，且可审计、可复现、可回滚**；对人**默认可读、可交互**。这是同一个 CLI 的两个受众，不是两套工具。 ## 什么时候读哪个 reference - 设计命令面 / 输出契约 / 退出码，或评审一个 CLI 是否 agent-friendly → 读 [references/design-principles.md](references/design-principles.md)（P0/P1/P2 分层 + 人机双受众规范）。评审时逐条核对，缺失项就是要报告的问题。 - 动手实现，想避开真实事故 → 读 [references/pitfalls.md](references/pitfalls.md)（dry-run 真只读���幂等信号、密钥安全、测试隔离等踩坑教训）。 - 写完要验收 → 读 [references/verification.md](references/verification.md)（逐项粘证据的验收清单 + Agent 实测评测方法论）。 ## 工作流 ### 设计阶段 先过 **P0 七条硬性要求**——没有这些 Agent 根本用不了，细节见 design-principles.md： | P0 | 一句话 | |---|---| | 非交互模式 | 检测到非 TTY 自动关交互（用 `isatty()`，stdin/stdout 分开测），不要求调用方主动传 flag | | 结构化输出 | `--json` 统一 envelope `{ok, data, error, meta}`；失败也走 stdout JSON + 非零退出码 | | 退出码分层 | 0 成功 / 1 一般失败 / 2 用法错误 / 3 不存在 / 4 权限鉴权 / 5 冲突 / 6 超时 | | dry-run | 有副作用的命令能预演，输出结构与真实执行一致，且真只读、不花钱 | | 验证命令 | 提供 `status`/`verify`/`doctor`，让调用方在退出码之外再查一遍 | | 输入校验 | 硬拦路径逃逸、命令注入 | | 自助安装 | 配套 Skill 找不到 CLI 时提供可信下载地址并自动安装到用户目录，再校验版本与能力 | 过完 P0 再按需要加 P1（`describe` 自描述、结构化错误带 `hint`/`next_commands`、体积控制、写前日志、自动生成 SKILL.md、可组合性）。默认采用**声明式命令**（`ensure`/`apply`）而非命令式（`create`/`delete`），天然幂等安全。 **人机双受众**贯穿始终：默认输出人类可读（表格、颜色可用），`--json` 或非 TTY 时全部剥离只留机器契约；交互向导必须有非交互等价路径（`--yes` + 全量 flag）；同一信息给双字段（程序用英文枚举 `status`，人看本地化 `status_tag`）。 ### CLI 可获得性与自助安装 配套 Skill 的第一步必须探测 C