opus-4-7-migration

Opus 4.7 迁移扫描器

识别代码仓库中会在 Anthropic 平台将请求路由到 Opus 4.7 时出错或悄然降级的模式。生成分类报告，并附上文件:行号引用，帮助维护者规划范围明确的迁移 PR，而不必事后追查症状。

参考文件

文件	内容	加载时机
scripts/scan.py	生成分类发现报告的代码仓库扫描器	始终
references/migration-map.md	各类别对应的迁移措施，附有迁移前后的代码示例	某个类别有发现时

何时运行

• 将服务或 Agent 技术栈升级到 Opus 4.7 之前
• 现有的 Anthropic SDK 集成在平台推出 4.7 后开始返回错误时
• 定期在 CI 中或每周审查时运行，防止代码仓库不断扩展造成偏离
• 发布下游用户将针对 4.7 运行的包之前

范围——扫描器会标记的内容

扫描器的范围有意保持狭窄。它会报告三类确定性模式，以及两类需要人工审查的启发式模式。

类别 A——固定预算扩展思考（确定性）

Opus 4.7 不支持使用固定 budget_tokens 值的扩展思考。仍传入 thinking={"type": "enabled", "budget_tokens": N} 的代码会报错，或根据 SDK 版本被忽略。

标记的模式：

• Python 源代码中的字面量 budget_tokens=
• thinking={...} 字典字面量中的 "budget_tokens" 键
• .thinking.budget_tokens 属性引用

类别 B——已退役的模型 ID 别名（确定性）

不再映射到当前模型的带日期或已被取代的 Claude 模型别名。使用这些别名不会导致故障，但会绕过平台的模型路由。

标记的模式：

• claude-opus-4-5、claude-opus-4-4、claude-opus-4-3、claude-opus-4-2、claude-opus-4-1、claude-opus-4-0
• claude-sonnet-4-5、claude-sonnet-4-4、claude-sonnet-4-3、claude-sonnet-4-2、claude-sonnet-4-1、claude-sonnet-4-0
• 带日期格式的别名：claude-*-20250514、claude-*-20241022 等
• claude-3-* 系列（已被取代）

类别 C——配置之外的硬编码模型引用（确定性）

按照 armory 约定“模型引用只放在配置文件中”，.py / .ts / .js 源代码中任何位于 config.toml、.env 之外且并非仅用于测试的哨兵字符串的 claude-* 字面量，都应考虑提取出来。

类别 D——假设 Opus 4.6 输出详尽的提示词（启发式）

Opus 4.7 的默认输出详尽程度低于 Opus 4.6。依赖 Opus 4.6 主动提供大量内容，或从未需要深度提示的提示词，在 4.7 上可能会产生短于预期的回复。

标记的模式（需要审查）：

• 要求输出“详细”或“全面”，但没有对应的长度指示
• 依赖隐含的详尽程度，超出 Opus 4.6 默认输出的提示词
• Agent 提示词未明确要求完整说明首轮任务

类别 E——未明确要求并行调度子 Agent（启发式）

Opus 4.7 比 Opus 4.6 更谨慎地委派任务。Agent 提示词要求“并行启动”，但未包含“在同一条消息中”或未说明子任务彼此独立，在 Opus 4.7 上通常会变成串行执行。

标记的模式（需要审查）：

• Agent 提示词中包含 Spawn 和 parallel 相关表述，但未提及“同一条消息”或“独立”
• 在循环或顺序执行代码块中进行 subagent_type 调度，但原本意图是并行执行

工作流

阶段 1：运行扫描器

执行：

python3 scripts/scan.py /path/to/repo

可选标志：

• --categories A,B,C — 仅运行确定性类别（跳过启发式类别）
• --exclude tests/,vendor/,node_modules/ — 排除路径
• --format json — 输出机器可读格式，用于 CI 集成
• --exit-code — 如果发现任何问题则退出码为 1（适用于提交前钩子）

阶段 2：分类处理发现项

按类别分组并按严重程度排序。确定性类别（A、B、C）始终需要处理。启发式类别（D、E）需要先阅读周围的提示词上下文，再进行编辑。

迁移 PR 的优先级顺序：

1. 优先处理类别 A — 这些问题在 4.7 上要么会报错，要么会悄悄导致错误行为
2. 类别 B — 重命名为当前逻辑别名（claude-opus-4-7、claude-sonnet-4-6、claude-haiku-4-5），或平台的自动路由名称
3. 类别 C — 按仓库约定提取到 config.toml
4. 类别 D、E — 手动审核；修复那些会实质改变行为的问题

阶段 3：编写迁移 PR

对于每个发现问题的类别，按照 references/migration-map.md 中记录的操作进行处理。优先按类别拆分成小型 PR，而不是提交一个大型 PR。

迁移时一并提供：

• 单元测试或集成测试，用于在 Opus 4.7 上验证更新后的代码路径
• 简短的 CHANGELOG 条目，注明“Opus 4.7 兼容性：从……中移除了 budget_tokens”
• 如果该服务对生产环境至关重要，则提供推出计划（针对目标 Agent，工作量级别为 high/xhigh）

输出格式

扫描器会生成分类报告：

Opus 4.7 Migration Scan — /path/to/repo

Category A: Fixed-budget Extended Thinking       2 findings
  src/agent/reasoner.py:47   budget_tokens=8000
  src/agent/planner.py:112   thinking={"type": "enabled", "budget_tokens": 4096}

Category B: Retired model ID aliases             3 findings
  tests/test_agent.py:89     claude-opus-4-5
  config/dev.yaml:14         claude-sonnet-4-5
  src/llm/client.py:23       claude-sonnet-4-20250514

Category C: Hardcoded model refs outside config  1 finding
  scripts/bulk_process.py:8  DEFAULT_MODEL = "claude-sonnet-4-6"

Category D: Verbosity-assuming prompts          0 findings (heuristics disabled)
Category E: Non-explicit parallel dispatch      0 findings (heuristics disabled)

Total: 6 deterministic findings across 3 categories.

错误处理

条件	操作
仓库路径不存在	以退出码 2 退出，并显示清晰的错误消息
仓库中没有 Python / TypeScript / JS 文件	跳过类别 A、C；继续检查其他文件类型中的 B、D、E
扫描器中的正则表达式错误	以退出码 3 退出；使用导致问题的模式提交错误报告
类别 B 在变更日志中出现误报	默认排除 CHANGELOG.md；使用 --include-changelogs 覆盖默认设置

限制

• 类别 D 和 E 基于启发式规则，可能会对精心编写的提示词产生误报。修改前请先审核。
• 扫描器不会执行代码 — 它只进行静态模式匹配。即使 budget_tokens 变量从未传递给 Anthropic SDK，仍会被标记。
• 扫描器无法检测运行时动态模型选择（例如，model = config["models"][stage]）— 这类情况需要集成测试，而非静态分析。
• 跨语言分析仅限于 Python、TypeScript、JavaScript、YAML、TOML 和 Markdown。其他语言会被跳过。

相关内容

• rules/adaptive-thinking-control/RULE.md — 替代固定思考预算的提示词级控制
• skills/usage-audit/SKILL.md — 更广泛的上下文膨胀审计（互补工具）
• skills/mcp-to-skill/SKILL.md — MCP 到 skill 的转换（迁移过程中发现大量 MCP 用法时适用）