实现篇第6章 开一扇可靠的闸——CLI ​

本章导读: 你会写
src/cli.ts的runCli、runInteractive和纯函数exitCodeForStopReason。这一步的关键是分离契约:可测试的 CLI 函数靠注入ask/write摆脱终端,退出码 0/2/130 各有含义,而main()才是把异常变成 stderr 的边界。
会话和循环都有了。小A兴冲冲地想把 main.ts 当成所有入口,不管什么命令,都从这里进。老Z拦住他:“先别急着合并。可测试的 CLI 函数和生产 argv 入口承担的是不同契约,揉成一个,测试没法写,退出码也没法保证。”
“那到底要几个入口?”
“三个,各管各的。本章只实现一次问答,不实现 REPL、流式界面或诊断框架。”
三个入口,三个责任 ​
| 符号 | 输入 | 输出/退出语义 | 不负责什么 |
|---|---|---|---|
main.ts |
process.argv、环境变量 |
只打印最后一条 assistant content,并把 stop reason 映射为进程退出码 | signal、session、REPL |
runCli() |
注入 client、工具、ask、write |
输出每条非空 assistant content,并返回 Promise<number> |
创建真实 Provider |
runInteractive() |
标准输入输出 | 调一次 runCli() 后关闭 readline |
连续 REPL |
argv 的生产路径 ​
“先看 argv 进来以后发生什么。”老Z打开 main.ts:
user: process.argv.slice(2).join(" ") || "Describe the workspace.",
maxTurns: 8,
beforeToolCall: denyBashByDefault,“这里把 argv 余项拼成一条用户消息,并装配真实 AnthropicModelClient、工作区工具和默认 bash 拒绝策略,调用一次 runAgent,再筛选最后一条 assistant 文本打印。argv 为空时不进对话循环,用的是默认问题。”
小A:“那 API key 怎么处理?测试的时候可不能读真实 key。”
“这就是凭据边界。”老Z敲出同文件的另一段:
const apiKey = process.env.ANTHROPIC_API_KEY;
if (!apiKey) throw new Error("ANTHROPIC_API_KEY is required for production use; npm test uses no API key.");“正常路径要求同时提供 key 与模型名,缺任一项都会在调用网络之前失败。main() 捕获启动或运行异常后,以稳定的 mini-agent: failed to start or run: stderr 前缀输出受控诊断,并设置退出码 1;格式化时会替换已配置的 API key,key 的值不能写入 stderr。异常消息也不会被静默吞掉。”
“为什么要把 key 从错误消息里 redact?异常又不是模型吐的。”
“防的就是我们自己的错误日志。”老Z说,“SDK 在认证失败时会怎么报错?它可能把请求头打进去,而请求头里就有 x-api-key: sk-ant-...。main() 要是把原始 error.message 直接写进 stderr,key 就泄漏到日志里了。所以 formatMainError 做了一件事:detail.split(apiKey).join("[REDACTED]"),把 key 字面量替换掉。测试里专门构造了一个 new Error(\provider rejected ${apiKey}`),断言输出里能匹配到 [REDACTED]` 且匹配不到原始 key。”
“那为什么不在请求阶段就脱敏,要等到 catch?”小A追问。
“因为 key 是用来发请求的,发的时候不能改。”老Z说,“脱敏只能发生在要把信息写出去的那一刻,也就是 stderr。在内存里 key 必须是原值,否则 SDK 没法用它认证。”
小A:“那 formatMainError 为什么是导出的纯函数,而不是嵌在 catch 里?”
“为了能直接测。”老Z说,“cli-exit.test.ts 里就是直接调 formatMainError(new Error(...), apiKey)。这要求它不碰 process.env、不写终端,输入输出都是值。要是嵌进 main 的 catch,测试就得真的启动进程,还要伪造 ANTHROPIC_API_KEY,单测就背上了集成测试的负担。拆完之后,main 里只剩读 env、调 runAgent、打印、设退出码四件事,其余都是纯函数。”
“退出码呢?”小A接着问,“总不能全都返回 0 吧?”
“在打印最后一条 assistant content 后,main() 和 runCli() 都调用同一个纯映射:complete 为 0,max_turns 为 2,aborted 为 130。所以 npm start 遇到轮次耗尽不会再以 0 结束。main 目前没有装配 signal;aborted 在这里只表示映射完整性,不代表已经支持 Ctrl-C。”
四个退出码的完整语义摊开看:
| 退出码 | stop reason | 含义 | 脚本怎么判断 |
|---|---|---|---|
| 0 | complete |
循环完整结束 | 正常收尾 |
| 2 | max_turns |
轮次耗尽,没跑完 | 结果可能不完整 |
| 130 | aborted |
调用方主动中止 | $? -eq 130 就是被中断 |
| 1 | (main 捕获异常) | 启动或运行失败 | 要看 stderr 诊断 |
“注意 1 不在 exitCodeForStopReason 里。”老Z说,“1 是 main() 的 catch 分支设的(见 main.ts 的 process.exitCode = 1),对应的是异常,不是 stop reason。四种结局里,三种正常退出的 stop reason 由纯函数映射,剩下一种异常由 main 兜底。”
main 的生产路径画成一张图:
process.argv.slice(2).join(" ") 或默认问题
│
▼
main(): 校验 ANTHROPIC_API_KEY / ANTHROPIC_MODEL
│ 缺任一 → throw → formatMainError → stderr + exit 1
▼
runAgent({ client, tools, user, maxTurns: 8, beforeToolCall })
│
▼
筛选最后一条 assistant content ── 打印(空则 ?? "")
│
▼
exitCodeForStopReason(stopReason) → process.exitCode本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。