ArtPlayer/refactor/toolchain-release.md

# 工具链、分发与发布

## 目标组合

TypeScript 用于自有源码、检查与声明生成；Vite/Rollup 保留现有产物能力；Node 继续运行现有测试和必要脚本；用户已指定 Yarn 为默认包管理器，Bun 仅作隔离试点评估。浏览器消费者不依赖 Bun。

实际固定版本与命令见 toolchain-setup.md，Yarn 切换由 ENG-PM-01 验证。新增工具必须显式声明并通过干净环境检查，不能沿用开发机器上偶然存在的传递依赖。

## 新依赖与脚本的自主选择

用户已授权按重构需要安装新依赖、添加及改进合理脚本，常规选择不需要再次确认。此授权覆盖测试、类型检查、声明生成、构建、文档和代码维护工具，以及确有必要的运行依赖。

- 以正在解决的问题为依据引入工具；记录用途、选定版本及相对现有方案的收益，避免用途相同的工具长期重复堆积。
- 区分 devDependencies、dependencies 和 peerDependencies，放入正确 workspace。开发工具不应意外进入消费者浏览器 bundle。
- 更新 manifest、适用的锁文件、CI 和使用文档；检查干净安装和执行，不能依赖全局安装或偶然存在的传递依赖。
- 运行依赖需要比较包体积、浏览器/Node/TS 要求、许可和分发影响；必要升级单独记录，继续保持旧用户接口可用。
- 脚本职责清楚，名称易理解，支持自动化所需的非交互参数和可靠退出码；兼顾本地 Windows 与 CI 环境。
- 区分只读检查、自动修复、构建生成和发布命令。旧脚本入口已有用户时保留转发或兼容调用。
- 文档写明脚本输入、输出、是否修改文件、运行环境和示例；复用成熟工具，避免无必要地自建复杂框架。
- 在对应任务 commit 中一起保存依赖/脚本、测试、锁文件及文档；不因安装了工具就宣称迁移完成。

工具选择可以根据证据调整既有计划，在 decisions.md 更新理由。旧 API 和产物能力仍是验收条件；本地工具授权不等同推送或公开发布授权。

## TypeScript

1. 根目录管理基础配置，核心、插件、工具、构建脚本、worker/Worklet 各自配置环境。
2. typescript 和必要测试工具显式声明为开发依赖。区分本仓库根工具依赖与每个发布包运行依赖。
3. allowJs 过渡，逐包 strict；声明输出保持既有路径，禁止发布内部测试类型。
4. 类型消费者矩阵包含旧支持的最低 TS 版本与选定当前版本，解析方式包含 bundler 和 Node；不能默认借重构抬高最低 TS 版本。
5. docs/assets/ts 的编辑器声明由可验证的生成流程产出；不再依赖简单删除 import/拼字符串保证正确性。
6. 保留直接消费 JS 的例子；TS 是维护手段，不成为用户必须使用的语言。

## Bun 试点

MOD-01 已完成固定版本隔离评估，结论为保留 Yarn。Bun 1.4.2 普通迁移后 Node
测试/类型/完整构建通过，但冻结迁移、传递依赖和钩子策略不等价；详见
[实测结论与复跑](bun-evaluation.md)。以下是评估标准，不表示已采用 Bun。

| 步骤 | 检查 |
| --- | --- |
| 依赖基线 | 保存当前依赖和工作区行为，明确唯一锁文件与版本 pin；初次固定锁不夹带大规模升级 |
| 安装对比 | 在独立干净目录执行 Bun 安装，检查 lifecycle scripts、workspace/peer 解析、原生依赖、缓存和许可 |
| 命令对比 | `bun run` 只是脚本入口；脚本中的 node 仍由 Node 执行，不能声称已经换运行时 |
| 构建对比 | 相同版本和源码下构建全部包、文档、worker/WASM，比较包内容与消费者行为 |
| Node 回归 | npm/Node 消费发布包仍通过；现有 node:test 不因包管理器变化被替换 |
| 采用或保留 | 记录对 Yarn 的对比结论；用户已选择 Yarn，未经后续新决定不得改默认文档/CI/锁文件 |

评估时本机 Bun 1.3.14 直接运行现有测试遇到 node:test mock.fn 不兼容；这是具体版本的观察，未来升级应重测。Bun bundler 不作为本轮替换目标，因为需要保留 UMD、legacy 语法降级和现有资源处理。参考：[Bun bundler](https://bun.com/docs/bundler)、[workspaces](https://bun.com/docs/pm/workspaces)、[lifecycle](https://bun.com/docs/pm/lifecycle)、[TS allowJs](https://www.typescriptlang.org/tsconfig/allowJs.html)。执行时重新核对官方文档。

## 构建改造

- 当前 scripts/build.js 和 dev.js 写死 src/index.js；迁移时支持 JS/TS 入口及非交互指定包，并保留旧交互调用。
- 保留现代 UMD、legacy UMD、ESM、banner、全局名称、AMD 处理、Less/SVG 与 worker 行为。
- 统一内部构建配置不代表统一公开文件名。thumbnail tool 的 .esm.js 等历史路径必须有生成兼容产物或明确核实结论。
- 区分源码构建、类型、文档、测试和站点部署；禁止验证步骤顺带修改源码或推送 gh-pages。
- 移动文件不要与改变运行行为同时铺满全仓库；每次检查 imports、exports、demo URL 和产物。
- Lerna independent 版本模式保持。是否移除安装/链接脚本要先确认作用，不能因 workspaces 存在就直接删除。

## 发布流程

GitHub CI/CD 的优化属于本次重构范围，按 [CI/CD 规范](github-ci-cd.md) 分离 PR 检查、候选准备、Pages 部署与 npm 发布。新增 CI-01 至 CI-04 交付矩阵/报告、部署、分包发布准备及远端准入验收；第三轮复盘需核对这些结果。

实现完成后等待用户指导启动 [三轮全局复盘](release-reviews.md)（REVIEW-01/02/03），不得自动开始；各轮分别核对架构兼容、真实环境和最终 npm 候选内容。REL-05 依赖三轮通过；候选反馈修复后的正式发布重新核对受影响证据，不能直接复用旧候选的验收结果。

1. BASE-01 确定旧核心和插件的支持矩阵，登记 npm tarball integrity。起点 SHA 不能代替消费者产物基线。
2. REL 阶段为每个发生变化的包生成候选 tarball，用隔离消费者验证，无需先公开发布。
3. 按用户要求，全部 workspace 包各自升级一个大版本：M.m.p → (M+1).0.0，具体目标见 [版本策略](version-policy.md)。保留独立版本、同步变更日志和依赖范围；大版本升级不放宽旧 API 兼容要求。
4. 预发布 tag、npm 发布、站点部署及推送属于后续实际发布步骤；当前仅创建本地分支与文档，不执行这些动作。
5. 经授权后按风险批次发布候选版本。优先简单包，再核心兼容候选，最后高风险生态包；不要求用户同时升级整个生态。
6. 收集有复现步骤的反馈，与旧版本 A/B 对照。达到记录好的验收条件后才能更新正式 tag；不设无依据的自动等待天数。
7. 记录发布后的 tarball integrity、版本组合、测试、已知限制和回退版本。

候选准备与真实环境验收分开推进。REL-08 维护逐包发布台账，REL-01/02 可以在全项目真机验收前完成方案与本地候选验证。实际公开发布仅对范围冻结、所需证据完整的批次进行；全项目任务仍保持原范围。测试后不能重新构建一份未经验证的内容直接发布，必须核对 tarball integrity；内容变化则失效相关旧证据。具体门槛见 [执行门槛与分批交付](execution-gates.md)。

## 回退与维护

- 不删除旧包版本和历史 CDN 文件。包回退通过恢复已验证版本/tag/锁定依赖；不把 unpublish 作为默认方案。
- 核心和插件可分别回退；候选插件不得只能依赖尚未广泛发布的新核心内部方法。
- 在发布清单中维护每包的旧版本、新版本、依赖范围和消费者回退命令。
- 保持 master 的必要修复，并记录如何同步到重构分支；发布前重新建立准确差分基线。
- 新漏洞、外部 SDK 不兼容和类型破坏单独记录，不能藏在“代码整理”变更日志里。