ArtPlayer/refactor/README.md

# ArtPlayer 兼容性重构

本目录是核心、插件、proxy、工具和开发流程重构的长期工作记录。目标是让实现、类型、测试和构建更易维护，同时让已有用户继续使用原来的接口。

## 基线与范围

- 创建日期：2026-09-10。
- 工作分支：`codex/compatible-modernization`。
- 起点：`master`，`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。
- 清点范围：22 个 workspace 包，包括核心、16 个插件、2 个 proxy、2 个工具、1 个文档站；另含 React/Vue 示例、浏览器 demo、构建和发布脚本。
- 已进入实施，真实发布基线及当前执行结果见 progress.md；生产迁移与测试基础设施进度分别记录。提交以任务 ID 对应的 Git 历史为准；本地提交不代表已推送或发布。
- 本目录位于仓库根目录，避免被 `docs/` 的站点部署流程直接作为产品文档发布。

## 从哪里开始

| 文档 | 用途 |
| --- | --- |
| [完整执行计划表](plan.md) | 每一步的固定 ID、依赖、具体交付物、验收条件、风险及状态 |
| [全项目质量要求](quality-contract.md) | 用户确认的自主改造范围、文件拆分、AI 维护文档和有效测试的共同验收条件 |
| [阶段路线](roadmap.md) | 执行顺序、里程碑、范围和阶段出口 |
| [执行门槛与分批交付](execution-gates.md) | 最小启动基线、早期试点、历史失败、设备门槛和分包准入 |
| [兼容性契约](compatibility.md) | 不可静默改变的接口、行为、类型、样式与包分发约定 |
| [契约覆盖与证据索引](contract-coverage.md) | 22包逐类责任、稳定测试ID、精确版本依据和候选/历史报告对应 |
| [核心设计](core-design.md) | 核心各模块的目标职责、迁移方式和生命周期设计 |
| [核心阶段验收范围](core-acceptance.md) | 核心契约、已处置差异、性能风险与后续生态/发布门槛 |
| [包迁移规范](packages.md) | 全生态统一流程、组合矩阵及包特有风险 |
| [测试与验收](testing.md) | 测试层次、浏览器/消费者矩阵、证据和回归门槛 |
| [已落实的测试可靠性规则](test-reliability.md) | 历史失败、候选回归、设备缺口、精确异常及等待/重试的执行规则 |
| [docs 页面与编辑器测试](docs-browser-testing.md) | 复用已有 HTML、加载版本、隔离状态和补强文档 smoke |
| [多轮复盘与 npm 准入](release-reviews.md) | Chrome 验证分工、三轮全局复盘、问题闭环和候选发布门槛 |
| [工具链与发布](toolchain-release.md) | TypeScript、Bun、构建、版本管理和发布回退 |
| [已实现的开发环境](toolchain-setup.md) | Node/Yarn 固定版本、锁文件、安装命令和实际验证范围 |
| [全包大版本策略](version-policy.md) | 每包分别升级一个 major 的目标清单、兼容要求和版本落地步骤 |
| [已实现的 CI 入口](ci-setup.md) | Yarn 检查/构建、只读 lint、Pages 隔离及远端待验收状态 |
| [GitHub CI/CD](github-ci-cd.md) | PR/兼容矩阵、构建报告、Pages、npm 发布及远端准入验证 |
| [AI 协作流程](ai-workflow.md) | AI 接续工作、任务边界、验证、记录和交接模板 |
| [每任务提交审计](commit-audit.md) | 实际Git状态迁移、独立提交、初始例外、分支合并和CI报告 |
| [全包影响映射](impact-analysis.md) | 变更范围、依赖/验证关系、必需CI命令及尚缺的包验证 |
| [架构决策](decisions.md) | 已选方向、待验证方案及被拒绝方案 |
| [进度与证据](progress.md) | 本次会话结果、阻塞、下一步；不重复维护每个任务状态 |
| [变更记录模板](changes/TEMPLATE.md) | 每次行为/类型/结构变化的详细记录 |
| [任务数据](tasks.json) | 任务状态和依赖的唯一数据来源 |
| [包基线](package-inventory.json) | 包版本、入口、声明、源码清单及对应 demo 的初始快照 |
| [发布基线与重跑说明](baselines/README.md) | 固定 npm tarball、完整性及已知源码/发布差异 |
| [差异与风险索引](risk-table.md) | 已复现问题、源码事实和待核实事项的责任任务 |
| [风险维护说明](risk-guide.md) | 证据等级、关闭条件、第三方边界和校验命令 |
| [第三方来源清单](third-party.json) | 依赖解析、vendor 文件指纹、SDK/CDN 与许可来源缺口 |
| [消费者与真实环境矩阵](environment-matrix.md) | 22 包的版本依据、能力/设备/样本、现有证据、验证任务及发布影响 |
| [类型检查与迁移入口](typechecking.md) | 根/分包配置、当前/旧编译器、严格正反例和历史声明错误 |
| [核心公共类型出口设计](core-public-types.md) | CORE-21 的声明生成、旧编译器兼容、精确入口和编辑器验收 |
| [JS/TS 构建与开发](build-development.md) | 非交互选包、开发重建、资源夹具和 AMD 全局修复 |
| [测试目录维护说明](../test/README.md) | 统一测试命令、JS/TS loader、受控媒体及新旧公共契约 |
| [真实浏览器入口](../test/browser/README.md) | 三浏览器、解码画面与媒体状态、Range/失败服务及候选文件映射 |
| [实际打包消费](../test/package/README.md) | 仓库外安装、运行时/声明检查、安装产物浏览器验证与严格发布检查 |

## 维护规则

1. 任务状态只修改 `tasks.json`；运行 `node refactor/scripts/plan.mjs --write` 更新计划表。
2. 运行 `node refactor/scripts/plan.mjs --check` 检查任务 ID、依赖环、包覆盖、完成证据、本地文档链接和生成表同步。它检查链接文件存在，不验证网页可用性或 Markdown 标题锚点。
   校验同时保护试点/首轮设备依赖、版本准备、CI/复盘发布门槛，以及全部实施任务到最终里程碑的可达性；测试本身是否有效仍需逐任务验收。
3. 开始前选择一个依赖已完成的任务。拆分任务时保留旧 ID 的历史，不复用 ID。
4. 有实现变更时，在 `changes/` 创建记录，补充基线、测试证据、兼容差异和回退方式，再将任务标为完成。
5. 当前源码、已发布包、声明和文档有冲突时，先登记差异；不得把其中任何一个自动当作全部用户行为的唯一依据。
6. 修改架构方向时更新决策记录；完成会话时更新 `progress.md` 的下一步。
7. `package-inventory.json` 是初始基线，保留不覆盖。未来新增/删除包需独立记录范围变更，并扩展校验器识别新基线。
8. 每完成一个任务，立即单独提交一个本地 commit，提交信息包含任务 ID；对应实现、测试、文档、任务状态和生成表同次提交。确认提交成功后再开始下一任务，不累计多个已完成任务后统一提交。

## 状态和风险

- `todo`：尚未开始；`doing`：执行中；`blocked`：有明确阻塞；`done`：有验收证据；`deferred`：明确延期并登记影响。
- 风险 `L/M/H` 分别表示低、中、高兼容风险，不是工期。高风险步骤必须先有行为基线和回归用例。
- 不给所有任务承诺日历工期。先完成一个小插件试点，再按实际实现、浏览器验证和审查成本估算批次；AI 生成速度不等于验证速度。

## 重构完成的定义

完整计划内任务都有结论，22 个包均有迁移及兼容证据，旧调用样例无需修改即可通过，发布包与目标浏览器验证通过，已知差异有处理结论，文档、源码、声明和构建产物保持一致。外部 SDK、真机或旧版本验证缺失时，明确保留阻塞，不能用 mock 通过替代。

所有实施任务同时满足 quality-contract.md 的结构、类型、兼容、测试、文档及交接要求。任务表允许根据审查发现继续扩展，190 项是初始计划，不是限制改善范围的上限。