视觉检查
使用 Render Runtime、Screenshot 与 Layout Lint 为 Agent 提供渲染后的视觉信息。
Inspection 可以校验值、段落和页面结构,但无法完整描述文本溢出、元素重叠、图形位置和最终版式。完成结构化内容读写之后,再加入浏览器渲染,Agent 即可检查真实的视觉效果。
最新 UnitData→ Render Runtime├── Screenshot ──> PNG ──> Agent 视觉检查└── Layout Lint ─> 结构化 finding ──> Agent 修正第一步:准备明确的内容状态
Screenshot 和 Layout Lint 处理已经 materialize 的 UnitData,不加载远程 target,也不解释 changeset。如果 Unit 处于协同环境,需要先同步并导出当前完整状态:
await runtime.pull();const unitData = await runtime.exportUnitData();在 Worktree 场景下,从 draft target 导出 UnitData。本地应用可以直接使用已经加载或导入的 UnitData。无论来源是什么,视觉检查始终针对一个明确的内容状态。
第二步:构建 Render Page
@univer-cli/univer-render-page 负责组装浏览器端的 Render Page。应用决定启用哪些 Univer 插件,并构建静态页面:
import { createPresetRenderUniver, mountUniverRenderPage } from "@univer-cli/univer-render-page";const container = document.querySelector<HTMLElement>("#app");if (container === null) throw new Error("#app is required");await mountUniverRenderPage({ container, createUniver: createPresetRenderUniver,});Render Page 是浏览器端的渲染入口,不是供人审阅的页面。它接收 Node.js 传入的 UnitData,返回 PNG 或布局数据。
第三步:创建 Render Runtime
@univer-cli/univer-render-runtime 在 Node.js 中托管 Render Page、启动浏览器,并管理页面协议:
import { createUniverRenderRuntime } from "@univer-cli/univer-render-runtime";const renderRuntime = await createUniverRenderRuntime({ renderPageRoot,});一个 Render Runtime 可以按顺序执行多次操作。应在更外层的生命周期边界复用它,不要为每张图片重新启动浏览器。
第四步:生成 Screenshot
@univer-cli/unit-screenshot 是 Sheet、Doc、Slide、Board 和 Base 截图的高层入口,负责 target 选择、分页、缩放、命名和资源限制:
import { createUnitScreenshot } from "@univer-cli/unit-screenshot";const screenshot = createUnitScreenshot({ runtime: renderRuntime });const result = await screenshot.capture({ unitType: "sheet", unitData, target: { kind: "sheet-range", sheetName: "Data", range: "B2:H40", scale: 2, },});返回结果可能包含多张图片。每张图片都带有 PNG bytes、宽高、所属页面或 target 的标识,以及建议的文件名。该包不写入文件;图片的存储位置和交付给 Agent 的方式由业务应用决定。
不传 target 时,Screenshot 按 Unit 类型选择默认内容,例如 Sheet 的 active worksheet used range、Doc 的所有页面或 Slide 的所有页面。
第五步:诊断 Slide 布局
@univer-cli/unit-layout-lint 基于真实浏览器生成的布局数据,返回带证据的结构化 finding:
import { createUnitLayoutLint } from "@univer-cli/unit-layout-lint";const lint = createUnitLayoutLint({ runtime: renderRuntime });const report = await lint.lint({ unitType: "slide", unitData, pages: [1, "closing-slide"],});当前规则包括:
text-off-page:文字实际 ink 超出页面;text-escapes-container:文字明显溢出较小的不透明容器;text-overlaps-text:两个实际文字 ink 区域明显重叠。
finding 是带证据的审阅建议,不一定都需要修改。Agent 可以结合 Screenshot 判断,继续修改 Facade 代码,然后重新执行视觉检查。
第六步:接入 Commander
Screenshot 和 Layout Lint 都提供原生 Commander 预设。将前面创建的 capability 和业务侧的 UnitData loader 注入预设,再把它们添加到文档内容加载与读写中创建的同一个 program 上:
import type { UnitScreenshotCommandDependencies } from "@univer-cli/unit-screenshot-command";import { createUnitScreenshotCommand } from "@univer-cli/unit-screenshot-command";import type { UnitLayoutLintCommandDependencies } from "@univer-cli/unit-layout-lint-command";import { createUnitLayoutLintCommand } from "@univer-cli/unit-layout-lint-command";import type { Command } from "commander";function addVisualCommands( program: Command, dependencies: { loadUnit: UnitScreenshotCommandDependencies["loadUnit"]; writeImages: UnitScreenshotCommandDependencies["writeImages"]; loadSlide: UnitLayoutLintCommandDependencies["loadUnit"]; },): void { program.addCommand( createUnitScreenshotCommand({ screenshot, loadUnit: dependencies.loadUnit, writeImages: dependencies.writeImages, }), ); program.addCommand( createUnitLayoutLintCommand({ lint, loadUnit: dependencies.loadSlide, }), );}预设命令负责截图 selector、Slide page selector、--json、默认文本输出和 Commander 的错误退出。Unit ID 到内容状态的映射与 PNG writer 通过函数参数显式注入。Render Runtime 的生命周期仍由应用管理。
Screenshot 预设还可以包含浏览器安装与探测子命令。浏览器不会在每次截图时被隐式下载。
第七步:释放浏览器资源
创建者在最外层的 Commander 生命周期边界关闭 Render Runtime:
try { await program.parseAsync();} finally { await renderRuntime.close();}如需自定义 Agent 的输入与输出,可以绕过预设,直接调用基础包。不要在共享的高权限主机上直接渲染不可信的 UnitData,应在中间加入受限用户、容器或其他进程隔离边界。
具备视觉检查能力之后,即可将同一组内容操作与检查能力接入 Worktree:Agent 编辑与人类审阅 流程。
你觉得这篇文档如何?