Claude API 升级需排查三类不兼容

Claude API 升级最容易踩的坑，可能藏在一次普通的依赖更新里。按原文的说法，新版 SDK 会默认切换到 anthropic-version: 2026-10-21，让过去能正常发送的采样参数、消息内容直接触发 400。迁移的重点，是把依赖版本、请求结构和测试一起管理。

这份指南有用的地方，是列出了排查顺序和双版本测试思路。不过，原文缺失部分字段对照，示例也有脱敏残缺；下面涉及产品变更的内容均按原文转述，不能把它当成已经独立核验过的发布说明。

为什么更新 SDK 会让旧请求突然报错

anthropic-version 用来固定 Claude API 的协议版本，可以理解为客户端与服务端约定的一套请求、响应规则。原文称，2026-10-21 是自 2023-06-01 以来的首个新版本。

固定版本也不代表接口永远没有新增内容。按原文描述，同一版本仍可能增加可选输入、新的输出值、枚举成员、流式事件类型和错误条件。因此，客户端解析响应时，仍要考虑遇到未知值的情况。

官方 SDK 通常自动发送版本头。原文列出的新主版本包括 Python 2.0.0、TypeScript 1.0.0、Go 2.0.0，默认使用新 API 版本。这就把两件事绑在了一起：更新客户端依赖，也可能同步更新服务端协议。

不过，原文拿 pip install -U anthropic 和 npm update 举例，不能理解成它们必然跨主版本。是否升级，还取决于依赖范围和锁文件。真正要检查的是最终安装了什么版本。

原文建议先限制旧主版本，例如 Python 使用 anthropic<2，npm 使用 "@anthropic-ai/sdk": "^0"，再开展迁移。

哪些请求内容需要优先排查

原文列出的三类请求变更，适用于 POST /v1/messages、token 计数，以及用新版创建的 Message Batch 内部请求。

第一类是 temperature、top_p、top_k。按原文说法，新版对所有模型都拒绝这些字段，连默认值也不接受。配置里残留一个 temperature: 1.0，就足以触发 400。

这里要区分请求兼容和生成效果。原文称，Claude 4.7 及以后只接受默认采样值，删除字段不会改变采样行为；Claude Sonnet 4.6 等旧模型若曾依赖非默认值，删除参数就可能改变输出。原文也明确说，没有其他设置可以替代。需要保留这类行为的请求，可以继续使用 2023-06-01。

删除字段可以解决协议报错，却不能证明输出质量保持不变。

第二类是 assistant 消息中的直接 document 块，需要移到 user 消息。原文保留了一个例外：嵌套在其他块内部的文档，例如 Claude 返回的 web fetch 工具结果，仍可接受。修复时不能对整个历史记录做无差别删除。

第三类是 user 的 text 块中非空的 citations 数组，连 search_result 内部的文本也在范围内。应删除这些位置的引用数据，但回传 Claude 自己生成的 assistant 引用仍然有效，文档和搜索结果上的 "citations": {"enabled": true} 也继续可用。

管理接口还有另一种风险：请求成功了，界面却解释错了数据。原文称 Admin API、Enterprise Analytics API 的多个字段改名，旧名不再返回，但所给材料缺少完整对照表，无法据此列出全部修改项。

可以确认原文讲清的一项，是 API key 的工作区归属。旧版 workspace_id: null 同时可能表示默认工作区或全部工作区；新版默认工作区使用真实的 scope.workspace_id，组织范围的 key 则使用 scope: {"type": "organization"}，不带 workspace_id。管理后台若继续把空值标成默认工作区，就会显示错误。

安全迁移要同时覆盖 SDK 和网关

按原文描述，新 SDK 还有一些独立于 API 日期版本的变化：

• 鉴权从 X-Api-Key 改为 Authorization: Bearer <key>，API 两者都接受，但网关、日志过滤器和测试桩可能只认识旧头。
• TypeScript、Go、Java、Ruby SDK 及 CLI 移除 Text Completions，需要改用 Messages API，并排查 completions.create。
• 非 beta 的 Models 方法移除 betas，改用 client.beta.models；类型化 SDK 的 MessageParam 按角色拆成联合类型。
• Go 的导入路径改为以 /v2 结尾；TypeScript 的 Bedrock、Vertex、Foundry、AWS、Google Cloud 配套包需要同步迁移到 v1，避免安装两份不同版本的核心 SDK。
• 许可证由 MIT 改为 Apache 2.0。

Amazon Bedrock 另有前提：原文称新版仅支持 Claude 4.7 及以后。仍调用 Opus 4.6 或更早模型时，应先保留现有 SDK 或版本头，换模型后再迁移。

测试方法倒不复杂：保存真实请求的 JSON 样本，同一份 payload 分别使用两个版本头运行，比较状态码、响应结构和错误信息；涉及旧模型采样策略时，再单独检查生成结果。

原文推荐让 Claude Code 通过 Apidog CLI 批量建用例，下面是其初始化命令：

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code when prompted

第三行会安装供编程代理使用的技能；原文注释要求在提示时选择 Claude Code。这里的 @latest 是安装写法，不能代替项目自己的版本管理。

原文的测试方案是在 claude-api 环境中设置 https://api.anthropic.com，读取 ./fixtures/claude/，为每份 JSON 创建 POST /v1/messages 用例，发送 anthropic-version: {{anthropic_version}}，断言状态为 200 且 content 数组非空。

执行时通过 --env-var "anthropic_version=2023-06-01" 和 --env-var "anthropic_version=2026-10-21" 切换版本，用 -r cli,json 输出报告；--upload-report 用于上传报告，-r junit 可接入 CI。原文还提到用 apidog cli-schema get test-case-create 和 apidog cli-schema validate test-case-create --file case.json 检查创建用例的输入。

原文的 curl 鉴权行、代理提示词和部分 CLI 参数存在缺失，不能直接照抄执行。示例中的 claude-opus-5-5 与 max_tokens: 1024 也只是给定配置，材料没有进一步证明该模型标识的可用性。

我的判断

这篇最有价值的是测试方法：保持请求不变，只切换版本头，把兼容性问题从上线后的异常变成发布前的差异报告。对于维护 Node 服务、聊天历史持久化和企业网关的团队，这比单纯修复 SDK 类型报错更完整。

但原文没有提供实际项目迁移记录、失败比例、质量对照或节省工时的数据。Apidog 的部分属于工具方案推荐，不能据此认定它比现有测试框架更高效。原文提到免费方案支持最多 4 位用户，也不足以说明一般团队的总成本。

状态 200 加非空 content 只能覆盖基础可用性，无法证明工具调用、引用展示、流式处理和业务结果都正常。已有测试设施的团队，可以直接复用现有请求样本与 CI；只有确实需要共享用例、环境和报告时，再评估额外平台。

原文称 2023-06-01 尚无公布的退役日期，因此它把升级视为可规划的工作。这个判断有一个边界：这是材料所描述的状态，不能把没有退役日期理解成永久支持承诺。

能拿来做什么

• 在 Node 项目里检查 SDK、配套云平台包、依赖范围和锁文件，把协议变更与依赖更新放进同一个评审。
• 从请求构造器和历史回放逻辑中排查三个采样字段、assistant.document、user.text.citations，避免只修改新消息入口。
• 让 AI 编程代理基于真实 fixtures 生成双版本测试，并保留错误响应；涉及旧模型非默认采样的调用，再补业务结果检查。
• 在发布 SDK 更新前，检查网关鉴权、日志过滤和 API key 工作区展示，并将请求修复与依赖升级一起交付。