ArtPlayer/refactor/ci-setup.md

# PR 检查和 Pages 操作说明

同一20包安装映射的Windows WebKit26.6完整运行现已结束：bb2c12df3执行77文件/845项，
694通过、13失败、138能力跳过、0重试，1214.860秒。失败包括8项Audio、1项Chapter、
1项候选弹幕CPU间隔漏发和3项旧JASSUB；候选JASSUB三核心通过。见
[记录](changes/2026-09-15-CI-01-installed-webkit.md)及
[完整证据](baselines/ci-installed-webkit-validation.json)。三引擎均已执行但矩阵未全绿，
CI-01仍进行中；不要把下列较早检查点的“待执行”当作当前状态。

同一run-cRduve安装映射随后在b3344a7c6执行完整Firefox155.0：77文件/845项，
844通过、1个裸DASH4.5.2暂停seek失败、0跳过/重试，1043.223秒，退出1。
执行HEAD与打包HEAD分别记录，启动时再次验证指纹；没有重新打包或修改测试。
见[Firefox记录](changes/2026-09-15-CI-01-installed-firefox.md)和
[完整输入/结果](baselines/ci-installed-firefox-validation.json)。完整WebKit安装回归仍待执行。

最新完整Chromium安装回归固定5e0447fc5：重新构建并隔离安装20包后，77文件/845项
执行844通过、1个裸DASH4.5.2暂停seek失败、0跳过/重试，948.777秒，退出1。
候选DASH四个稳定边界组合及安装JASSUB三核心原生绘制清理通过；保留历史失败。
见[记录](changes/2026-09-15-CI-01-installed-chromium.md)及
[逐包输入和结果](baselines/ci-installed-chromium-validation.json)。该轮仍是major升级前
产物，其他两引擎的完整安装运行、远端Actions和设备门槛继续单独验收。

本地完整源码回归现分别有 Chromium、Firefox 和 Windows WebKit 的记录，
对应不同提交与测试集合，不能拼成同一候选的绿色矩阵。最新 WebKit 在 ae56937d3
执行174文件/1664项：1515通过、11失败、138能力跳过、0重试，1816.373秒。
8项真实音频缓冲失败与3项冻结JASSUB渲染失败保留；58项ASR、48项DASH和32项HLS
缺能力，不计播放通过。详见[本轮记录](changes/2026-09-15-CI-01-source-webkit.md)
及[各引擎入口](../scripts/browser-validation/README.md)。CI-01/CI-04仍未完成，
本地报告不代替远端Actions、完整安装候选及物理设备。

CI-TYPES-02 增加 `yarn test:ecosystem-types`：四包共享消费者加十七个独立
类型检查命令覆盖全部二十一库包，先重建声明/分发/i18n，再逐包隔离安装验证。
browser-consumers 在恢复标准 Node 并完成原消费步骤后执行；类型失败使作业失败，
上传总报告和各包原始 JSON/log。维护入口见
[消费者模块](../scripts/consumers/README.md)。这些类型结果不批准 Thumbnail
尚未决策的默认运行时行为，也不代替真实播放、设备或远端流水线验收。

最新统一安装清单含二十包。VAST 的完整 glomex 加载边界进入普通 installed
范围；真实 IMA 仍由独立 test:vast-native 按显式安装 map 验证，本地 39/39
通过不表示远端 CI 已覆盖真实广告。见[记录](changes/2026-09-15-CI-01-vast-installed.md)。

浏览器CI现在分别执行 `yarn test:browser:source` 和
`yarn test:browser:installed`。前者清除继承的安装map并保留全部spec；后者要求已
核验的统一包清单，执行明确列出的 installed 子集；清单维护在
`scripts/browser-validation/scope.ts`。两步不
吞失败，普通失败后仍保存另一范围的证据，分别上传browser-source/browser-installed。
入口与报告规则见[维护说明](../scripts/browser-validation/README.md)。
目前按 OS × 引擎拆分播放作业，消费者另行执行；各作业的实际远端耗时/60分钟预算、
其余插件安装矩阵与远端运行仍待CI-01/CI-04，不计为已通过。

Iframe 接入后共同安装清单含十九包；新增五文件本地三引擎 426/426 通过，
完整 installed collection 为 72 文件/2,406 项，见
[安装记录](changes/2026-09-15-CI-01-iframe-installed.md)。原 browser-consumers 的
history 仍保留源码/显式工具加核心 map 的独立语义，不因新增安装清单而自动
宣称 BFCache 已使用安装工具验收。

## 本地命令

使用 toolchain-setup.md 的 Node/Yarn 环境与冻结安装。

| 命令 | 行为 |
| --- | --- |
| `yarn lint` | 只读 ESLint，覆盖包源码/声明、JS/MJS 工具、docs-smoke TS 模块、测试和编辑器声明 |
| `yarn lint:fix` | 显式自动修复相同范围 |
| `yarn check:release-ledger` | ci:check中的逐包准入登记结构检查；当前blocked不导致结构检查失败，不是发布准入通过 |
| `yarn release:preflight --packages ...` | 严格候选/证据/任务/设备/许可预检，任一缺口退出1；CI-03后续发布工作流使用此入口 |
| `yarn release:bundle --packages ... --tag next` | 干净源码下重新执行准入检查，仅复制已验证候选并绑定完整报告/文件摘要；不构建、不联网、不发布，当前缺口仍阻止输出 |
| `yarn typecheck:release` / `yarn test:release-bundle` | 严格检查候选交付 TS 模块及字节身份、输入漂移、路径和失败清理回归；分别接入 ci:check/test:baseline |
| `yarn typecheck` | 根/迁移包严格检查、当前与兼容 TS 消费；历史 NodeNext ESM 错误单独核对，见 typechecking.md |
| `yarn typecheck:react` / `yarn typecheck:vue` | 原 React TSX / Vue SFC 示例严格检查，ci:check 同时执行对应 lint |
| `yarn typecheck:docs-tools` / `yarn check:docs-smoke` | 严格检查 TS 示例/声明生成器及 JS/MJS 门面；只读核对确定性生成的 readiness smoke，ci:check 执行 |
| `yarn typecheck:scaffold` / `yarn test:scaffold` | 严格检查插件生成器与旧 JS 入口；生成包真实构建/类型/分发消费和写入失败回归；分别接入 ci:check 与 test:node |
| `yarn typecheck:library` / `yarn test:library` | 严格检查库构建/开发 TS 与旧门面；复用真实资源构建、分发、性能证据和生成器回归；类型检查接入 ci:check |
| `yarn test:dev-server` | 自有 HTTP/SSE 生命周期、端口冲突退出码、Range/HEAD/gzip、取消与重复启动回归；接入 test:node 和 test:library，真实 docs/CLI 检查进入既有三引擎 browser 矩阵 |
| `yarn check:editor-types` | 只读核对全部编辑器声明、SDK notices 和实际 libUris；主 TS 5.9.3/历史 4.3.5 整组语义检查，ci:check 执行 |
| `yarn build:site-assets` / `yarn check:site-assets` | 从站点 browser/ TS 生成三个经典脚本；check 只读，root build:docs 先生成；完整 VitePress 构建另行验收 |
| `yarn typecheck:site-assets` | 严格检查站点 browser/ 模块；生成脚本由 typecheck:docs-tools 的 checkJs 覆盖；均进入 ci:check |
| `yarn test:react-consumer` / `yarn test:vue-consumer` | 仓库外 tarball 安装、原框架示例、开发/生产三引擎；browser-consumers 每个系统执行一次并上传独立目录，本地证据不代替远端矩阵 |
| `yarn test:unit` | 原播放/DASH 回归、同夹具的新旧公共契约与 JS/TS loader 验证 |
| `yarn test:node` | test:unit 加工具链/文档构建回归，保留原 test:playback/test:dash-control 入口 |
| `yarn test` | 统一执行 Node 与基线测试，源码/夹具维护入口见仓库 test/README.md |
| `yarn test:browser` | 隔离服务执行 Chromium/Firefox/WebKit 真实播放；首次先运行 test:browser:install，详见 [入口](../test/browser/README.md) |
| `yarn test:imports` | 3 个既有包导入 smoke，构建后执行以使用新产物；不把 console 示例视为完整行为断言 |
| `yarn test:baseline` | 固定发布包完整性及本地 HTTP 基线测试；首次可能下载已固定归档到缓存 |
| `yarn test:contracts` | 重跑已登记断言的Node文件并采集精确事件/候选指纹，当前44项包含10个索引断言 |
| `yarn check:contracts --report` | 校验12类契约/22包归属、版本及报告对应；--write更新静态表，详见 [维护说明](contract-coverage.md) |
| `yarn ci:check` | 严格 Node/Yarn/锁检查、计划、只读 lint、类型、Node 和基线测试；允许写忽略缓存，不修改源码 |
| `yarn check:ci` | 只读校验实际工作流的完整系统矩阵、安装、缓存、报告和最终检查；已接入 ci:check |
| `yarn test:ci` | CI 汇总退出码、工作流/影响分析反例与隔离运行时校验；CI-01 引擎拆分后实测 77 项 |
| `yarn test:package:runtime` | 标准 Node 重装同一已检查 tarball；须先运行 test:package，其他 Node 使用显式 --expected-node |
| `yarn ci:build` | 21 库包、i18n、编辑器声明、文档 readiness smoke 和文档站构建，以及构建后包导入 smoke；会生成 dist 和 docs 内容 |
| `yarn check:impact --report` | 读取实际依赖/验证关系和Git变更，核对workflow必需命令，写CI影响报告；已接入ci:check，见[影响映射](impact-analysis.md) |
| `yarn build:all` | 保留旧入口，执行 ci:build 后只读 lint |

scripts/build-docs.js 保留原 npm run build 子命令兼容入口，现在传播失败退出码；包管理/锁维护继续使用 Yarn。MOD-02 可再统一旧内部脚本。build-ts.js 仅对刚生成的声明执行 ESLint layout 格式修正，使只读 lint 在构建后仍能通过；不是对生产源码执行自动修复。

## PR 和主线

.github/workflows/nodejs.yml 在 PR、master/codex/** push 和手动运行时触发，也供 Pages 复用。检查作业只授予 contents: read，checkout 不保留 Git 凭据，没有提交、推送、npm 发布或部署步骤。PR/推送取消过期运行；Pages 部署继续使用独立队列。

Actions 固定完整 SHA，Node 来自 .node-version，Yarn 固定 1.22.22；安装使用 frozen-lockfile。actionlint 1.7.12 从官方固定归档取得，先核对提交在 workflow 中的 SHA-256，再执行。没有执行 curl 管道脚本。日志在失败时也尽量上传，包含源码 SHA、工具版本、锁摘要和生成差异概览，保留 14 天。

## CI-01 当前矩阵与结果汇总

| 作业 | 系统 | 内容 | 超时 |
| --- | --- | --- | --- |
| checks | Linux、Windows | ci:check、ci:build；Linux 额外执行 actionlint | 45 分钟 |
| coverage | Linux、Windows | 既有源码映射与生命周期覆盖检查 | 15 分钟 |
| browser-smoke | Linux、Windows、macOS × Chromium、Firefox、WebKit | 每个引擎独立打包/冻结安装完整 browser 包清单，再执行该引擎全部 source 与已列出的 installed 用例；9 个组合，最多同时运行 6 个 | 每个组合 60 分钟 |
| browser-consumers | Linux、Windows、macOS | 同一 core/chapter tarball 的 Node 20/22/24 消费，React/Vue 三引擎、iframe history、性能；每个系统一次，最多同时运行 3 个 | 每个系统 60 分钟 |
| CI result | Linux | 汇总以上四个作业组，所有结果必须为 success | 5 分钟 |

构建与浏览器工具使用 .node-version 的 24.21.0。安装运行时消费分别使用固定 20.19.0、
22.12.0 和标准 Node，不重新构建候选。它们是根工具 engines 的边界测试点，发布包没有
声明 Node 下限；更早 Node 和最低工具链干净安装仍需验证。TS 5.9.3、4.3.5 和迁移运行时兼容 5.1.6
继续由既有类型脚本按各自适用范围运行，不代表最低 Node 或所有包/TS 组合已验收。
矩阵不设置 fail-fast，单个系统失败后仍尽量收集其他系统证据；显式 bash 保留 tee
上游命令的失败退出码。影响报告继续扩大核心/共享变更到全生态，当前不缩减必需作业。

稳定名称为 **CI result**。它以 always() 依赖 checks、coverage、browser-smoke、browser-consumers，结构化
读取 needs；失败、取消、跳过、缺失、错误 JSON 或未知额外作业都失败。增加独立 job 时
同时修改 ci-summary.mjs 的 requiredJobs、workflow needs、矩阵策略和测试，防止遗漏汇总。
全局取消/runner 故障下的真实调度仍待 CI-04；本地退出码测试不证明远端作业一定被调度。
required checks 的实际绑定尚未设置，不能宣称分支保护已经生效。

播放与消费者作业互不依赖，避免一组失败阻止另一组采集证据。播放步骤仅传入
`--project=${{ matrix.browser }}`；不添加 grep、文件过滤、重试或容许失败。
每个组合内部仍顺序执行 source/installed，使用独立报告目录和端口；不同组合由
独立 runner 隔离。浏览器 artifact 名包含 OS、引擎、run ID 和 attempt，消费者
artifact 使用独立前缀。每个 runner 冻结安装和构建自己的产物，代价是增加 runner
数量和重复打包时间；下载缓存仍使用精确版本键。这是减少单任务串行工作量的调整，
实际排队时间、总计费分钟和远端速度仍待验证。

## 下载缓存、日志与维护

scripts/ci-context.mjs 从真实 checkout、package.json、.node-version 和 yarn.lock 读取
来源与版本，将绝对缓存目录写入 GITHUB_ENV/OUTPUT，运行信息写入 refactor/.cache/ci/context.json。
Yarn 缓存与浏览器缓存均按 OS/架构/Node/Yarn/ref/锁隔离，浏览器另绑定 Playwright 版本；
只缓存下载内容，无宽松 restore-keys、跨 OS 恢复或 node_modules/产物缓存。每次 frozen
install；浏览器每次 install --with-deps，缓存命中不能替代 Linux 系统依赖安装。
相关行为依据 [Playwright CI 文档](https://playwright.dev/docs/ci)。

新增 actions/cache 固定 caa296126883cff596d87d8935842f9db880ef25，来自当次核实的
[官方 v5 ref](https://api.github.com/repos/actions/cache/git/refs/tags/v5)，
[该提交 action.yml](https://github.com/actions/cache/blob/caa296126883cff596d87d8935842f9db880ef25/action.yml)
使用 node24；升级时重新核对 tag/SHA、runner 和缓存格式，不使用浮动标签执行。
本批没有新增 npm 依赖或修改 yarn.lock。

安装/构建/测试日志和已有 HTML/JSON、截图、trace、tarball 由 always 上传步骤留存；
名称包含系统、run_id 和 run_attempt，保留 14 天。最终脚本独立写 summary.json、
summary.md 和 GitHub Job Summary，不依赖先前下载的 artifact 来判断作业是否成功。
下载对应作业 artifact，先核对 context.json 的 source/workflowSource、工具版本和锁摘要，
再查看失败阶段的日志和浏览器 trace。缓存异常时可删除对应远端 key 后重跑；该动作
必须针对实际故障，不以清缓存代替修复锁或构建问题。

本地验证与指纹见 [CI-01 记录](changes/2026-09-13-CI-01-matrix-summary.md)。
三个 Node 的 Windows 安装证据及新发现见 [消费者记录](changes/2026-09-13-CI-01-node-consumers.md)。
CORE-25 已修复无 navigator 默认选项缺陷，严格 test:package:release 的当前 core/chapter
夹具已通过；此前的失败记录保留，见 [修复证据](changes/2026-09-13-CORE-25-defaults-ssr.md)。
更早 Node 消费/最低工具环境、全生态安装矩阵和有证据的影响调度仍待 CI-01；CI-04 负责
各系统远端运行、冷热缓存、失败/取消演练及 required check 设置。没有新增远端通过证据。

## Pages 隔离与启用条件

CI-02已实现独立暂存与旧路径预检，并验证21个重新构建的uncompiled入口、63个
compiled/dist匹配和6项三浏览器暂存播放检查。上传路径为prepare:pages的精确输出，
不再直接上传工作区docs；新增脚本和回退说明见[Pages部署](pages-deployment.md)。
2026-09-14只读API确认线上仍为gh-pages根目录的legacy部署，域名github.artplayer.org；
环境允许master/gh-pages，启用变量查询404，状态未知。后面的初始记录保留为历史背景，
其“远端未知”描述不代表本次没有读取配置；CI-04实际部署/切换仍未验证。

ENG-07 将浏览器候选改为 `yarn test:package` 实际打包并安装后的文件，使用输出映射禁止
回退到源码。安装/构建日志、tarball、成员指纹和浏览器结果一并上传，构建快照的 node_modules
链接不上传。初始包范围为 core/chapter；PKG-CHAPTER-04 已将这两个包的已知类型诊断清零，
严格打包检查现已通过，仍不等于整批发布准入或远端 CI 已通过。
见 [消费者说明](../test/package/README.md)。本地已验证，远端执行仍待 CI-04。

.github/workflows/pages.yml 仅支持手动运行，限定 master，且仓库变量 PAGES_DEPLOY_ENABLED 必须为 true。初始启用状态未经远端核实；没有修改该变量或其他 GitHub 设置。保留此门槛用于 CI-02 完成域名、路径和远端配置验收后再启用，不能直接自动部署 PR 产物。

Pages 先调用同一检查/构建 workflow，成功后上传同一次运行生成的完整 docs artifact，再在 github-pages 环境的独立作业调用官方 deploy-pages。仅 deploy 作业有 pages: write / id-token: write，没有 Git contents 写权限，也没有原先的 gh-pages force push。发布排队执行，不取消正在执行的发布。

已静态核对当前 docs/CNAME 为 github.artplayer.org；上传包含隐藏文件以保留 .nojekyll。docs 根、document、compiled、旧 HTML/编辑器等实际线上路径和历史站点来源仍需 CI-02 逐项预检；目前未确认或修改线上 Pages source。合并该变更后旧 push-master 自动部署会停止，需先完成以下迁移步骤再启用新流程。

1. CI-02 记录当前 Pages source、gh-pages ref、域名/DNS、关键 URL 和可恢复的旧产物。
2. 先验证 artifact 内容及旧路径；设置 Pages source 为 GitHub Actions，核对 github-pages 环境只允许受信任 master 部署和所需审批。
3. 经实际部署授权后设置 PAGES_DEPLOY_ENABLED=true，在 master 手动运行 Deploy Pages；记录 CI 和部署 URL，逐项探测旧路径。
4. 出现问题时关闭启用变量，按保存的 Pages source/gh-pages ref 恢复；不默认重新 force push 覆盖历史。恢复旧 workflow 可从 ENG-02 前 Git 历史取回，但执行远端写入仍按部署授权处理。

## 待核实的外部状态

| 项目 | 当前证据 | 负责任务 |
| --- | --- | --- |
| 新 PR/主线 workflow 实际执行、故障演练 | 仅本地静态和命令验证，无远端 run | CI-04 |
| required checks、fork 权限和环境审批 | 未读取/修改仓库设置 | CI-04 |
| Pages source、启用变量、域名和回退目标 | 只读源码 CNAME，远端未知 | CI-02 |
| npm 权限、trusted publisher、候选发布 | 未配置、未执行 | CI-03/CI-04 |

参考：[GitHub Pages 自定义 workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)、[setup-node](https://github.com/actions/setup-node)、[actionlint 1.7.12](https://github.com/rhysd/actionlint/releases/tag/v1.7.12)。本轮已核对选用 Actions 的实际 action.yml 和发布 tag 对应 SHA；后续升级需重新检查。

## SITE-AI-DOCS-01 文档生成补充

`ci:check` 新增 `yarn check:llm`，只读校验 `docs/llms.txt` 和来源指纹清单。
`ci:build` 在 `build:ts` 后运行离线 `build:llm`，不读取 API key 或请求模型。
文档 TS 模块进入根 lint 和 docs-tools 严格类型检查，文档流程回归进入
`test:node`。`trans:docs --remote` 不进入 CI；远端工作流运行结果仍待独立验收。

## SITE-BUILD-01 构建编排补充

`build:i18n` 和 `build:docs` 先暂存再替换固定生成目录；文档子进程使用当前
Yarn Classic 可执行文件，不再调用 npm。入口仍由 `ci:build` 按原顺序调用。
新增 `test:site-build`，其测试进入 `test:node`；构建 TS 模块与 VitePress
稳定代码分组 ID hook 进入根 lint/docs-tools 类型检查。真实本地构建和三浏览器
页面验证见任务变更记录，远端工作流、Pages 与 npm 验收不因此完成。

## SITE-03 编辑器来源与检查

SITE-07检查点新增check:site-notices到ci:check、build:site-notices到ci:build，
将固定Monaco/vConsole上游原文复制进docs/licenses；源文件指纹漂移会失败。
新TS模块进入docs-tools类型和根lint，文件回归进入test:node。vConsole上游许可
正文缺失及WebKit销毁异常仍开放；新浏览器回归保留失败，不代表整体CI现在已通过。

common.js/bootstrap.js 由 browser 下的 TS 生成，源代码进入 typecheck:site-assets
和根 lint，产物由 check:site-assets 比较；不再对生成 common.js 应用源码 lint。
build:ts 生成声明 URL 清单后重建站点浏览器产物，check:editor-types 保持只读。
新增 test:site-editor 并接入 test:node，新增真实 Monaco 交互测试走现有三引擎矩阵。

安装准备使用 `yarn test:package --browser`，从 browser-validation/scope.ts 的同一
包清单生成，不再在工作流复制列表。默认 core/chapter 消费者及显式 --include 保留；
此选项不表示全生态类型、SDK 或发布准入。

十八包安装清单的弹幕/Mask 子集实跑 399 项耗时 22.5 分钟，见
[CI-01 记录](changes/2026-09-15-CI-01-danmuku-installed.md)。随后完成上述引擎与
消费者拆分，见[拆分记录](changes/2026-09-15-CI-01-browser-matrix.md)。60 分钟预算
尚未经过完整远端验证；保留完整用例和失败报告，后续依据各组合实测数据决定是否
还需按文件分片。不能从本地子集通过推断整个工作流可在预算内完成。

安装范围的环境策略现由入口和 Playwright installed 配置共同校验。JASSUB 的
渲染/截图/队列替换及 Multiple Subtitles 的原生事件恢复对照不能继承进入标准
安装验收；MediaBunny/Iframe/Mask/DASH 既有规则也不能通过直接载入配置绕开。
普通 source/ad hoc 诊断保持可用，明确停用的环境值不被误拒绝。详见
[CI-01 环境策略记录](changes/2026-09-15-CI-01-rendering-policy.md)。这只是本地
测试入口修复，不代表原有浏览器失败、远端工作流或发布门槛已关闭。