实现篇第12章 把零件拼成机器——Assembly ​

本章导读: 这一步把实现篇前面章节写出的源文件(types、model-client、agent、tools、approval、session、context、cli)由 main 拼成一个能跑的系统,并盘点已知限制清单。读完你会带走一条纪律:已实现和故意不做的同样重要,它们共同定义产物的真实边界。
十二个章节走完:前七章的代码、测试和命令都齐了,后四章的扩展、Hooks、Skill 和 MCP 留下了推演笔记。小A盯着满屏的绿色测试输出,长长地吐了口气,问老Z:“所以……这就是一个生产 Agent 了?”
老Z沉默了一会儿:“得到的是同一份能测试、能启动、且边界写明的 TypeScript 产物。不是生产保证,这两件事别混。”
装配路径 ​
小A把刚写完的几个文件从上往下翻了一遍,问老Z:“单看每个都懂,合起来是从哪儿进、往哪儿走?”
老Z画了一张装配图:
main.ts/runCli → runAgent → ModelClient.stream → ModelEvent
↘ Tool.execute → ToolResult → Message
↘ appendSession/trimContext小A盯着箭头看了两遍:“main 和 runCli 都通向 runAgent,但它们前面各自处理入口,后面各自处理出口,那它们是不是共享了最危险的一段?”
“对,这正是取舍的核心。”老Z说,“两个入口各自负责:读环境变量、收集参数、决定 system、注入工具和审批;runAgent 只负责中间的循环,最后返回 RunResult。出口也不在 runAgent 里:main 打印最后一条 assistant 文本,runCli 把每条非空 assistant 都写给 write,退出码则统一由 exitCodeForStopReason 这个纯函数映射。整条链可以拆成入口、循环、出口三段,任何一段替换都不影响另外两段:想要交互式输入,换入口;想要换 Provider,换 client;想要换退出语义,改 exitCodeForStopReason 的调用位置。”
“关键在装配点。”老Z打开 main.ts:
client: new AnthropicModelClient({ apiKey, model }),
tools: createWorkspaceTools(process.cwd()),
beforeToolCall: denyBashByDefault,“main 选择真实 adapter、当前目录工具和默认审批;runAgent 才拥有消息数组和轮次。跑完后,main 通过和 runCli() 共用的纯映射设置进程退出码:complete 为 0、max turns 为 2、aborted 为 130。把装配放在入口而非 loop 内,fake client 和不同工具集才可被测试替换。”
小A追着问:“为什么不让 runAgent 自己 new 一个 client?把参数都收进去不是更省事?”
“因为那样 loop 就把‘用什么 Provider’和‘怎么循环’焊死了。”老Z说,“你看 runAgent 的签名:它收的是 client: ModelClient,一个接口,不是 AnthropicModelClient。agent.ts 全文没有一处 import SDK,这就是依赖倒置的落点。loop 只认 stream() 这个方法和它吐出的 ModelEvent,至于背后是真实网络还是 fake 的内存队列,loop 根本不关心。测试里 FakeClient 直接替换它,loop 一行不改。”
小A换了个思路:“传一个 provider: "anthropic" 字符串不是也一样吗?loop 里 switch 一下,一样能换 Provider。”
“字符串 switch 和接口注入的区别,是依赖的方向。”老Z说,“传字符串,agent.ts 就得 import 每家 SDK,loop 知道全部实现,依赖倒置就还没完成。传接口,agent.ts 只认 stream() 的签名,它 import 的只有 ./types.js、./context.js、./session.js,你打开文件第一行看,没有一行来自 SDK。测试持有接口,所以测试能替换;将来真要加别的 Provider,也只改装配处,不改循环。”
“system 提示词呢?”小A又问,“我看到 main 传的是 You are a careful coding assistant.,runCli 又另写一句,这算不算各说各话?”
“这正是装配的边界:system 由调用方决定,不由 loop 决定。”老Z指 runAgent 的参数列表里 system: string 单独成一项,“loop 把它原样塞进 stream({ system, ... }),不拼接、不覆盖。main 面向生产脚本,措辞中性;runCli 面向交互,额外强调凭据安全。两套 system 共用同一个 loop,因为这条规则属于入口的决策,不属于循环的逻辑。”
小A顺着想:“那我能不能让 loop 自动把工作区目录也拼进 system?省得 main 每次都要写。”
“能,但那是循环替调用方做决定。”老Z说,“stream({ system, ... }) 里 system 是原样透传,loop 不检查内容、不追加前缀。一旦 loop 开始‘帮忙’,它就必须知道该往 system 里塞什么:工作区路径、用户身份、时间戳,每加一样都是 loop 对应用场景的一个新假设。main 面向脚本可以接受‘当前目录就是工作区’,runCli 却要强调凭据安全。同一个 loop 服务两种场景,恰好说明这个决策该留在入口。”
“消息记录呢?”小A问。
老Z又打开 agent.ts:
const record = async (message: Message) => {
messages.push(message);
if (options.sessionPath) await appendSession(options.sessionPath, message);
};“内存消息是本次运行状态;可选 JSONL 是追加式恢复材料。持久化写入失败会使运行 reject,不能悄悄继续,假装会话已保存。”
“为什么不在最后才一次性写盘?”小A追问,“跑完再 dump 不是更快?”
“因为跑完之前可能就崩了。”老Z说,“record 是每条消息都 await,哪怕跑到第三轮工具执行时进程被杀,前两轮的记录已经在磁盘上了,这就是追加式写入的回报:断点即终点。代价是每条消息一次 I/O,但这套产物的吞吐瓶颈从来不在这里。把‘写’和‘记’放在同一个 await 里还有一个好处:若磁盘满或权限错,appendSession 抛错会沿着 record 一路 reject 出去,调用方拿到的是一个失败,不是‘写成功了、文件却是空的’的假象。”
小A把这一段和 agent.ts 的 record 对照着看了一遍,又提出一个疑点:“要是 session 文件从一开始就不存在呢?第一次 appendSession 会不会炸?”
“不会,这正是测试覆盖过的事实。”老Z说,“appendFile 在文件不存在时会创建它;而恢复侧 loadSession 遇到 ENOENT 返回空数组而不是抛错,‘没有会话记录’是合法的起点,不是错误。你再顺着这条链看一遍:先 loadSession 恢复历史,再 record 新 user 消息,两条路径都碰到同一个磁盘文件。这一对语义合起来,session 文件从第一次运行就能成立。”
“messages 数组在内存里和磁盘上是同一份吗?”小A追问。
“是同一份事实的两份视图。”老Z说,“record 先 push 进内存数组,再 appendSession 落盘。内存那份是循环马上要用的:模型请求、工具分派、结果回传都读它;磁盘那份是‘进程死后还能再起来’的保障。两份数据由同一个 record 维护,避免出现‘内存说写了、磁盘说没有’的分叉。”
正常和异常控制流 ​
小A盯着装配图看了一会儿:“这是静态的接线。真跑起来呢?顺利时每一步怎么接,出了岔子又怎么走?”
“正常路径是 user message → model text 或 tool call → assistant message → tool result → 下一轮,直到无 tool call。空模型响应抛出,max turns 返回状态,取消在四个 checkpoint 返回 aborted,工具失败作为带 isError 的消息继续交给模型。”老Z说,“若取消发生在工具执行期间,循环等待已经启动的工具交还控制权:真实返回会先记录,取消后抛错会形成诊断结果,尚未执行的关联调用会标成 aborted before execution。toAnthropicMessages 负责把三种内部消息转成 Provider 所需角色,但它证明不了另一家 Provider 也接受同一形状。”
老Z把这条链画成状态图,小A盯着看了半天:
[inbox] → stream 中 → 无 tool call → [complete]
│ text/call 累积
▼
assistant commit ── 有 tool call ──▶ 逐个工具
│ approval 拒绝 → 记录 reason,继续
│ 未知工具 → 记录 unknown tool,继续
│ 执行返回 → 记录结果
▼
还有未执行 call?── 否 ──▶ 下一轮
│ 是(但 signal 已取消)
▼
记录 aborted 结果,[aborted]“注意状态图里没有‘回滚’这条边。”老Z补了一句,“每次转换只做两件事:要么记录事实,要么返回停止原因。工具一旦启动,它的副作用就不在状态图管辖范围内,那张图的边界就是 agent.ts 的边界。”
小A盯着“四个 checkpoint”想了想:“为什么是四个,不是一个?把取消检查放在循环开头不就够了?”
“不够,因为取消是异步的。”老Z说,“signal 可能在任何时候被 abort:模型正在流式吐字、approval 正在 await、工具正在执行。如果你只在循环开头看一眼,那 signal 在流式过程中被触发,loop 要等整轮流完才反应,这就不是‘协作式取消’了。你看 agent.ts 里 aborted(options.signal) 出现的地方:进循环前、流式循环里每收到一个事件、流结束之后、approval 前后、工具前后。每一处都是‘控制权交还到 loop 手里’的瞬间,loop 在这些点上才有机会看 signal。这不是为了精密,是为了不漏。”
“四个 checkpoint 和测试是怎么对上的?”小A问。
“每个 checkpoint 都有至少一个回归测试钉住。”老Z说,“cancellation.test.ts 里的八个用例,从‘首次记录前取消不改 session’到‘流完成竞态不提交 assistant’,再到‘审批期间取消后不启动工具’‘工具已返回但 signal 已触发时保留真实结果’,最后是‘一个工具完成后取消,剩余调用全部补上 aborted 结果’。你数一数,正好把四个 checkpoint 各覆盖一轮,外加纯退出码映射。测试不是‘顺便验证取消’,是先把取消的每种交还瞬间列出来,再一个瞬间配一个用例。”
“工具失败为什么不直接抛?”小A接着问,“前面说持久化失败要 reject,这里又说工具失败转成消息。”
“因为这是两种不同的失败。”老Z说,“持久化失败是‘连记忆都坏了’,loop 没法继续;工具失败是‘模型想做的事没做成’,这恰恰是模型应该知道的事实。你看工具返回的是 { content, isError: true },它被 record 成一条 tool message 交给下一轮,模型读到‘命令没找到’或‘路径越界’,自己决定要不要换个方式。把工具失败当异常抛,等于剥夺了模型自我修正的机会;而把持久化失败当消息吞,等于对调用方撒谎。”
“空响应为什么又是抛?”小A指着前面那条 model completed without text or tool calls。
“因为空响应不是‘模型想做的事没做成’,而是‘模型根本没给出可用的输出’。”老Z说,“这条抛错发生在 assistant commit 之前:text === "" && calls.length === 0 时,loop 连一条 assistant 消息都没记录就拒绝继续。如果把它也转成消息,模型会读到一条‘我没说话’的自我对话,越滚越怪。工具失败是模型那边的正常反馈,空响应是 loop 这边的契约违约。”
老Z把整条验证链收进一张表:
| 检查 | 覆盖内容 | 不覆盖内容 |
|---|---|---|
npm test |
离线 fake-client 测试,包括工具循环、取消竞态、session、CLI、schema、symlink、trim,以及三种 stop reason 的纯退出码映射和 API key 脱敏格式 | 真实网络、费用、模型质量、真实子进程 Provider |
npm run typecheck |
TypeScript 静态一致性 | 运行时 Provider 契约 |
npm start -- "任务" |
真实 key/模型下的一次调用 | 无成本、无副作用或安全隔离 |
| VitePress build | 书稿链接与渲染 | example 真实 API |
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。