ArtPlayer/refactor/README.md

# ArtPlayer 兼容性重构

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

## 基线与范围

- 创建日期：2026-09-10。
- 工作分支：`codex/compatible-modernization`。
- 起点：`master`，`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。
- 清点范围：22 个 workspace 包，包括核心、16 个插件、2 个 proxy、2 个工具、1 个文档站；另含 React/Vue 示例、浏览器 demo、构建和发布脚本。
- 当前完成的是计划与文档基础设施，生产代码重构尚未开始。提交以任务 ID 对应的 Git 历史为准；本地提交不代表已推送或发布。
- 本目录位于仓库根目录，避免被 `docs/` 的站点部署流程直接作为产品文档发布。

## 从哪里开始

| 文档 | 用途 |
| --- | --- |
| [完整执行计划表](plan.md) | 每一步的固定 ID、依赖、具体交付物、验收条件、风险及状态 |
| [全项目质量要求](quality-contract.md) | 用户确认的自主改造范围、文件拆分、AI 维护文档和有效测试的共同验收条件 |
| [阶段路线](roadmap.md) | 执行顺序、里程碑、范围和阶段出口 |
| [执行门槛与分批交付](execution-gates.md) | 最小启动基线、早期试点、历史失败、设备门槛和分包准入 |
| [兼容性契约](compatibility.md) | 不可静默改变的接口、行为、类型、样式与包分发约定 |
| [核心设计](core-design.md) | 核心各模块的目标职责、迁移方式和生命周期设计 |
| [包迁移规范](packages.md) | 全生态统一流程、组合矩阵及包特有风险 |
| [测试与验收](testing.md) | 测试层次、浏览器/消费者矩阵、证据和回归门槛 |
| [docs 页面与编辑器测试](docs-browser-testing.md) | 复用已有 HTML、加载版本、隔离状态和补强文档 smoke |
| [多轮复盘与 npm 准入](release-reviews.md) | Chrome 验证分工、三轮全局复盘、问题闭环和候选发布门槛 |
| [工具链与发布](toolchain-release.md) | TypeScript、Bun、构建、版本管理和发布回退 |
| [AI 协作流程](ai-workflow.md) | AI 接续工作、任务边界、验证、记录和交接模板 |
| [架构决策](decisions.md) | 已选方向、待验证方案及被拒绝方案 |
| [进度与证据](progress.md) | 本次会话结果、阻塞、下一步；不重复维护每个任务状态 |
| [变更记录模板](changes/TEMPLATE.md) | 每次行为/类型/结构变化的详细记录 |
| [任务数据](tasks.json) | 任务状态和依赖的唯一数据来源 |
| [包基线](package-inventory.json) | 包版本、入口、声明、源码清单及对应 demo 的初始快照 |

## 维护规则

1. 任务状态只修改 `tasks.json`；运行 `node refactor/scripts/plan.mjs --write` 更新计划表。
2. 运行 `node refactor/scripts/plan.mjs --check` 检查任务 ID、依赖环、包覆盖、完成证据、本地文档链接和生成表同步。它检查链接文件存在，不验证网页可用性或 Markdown 标题锚点。
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 项是初始计划，不是限制改善范围的上限。