# 重构后的多轮复盘与 npm 准入

2026-09-10 用户要求：实现完成后继续进行多次全局复盘，以达到可以发布到 npm 的质量。复盘是必须完成的验收工作；规划完成、源码迁移完成、发布就绪和实际发布分别报告。

## 浏览器验证的分工

本地验收优先复用 [docs HTML 与在线编辑器](docs-browser-testing.md)，保留旧页面/参数并核实每个资源的候选来源。REVIEW-02 检查这些入口的实际行为，REVIEW-03 核对测试页面加载内容与待发布包一致。

| 方式 | 负责内容 | 证据和边界 |
| --- | --- | --- |
| API/类型/产物自动测试 | 旧调用、返回值、事件语义、声明、入口及新旧核心/插件组合 | 对固定旧 tarball 和候选 tarball 使用相同用例；不以编译成功代替运行验证 |
| 用户连接的 @Chrome | 本地 demo 的实际点击、拖动、键盘、播放、切源、字幕、控件、销毁重建及故障排查 | 记录 Chrome/系统版本、操作步骤、状态断言、错误和截图；一次交互验收不能代替持续回归 |
| Codex 内置浏览器 | Chrome 不可用时接续其支持的真实页面/API/媒体/交互验证 | 用户已明确授权自动回退；记录实际浏览器、版本、操作和限制，不将结果标成外部 Chrome 或真实设备通过 |
| 仓库浏览器自动化 | 将稳定回归用例保存为测试，运行 Chromium/Firefox/WebKit 及所需正式 Chrome 组合 | 固定样本、环境和版本，CI 保存报告及失败证据；Playwright 的 WebKit 不等于真实 Safari |
| 设备和外部资源 | iPhone/iPad Safari、Cast 接收端、相关 PiP/codec/SDK/广告/模型路径 | 按 BASE-08 的支持矩阵验证；模拟尺寸、mock 和其他浏览器的通过不能代替真机结论 |

@Chrome 用于本地演示和候选产物验收，稳定场景同步沉淀为仓库测试。发布验收应加载与待发布内容一致的候选包；仅测试 docs/uncompiled 的源码开发构建不足以批准发布。

2026-09-10 用户补充：Chrome 不可用时使用内置浏览器。无需等待扩展恢复即可继续它支持的验证；若特定能力不支持，再将该能力登记为未验证并继续其他任务。内置浏览器已实际打开固定发布包的 api.html，9 项基础 API 检查通过，页面 errors 为空；播放推进、切源、设备/SDK 及完整 API 基线仍分别验收。

播放验证至少检查媒体时间确实推进、暂停后停止、seek 到达预期位置、切源后旧异步结果不覆盖新状态、事件次数/顺序符合契约、插件 UI 与实际轨道一致、销毁后资源被回收。不能只凭页面加载、截图或播放按钮变化判断成功。事件比较允许有依据的浏览器差异，遵循 testing.md 的语义断言规范。

环境事实：2026-09-10 已通过浏览器工具清单确认 Chrome 扩展连接可用；当时未运行播放器用例、未确认 Chrome 版本，也未核实真机或接收设备可用性。此事实会过期，每次验收重新检查，不填写为测试通过。

技术依据：[Playwright 浏览器支持](https://playwright.dev/docs/browsers)、[设备模拟范围](https://playwright.dev/docs/emulation)。实际建设测试框架时再次核对选定版本。

## 三轮完整复盘

默认至少三轮，各有独立任务、报告和完成提交。首轮可在本地候选形成后先审查代码，待验证的设备能力必须继续留在后续门槛；不能借首轮完成宣称整个项目发布就绪。

首轮不依赖 MOD-05 的重型插件真机汇总；需要该证据的能力转由 REL-03/REVIEW-02 验收，避免间接设备依赖阻止先审代码。版本修改先由 REL-09 落实，首轮使用 REL-02 在目标版本下生成的候选。

| 任务 | 范围 | 通过条件 |
| --- | --- | --- |
| REVIEW-01 架构与兼容性 | 全部 22 包、模块边界、依赖方向、生命周期、TS 推断、公开契约、历史路径、测试盲区和 AI 维护文档 | 逐包有审查结论和旧版对照；本轮阻断项修复并复测，环境缺口明确转交 REVIEW-02 |
| REVIEW-02 浏览器与生态集成 | 全项目 demo/消费者、旧插件+新核心、新插件+支持的旧核心、媒体故障/并发/销毁、真实设备、性能及资源 | REL-03 的全范围环境验收通过；本轮问题闭环，必要组合没有未知或缺失证据 |
| REVIEW-03 npm 候选包与发布准备 | 干净安装/构建、隔离消费者、文件与入口、声明/资源/许可、独立版本及依赖范围、变更日志、发布目标/tag、回退和前两轮证据时效 | 准备发布的包完整性与已测内容一致；阻断项为零，报告足以让用户审阅具体发布批次，不执行发布 |

复盘覆盖全范围，改变检查重点而非仅重复同一条测试命令。可在后续用户任务中分轮执行；本规范不自动创建新对话或代理。若需要更多轮次，新增 REVIEW-04 等任务及发布依赖，保留已有 ID 和历史。

## 发现、修复和重新验收

- 每项发现记录固定 ID、范围、严重程度、源码/候选标识、旧版复现、预期/实际行为、最小复现、修复任务和复测证据。报告必须列出已检查范围、未覆盖范围及其原因。
- 兼容破坏、关键功能失败、未解决的发布相关安全问题、缺失必要环境证据、错误包内容及不可复现构建均阻断相应发布。低风险非阻断项仍需理由、影响和后续任务，不因测试多次通过就自动豁免。
- 问题修复拆成独立任务，例如 REVIEW-FIX-01；每完成一项立即提交。复盘任务在阻断项关闭后单独提交报告和状态，不能将多项已完成修复累计在一个复盘提交中。
- 修复后重跑复现用例及受影响回归；修改核心或共享构建时扩展到生态组合。下一轮再次检查前轮修复，防止修复引入回归。
- 新提交、依赖锁、版本或构建配置改变时，重新生成候选并核对内容，更新受影响证据。REVIEW-03 最终需要对实际候选完整执行发布检查；不能直接沿用不同 tarball 的绿灯。
- 每轮报告保存起止源码标识、逐包候选 integrity、工具/浏览器/系统版本、样本、命令、通过/失败/跳过/重试数、持久报告链接和未决项。旧报告保留历史事实；证据过期时新增复验任务和发布依赖，不把历史 done 当作当前准入。

## 发布关系

REVIEW-03 必须逐包核对 [全包大版本目标](version-policy.md)、依赖范围、变更日志和候选标识；升级 major 不代表允许破坏旧调用或强制用户同时升级核心和插件。

REVIEW-03 还依赖 CI-04，核对 [GitHub CI/CD](github-ci-cd.md) 的真实检查结果、候选来源和必要远端配置。只有 YAML 或本地 dry run 通过，不能声称 npm 发布权限及正式工作流已验证。

REVIEW-01 -> REVIEW-02 -> REVIEW-03 -> REL-05（经授权候选发布）-> REL-06（经授权正式发布）。REL-03 的真机验收与 REL-04 的回退演练继续保留；复盘不替代它们。代码迁移完成后仍需完成这些门槛。

用户在复盘后审阅具体发布批次：包/版本、目标 registry/tag、兼容结论、候选 integrity、剩余非阻断项和回退方法。表达将来发布到 npm 的目标不等同当前执行 publish；可以自主完成本地准备与复盘。

REL-08的[逐包台账](release-ledger.md)负责候选和证据的机械绑定。CI-03及REVIEW-03应对
具体批次运行`yarn release:preflight --packages ...`，缺口会退出1；普通
`check:release-ledger`的结构检查通过不能代替它。封套和实际附件仍须逐项审阅，
脚本不会验证报告叙述真实性、执行设备测试或授权发布。

候选反馈导致修复时，先创建修复和复验任务，重新核对前三轮受影响结论及最终候选内容，再进入正式发布。即使前三轮任务历史已 done，发生变化后也不能直接发布。分批交付遵循 execution-gates.md，每批具备同等三轮审查和必要环境证据，不以分批绕过全项目要求。