fix(danmuku): [PKG-DANMUKU-MASK-LOAD-01] recover stalled-frame rows and remove relaxed placement backlog

2026-10-18 19:01:20 -08:00 · 2026-09-14 22:13:08 +08:00
1 parent 475d38043e
commit 314a1c3163
@@ -0,0 +1,103 @@
+# PKG-DANMUKU-MASK-LOAD-01 真实模型负载下的弹幕调度
+
+状态：本缺陷修复验收完成；完整组合/分发任务仍独立开放。起点
+475d38043e917b412018c6851d6a7464ef7bda67。范围为弹幕内部调度及组合验证；
+Mask生产实现、MediaPipe模型/SDK、视频尺寸、负载与等待预算不变。
+
+## 缺陷与诊断
+
+原始真实模型矩阵18项12通过6失败，保留在
+[原始记录](2026-09-14-PKG-DANMUKU-08-combined-load.md)及
+[原始证据](../baselines/danmuku-combined-load-validation.json)。
+5项候选120行未完整显示，另1项beta核心负载前行未显示；旧插件也漏显，
+不能据此声称是重构引入的回归。
+
+增加只读pending/reserved行快照和显式Chromium CDP CPU诊断入口。
+单worker原实现诊断仍失败：120行均已采样，仅68行显示，reserved中62行，
+其中52行尚未显示，确认串行放置积压。CPU采样显示SDK结果转换中的
+createImageBitmap约5.57秒，二值mask转换约1.01秒，drawImage约0.89秒；
+自有调度约15毫秒。这是一次采样的自耗时，不是精确分阶段计时或总成本保证。
+调用栈指向MediaPipe转换image/segmentationMask的原有路径；没有替换SDK私有
+函数、禁用输出、降低模型/视频尺寸或使用假时钟让负载通过。
+
+## 结构与兼容边界
+
+- `placement.ts`从Worker中原样提取轨道计算。Worker保留旧消息协议；
+  scheduler仅在`antiOverlap: false`时直接调用同一计算，消除逐行消息往返。
+  默认防重叠模式和内部postMessage仍使用Worker，没有新增公共选项或依赖。
+- `sampling-window.ts`拥有连续媒体采样及当前document的visibility监听器。
+  自动调度可补回上次已在wait池、尚未被采样而被连续播放跨过的行。
+  不追加播放刚插入的过期行，不因跨窗口再次调用已采样的false回调。
+  pause/seek/hide/reset等失效、原生seeking、页面隐藏、反向时间和document切换
+  切断追赶窗口；销毁释放监听器及保留引用。
+- 公开`readys`仍是当前时间±0.1秒查询；公开wait/ready池不被采样模块写入。
+  ready优先级、批次身份保留、beforeVisible串行与取消、可见事件顺序、
+  显示寿命和已有DOM/CSS/类型/分发入口保持不变。
+
+这是API-04/05/08/11/12边界内的缺陷修复，扩展了PKG-DANMUKU-12只处理
+异步等待期间采样的能力。连续播放CPU卡顿后可能出现旧版漏掉的行；
+它不承诺跨暂停、seek或后台时段重放，也不承诺无限吞吐量。
+架构、维护入口和资源归属同步更新于两个包的ARCHITECTURE.md。
+
+## 验证记录
+
+固定Node24.21.0、YarnClassic1.22.22；没有新增依赖。
+
+- 可控旧红：首批6项4通过2失败，分别复现允许重叠模式Worker积压和CPU跨窗漏显。
+- 当前弹幕Node套件275/275通过，包含串行回调、生命周期重入、公开readys不变、
+  不重放追加过期行、false回调不额外重试及visibility监听器释放。
+  后续增加document迁移用例：旧窗口不追赶、旧监听器移除、新窗口恢复连续采样，
+  最终source/main/legacy各276/276通过。直接内部用例仍执行源码，集成用例加载
+  指定产物及其实际内嵌Worker，不把所有276项都称为产物执行。
+- 首次直接`yarn tsc`错误地进入根`.bin/tsc`所指向的TS5.1.6兼容别名，
+  setting-lifecycle闭包收窄产生TS18048。按既有typechecking.md指定的
+  `node node_modules/typescript/bin/tsc -p packages/artplayer-plugin-danmuku/tsconfig.json --noEmit`
+  使用生产编译器TS5.9.3通过。未修改该源文件或放松strict；TS4.3/5.1的
+  消费者兼容与生产源码编译器是不同要求。
+- 第一轮修复后真实模型矩阵18/18退出0：9候选完整交付、9冻结旧插件行为观察；
+  Chromium/Firefox/WebKit、当前/5.4.0/5.3.1-beta.1核心覆盖。每个候选120行
+  完整显示且回收，模型保持运行。
+
+最终结果及实际输入指纹见[机器证据](../baselines/danmuku-mask-load-validation.json)。
+
+| 验证 | 结果与范围 |
+| --- | --- |
+| 实际模型源码矩阵 | 18通过，9候选完整交付、9旧插件观察；216.28秒 |
+| 首次寿命/PiP/时钟回归 | 72通过12失败；12失败全部是候选允许重叠路径零Worker请求与旧测试前提冲突。48项PiP包含32原生播放和16API不可用记录 |
+| 扩展两种放置路径后的源码寿命/时钟 | 60通过；48寿命含24候选/24旧插件，12时钟含6候选/6旧插件；114.36秒 |
+| main候选 | 39通过：9模型、24寿命、6时钟；162.43秒 |
+| legacy候选 | 同范围39通过；160.03秒 |
+| Node source/main/legacy | 每轮276通过；内部纯函数仍是源码测试，集成测试加载对应产物 |
+| 类型与实际安装 | TS5.9.3严格源码通过；4项类型/实现赋值/编辑器测试通过；实际隔离包12组消费者通过，保留精确旧声明诊断对照 |
+| 构建/字节一致性 | 弹幕与Mask三格式构建通过；Mask产物无变化；原轨道函数逐字一致；隔离包79个成员仍匹配当前文件，三份docs/compiled与dist一致 |
+
+源码/main/legacy的27个候选真实模型负载均显示120个唯一行，最终120行wait、
+无节点引用、pending/reserved均为空，模型继续输出。原来负载前漏显的beta核心
+路径同样通过。全部最终浏览器报告零重试、零跳过；API不可用是独立记录。
+浏览器为Windows Chromium153.0.8010.12、Firefox155.0、WebKit26.6。
+模型下帧间隔P95仍约79–275毫秒，故这里确认交付完整性，不宣称解决模型帧率
+或GPU/WASM性能。公开类型、模型输入、负载和原等待预算未改变。
+
+另一次错误调用把`.mjs`传入只接受CommonJS/UMD的同步VM测试宿主，271项
+146通过125失败，语法解析报Unexpected token export，插件尚未执行。
+保留该日志；不通过改写ESM字节伪装原生模块执行。test/README.md已明确入口范围。
+真实ESM导入由仓库外打包消费验证，完整ESM浏览器分发仍属PKG-DANMUKU-09。
+
+原始日志、CPU profile和各轮浏览器报告归档在refactor/.cache/danmuku-mask-load-*。
+首次寿命回归仍假设允许重叠模式必经Worker，该前提已被本修复取消；已保留
+原失败并扩展两种模式。防重叠候选仍要求一对真实Worker请求/回复、至少1400ms
+受控延迟及至少900ms显示；允许重叠候选要求零请求/回复和至少900ms显示。
+旧插件两种模式都仍复现被等待吃掉寿命的缺陷。原寿命断言没有降低。
+CPU卡顿用例新增候选全部三行按序显示的断言，旧插件CPU漏显继续独立观察。
+
+## 重跑与回退
+
+实际模型：`yarn test:browser:source test/browser/danmuku-mask-native.spec.js
+--grep 'actual model and Danmuku' --workers=2`。main/legacy分别指定存在的
+ARTPLAYER_DANMUKU_ARTIFACT和ARTPLAYER_MASK_ARTIFACT文件；报告包含实际输入哈希。
+诊断仅Chromium单worker增加ARTPLAYER_MASK_PROFILE=1；正式验收不打开profile。
+每轮终止后先归档报告，再运行下一轮，不能混用源与产物证据。
+
+回退本任务的独立提交会恢复原Worker逐行路径及点采样，并重新暴露记录中的漏显。
+没有公共类型或数据迁移。完整组合任务08/Mask05、设备、其他包和发布复盘仍独立
+验收；本修复不授权push、部署或npm发布。