视觉检查

使用 Render Runtime、Screenshot 与 Layout Lint 为 Agent 提供渲染后的视觉信息。

Inspection 可以校验值、段落和页面结构,但无法完整描述文本溢出、元素重叠、图形位置和最终版式。完成结构化内容读写之后,再加入浏览器渲染,Agent 即可检查真实的视觉效果。

text
最新 UnitData→ Render Runtime├── Screenshot ──> PNG ──> Agent 视觉检查└── Layout Lint ─> 结构化 finding ──> Agent 修正

第一步:准备明确的内容状态

Screenshot 和 Layout Lint 处理已经 materialize 的 UnitData,不加载远程 target,也不解释 changeset。如果 Unit 处于协同环境,需要先同步并导出当前完整状态:

TypeScript
await runtime.pull();const unitData = await runtime.exportUnitData();

在 Worktree 场景下,从 draft target 导出 UnitData。本地应用可以直接使用已经加载或导入的 UnitData。无论来源是什么,视觉检查始终针对一个明确的内容状态。

第二步:构建 Render Page

@univer-cli/univer-render-page 负责组装浏览器端的 Render Page。应用决定启用哪些 Univer 插件,并构建静态页面:

TypeScript
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、启动浏览器,并管理页面协议:

TypeScript
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 选择、分页、缩放、命名和资源限制:

TypeScript
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:

TypeScript
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 上:

TypeScript
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:

TypeScript
try {  await program.parseAsync();} finally {  await renderRuntime.close();}

如需自定义 Agent 的输入与输出,可以绕过预设,直接调用基础包。不要在共享的高权限主机上直接渲染不可信的 UnitData,应在中间加入受限用户、容器或其他进程隔离边界。

具备视觉检查能力之后,即可将同一组内容操作与检查能力接入 Worktree:Agent 编辑与人类审阅 流程。

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.