yzfly AI-First CLI 设计哲学
核心命题
CLI 的首要读者正在从人变成 agent。 过去 CLI 为人优化（漂亮的表格、交互式提示、彩色输出、man page）；agent-first 的 CLI 把这些当成"次要降级路径"，把机器可调用、可预测、可解析当成主路径——同时不牺牲人的体验。
一句话判据：一个 agent 读完命令的输出，应该确切知道下一步做什么——不用猜、不用幻觉命令、不用卡住。
这不是给旧 CLI 加个 --json 就完事。是把"使用者会读报错、会手动调试、会读文档"这套人类假设整个倒过来重做接口。Vercel 把它推到极致：CLI 转零依赖自更新签名二进制、Sandbox 内跑 Docker、甚至造了 Zero 语言让编译器吐 JSON 诊断给 agent 修。详见 references/vercel-case-study.md。
何时用本技能
- 设计 / 重写一个会被 AI agent 调用的 CLI
- 评审一个 CLI 是否"agent 友好"
- 纠结：要不要做 MCP server，还是把 CLI 做好就够了
- 决定输出格式、错误结构、退出码、flag、打包方式
- 给现有工具加 agent 安全护栏（dry-run、输入校验、幂等）
不适用：纯人机交互的本地工具（如个人 dotfiles 脚本），或决策已被 lint/schema 机械约束的场景。
十二条原则（速查）
| # | 原则 | 一句话 |
|---|---|---|
| 1 | 机器输出是默认，不是选项 | --json 结构化信封；TTY 给人看，管道给机器 |
| 2 | stdout/stderr 分流 | 数据走 stdout，诊断/日志/错误走 stderr，管道才干净 |
| 3 | 接收原始 payload | 允许直接传与 API schema 同构的 JSON，LLM 零翻译损失 |
| 4 | 错误要可执行 | 退出码 + 稳定错误码 + message + 修复命令 + 重试提示 |
| 5 | 自描述、可发现 | --help、schema introspection、explain CODE，CLI 是"此刻 API 接受什么"的唯一真相源 |
| 6 | 默认非交互 | 每个提示都有 flag 绕过；env var 认证，无浏览器登录 |
| 7 | 零依赖、自包含 | 单一签名二进制，快启动、可信、沙箱里无依赖链惊喜 |
| 8 | 可组合（Unix） | 可 pipe、读 stdin、NDJSON 流式分页 |
| 9 | 自治护栏 | --dry-run、幂等键、输入加固、响应净化防注入 |
| 10 | 省 token | 字段裁剪、分页、简洁输出，别撑爆上下文窗口 |
| 11 | 确定性优先 | 稳定输出契约 + 版本化 schema，agent 要可预测胜过聪明 |
| 12 | 一核多面 | CLI / MCP / SDK / env var 共享同一核心能力 |
原则展开（关键的几条）
1 + 2 双形态输出。 检测 TTY：交互终端给人类友好输出，非 TTY（被管道/agent 调用）默认结构化。或显式 --json。结构化信封要稳定：{ "ok": bool, "data": ..., "error": ... }。数据只走 stdout，这样 cmd --json | jq 不会被日志污染。
4 可执行错误。 反例：Error: something went wrong（exit 1）。正例：
{"ok": false, "error": {
"code": "AUTH_004",
"message": "Token expired",
"fix": "run `tool auth login`",
"retryable": false
}}
错误码要稳定（agent 靠它精确匹配，而不是解析自然语言），并配 tool explain AUTH_004 给结构化解释——别让 agent 去爬外部文档。
5 自描述。 --help 是 agent 的发现入口（这也是"CLI 是新 MCP"论点的核心：现成 CLI 自带 --help、自带认证/分页/重试，零集成负担）。更进一步：内置 schema introspection 命令、随二进制版本对齐的用法指引（Vercel Zero 的 zero skills），解决"外部文档与实际版本不同步"。
6 非交互默认。 agent 跑在 headless 环境，任何 Are you sure? [y/N] 都会让它卡死。规则：每个交互提示必须有 flag 旁路（--yes / --force），凭证走环境变量。
7 零依赖二进制。 动机：agent 在临时沙箱里反复拉起工具，依赖链 = 不可预测 + 慢 + 攻击面。单一代码签名二进制可验证来源、快启动、跨平台。这正是 Vercel CLI 改造的方向。
9 自治护栏。 agent 会幻觉输入——"build like it"。校验并拒绝路径穿越、控制字符、注入；变更操作给 --dry-run；副作用操作用幂等键（同键重试不重复执行）；返回数据做净化，防止响应里夹带的 prompt injection 顺着喂进 agent。若工具会执行 agent 产出的代码/命令，输入校验只是第一层——隔离要做到 VM 级（trust-domain microVM），而非容器级共享内核：默认假设"agent 生成的代码不可信"。这正是 Vercel Sandbox 的核心论点（详见案例）。
CLI vs MCP（常见决策）
| 维度 | 做好 CLI | 写 MCP server |
|---|---|---|
| 集成成本 | 零（agent 直接 shell out） | 每个集成建专用 server |
| 可组合 | Unix pipe 天然 | 协议内组合较弱 |
| 发现 | --help 自带 |
需 schema 定义 |
| 权限/审计 | 复用系统权限 + shell history | 另建 |
| 何时选 MCP | 需要持久连接、结构化双向流、富类型协商时 |
经验法则：先把 CLI 做成 agent-first，多数场景就够了；MCP 留给真正需要有状态协议的场景。 一核多面（原则 12）让两者共享同一底层。
反模式
200-with-error-body：永远退出 0，把错误塞进正文 → agent 以为成功- 人类输出和机器输出混在 stdout
- 报错只有散文，没有稳定码，没有修复建议
- 默认交互、没有
--yes旁路 → headless 卡死 - 输出不稳定（随机顺序、带时间戳/颜色码污染 JSON）
- 信任 agent 输入不校验
- 文档在外部网站，和二进制版本漂移
自检清单
- 非 TTY 下默认结构化输出？
--json存在？ - 数据→stdout，日志/错误→stderr？
- 失败退出码非 0，且错误带 code+message+fix+retryable？
- 错误码稳定且有
explain？ - 每个交互提示都有 flag 旁路？env var 认证？
- 变更操作有
--dry-run/ 幂等？ - 输入做了加固校验？
- 输出契约稳定、版本化、省 token？
-
--help/ schema 自描述完整？ - 打包尽量零依赖、可信？
来源
调研来源与 Vercel 案例细节见 references/vercel-case-study.md 与 references/sources.md。