从 27/0 到真实浏览器：交互式实训生成器的可复现验证链

生成一个单文件 HTML 实训页面，看起来很容易：输入场景 JSON，运行生成脚本，再打开页面检查标题和按钮。但在实际工程里，这一步经常把“文件生成了”误当成“产品可用了”。我最近用华为云 AI 办公实践中心的 interactive-practice-gen 做了一次干净环境复现，得到的结论很明确：逻辑桩件全部通过，不能替代真实浏览器验证；而验证链本身必须可复现。

一、复现目标与环境

目标是验证“校园宿舍消防安全隐患巡查与处置闭环”示例能否从场景 JSON 生成一个可交互的静态实训页面。测试基线为 GitCode 仓库 agent-best-practices/skills 的 commit：

5897aaf60fb5ab2a65a93af20530d7b22baf7876

在干净目录中依次执行：

python3 generate.py examples/campus_fire_patrol.json -o /tmp/campus.html
node tests/logic_check.js /tmp/campus.html
node tests/browser_check.js /tmp/campus.html

前两步的结果符合预期：生成器输出约 65.2 KB 的 HTML，并通过语法检查；逻辑检查 27 项通过、0 项失败，覆盖场景注入、S0-S8 流程、四步处置、评分引擎、telemetry 和闭环漏检等关键断言。

二、为什么 27/0 还不够

第三层验证启动时，立刻出现了另一个问题：

Error: Cannot find module 'playwright-core'

这说明逻辑测试通过后，浏览器测试并没有真正开始。原因不是生成的 HTML 有缺陷，而是测试脚本需要 Node 模块 playwright-core，当前技能的说明没有给出可执行的依赖安装入口，仓库里也没有一个能直接安装该依赖的 package manifest。

这也是自动化验证中很容易被忽略的分界点：

1. 生成成功：证明脚本能产出文件，不代表页面能运行。
2. 逻辑通过：用桩件 DOM 验证状态机和业务函数，不代表真实浏览器能加载、渲染和点击。
3. 浏览器通过：只有真实浏览器完成加载、交互和结果断言，才能证明用户路径可用。

如果测试框架把第三层失败显示成“未执行”，而报告封面仍写着“全部检查通过”，维护者就会得到一个错误的安全感。因此，验证报告必须把“跳过、依赖缺失、真实失败”分开记录，不能用同一种绿色状态表示。

三、把可复现验证做成三层质量门

第一层：静态生成契约

先锁定输入、输出和基线版本。生成后至少检查：

• 输出文件存在且大小合理；
• HTML 标题与场景配置一致；
• 场景数据被正确注入；
• 页面不依赖未声明的外部资源；
• 基线 commit 和生成命令可被另一位工程师原样复现。

第二层：桩件 DOM 逻辑测试

这一层适合快速验证状态机、评分和异常分支。本次 27 项断言就属于这一层，它能在几秒内发现业务逻辑回归，但它的 DOM 是模拟的，无法验证浏览器中的布局、事件绑定和第三方依赖加载。

第三层：真实浏览器冒烟测试

真实浏览器至少完成四步：

1. 页面加载成功，标题和主入口可见；
2. 点击“开始任务”，状态从 S0 进入 S1；
3. 至少点击一个异常对象，确认时间线和步骤状态发生变化；
4. 导出 telemetry，检查事件结构可被解析。

本次在浏览器中实际加载后，页面标题、场景说明、对象档案和“开始任务”按钮均正常显示；点击后进入“探索”步骤，进度变为 11%，说明 HTML 的初始交互链路有效。但自动化 browser_check.js 因 Node 依赖缺失未能执行，所以不能把自动浏览器校验标记为通过。

四、依赖缺失时应该怎样报错

比起直接抛出 MODULE_NOT_FOUND，测试入口更适合做一次前置检查：

browser_check 未执行：缺少 playwright-core。
请先按仓库文档安装浏览器测试依赖，再重新运行。

同时建议仓库提供最小 package.json，将浏览器测试依赖声明为 dev dependency，并让测试命令统一入口，例如：

npm install
npm run test:logic
npm run test:browser

对于 CI，则应把依赖安装、浏览器可用性和测试断言拆成三步。任何一步失败都返回非零退出码，并在报告里明确写出“已执行/未执行”，避免把环境缺失伪装成业务通过。

五、本次复现的结论

这次真实复现带来的价值，不只是发现一个模块导入错误，而是确认了一条更稳妥的验证原则：生成器项目的质量门必须覆盖“静态产物、业务逻辑、真实浏览器”三层；每层都要有清楚的执行边界和失败语义。

逻辑测试的 27/0 是积极信号，但它不是最终验收。只有把依赖、命令、基线 commit、输出和真实用户路径一起固定下来，后续维护者才能准确判断问题出在生成内容、业务逻辑，还是测试环境本身。相关可复现问题已记录在 GitCode Issue #46，后续可以在修复后用同一组命令进行回归对照。

复现与验证的关键不是“跑过一次”，而是让下一位工程师能够在干净环境中得到同样结果，并能从报告中一眼看出：哪些检查真的通过，哪些检查根本没有开始。