ArtPlayer/refactor/rollback-rehearsal.md

回退演练与维护入口

REL-04 的早期演练已完成，覆盖核心/Chapter 连续安装、iframe 更名、主线冲突同步和旧站点本地恢复。正式候选逐包回退由 REL-02 承接，并受发布台账及 REVIEW-03 约束；本页不代表所有包或最终大版本候选已可回退。

已实现的安装演练

固定 Node .node-version、Yarn Classic 1.22.22，先运行 yarn test:package，再运行 yarn test:rollback。前者在隔离快照中执行正常生产构建、类型生成和打包；后者读取 同一 HEAD 的构建报告及已冻结 npm 历史 tarball。不会改写工作区生产产物或根锁文件。

scripts/rollback-consumer.mjs 建立四套消费者 manifest/lock：旧核心+旧插件、 新核心+旧插件、旧核心+新插件、新核心+新插件。准备锁文件时从根锁解析离线依赖， 随后在同一个仓库外消费者目录中连续执行以下步骤：

步骤	安装状态	验证意图
install-old	旧核心+旧插件	原始安装
upgrade-core	新核心+旧插件	独立升级核心
upgrade-plugin	新核心+新插件	升级插件
rollback-plugin	新核心+旧插件	单独回退插件
restore-candidate	新核心+新插件	恢复升级状态
rollback-core	旧核心+新插件	单独回退核心
rollback-all	旧核心+旧插件	恢复完整旧组合

每一步恢复对应 manifest/lock 后执行 Yarn install --offline --frozen-lockfile --force --ignore-scripts --non-interactive；不会先删除 node_modules，因此能够检测 替换过程中遗留的新版文件。冻结锁字节必须不变，所有包成员及文件清单必须与实际 tarball 一致。版本号相同也检查内容；例如本次 Chapter 新旧均为 1.1.0。

scripts/rollback-files.mjs 专门检查安装清单、成员哈希和 workspace/symlink 逃逸。 仅忽略包根目录的 Yarn .yarn-metadata.json、.yarn-tarball.tgz 安装元数据。 负例覆盖相同版本的错误内容、新版残留文件及缺失文件；纳入 test:node。 消费者临时目录在成功或失败后清理，日志、锁和已核验安装副本保存在 refactor/.cache/rollback/run-*，latest.json 指向最近一次结果并记录成功状态。

复用 test/package/runtime.cjs 检查实际 CJS/ESM/UMD/AMD/legacy/i18n、SSR 与 Emitter/公开形状。旧核心显式使用历史配置，保留历史 SSR 失败断言；不会因为 回退而要求旧包支持新 /runtime 入口。安装脚本禁用不代表验证了 lifecycle hooks。

真实浏览器验证

设置 ARTPLAYER_BROWSER_ARTIFACTS 为成功演练输出中的某个 <action>-browser-artifacts.json，运行 yarn test:rollback:browser。 playwright.rollback.config.js 复用已提交播放用例，三引擎、零自动重试；检查实际 解码像素、播放、暂停、seek、切换 docs 媒体、Chapter DOM、事件与 destroy。

scripts/rollback-artifacts.mjs 在浏览器启动前校验：演练已成功、HEAD/Node 一致、 候选构建输入仍匹配当前源码/工具链、包来自已验证候选或冻结历史 archive、安装 副本所有文件和对应锁哈希一致。直接使用普通 installed runner 会因报告不是 ENG-07 而被拒绝；保留该门槛，回退使用独立验证入口。

浏览器通过独立 fixture 服务读取已核验安装副本，不是从仍存活的临时消费者目录 加载。用例中的 candidate 是路由名，具体版本以演练 profile 为准。 报告写入 refactor/.cache/rollback-browser；连续测试不同状态前，在前一进程 结束后把报告移入唯一 cache 子目录，防止覆盖。端口沿用测试服务 8084。

当前结果与剩余工作

2026-09-15，七步安装/回退均通过，共 237 个运行时检查；五组状态在三个桌面引擎中 15/15 真实播放通过。隔离候选构建另有 5/5 旧类型模式、8/8 精确类型模式通过。 详见 机器证据 和 检查点。

后续检查点已补齐22 包恢复清单、iframe 更名安装回退以及 JS→TS 冲突同步/中止演练。yarn check:rollback-inventory 校验生成表并重新检查 20 份完整冻结 archive；CI 的 ci:check 同样运行该检查。缺失 tarball 时只按 冻结 registry URL/完整性恢复缓存，不查询或跟随 latest。

iframe 更名回退

运行 yarn test:rollback:iframe。scripts/iframe-rollback.mjs 在隔离构建快照内 用正常构建器打包当前 tool 包，并从冻结来源验证旧 plugin 包。先准备两套应用 manifest、lock 和导入代码，再在同一仓库外消费者中依次安装旧包、升级新包、恢复 旧包。检查完整成员、冻结锁、应用代码哈希和被替换包目录确实消失；各步另有实际 require/helper/legacy 及 TS 5.9.3 strict 消费者验证。

实际旧包 artplayer-plugin-iframe@1.0.0 的根 require 返回对象，构造类位于 .default，并有独立 helper 文件；新 tool 包根 require 直接返回类。负例已实际 把旧 tarball 安装在新的依赖键下，确认构造和 /legacy 均无法沿用新版写法。 这是本地 file 依赖键映射验证，没有声称执行过 registry 的 npm alias 协议。 回退要恢复应用导入代码和包名/锁，不能只换版本或别名。

输出为 refactor/.cache/iframe-rollback/run-*，包括两套锁、应用代码、构建及 安装日志和报告。该演练覆盖安装/导出/类型恢复，iframe 真机和跨窗媒体测试仍由 PKG-IFRAME-05 承担，不借此关闭其门槛。

主线修复同步与中止

运行 yarn test:rollback:mainline。scripts/mainline-rehearsal.mjs 在仓库外创建 独立 Git 仓库，合成 JS 计算模块迁移至两个 TS 模块后，主线修复旧文件的情形。 它实际复现负数计算的断言失败、cherry-pick 的 modify/delete 冲突；先中止并验证 HEAD/tree/工作区完全恢复，再次应用并把修复移入 TS 计算模块。最终回归通过、旧 JS 文件不存在、提交中保留 cherry-pick -x 来源。原仓库没有被切换分支或 cherry-pick。

Git fixture 只使用目录内身份配置，禁用全局配置；所有命令/退出码、断言、冲突内容、 最终 patch 和可验证 Git bundle 保存到 refactor/.cache/mainline-rehearsal/run-*。 失败也写报告，并清理已验证的临时消费者目录。该合成演练验证工作流，不代表发现或 修复了真实 ArtPlayer 重试逻辑问题。

实际同步时先 git fetch origin master，记录 git rev-list --left-right --count HEAD...origin/master 及修复 SHA，再审查每个上游 diff。找出迁移后的责任模块， 为原缺陷补可重跑回归，在隔离工作树应用 git cherry-pick -x <已核实修复SHA>。 发生冲突时审查 git status、git ls-files --unmerged 和上游完整 diff，不能为 结束冲突而直接恢复已淘汰 JS 文件。修复迁移后的对应模块、暂存明确文件、运行相关 单元/类型/浏览器检查，再 git cherry-pick --continue。无法正确落地则 git cherry-pick --abort，核对原 HEAD/tree 和工作区状态后登记待同步项。 每个实际修复仍建立任务、保留上游归属、独立提交并通过提交审计。

本次再次 fetch 后 master 仍无新增提交；真实仓库没有需要应用的修复。冻结起点和 当前差分记录在后续检查点证据。

文档站的固定旧快照已通过完整本地恢复， 包括全部 538 个文件、12 条 HTTP 路径和六项播放检查。Thumbnail 的完整旧 npm tarball 缺失、文档站的真实远端部署恢复继续受原有发布门槛约束。 REL-02 在 REL-04 早期演练完成后，仍须逐包准备完整回退产物，并重新绑定实际 next-major 候选及旧包产物、应用导入和冻结锁，重跑对应验证。Thumbnail 归档 缺口继续阻止该包准入，远端恢复仍由 CI-04 验证；不以本地演练替代。 不执行 npm tag 修改、unpublish、推送或部署，不把本演练当作这些动作的授权。

2026-09-15 的早期验收在 8dcbe9441eb06971a34785857f9cf47451047bb5 重新构建并执行七步连续安装、 五种状态的三浏览器播放、iframe 和主线同步演练。旧站点恢复实现与实际交付提交 ddf3d6ccb 一致，本轮重新核验已恢复的 538 文件及 HTTP/播放；未再次破坏和恢复 站点。新增发布负例确认：即使早期任务完成，缺少候选回退报告、候选版本错误或 tarball 不一致仍拒绝准入。机器证据 保留输入身份、报告哈希、验证范围与取消请求；早期报告不能直接登记为最终发布证据。