实现篇第8章 为未来留三个插孔——Extensions ​

本章导读: 这一步不写新功能,而是盘点三条已被循环调用、已被测试覆盖的扩展缝:
ModelClient、Tool、BeforeToolCall。核心纪律:预留接口是未维护的承诺,先有失败证据再扩展。
Agent 基本成型了。小A坐在工位上,脑子里全是更宏大的计划:“老Z,我想加第二家模型、接 MCP、再加 Skill,最好还能搞多 Agent!”
老Z没有泼冷水,只是把键盘接过来:“先别急着堆功能。先分清‘已经存在的接口’和‘未来需求’。这个产物当前只有 ModelClient、Tool、BeforeToolCall 三条真实扩展缝,其余的只谈触发条件和草图。”
小A:“三条缝听着不少了,怎么还说‘别急着堆’?”
“因为这三条缝是 loop 真的在调用的,不是你画在纸上的。”老Z说,“ModelClient 被 runAgent 每轮调用(见 agent.ts 的 options.client.stream);Tool 被 runAgent 在分派时调用(见 agent.ts 的 tool.execute);BeforeToolCall 被审批分支调用(见 agent.ts 的 options.beforeToolCall?.(call))。有调用方、有测试覆盖的才叫接口,写在 TODO 里的叫愿望。你想加的 MCP、Skill、多 Agent,现在哪一条有调用方?没有。所以这一章只盘点已实现的三条缝,其余的留到触发条件成熟。”
小A:“被调用和只是被 import,怎么分?”
“看调用链里有没有决策。”老Z说,“options.client.stream 是 runAgent 每轮真正走的分支,少了它循环跑不起来;tool.execute 是工具分派的核心,beforeToolCall 是审批分支的入口,三者都长在 agent.ts 的控制流里。反过来,一条缝如果只被 import、没有任何分支依赖它,删掉它测试照样绿,那它就是装饰。验证也便宜:把那条缝的代码注释掉,跑一遍 npm test,看测试红不红。红的才是接口。”
“这三条缝各自的调用点,画出来就是一张图。”老Z把 runAgent 每个 turn 的流程画了下来:
runAgent 每个 turn(agent.ts)
│
├─► options.client.stream({ system, messages, tools, signal })
│ │ 每轮必然进入,产出 ModelEvent
│ ▼
│ for await (event of stream)
│ │ text → 累积;tool_call → 收集
│ ▼
│ 分派:for call of calls
│ │
│ ├─► options.beforeToolCall?.(call) ← 审批缝
│ │ └─ approved:false → 记录拒绝,continue
│ ▼
│ ├─► toolsByName.get(call.name) ← 工具查找
│ │ └─ 查不到 → 记录 unknown tool,continue
│ ▼
│ └─► tool.execute(call.input, signal) ← 工具缝
│ └─ 结果以 tool message 记录
│
▼
下一轮 / 返回“三条缝画在图上的位置各不相同:ModelClient 在每轮最开头,BeforeToolCall 在分派前,Tool 在分派后。扩展它们就是扩展这三段控制流,接入点精确到调用点。测试覆盖也从这三个点出发:agent.test.ts 的 fake client 替掉 ModelClient,agent-branches.test.ts 的 fake 轮次和 beforeToolCall 打满审批分支,工具行为由 createWorkspaceTools 单测盯着。”
已实现边界 ​
| 接口 | 调用者期待 | 扩展者必须保证 | 测试重点 |
|---|---|---|---|
ModelClient |
异步事件流 | 事件顺序、tool input 对象、取消传播 | fake 流、空响应、解析错误 |
Tool |
spec 加 execute |
schema 与执行结果一致、错误可读 | 非法输入、路径/副作用 |
BeforeToolCall |
单次审批结果 | 明确 allow/deny 和原因 | 拒绝记录、默认策略 |
小A:“扩展的时候,直接写实现就行吧?”
“顺序反了。”老Z说,“这三条缝共用同一条纪律:先确认失败证据,再改类型,再写实现,最后补回归测试,每一步都有测试变红变绿的节点。三条缝各自有一条最硬的测试守着:ModelClient 有 toModelEvents 的契约测试,Tool 有 agent-branches.test.ts 的非法输入与路径逃逸,BeforeToolCall 有 agent-branches.test.ts 的拒绝记录与 tool-failure-session.test.ts 的抛错收据。改动前先跑一遍测试记住基线,改动后任何一条红,就是你的改动破坏了哪条已承诺的边界。”
ModelClient 是协议适配缝 ​
“先看 ModelClient。”老Z打开 types.ts:
export interface ModelClient { stream(request: {
system: string; messages: Message[]; tools: ToolSpec[]; signal?: AbortSignal;
}): AsyncIterable<ModelEvent>; }“第二家 Provider 必须把它 SDK 的流映射成 text、tool_call、done。这不是换个 URL 就完事:消息角色、工具 schema、增量 JSON、取消和错误都要转换。当前 Anthropic adapter 对非对象 tool input 抛错,并在 content_block_stop 解析累计 JSON;另一个 API 的 partial JSON 语义不同,必须用 fake stream 和真实服务的受控测试验证。”
小A:“换一家 Provider,具体要重写哪些东西?”
“实现篇第2章那张映射表就是你的清单。”老Z说,“四个翻译点。消息角色:Anthropic 把 tool result 塞进 role: user 的内容数组,别的 SDK 可能单独有 tool 角色,toAnthropicMessages 整个要重写。工具 schema:Anthropic 要 input_schema,别家可能叫 parameters。增量 JSON:partial_json 的语义、事件名、闭合方式都不同,toModelEvents 状态机要重推。停止语义:end_turn/tool_use 是 Anthropic 的名词,stop_reason 的定义每家一套,supportedStopReason 是写死本家的。每一条都是实现篇第2章定义的协议边界,改个构造参数糊弄不过去。”
“接口本身不用动?”小A追问。
“不用,这正是实现篇第2章隔离的意义。”老Z说,“ModelClient 的签名不关心厂商,三家 Provider 共用同一个 runAgent、同一套 model-client.test.ts 的契约测试思路。真正的工作量全在 adapter 内部,接口负责把差异关在门后。”
老Z又打开 model-client.ts:
// src/model-client.ts,toolInput
if (input === null || typeof input !== "object" || Array.isArray(input)) {
throw new Error("tool input must be an object");
}“这个错误在 toModelEvents 里会被包成 tool_use block N returned non-object input 的协议错误,实现篇第2章讲过。”
“正常路径是 adapter 产出合法事件,loop 继续;失败路径是 provider 返回坏输入或网络抛错,runAgent 向上失败(除非 signal 已中止)。没有 Provider 注册表、重试或模型目录。”
小A:“为什么没有注册表?加一个 { name, client } 的 Map 不难吧?”
“不难,但没人查它。”老Z说,“runAgent 接收的是 client: ModelClient(见 agent.ts),拿来就用,不查注册表。你加了注册表,就得有人决定这次用哪个:是 main.ts 根据环境变量选,还是模型自己选?mini-agent 现在只有 AnthropicModelClient(见 main.ts 的 new AnthropicModelClient({ apiKey, model })),一家 provider,没有选择的需求。注册表解决的是多家 provider 怎么选,选的问题不存在,它就是一段空跑的代码。等你真有第二家、真需要在运行时切换再回来加,那时候你才知道切换的依据是什么,成本、延迟还是能力,接口也才知道该接什么参数。”
小A:“不写真 adapter,能不能先验证接口?”
“能,用 fake。这也是为什么接口里没有厂商字段。”老Z现场写了一个:
// 示意:为测试假想的"第二家 Provider"写的最小 client
class FakeSecondProvider implements ModelClient {
async *stream(request): AsyncIterable<ModelEvent> {
yield { type: "text", text: "我先看看工作区" };
yield { type: "tool_call", call: { id: "c1", name: "read", input: { path: "config.ts" } } };
yield { type: "done" };
}
}“把它传给 runAgent,循环完全不知道背后是 Anthropic 还是别的。接口能这样便宜地测,跟它能随便换,是同一件事。阶段验收让你‘新增一个 fake ModelClient 确保现有测试仍通过’,就是这个意思:扩展缝好不好用,用最小代价试一遍就知道。”
小A有点意外:“fake 里 done 事件为什么建议 yield?少一个会怎样?”
“少了 done 本身不会让 runAgent 抛错或挂起。”老Z说,“看 agent.ts:流结束后,只有 text === "" && calls.length === 0 才会 throw new Error('model completed without text or tool calls');如果 fake 已 yield 文本或工具调用,缺少 done 也能走完当前实现。另一头,Anthropic 适配器 toModelEvents 会校验自己的源事件:message_stop 没收到就抛 'stream ended before message_stop',stop_reason 缺失就抛 'did not provide a stop_reason'。所以要分清两层:内部接口建议产出 done,fake 也应忠实模拟协议收尾;但不要断言 runAgent 强制要求 done。”
小A:“fake 和真 provider 的差距怎么控制?”
“两条原则。”老Z说,“第一,fake 只比真协议简单,不比真协议宽松:done 必须有,事件顺序要合法,tool input 要是对象。第二,能离线构造的契约全测:实现篇第2章用构造的 MessageStreamEvent 把 toModelEvents 的每条错误路径都喂了一遍,那些测试不依赖任何网络。fake 的价值不在像真,在契约可执行。”
| fake 的职责 | 真的能测 | 测不到 |
|---|---|---|
| 事件序列 | 循环的累积、分派、提交逻辑 | 真实 SDK 的时序与并发 |
| 合法/非法轮次 | 拒绝、失败、中止分支 | 网络中断、限流、超时 |
| 契约强制(done 必须) | model completed without text or tool calls 抛错路径 |
provider 端实际行为 |
“真正要交到真实服务手里的验证,是另一类测试。main.ts 的 AnthropicModelClient 在测试里从不实例化(源码注释写着),真实端到端留给人工受控验证。”
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。