ArtPlayer/refactor/toolchain-setup.md

可重跑的开发环境

用户指定 packageManager 使用 Yarn。标准组合为 Node 24.21.0（根 .node-version）和 Yarn Classic 1.22.22（根 package.json），唯一维护的安装锁文件为 yarn.lock。Yarn 版本沿用仓库原有 v1 锁格式；播放器消费者 API、包版本和浏览器构建目标不受该选择影响。

使用

1. 切换到 .node-version 指定的 Node，安装 Yarn 1.22.22；例如 npm install --global yarn@1.22.22，然后确认 node --version 和 yarn --version。npm 仅可用于安装 Yarn 工具及消费者兼容检查，不用于维护本仓库依赖锁。
2. 干净 checkout 执行 yarn install --frozen-lockfile --non-interactive，禁止 CI 自动更新锁或忽略安装脚本/engines。参见 Yarn Classic install。
3. 执行 yarn check:toolchain --strict，核对实际 Node/Yarn、根固定开发工具和 22 个 workspace 的声明及传递依赖锁条目。工具数量以本次输出为准；普通检查允许满足最低工具要求的 Node，同时打印标准版本。
4. 执行 yarn test:playback、yarn test:dash-control、yarn build all 和 yarn workspace artplayer-vitepress build。ENG-02 已拆分只读 lint 与 lint:fix；PR/主线入口和独立 Pages 流程见 ci-setup.md。

私有根包最低 Node 为 ^20.19.0 || >=22.12.0，与原本使用的 Vite 7 一致。标准工具链验证 使用 Node 24.21.0；CI-01 已在 Windows 的 20.19.0/22.12.0/24.21.0 上重装消费相同 core/chapter tarball，见 Node 记录。 这不是在最低 Node 上完成仓库工具链的干净安装/构建测试，也不是发布包的最低 Node 声明。 CORE-25 默认选项缺陷已修复并通过相同三 Node 与严格打包检查，见 修复记录；完整工具与消费范围由 CI-01 继续验证。

锁文件和依赖维护

• 根构建工具固定精确版本并放在 devDependencies；发布包的 dependencies/peer 范围保持原样。
• SITE-05 将已有传递依赖 htmlparser2@10.1.0 显式声明为根 devDependency，供 yarn check:site-links 解析生成 HTML 使用；不进入播放器包。原版本和完整性不变， 根 yarn.lock 只合并新增的精确选择器。链接检查不执行 HTML 的脚本，不请求外部 URL。 文档站 FlexSearch peer 已对齐 0.7.43，见搜索验证。 Yarn workspace add 后须再从根目录安装并核对 resolutions，防止工作区子命令遗漏根覆盖。
• PKG-JASSUB-09 新增根 devDependency pngjs@7.0.0，在 Node 中解码 Playwright 截图， 用实际合成画面与转移画布 readback 对照；不进入发布包。仅新增其精确 Yarn 锁条目， 并验证固定 Node/Yarn 的 frozen 安装及严格工具链检查。上游 API 见 pngjs 文档。
• ENG-04 新增 typescript-compat（npm:typescript@4.3.5）作为旧编译器消费探针；源码继续使用 typescript 5.9.3。精确 npm alias 也由锁检查保护；实际覆盖与命令见 类型检查说明。
• 添加根开发依赖使用 yarn add --dev --exact --ignore-workspace-root-check <name>@<version>，包级依赖使用 yarn workspace <name> add ...；运行依赖升级需要独立兼容证据。
• manifest 和 yarn.lock 同次提交；不提交 package-lock.json、bun.lock 或第二份安装锁。旧 npm 锁及验证报告保留于 ENG-01 Git 历史，原本地 Yarn 锁也已在忽略缓存中备份。
• 新增 @yarnpkg/lockfile 1.1.0 为显式开发依赖，供检查器使用 Yarn 官方锁解析器；不依赖 Lerna 偶然安装的传递依赖。只验证 registry 依赖图及完整性字段，实际下载完整性由 Yarn 安装验证；peer 兼容仍由消费者测试和安装报告验证。
• 另将原已解析的 TypeScript 5.9.3 和 @vue/compiler-sfc 3.5.28 显式声明为根开发依赖，满足 ESLint 工具链 peer 要求，防止依赖偶然提升到根目录；不在本任务迁移生产 TS 或更新公开声明。
• packageManager 字段只是声明，严格检查核对实际执行工具。Yarn 不像 npm lock 一样存储 workspace manifest 副本，workspace 名称/版本的发布基线仍由 refactor 清单和版本任务维护。
• 用户已选 Yarn；MOD-01 可在独立目录评估 Bun，但不能凭试点结果自行替换默认包管理器。
• 现有 npx/npm 脚本入口仍可用，脚本整理由 MOD-02 接续；新增脚本采用本地依赖。当前 postinstall 的 Lerna prepare 在 22 包均无 prepare 时为空操作。

验证记录

SITE-03 新增根开发依赖 monaco-editor@0.30.1，仅为桌面编辑器提供与既有 Monaco 浏览器资产匹配的精确 API 类型。只使用 type import，不替换 vendor 或加入播放器产物；root yarn.lock 仅增加该版本的一个条目。新增 yarn test:site-editor 验证编辑器状态/读取失败；浏览器检查仍使用原 assets/js/vs。

ENG-01 的 npm 验证报告 是切换前历史证据，不代表 Yarn 已验证。Yarn 验证报告 记录最终干净冻结安装、20 项 Node 测试、21 库包 63 产物及文档站构建全部通过；63 产物 SHA-256 与 ENG-01 完全相同。保留的旧锁条目版本变化为零，9 个 workspace runtime 依赖解析与 npm 基线一致。搜索 peer 后续已由 SITE-05 对齐版本并完成三引擎交互验证；未启用的托管提供方警告保留说明。

构建通过不代表运行时、类型、真实浏览器或 npm 发布验收已完成。Chrome 不可用时按 release-reviews.md 使用内置浏览器并注明实际环境。

可选原生浏览器诊断工具

PKG-HLS-SDK-01 将官方 Microsoft ProcDump 12.01 解压到忽略的 refactor/.cache/toolchains/procdump，运行时核对精确哈希和 Authenticode。 用途仅为本次HLS测试的Firefox子进程异常取证，配合PowerShell 7.6.5； 不进入npm依赖或CI默认安装，不更改Yarn/锁文件。来源、校验值、许可接受、 权限限制和复现命令见原生取证记录。