HyperFrames v0.7.84 可观测性升级：全量实时 DOM 元素计数与静态扫描去偏实践

HyperFrames v0.7.84 可观测性升级：全量实时 DOM 元素计数与静态扫描去偏实践

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

HyperFrames v0.7.84（发布于 2026-07-30）聚焦于一个"观察型"（observational）升级：让"composition 元素数量（element-count）"这一信号在整个渲染集群中变得可信。此前只有约 17% 的渲染会通过 probe 会话拿到实时 DOM 计数，其余渲染只能依赖静态标记扫描，而该扫描会被内联脚本中的标记文本污染计数。本次版本让每次渲染都上报实时 DOM 大小，并修正了静态回退扫描的偏差。阅读本文后，你将理解 HyperFrames 中元素计数信号的两条来源链路（live/static）、其源码级实现原理，以及如何通过可观测性字段验证本次修复的效果。

版本概览：一次纯观测性的信号修复

v0.7.84 的定位非常明确——不改变任何路由行为（no routing behaviour changes），只修正"元素计数"这一可观测性信号的准确性与覆盖度。核心变更可归纳为三点：

• Feature（Engine）：每次渲染都测量实时 DOM 大小，不再只覆盖获得 probe 会话的渲染（commitd74afc7b7）。
• Fix（Producer）：将<script>脚本体剥离收敛到固定点（fixed point），而非只做一遍替换（commit042d5aaba）。
• Fix（Producer）：消除静态元素计数的偏差，并停止在测量失败时把计数归零（commitc61a24b51）。

要理解这三项变更的价值，必须先搞清楚"元素计数"在 HyperFrames 渲染管道中扮演的角色。

背景：为什么元素计数信号必须可信

元素计数（element count）是 HyperFrames 渲染决策中的重要输入。从源码注释可以还原它的用途：

• 它是"短合成波段门控"（short-comp band gate）的判定依据，对应resolveCompositionElementCount解析器（见 renderOrchestrator.ts）；
• 它用于评估大型运行时 DOM（runtime DOM）的分布形态——"源代码很小、运行时 DOM 巨大"正是需要被捕获的危险形态（见 observability.ts 与 frameCapture.ts 的注释）。

在 v0.7.84 之前，元素计数存在两个系统性缺陷：

1. 覆盖度不足：路由门控（routing gate）只能从 probe 会话读取实时计数，而 probe 会话是有条件的（conditional）——只有时长未知、合成未解析或特定媒体场景才会启动（见 renderOrchestrator.ts）。这意味着整个集群约 83% 的渲染（无 probe 会话）完全没有实时元素信号，其元素计数分布对可观测性管道而言是"不可知"的。
2. 静态扫描有偏：静态回退扫描是对编译后 HTML 的字符串扫描，内联脚本中的普通 JS 文本（如const html = "</div>"或模板字符串拼出的</span>）会被误计为真实标签，造成系统性高估（bias）。

Feature：每次渲染都测量实时 DOM 大小

v0.7.84 的引擎侧核心变更位于 frameCapture.ts 的collectSessionInitTelemetry函数。它在初始化序列完成后测量实时 DOM 大小：

let elementCount: number | undefined; try { elementCount = await page.evaluate(() => document.getElementsByTagName("*").length); } catch { elementCount = undefined; }

实现细节体现了几个值得注意的工程决策：

• 测量时机：在 init 序列完成之后执行，此时脚本生成的元素已存在，page.evaluate能看到运行时创建的节点；
• API 选择：刻意使用document.getElementsByTagName("*")而非querySelectorAll——前者返回实时 HTMLCollection，其length不会像静态 NodeList 那样在 4 万节点的大 DOM 上物化出额外内存开销（见 frameCapture.ts 注释）；
• 失败语义：测量失败时保持undefined（绝不写 0）——0 与"合法的空合成"无法区分，若被并入统计会让集群的 p50/p99 悄悄吸收错误读数（见 frameCapture.ts 注释）。

测量结果通过[FrameCapture:INIT]日志行输出：

[FrameCapture:INIT] complete initDurationMs=... tweenCount=... elementCount=...

注意elementCount未测量时该字段整体省略而非写 0，以便下游解析器报告"缺失"而不是"空 DOM"（见 frameCapture.ts）。

覆盖率边界（务必理解）

源码注释明确警告了一个容易过度解读的边界（见 frameCapture.ts）："每次渲染"指"存活到 init 结束的每次渲染"。在浏览器启动、导航或 OOM 阶段死亡的渲染不会发出该字段——而恰好是超大 DOM 的合成更可能在早期失败，因此该分布存在幸存者偏差（survivor-biased），应把尾部视为下界。

Fix 1：脚本体剥离收敛到固定点

静态回退扫描countElementTags（见 renderOrchestrator.ts）会先剥离内联<script>/<style>体再计数。v0.7.84 将其从"一遍替换"改为"循环到固定点"：

let markup = html; for (let previous = ""; markup !== previous; ) { previous = markup; markup = markup.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, ""); }

这样做的原因：一遍替换可能重新形成它刚删除的模式——例如<scr<script>ipt>剥离后留下<script>，这属于不完整的多字符净化（CodeQL 会标记）。虽然影响本身为零（剥离后的字符串只用于计数、从不渲染），但一个"重新形成"的标签会扰动门控读取的计数。循环版本保证收敛：每轮迭代要么严格缩短字符串，要么无变化退出。

Fix 2：消除静态计数偏差，失败不再归零

计数的三种形态与"不数开标签"的取舍

countElementTags刻意设计为字符串扫描而非parseHTML+querySelectorAll——它在每次渲染、路由决策之前都要运行，而 2 万到 4 万节点的文档做完整解析是最昂贵的场景（见 renderOrchestrator.ts）。计数覆盖三种形态，每种都能补上其他形态的盲区：

开标签（非自闭合、非空元素）被刻意排除：编译后的合成内嵌内联脚本，a < b或x <breadth这类 JS 比较会在裸<letter扫描上产生误报。上述三种计数形态都要求字面闭合标记，普通 JS 比较和除法不满足条件——这一点有测试佐证（见 renderOrchestrator.test.ts）。

从"静态优先"到"live 优先、静态仅兜底"

更关键的是语义反转：v0.7.84 之前静态扫描是主要信号，而现在它只是 fallback。原因在于源码扫描永远看不到合成脚本运行时创建的元素（document.createElement）——这是正则无法闭合的无界低估。典型例子是style-10-prod的逐字幕词 caption 生成器：源码里只有 2 个标签，init 之后活 DOM 却有数千节点（见 renderOrchestrator.ts 与 renderOrchestrator.ts）。

新的解析优先级resolveCompositionElementCount（见 renderOrchestrator.ts）：

if (probeSession?.isInitialized) { try { const liveCount = await probeSession.page.evaluate( () => document.getElementsByTagName("*").length, ); if (typeof liveCount === "number" && Number.isFinite(liveCount)) { return { count: liveCount, source: "live" }; } } catch { // 导航中/页面崩溃等场景下回退到静态扫描，不阻塞渲染 } } return { count: countElementTags(html), source: "static" };

两点关键语义（见 renderOrchestrator.ts）：

• 只有live计数可以打开短合成波段（short band）——静态计数仅用于诊断。原因：已知时长、无媒体的合成如果脚本构建 4 万节点，不会启动 probe 会话，静态计数会读到 "2"。把这种读数当作实测值，等于放行波段本要排除的回归场景。调用方对非live一律失败关闭（fails closed）；
• 该语义在短波段基线读取期间被冻结（FROZEN）：基线版本记录的集群分布必须由后来做路由门控的同一个解析器测量，否则基线无效。

可观测性管道：elementCount 如何进入 telemetry

elementCount通过两层结构进入渲染可观测性汇总（见 observability.ts）：

• RenderInitObservability.elementCount：capture 会话 init 结束时的活 DOM 元素数，在路由决策之后测量，纯观测用途（覆盖门控看不到的渲染分布与尾部），见 observability.ts；
• RenderCaptureObservability.compositionElementCount+compositionElementCountSource: "live" | "static"：路由前的门控读数，带来源标记。live来自 probe 会话的真实 DOM，static来自countElementTags扫描，见 observability.ts。

两条字段不可互换（见 observability.ts）：前者查分布/尾部，后者查路由行为。

控制台日志与结构化汇总通过summarizeInitObservability合并（见 observability.ts）：它解析所有[FrameCapture:INIT]行，用maxReading取多会话中的最大值（"保留最坏观测值"语义）。并行渲染时，worker 的控制台缓冲区只在失败时传播，因此成功路径的 init 遥测通过mergeWorkerInitObservability（见 renderOrchestrator.ts）从各 worker 的 perf summary 结构化合并——同样使用 max 语义（防御某个 worker 在 init 脚本尚未完成 DOM 填充时被采样）。

测试验证：回归防线

仓库测试覆盖了本次修复的关键行为（见 renderOrchestrator.test.ts）：

• countElementTags("<div><span>a</span></div>") === 2——常规 HTML 闭合标签计数；
• countElementTags('<img src="a.png"><IMG SRC="b.png">') === 2——空元素（含大小写变体）计数；
• countElementTags("<circle/>".repeat(40000)) === 40000——40k 自闭合 SVG 元素不再数成 0；
• countElementTags("if(a<b/c>d){}") === 0——JS 比较表达式不产生误报；
• <script>if (a < b && x <breadth && y <imgWidth) {}</script>不膨胀计数——脚本体剥离有效；
• <div></div><script>const h = "</div></div></div>";</script>只数 1 个——模板字符串中的闭合标签不再污染；
• <div></div><scr<script></script>ipt>alert(1)</script>只数 1 个——嵌套混淆标签（fixed-point 剥离场景）不产生膨胀；
• resolveCompositionElementCount系列用例验证了 live 优先、无 probe 时回退 static 的优先级，以及失败的降级路径。

升级与验证建议

v0.7.84 为纯观测性发布，不改变渲染路由行为，因此可以直接升级而无需调整配置。升级后建议通过以下方式验证修复生效：

1. 覆盖度：观察 telemetry 中init.elementCount的上报率——修复前只有约 17% 的渲染（获得 probe 会话者）有此字段，修复后应覆盖所有存活到 init 结束的渲染；
2. 来源标记：查看capture.compositionElementCountSource字段，区分live与static占比——static的集群占比直接刻画了未来有条件 probe 启动可解锁的波段人口规模（见 observability.ts）；
3. 偏差消除：对比修复前后static计数的分布，验证内联脚本密集的合成不再出现系统性高估；同时确认超大 DOM 合成的测量失败保持缺失（undefined）而非 0。

如果需要对计数信号做更深层排查，可从 renderOrchestrator.test.ts 的用例出发，沿resolveCompositionElementCount → countElementTags → collectSessionInitTelemetry → summarizeInitObservability这条链路逐层核对。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes