# 决策记录

状态：采用方向 / 待验证 / 已拒绝 / 已替代。采用方向不代表实现完成，技术细节可由后续证据修订。

| ID | 状态 | 决策 | 原因与约束 |
| --- | --- | --- | --- |
| ADR-001 | 采用方向 | 保留公共 Artplayer 门面、渐进替换内部 | 大量旧用户及插件；属性/事件/分发均是契约 |
| ADR-002 | 采用方向 | 自有核心、插件、proxy、工具逐步 TS 化 | 消除实现/声明漂移；JS/TS 过渡，公开类型兼容 |
| ADR-003 | 采用方向 | 先测试、生命周期，再大范围模块调整 | 已有销毁与切源风险；不能仅靠改写语言获得可靠性 |
| ADR-004 | 已替代 | Bun 仅作隔离评估，默认包管理器使用 Yarn | 用户明确指定 Yarn，见 ADR-021；保留 Node 测试语义 |
| ADR-005 | 采用方向 | 保留 Vite/Rollup 的既有分发能力 | UMD/AMD/legacy、Less/SVG/worker 兼容成本明确 |
| ADR-006 | 采用方向 | 每包独立任务和版本，公共共享依赖谨慎增加 | 支持旧核心配新插件；不强制生态同步升级 |
| ADR-007 | 采用方向 | 机器任务表 + 可读生成表 + 每次变更记录 | 支持 AI 接续、依赖检查和证据追溯 |
| ADR-008 | 待验证 | 内部资源作用域和操作身份隔离 | 清理/取消语义待基线测试，不能先决定新增 Promise 拒绝 |
| ADR-009 | 待验证 | 精确公共类型的兼容扩展策略 | 错误声明修正也可能破坏现有 TS 用户；逐项记录 |
| ADR-010 | 采用方向 | AI 改善工程，不默认给播放器加入远程 AI 能力 | 避免增加运行依赖、网络请求、成本和用户行为变化 |
| ADR-011 | 采用方向 | vendored 代码维持独立来源和许可 | TS 迁移限自有逻辑，第三方更新独立验证 |
| ADR-012 | 已拒绝 | 一次性重写核心并同时更换包管理器、bundler、测试框架 | 变量过多，难以定位回归和回退 |
| ADR-013 | 采用方向 | 用户授权在旧接口兼容前提下主动改善全部不合理内部设计 | 2026-09-10 明确要求：TS 迁移伴随清晰拆分、充分有效测试、持续文档和 AI 接续能力；任务清单可按证据扩展 |
| ADR-014 | 采用方向 | 每完成一个任务立即创建独立本地 commit | 用户明确要求；实现/测试/文档/状态同次提交，主题带任务 ID，核实成功后再开始下一任务；不等同推送授权 |
| ADR-015 | 采用方向 | 自主安装所需依赖并添加合理脚本 | 用户明确授权；按具体任务选型，记录用途/版本/环境/依赖归属，验证旧接口、产物与可复现执行，随任务独立提交 |
| ADR-016 | 采用方向 | 最小基线和旧核心上的早期插件试点 | DOC-07 发现原试点依赖 32 个前置任务；先验证工具闭环，再做核心大范围迁移 |
| ADR-017 | 采用方向 | 分离准备工作、自动化验证与真实环境发布门槛 | 文档/本地候选不等待无关硬件；相关能力发布仍须真实证据，全项目任务范围不缩减 |
| ADR-018 | 采用方向 | 历史失败台账与逐模块严格门槛 | 初始全包类型/环境不一定全绿；不掩盖既有问题、不允许新增回归，迁移包与发布范围严格验收 |
| ADR-019 | 采用方向 | 候选产物内容绑定测试证据 | 来源 SHA、锁文件/工具和 tarball integrity 可追溯，内容变化后重新验证，避免测一份发布另一份 |
| ADR-020 | 采用方向 | 全部 workspace 包各自升级到下一个 major，minor/patch 归零 | 2026-09-10 用户明确要求；替代旧“不自动提升全部 major”策略，保留 independent、旧 API 及跨版本插件兼容；目标见 version-policy.md |

| ADR-021 | 采用方向 | 用户指定 Yarn，固定 Classic 1.22.22 和唯一 yarn.lock | 与原 v1 锁格式一致；保留 Node 24.21.0 和既有依赖版本，ENG-PM-01 验证；替代 ENG-01 的 npm 默认工具选择 |
| ADR-022 | 采用方向 | Chrome 不可用时使用 Codex 内置浏览器 | 用户明确授权；记录实际环境和能力范围，必要设备测试仍独立验收 |
| ADR-023 | 已验证于 Audio Track | 参数类型纠正会破坏旧推断时，默认入口保留兼容类型，/runtime 复用相同运行文件提供精确类型 | PKG-AUDIO-04 的 Parameters 与无注解 update 实现证明 Partial/重载仍可能破坏旧用户；沿用核心的类型分层方向，具体包需独立编译与入口身份验证，不增加第二套实现或用 any 绕过 |
| ADR-024 | 已验证于 CORE-24 | 切源播放意图归属当前操作，在公开 play/pause 命令入口更新，内部暂停不覆盖用户意图 | Audio-05 三引擎复现连续切源最终停在 0；新操作继承未完成操作的意图，显式暂停及其修订号终止旧恢复副作用，过期 Promise 仍保留原结算语义；不依赖用户回调之后才执行的事件监听器 |

## 开始实现前需补齐的决定

1. 支持的历史核心/插件版本、TS 最低版本与浏览器能力矩阵，由 BASE-01/ENG-01 登记证据。
2. 连续切源、销毁中 Promise 的结果与错误策略，由 CORE-04/CORE-09 的变更记录明确。
3. 真机与外部 SDK 验证环境、负责者和缺失检查的发布处理，由 ENG-05/REL-03 明确。
4. 公共类型发现历史错误且无法完全兼容时的版本策略，由 CORE-07 和 REL-01 明确。

## 新决策模板

```text
ID / 日期 / 关联任务：
状态：
问题与源码/测试证据：
选择及备选方案：
为何选择：
公开 API、类型、包分发影响：
验证方法与回退：
替代的旧决策：
```