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。如果安裝了公式模組,它還會等待最新計算結果應用完成。
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。
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,並將改動交付協作與審閱。
你覺得這篇文檔如何?