AI SDK

Univer Office SDK 包含三個 SDK：Web SDK 提供嵌入式編輯器和無頭內容處理能力，Server SDK 提供協同與檔案匯入匯出能力，AI SDK 提供 Agent 工作流程能力。

AI SDK 是用於建立 Office CLI 的 TypeScript SDK。它為 AI Agent 與自動化流程提供 Node.js 入口，用於載入、理解、修改與檢查 Univer Unit¹。

AI SDK 是一組可組合的能力，並非固定的產品 CLI。命令名稱、參數、目標、身分與授權、輸出及部署都由業務應用程式決定。

建議的應用程式結構

本指南採用 CLI + Web + Server 架構：

• CLI 是 AI Agent 或使用者操作 Unit 的入口。
• Web 提供實際頁面，供互動編輯與人類審閱。
• Server 儲存 CLI 與 Web 共用的 Unit、修訂版本及協同狀態。

CLI、Web 與 Server 可分開部署，也能全部在本機執行。先以 Collaboration SDK 建立 Web + Server，再加入 CLI，是建議的學習路徑，不是部署限制。

使用 Commander 組織 CLI

AI SDK 基礎套件提供結構化 TypeScript API。命令預設集將常用能力轉成原生 Commander Command 物件。根程式始終由業務應用程式掌控：

import { Command } from "commander";const program = new Command("my-cli");program.addCommand(presetCommand);program.addCommand(applicationCommand);await program.parseAsync();

• 命令預設集提供預設參數、說明與文字或 JSON 輸出。
• 應用程式命令組合 Runtime²、業務目標、身分、提交策略或檔案策略。
• 兩者都是一般 Commander Command，可混合加入同一根程式。

後續每個主題會先介紹基礎能力，再說明如何接入 Commander。

逐步建立能力

AI SDK 指南從 Unit 核心內容操作開始，再加入檔案、視覺、協同與程序能力：

載入與編輯 Unit→ Office 檔案匯入匯出→ 視覺檢查→ 隔離的 Worktree 編輯與審閱→ Runtime 重用與 Daemon

1. 載入與編輯 Unit

先建立最小 AI Agent 迴圈：以 Collaboration Runtime 載入 Unit，透過 Inspection 理解內容，執行 Univer Facade 程式碼，並在需要時查找 Facade API。

2. 接入 Office 檔案邊界

使用 Exchange 在 Office 檔案與 UnitData 間轉換。匯入的 Unit 保留在 Collaboration Server；匯出前先透過 Collaboration Runtime 取得最新 UnitData。

3. 加入視覺檢查

結構化輸出無法完整描述頁面版面。Screenshot 為 AI Agent 提供渲染圖片，Layout Lint 則提供結構化的版面診斷。

4. 使用 Worktree 隔離修改

AI Agent 可以多輪編輯與檢查 Worktree 草稿。準備完成後，人類在 Web 審閱，再選擇 Merge 或 Reopen。

5. 重用成本較高的執行環境

先使用短生命週期 Runtime。只有啟動成本、並行或跨 CLI 程序重用變得重要時，才加入集區、Worker 或 Daemon。

建議閱讀順序

1. 文件載入與內容操作
2. Office 檔案匯入匯出
3. 視覺檢查
4. Worktree：AI Agent 編輯與人類審閱
5. Runtime 重用與 Daemon
6. 套件目錄
7. 範例