实现篇第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 里敲出一段:

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:

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