Web3 Agent 的脆弱点不只在模型。市场数据、签名格式、订单状态、资产表示和结算协议只要有一处变化，旧脚本就可能在“看起来能运行”的情况下产生错误状态。
个人 Obsidian 调研记录了 2025-11-28 的 SDK 重构观察点。这里把它当作历史迁移案例，不把后续生态状态倒推回当日。
先画依赖面，而不是先改 import
一次交易客户端迁移至少影响五层：
- 市场数据：标的 ID、分页、精度和盘口结构；
- 身份签名：密钥类型、域分隔、nonce 与授权范围；
- 订单生命周期：创建、部分成交、撤单和失败码；
- 持仓资产：条件代币、余额、授权和精度；
- 结算对账：结果解析、赎回与历史记录。
只替换 SDK 方法名，无法保证这些语义仍然一致。
Schema diff 要覆盖成功与失败
迁移检查不能只比较正常响应。需要保存旧版与新版对同一只读请求的字段差异，并测试空市场、分页结束、无权限、限流、部分成交和网络超时。
交易响应尤其要区分“请求接受”“订单挂出”“订单成交”和“资产到账”。如果新版把状态枚举或默认值改变，旧逻辑可能提前结束状态机。
用历史回放建立兼容层
合理做法是先把旧系统的一组公开市场快照、订单事件和结算结果转换为脱敏测试夹具。新版适配器在本地重放，输出统一领域模型。上层策略只依赖领域模型，不直接依赖某个 SDK。
兼容层还要明确精度、舍入和时间格式。交易系统中一个默认小数位变化，就可能让报价、限额和余额检查全部失真。
发布需要影子流量与停止窗口
新版先接只读影子流量，与旧版比较市场数量、盘口、延迟和错误分布。涉及订单时，先用 Paper Trading 或隔离账户验证，不在主账户上直接切换。
发布计划应包含：停止新订单、等待未完成订单清理、备份状态、切换适配器、余额对账、异常回滚。任何一步结果未知，都不继续下一步。
Agent 还需要工具版本声明
模型调用工具时，工具描述必须包含版本、输入约束和失败语义。否则模型可能继续按旧参数生成调用。工具版本变化应触发提示词回归测试，而不是把兼容责任交给模型猜测。
Web3 Agent 的版本迁移会一路触及协议层。产品经理必须理解状态与资产语义，才能判断一次“技术升级”是否真的可安全上线。
日期说明：2025-11-28 是 Obsidian 正文记录的 SDK 技术事件基准日，不是该笔记创建日。本文不描述当前平台版本，也不包含账户、签名或绕过限制的方法。
研究边界：本文用于产品与机制研究，不构成投资建议；涉及的策略表现仅代表历史回放、Shadow 或 Paper Trading 结果。
