截圖與視覺檢查
結合資料回讀、真實渲染截圖與簡報版面檢查。
視覺檢查把內容模型轉換為可供核驗的影像和版面配置證據。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 的,缺失的資源也需要核查。
從內容到穩定畫面
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 視覺檢查。
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 修改。
將檢查證據帶入交付
結構化結果、範圍與頁面資訊、圖片和診斷應當一併保留。截圖不能證明公式是否正確,Lint 也不能替代人工檢視頁面。涉及工具欄、焦點與彈出選單的互動,仍需要在 Web 編輯器中驗證。跨 Unit 的內容還需確認依賴已經載入。
在將 Worktree 標記為 Ready 之前完成這些檢查,審閱者才能將每處內容變化與證據對應起來。執行機制參見無頭與伺服器端計算,編排參見 Agent 與自動化。
你覺得這篇文檔如何?