企业官网建设流程全解析

OmO 的 Opus 5 迁移 QA 证据实践：用分层校验守住用户可见的模型推荐

【免费下载链接】oh-my-openagentOmO: Just type "mass ulw" keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent

这篇文章基于仓库中的 QA 证据文件 .omo/evidence/20260725-opus5-migration/qa-summary.md，完整还原 Oh My OpenAgent（OmO）在把默认模型推荐从 Claude Opus 4.6/4.8 迁移到 Opus 5 一代时所采用的验证体系：一条针对 21 个用户可见文件的“陈旧推荐审计”，一组钉死 Metis / Prometheus 等角色模型选择顺序的能力契约测试，外加类型检查、网站构建、无头浏览器渲染验证与全量测试门禁。读完后，你可以掌握一套可复制的“模型版本迁移 QA 分层法”——如何证明一次模型改名既没有污染面向用户的文档与示例，也没有破坏底层的角色-模型路由契约。

为什么模型迁移需要专门的 QA 证据文件

在 OmO 中，模型推荐同时出现在两类位置：

1. 用户可见面：README（五种语言）、docs/下的指南与 JSONC 示例、网站文案（packages/web/messages/下的多语言文件）；
2. 实现契约面：packages/model-core/src/agent-model-requirements.ts 与 packages/model-core/src/category-model-requirements.ts 中为每个 agent 角色（metis、prometheus、sisyphus 等）和任务类别（ultrabrain、deep、quick 等）定义的回退链（fallback chain）。

模型换代（Opus 4.6/4.8 → Opus 5）时，两类位置都会变化，且失败模式不同：文档面容易出现“漏改的旧版本号”（用户会照着过时的模型名去配置），实现面容易出现“回退顺序或变体被悄悄改动”（运行时路由行为漂移）。因此这次迁移的验证被组织成六个互不重叠的层，每层保护一种明确的风险，并在证据文件中留下“测了什么、观察到什么、为什么足够、刻意省略了什么”的完整记录。

第一层：陈旧推荐审计（RED → GREEN 的锚点测试）

证据文件中的第一条测试是：

bun test script/opus5-model-recommendation-audit.test.ts

它的作用是“证明用户可见的 README、指南、JSONC 示例、模型需求文件与网站文案中，不再包含任何 Opus 4.6 或 4.8 的推荐”。

从源码结构看，script/opus5-model-recommendation-audit.test.ts 的实现非常直白：

• 维护一个 21 个文件的白名单RECOMMENDATION_FILES，覆盖：
  • 五份 README：README.md、README.ko.md、README.ja.md、README.ru.md、README.zh-cn.md；
  • 七份文档：docs/guide/agent-model-matching.md、docs/guide/orchestration.md、docs/guide/installation.md、docs/guide/overview.md、docs/reference/configuration.md、docs/reference/features.md；
  • 三份 JSONC 示例：docs/examples/coding-focused.jsonc、docs/examples/default.jsonc、docs/examples/planning-focused.jsonc；
  • 两份模型需求源码：packages/model-core/src/agent-model-requirements.ts、packages/model-core/src/category-model-requirements.ts；
  • 四份网站文案：packages/web/messages/en.json、ja.json、ko.json、zh.json。
• 用一个正则/\b(?:claude[- ]?)?opus[ _-]?4[._-]?(?:6|8)\b/i匹配任意形式的 “opus 4.6 / 4.8” 写法（允许claude-前缀、以及-、_、.等分隔符变体）；
• 并发读取全部文件后断言命中的文件列表为空。

这条审计的价值在于它把“迁移完成”定义成了一个可机械判定的命题：只要任何一份用户可见文件里残留旧模型号，测试就会失败。证据文件记录了它在迁移前被捕获为 RED、迁移后转为 GREEN（1 pass, 0 fail）——这种“先红后绿”的记录正是证据文件的意义所在：它不只是“测试通过了”，而是“我们确实在迁移前抓到了真实缺陷”。

值得强调的是，这个审计至今仍在仓库中生效。在迁移完成后的仓库树上，对上述 21 个文件逐一检索opus 4.6/4.8模式已经没有任何命中，说明该门禁持续守护了后续的多次模型更新。

第二层：角色与能力契约测试（钉死回退顺序）

证据文件中的第二条测试是：

bun test packages/model-core/src/model-requirements-agents.test.ts \ packages/model-core/src/model-requirements-categories.test.ts

它保护的是“精确的 Metis 与 Prometheus 选择顺序和变体”。证据文件记录，迁移后的断言为：Metis 解析为 Opus 5 high，再落到 Kimi K3 low；Prometheus 解析为 Fable 5 xhigh，再落到 Kimi K3 max。

这类测试的写法在 packages/model-core/src/model-requirements-agents.test.ts 中可以看到典型形态——直接对fallbackChain的逐位断言，例如对 metis 的三级链：

const metis = AGENT_MODEL_REQUIREMENTS["metis"] expect(metis.fallbackChain).toHaveLength(3) expect(primary).toEqual({ providers: ["anthropic", "github-copilot", "opencode"], model: "claude-fable-5-1", variant: "max", }) expect(opusFallback).toEqual({ providers: ["anthropic", "github-copilot", "opencode"], model: "claude-opus-5", variant: "max", }) expect(kimiFallback).toEqual({ providers: ["opencode-go", "kimi-for-coding", "moonshotai", "opencode"], model: "kimi-k3", variant: "max", })

从当前仓库的源码看，迁移之后这些链继续演进：packages/model-core/src/agent-model-requirements.ts 中，prometheus 现为claude-fable-5-1 xhigh → kimi-k3 max两级链，metis 现为claude-fable-5-1 max → claude-opus-5 max → kimi-k3 max三级链。这恰好印证了证据文件的隐含方法论：每次模型换代都必须同步更新这些逐位断言，否则契约测试会立刻报警——它们既是回归防线，也是“链已随模型换代更新”的活文档。

类别侧的 packages/model-core/src/model-requirements-categories.test.ts 则对 ultrabrain、deep、quick、unspecified-high 等任务类别的整条链做toEqual全量断言，并附带像“deep 和 artistry 不再硬性要求主模型”（requiresModel为 undefined）这类迁移期的行为变化断言。

第三至四层：类型检查与网站构建

证据文件接着记录了两个构建面验证：

bun run typecheck

• 验证根目录、scripts/与packages/的 TypeScript 类型正确性，防止迁移改动（常量改名、字段结构调整）在静态层面引入破坏。

cd packages/web && bun run type-check && bun run build

• 验证网站构建面：对 packages/web 独立执行类型检查与 Next.js 生产构建。之所以单独列出，是因为多语言模型文案（如 packages/web/messages/en.json）属于“打包产物”的一部分——文案错误只有走完整构建流程才能暴露。

第五层：无头 Playwright 渲染验证

证据文件记录了在构建产物上对/en页面运行 Headless Playwright，观察到渲染内容中出现了Claude Opus 5 High与Claude Fable 5 XHigh两个迁移后的模型标签。

这一层保护的是“构建成功 ≠ 用户看到的是新文案”的风险：静态文件、消息字典与页面组件之间存在组合关系，只有真正加载构建出的站点、检查 DOM 输出，才能确认用户实际渲染出的模型名称已经是迁移后的版本。证据文件同时说明，为这次无头 QA 临时启动的本地 web 服务器在验证结束后已被终止，不残留任何本地状态。

第六层：全量仓库测试门禁

最后一层是：

bun test --reporter=dot

证据文件记录最终全量门禁结果为：12,151 通过、3 跳过、0 失败，覆盖 1,555 个文件。这一层不针对迁移本身，而是保证迁移没有以破坏任何其它模块的方式“挤”进代码库——它是打包与集成行为的兜底。

证据文件如何回答“为什么这些足够”

qa-summary.md 的 “Why this is enough” 一节给出了一段精炼的覆盖性论证，其逻辑是每一层对应一类风险，六层合起来构成闭环：

刻意省略什么：证据的卫生规范

文档的 “What was omitted” 一节同样值得学习：

• 原始环境转储、provider 凭据、生成的日志一律不写入证据；
• 临时用于无头 QA 的本地 web 服务器在验证后终止。

这表明该团队的证据规范是“只留可复现的结论与可执行的命令，不留环境与凭据的原始快照”——任何人拿着这份文件都能逐条重跑验证，但不必、也不应接触任何密钥或噪声日志。

与当前仓库状态的交叉印证

迁移证据是历史快照，而仓库是活的。对照当前仓库内容可以确认两件事：

1. 审计持续有效：对 21 个受审计文件做全量检索，opus 4.6/4.8模式的旧推荐已经不存在；当前文档与网站面向用户的模型面使用的是 Opus 5 一代及后续模型。
2. 契约链继续演进：迁移后 metis、prometheus 的回退链已更新到 Fable 5.1 时代（见 agent-model-requirements.ts 与 model-requirements-agents.test.ts 中的逐位断言），网站展示面也更新为新的模型标签（例如 packages/web/app/design/_showcase/ledger.tsx 中展示Claude Fable 5.1 Max）。可以推断，每次这样的换代都会重复本文描述的分层验证并留下对应的证据文件。

可复制的迁移 QA 清单

把这份证据文件的方法提炼出来，任何“影响用户可见推荐内容的版本迁移”都可以套用：

1. 先写一条 RED 测试：用正则/快照机械判定“旧版本标识仍出现在用户可见文件清单中”，在迁移前确认它会失败；
2. 对运行时契约写逐位断言测试：不测“大概路由正确”，而是钉死顺序、providers 与 variant；
3. 把构建面（类型检查 + 生产构建）独立成层，尤其是多语言文案参与打包的项目；
4. 用无头浏览器对构建产物做渲染断言，验证“用户实际看到的”而非“构建成功与否”；
5. 以全量测试作为最终集成门禁；
6. 写一份证据文件，固定四个小节：测了什么（命令）、观察到什么（含 RED→GREEN 与量化结果）、为什么足够（风险映射）、刻意省略什么（卫生规范）。

这套实践的全部原始证据都可以直接在仓库中复核：入口是 .omo/evidence/20260725-opus5-migration/qa-summary.md，配套实现见 script/opus5-model-recommendation-audit.test.ts、packages/model-core/src/model-requirements-agents.test.ts 与 packages/model-core/src/model-requirements-categories.test.ts。

【免费下载链接】oh-my-openagentOmO: Just type "mass ulw" keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent