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

小A把空白提问卡送入闸口,老Z守着控制杆,发光回答沿三条通道呈现完成、轮次耗尽和中止的不同结果。

本章导读: 你会写 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:

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敲出同文件的另一段:

ts
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?登录即解锁完整章节。