ArtPlayer/refactor

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/ 的站点部署流程直接作为产品文档发布。

从哪里开始

文档	用途
完整执行计划表	每一步的固定 ID、依赖、具体交付物、验收条件、风险及状态
全项目质量要求	用户确认的自主改造范围、文件拆分、AI 维护文档和有效测试的共同验收条件
阶段路线	执行顺序、里程碑、范围和阶段出口
执行门槛与分批交付	最小启动基线、早期试点、历史失败、设备门槛和分包准入
兼容性契约	不可静默改变的接口、行为、类型、样式与包分发约定
契约覆盖与证据索引	22包逐类责任、稳定测试ID、精确版本依据和候选/历史报告对应
核心设计	核心各模块的目标职责、迁移方式和生命周期设计
核心阶段验收范围	核心契约、已处置差异、性能风险与后续生态/发布门槛
包迁移规范	全生态统一流程、组合矩阵及包特有风险
测试与验收	测试层次、浏览器/消费者矩阵、证据和回归门槛
已落实的测试可靠性规则	历史失败、候选回归、设备缺口、精确异常及等待/重试的执行规则
docs 页面与编辑器测试	复用已有 HTML、加载版本、隔离状态和补强文档 smoke
控制台迁移边界	console.js 旧全局/实例/DOM 契约、冻结模块和待修复生命周期问题
控制台来源与署名审查	保留模块、内嵌来源、组件许可关联及历史构建恢复限制
多轮复盘与 npm 准入	Chrome 验证分工、三轮全局复盘、问题闭环和候选发布门槛
逐包发布准入台账	22包候选/证据绑定、源码和产物指纹、任务风险/许可阻断及严格预检
回退演练与维护	独立核心/插件回退、冻结安装文件检查、真实播放及剩余发布门槛
逐包恢复清单	全包精确旧版本、依赖及完整回退产物的缺口
工具链与发布	TypeScript、Bun、构建、版本管理和发布回退
已实现的开发环境	Node/Yarn 固定版本、锁文件、安装命令和实际验证范围
Bun 隔离安装评估	固定版本对比、传递依赖/资源差异及继续使用 Yarn 的依据
全包大版本策略	每包分别升级一个 major 的目标清单、兼容要求和版本落地步骤
已实现的 CI 入口	Yarn 检查/构建、只读 lint、Pages 隔离及远端待验收状态
GitHub CI/CD	PR/兼容矩阵、构建报告、Pages、npm 发布及远端准入验证
Pages部署与恢复	独立暂存、旧URL/域名预检、只读远端快照与人工切换恢复顺序
AI 协作流程	AI 接续工作、任务边界、验证、记录和交接模板
每任务提交审计	实际Git状态迁移、独立提交、初始例外、分支合并和CI报告
全包影响映射	变更范围、依赖/验证关系、必需CI命令及尚缺的包验证
架构决策	已选方向、待验证方案及被拒绝方案
进度与证据	本次会话结果、阻塞、下一步；不重复维护每个任务状态
变更记录模板	每次行为/类型/结构变化的详细记录
任务数据	任务状态和依赖的唯一数据来源
包基线	包版本、入口、声明、源码清单及对应 demo 的初始快照
发布基线与重跑说明	固定 npm tarball、完整性及已知源码/发布差异
差异与风险索引	已复现问题、源码事实和待核实事项的责任任务
风险维护说明	证据等级、关闭条件、第三方边界和校验命令
第三方来源清单	依赖解析、vendor 文件指纹、SDK/CDN 与许可来源缺口
消费者与真实环境矩阵	22 包的版本依据、能力/设备/样本、现有证据、验证任务及发布影响
类型检查与迁移入口	根/分包配置、当前/旧编译器、严格正反例和历史声明错误
核心公共类型出口设计	CORE-21 的声明生成、旧编译器兼容、精确入口和编辑器验收
JS/TS 构建与开发	非交互选包、开发重建、资源夹具和 AMD 全局修复
测试目录维护说明	统一测试命令、JS/TS loader、受控媒体及新旧公共契约
真实浏览器入口	三浏览器、解码画面与媒体状态、Range/失败服务及候选文件映射
实际打包消费	仓库外安装、运行时/声明检查、安装产物浏览器验证与严格发布检查

维护规则

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 项是初始计划，不是限制改善范围的上限。