第 05 章：消息变换 — 跨模型交接的隐藏复杂度

阅读日期：2026-09-14。书中版本基线：核心分析 v0.66.0，作者自述对照 v0.82.1；本笔记未独立验证源码或发行版本。

设计问题、机制与取舍

同模型要求 provider、api、model 三项一致。转换先归一空 content，再处理内容：有效同模型签名保留；跨模型可见 thinking 降为文本，不透明内容丢弃，文本和工具签名清洗。工具 ID 改写必须同步到结果。

第二遍修复缺失工具结果，在新消息或历史末尾补错误结果，并跳过失败或中止的 assistant。目标是降低重放错误，不是恢复未执行的工具，也不是无损迁移。转换在 provider 请求边界进行，不能与 AgentMessage 转 Message 的步骤混淆。

来源：本章原文。这是压缩后的原创读书笔记，完整论证、示例及版本说明请回到原章。

工程应用检查（整理者推导）

跨模型切换应保留原始历史，另生成目标请求视图。这样可以比较切换前后实际失去了哪些字段，也避免把一次有损转换永久覆盖为唯一记录。为知识库 Agent 可记录“本次请求使用哪个历史版本”，不必把厂商专用签名展示给访客。

验收样本至少包含：同厂商换模型、同模型换 API、工具调用无结果、只完成一部分工具、空内容和被中止的响应。检查结果关联是否一致，以及补出的错误是否被界面误报为真实工具执行。对有副作用工具，不能因为看到合成失败就盲目重做，应先检查实际写入回执。

本章将转换称为确定性操作，但示例补齐结果使用当前时间；若测试需要逐字相等，应注入时钟或排除时间字段。“不会导致 API 失败”也应理解为设计目标，仍需目标协议校验。这些是整理者对文中代码和承诺的审读及应用推导。