截图与视觉检查

结合结构化回读、真实渲染截图和幻灯片布局检查,验证内容结果。

视觉检查把内容模型转换为可供核验的图像和布局证据。Agent 先核对数据与公式,再检查实际渲染出的文字、图形和页面;发现问题后通过 Facade 修正内容,然后重新检查新的状态。

三类证据,回答不同问题

证据能够确认什么
结构化回读原始值、公式及其计算结果、段落与对象属性。
PNG 截图实际可见的内容,包括裁切、图表、颜色与整体版式。
布局诊断基于渲染结果得出的规则、对象 ID、边界与问题位置,用于定位需要修改的对象。

先准备内容状态与依赖

截图与 Layout Lint 处理的是已经物化的 UnitData。它们不连接远端 target,也不解释 changeset。对于协同内容,先调用 pull(),公式修改后等待计算完成,再调用 exportUnitData()。在 Worktree 中,导出的应当是确实要检查的那份草稿。应用可以将 target、revision 和检查范围与报告一并保存,从而说明所审阅的是哪一份状态。

主 Unit 的 Snapshot 并不包含全部依赖。跨 Unit 公式的 Sheet/Relational Table 源数据通过 formulaReferenceUnits 传入,嵌入内容通过 embeddedUnits 传入子 Unit。Render Page 先物化依赖,再创建宿主,因此公式和嵌入块加载时其来源已经就位。UUID 图片可以用 resolveUnitScreenshotImageAssets() 配合应用提供的 resolver 准备;解析是 best-effort 的,缺失的资源也需要核查。

从内容到稳定画面

100%

univer-render-runtime 托管应用构建的 Render Page,并在 Node.js 中启动浏览器。页面上的内容由 Univer 产品插件还原,双方会核对页面协议版本是否一致。一个 Runtime 的渲染操作通过一条串行队列执行,因此可以跨多轮检查复用同一个 Runtime。使用完毕后,由 Runtime 的所有者调用 close()。

就绪条件随产品而不同。由公式驱动的图形会等待结果离开 pending,必要时还要等待连续多帧像素保持不变,以避免截取到播放中的动画。Relational Table 会等待字体、计算、活动的 table/view,以及 DOM/Canvas 布局全部稳定。公式结果离开 pending 也可能是错误,因此数值和状态都需要检查。

当前实现将主 UnitData、公式来源与嵌入子内容的序列化结果一起计算哈希,作为渲染会话 key。只要内容发生变化,同一个 Unit ID 也会得到不同的 key,因此既能复用 Runtime,又不会仅凭 ID 复用旧图像。

按产品选择检查范围

产品可选范围与输出
Sheet选择工作表和 A1 区域,输出该区域的 PNG。重要的结果需要显式选入范围。
Doc选择页面或逐页遍历,每页输出一张 PNG。
Slide使用从 1 开始计数的页码或 page ID 选页,可以另外生成 contact sheet 总览。
Relational Table截取打开时的活动表格/视图工作台,画面来自浏览器 DOM + Canvas。
Canvases使用整页内容边界,或使用 region / elementIds 选择器,两者互斥;padding 与布局证据均为可选项。

unit-screenshot 返回图片 bytes、尺寸、页面或区域的标识以及建议的文件名,文件由应用保存。Scale 的取值范围是 0.1–4。maxPages 和单图的 maxPixels 可以配置。scale 翻倍会使像素数大约变为四倍,因此内容较大时应分区域检查。PDF 不在这套截图入口的范围内,该入口只覆盖上述五个产品。

截图与布局检查共用内容状态

以下示例对同一份 Slide 数据和公式来源执行截图和 Layout Lint。renderRuntime 是已有的渲染 Runtime,slideData 是准备好的快照。这两个能力都不写入文件。页面构建与资源清理请参见 AI SDK 视觉检查。

TypeScript
import { createUnitScreenshot } from '@univer-cli/unit-screenshot'import { createUnitLayoutLint } from '@univer-cli/unit-layout-lint'const source = {  unitType: 'slide' as const,  unitData: slideData,  formulaReferenceUnits,}const screenshot = createUnitScreenshot({ runtime: renderRuntime })const lint = createUnitLayoutLint({ runtime: renderRuntime })const capture = await screenshot.capture({  ...source,  target: { kind: 'slide-pages', pages: [1], scale: 2 },})const report = await lint.lint({ ...source, pages: [1] })

Slide:从字形墨迹定位问题

Layout Lint 使用浏览器提供的布局事实。模型中元素的 declared 是声明框,文本的 ink 是字形实际落墨的范围,会结合排版、对齐与旋转映射到页面坐标。文本框本身没有越出页面,并不能说明其中的字形也未越出。

当前规则检查依据
text-off-page文字实际 ink 超出页面边界。
text-escapes-container文字明显溢出匹配到的较小的不透明容器。
text-overlaps-text两段实际文字 ink 出现明显重叠。

报告包含 coverage.pages 和 coverage.rules,说明本次检查覆盖了哪些页面、执行了哪些规则。每条 finding 带有 pageId、元素 id、text.ink,以及相应的 overflow、container 或 other 证据。fingerprint 保持稳定,便于对比多轮修复的结果。目前所有 finding 均为 warning,需要结合截图一并查看;列表为空仅说明所选范围没有触发这几条规则。

Canvases:验证浏览器实际连线路径

Canvases 的截图还会额外返回 layoutAnalysis,其中包含浏览器解析得到的 routes、issues 与 summary。这与只支持 Slide 的 unit-layout-lint 是两个不同的入口。模型中的自动连线路径可能尚未解析,如需查看最终走向,应使用 source: 'rendered' 的结果。

诊断可以指出穿过元素的连线、交叉位置、箭头碰撞与标签冲突,并给出对应的 connectorIds、elementIds 和 focusBounds。修正涉及的对象后,先截取一块区域或一组元素进行检查,再回到整张画布确认。这样就能把一处视觉问题对应到一次具体的 Facade 修改。

把检查结果带入交付

100%

结构化结果、范围与页面信息、图片和诊断应当一并保留。截图不能证明公式是否正确,Lint 也不能替代人工查看页面。涉及工具栏、焦点与弹出菜单的交互,仍需要在 Web 编辑器中验证。跨 Unit 的内容还需确认依赖已经加载。

在将 Worktree 标记为 Ready 之前完成这些检查,审阅者才能将每处内容变化与证据对应起来。执行机制参见无头与服务端计算,编排参见 Agent 与自动化。

返回功能总览

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.