Agent 與自動化

組合內容檢查、編輯與驗證,讓既有 Agent 操作 Office 內容。

AI SDK 將 Univer 的內容模型、Facade 和協同能力封裝為一組可組合的 TypeScript 能力。已有的 Agent 可以讀取並修改內容,檢查結果,然後交付人工審閱。模型選擇、工具協議和任務編排均由應用決定。

將內容能力接到既有 Agent

能力包返回結構化結果,應用可以將其接入自己的工具、服務或 CLI。可選的 -command 包將同一批能力封裝為原生 Commander 命令。無論採用哪種接入方式,Agent 操作的都是與 Web 編輯器共用的內容模型和命令系統。

能力實際職責
Inspection讀取結構、區域、段落和物件細節,以縮小任務範圍。
API Reference離線查詢隨包分發的 Facade 宣告、過載、型別和範例。
Content Execution將 workbook、doc、presentation、base 或 board 繫結到指定的 Unit,並生成待執行的程式碼。
Collaboration Runtime載入內容、擷取 mutation、協調遠端變更並明確提交 changeset。

Runtime 如何還原可編輯狀態

一個 Collaboration Runtime 從建立到銷燬只繫結一個 Unit。載入時,它先開啟應用提供的 backend,讀取 UnitData 或 Snapshot checkpoint,並在此基礎上重放 changeset,隨後將 revision 連續補齊到遠端 head。如果安裝了公式模組,它還會等待最新計算結果應用完成。

100%

fetch() 負責取回變更並對其進行校驗。pull() 透過 OT 協調遠端變更與本地的 pending、awaiting 狀態,然後應用協調結果。Runtime 還維護 baseRevision、knownHeadRevision、pendingMutationCount 和 awaitingChangeset,應用可據此判斷進度。

先定位內容,再執行 Facade

先向模型提供一份 overview,再按穩定 ID 或精確選擇器查詢目標,而不是直接傳送整份 Snapshot。Inspection 覆蓋 Sheet 區域、Doc 段落、Slide 頁面、Relational Table 的結構概覽和 Canvases 物件。Relational Table 的概覽包含欄位配置,但不包含記錄值和 View projection;需要時應透過 Facade 讀取這些內容。

prepareContentExecutionProgram() 透過 Unit ID 取得根 Facade,不依賴瀏覽器當前選中的文件,並會拒絕重複宣告同一個注入變數。read 模式下,Runtime 會在執行前攔截任何會產生持久化的業務操作;write 模式則捕獲目標 Unit 的 mutation。建立和銷燬 Unit 屬於獨立的生命週期操作,不在這個只處理單個 Unit 的執行入口範圍內。

遇到不熟悉的 API 時,find() 列出候選,show() 輸出準確的宣告及相關型別。這份索引隨 SDK 一起分發,既不需要內容引擎,也不依賴線上文件。接入細節見內容操作與 Package 概覽。

執行成功與提交確認是兩件事

execute({ mode: 'write' }) 會修改 live Unit,並將 mutation 累積為 pending。這不表示伺服器端已經儲存變更。 commit() 將 mutation 組成一個附帶提交身分的 changeset;返回的 ACK 必須與身分、內容和 revision 一致,提交才算確認。

提交狀態應用程式的處理
confirmed / nothing-to-commit變更已確認,或者沒有需要提交的內容。
pull-required遠端 revision 已前進。先呼叫 pull() 協調,再重新呼叫 commit()。
retry / unknown在同一個 Runtime 中保留 awaiting 狀態並重試 commit(),不要重新執行編輯程式碼。
conflict停止寫入,由應用決定恢復方式或重新載入。

提交結果不確定時,Runtime 會保留 sid + reqId,backend 可據此以冪等方式確認同一個 changeset,避免重複寫入編輯內容。backend 必須實現這套冪等約定。程式碼執行中途丟擲異常時,此前已產生的 mutation 可能仍然保留,因此需要檢查 pending 狀態再決定如何恢復。execute() 不是會自動回滾的事務。

下面的範例接收一個已載入的 Sheet Runtime,同時返回執行結果和提交結果。呼叫方按上面的狀態表處理後續動作,並在持有期結束時關閉 Runtime。

TypeScript
import { prepareContentExecutionProgram } from '@univer-cli/content-execution'import type { UniverCollaborationRuntime } from '@univer-cli/univer-collaboration-runtime'async function updateSales(runtime: UniverCollaborationRuntime) {  const pulled = await runtime.pull()  if (pulled.status === 'conflict') return pulled  const code = prepareContentExecutionProgram({    unitId: runtime.unitId,    unitType: 'sheet',    code: `      const sheet = workbook.getSheetByName('Data');      if (!sheet) throw new Error('Worksheet Data not found');      sheet.getRange('A2:B2').setValues([        [{ v: 'East', t: 1 }, { v: 128000, t: 2 }]      ]);      return sheet.getRange('A2:B2').getRawValues();    `,  })  const execution = await runtime.execute({ mode: 'write', code })  const commit = await runtime.commit()  return { execution, commit }}

高頻任務如何重用 Runtime

高頻任務可以按應用定義的 key,從 Worker Runtime 池中獨佔租用一個例項。同一個 key 的冷建立是 single-flight 的,lease 按 FIFO 順序排隊,不同的 key 可以分配到不同的 Worker。release() 歸還例項,TTL/LRU 回收空閒資源,invalidate() 淘汰已不可信的例項。

key 應能區分 backend、Unit 和所在的 Worktree。池不會驗證兩次初始化輸入在語義上是否相容。Daemon 可以跨多次短 CLI 呼叫持續持有這個池,但複用的 Runtime 仍然需要同步並確認提交。啟動成本、常駐記憶體和 Worker 數量需要權衡,詳見 Runtime 複用與 Daemon。

從自動化任務到人類審閱

將這些能力組合起來,可以用於生成報表、整理業務資料、填充模板或生成內容。流程依次為:定位目標,透過 Facade 寫入,等待結果所依賴的計算完成,回讀數值、文字和物件屬性;需要檢視渲染效果時,再加入截圖與視覺檢查。

需要人工確認時,Agent 在 Worktree 中修改內容。它分多輪進行編輯和自檢,內容進入 Ready 狀態後由人審閱,決定是否 Merge。跨 Unit 的任務需要按 Unit 分別追蹤執行和提交結果,因為多個 Runtime 合起來並不構成跨文件的原子事務。

身分、授權、模型接入和任務生命週期仍由應用負責。read/write 限制約束的是業務操作的邊界;不可信 JavaScript 的程序隔離、檔案和網路權限仍需由應用配置。完整流程可從快速開始和 Univer CLI 範例開始。

透過 Skills 產生與編輯內容

如需讓現有 Agent 直接處理 Office 內容,可按檔案所在位置選擇對應的應用:

  • CLI Skills:建立、編輯和檢查本地 Office 檔案,再開啟 Viewer 審閱。
  • Workspace Skills:處理已連線 Space 中的檔案,生成 Office 內容和 Web App,並將改動交付協作與審閱。

返回功能總覽

你覺得這篇文檔如何?

© 2026 DreamNum Co., Ltd.