ArtPlayer/refactor

ArtPlayer 兼容性重构

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

基线与范围

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

从哪里开始

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