实现篇第2章 接通第一根管道——ModelClient ​

本章导读: 你会写
src/types.ts的ModelClient接口和ModelEvent类型,再在src/model-client.ts里把 Anthropic SDK 的事件翻译成内部事件。核心是一条纪律:业务代码永远不直接碰 SDK 的事件命名。
范围定了,小A打开编辑器,第一件事却是对着 types.ts 发呆。他问老Z:“模型接入怎么写?直接调 SDK 不就行了?”
“行,但你会后悔的。”老Z说,“先隔离模型协议。src/types.ts 的 ModelClient.stream() 产出内部 ModelEvent;src/model-client.ts 的 AnthropicModelClient 才依赖官方 SDK。业务代码永远不读 SDK 的事件命名。”
小A:“那中间这层,到底隔离了什么?”
先看内部消息契约 ​
老Z在 types.ts 里敲出一段:
// src/types.ts,节选
export type ModelEvent =
| { type: "text"; text: string }
| { type: "tool_call"; call: ToolCall }
| { type: "done" };“文本、工具调用、完成被拆成三种,是因为流里它们到达的时间不同。”老Z说,“done 不携带‘回答一定有效’的结论,循环还要检查是否累计了文本或工具调用。有了这个小契约,业务代码就不需要读 SDK 的事件命名。”
小A追问:“那为什么不干脆设计成一个 message 事件,把文本、调用、完成一次带齐?”
“因为到达时间不同,下游能消费的时机也不同。合成一个事件,要么等整条流收完再发,那 stream() 就不配叫流式了;要么发半成品,让循环去猜哪一段能执行。三种事件对应三种时间上可独立消费的事实:text 一到就能追加显示;tool_call 一到表示这个调用的参数对象已经完整;整轮协议校验通过后,循环才会分派执行。done 一到代表适配层认为协议收尾;runAgent 不依赖这个事件判定业务完成。事件的粒度,由‘下游最早能做什么’决定,不由 provider 的事件长什么样决定。”
| 设计问题 | 本产物的选择 | 放弃的替代方案 | 放弃的理由 |
|---|---|---|---|
| 事件粒度 | 三种原子事件 | 一条聚合 message |
聚合意味着等收齐,或发半成品 |
| 参数完整性 | tool_call 只发完整 input |
逐段增量参数 | 下游无从判断何时可执行 |
done 语义 |
只代表流收尾 | 代表“回答有效” | 有效性要循环自行检查 |
| 业务可见协议 | 内部三事件 | SDK 原始事件名 | 换厂商时业务层零改动 |
老Z随手画了一张映射示意:
Anthropic SDK 原始事件 内部 ModelEvent
───────────────────────────── ──────────────
content_block_delta (text_delta) ───────► { type:"text" }
content_block_start (tool_use)
content_block_delta (input_json_delta) (攒着,不产事件)
content_block_stop ──────► { type:"tool_call" }
message_delta / message_stop ──────► { type:"done" }“注意中间那块:input_json_delta 在映射表里没有对应行,它不产内部事件,只更新内部状态。SDK 事件是一段状态机的输入,内部事件是它解析之后的产出。”
消息映射不是类型断言 ​
小A盯着 toolInput 函数看了半天,问:“工具输入在 TypeScript 里是 unknown,为什么映射时还要检查?类型不都标好了吗?”
“因为模型和网络都能给出任意 JSON。”老Z打开 model-client.ts:
function toolInput(input: unknown): Record<string, unknown> {
if (input === null || typeof input !== "object" || Array.isArray(input)) {
throw new Error("tool input must be an object");
}
return input as Record<string, unknown>;
}“第一行保留不可信类型;条件排除三类 JSON 非对象;最后的断言只发生在运行时检查之后。”老Z说,“它也不验证字段是否符合某个工具 schema,那是工具执行层的事。”
小A:“那这层到底防什么、防到什么程度?”
“防‘结构性的不可能’,不防‘业务上的不合法’。”老Z说,“工具输入必须是 JSON 对象,null、数组、字符串在结构上就不可能是工具参数,这一层只拒结构:{ path: 42 } 这种字段类型错的输入会放行,留给 execute 里的 stringField 去拒。两层防线各管一段,一层管‘它是个对象吗’,一层管‘字段对吗’。对照真实代码能看见层次:model-client.ts 的 toolInput 只做结构检查;tools.ts 的 read.execute 第一行是 const path = stringField(input, 'path')。每一层只答自己该答的问题,错位就变成重复校验或漏校验。”
“这里还藏着一个细节:toolInput 抛的 tool input must be an object 不满足 toModelEvents 里 startsWith("Anthropic") 的判断,会被包成 tool_use block N returned non-object input 的协议错误。错误消息带上 block index,定位时才知道是哪一段流出了问题。”
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。