# AI SDK

> 了解如何透過 AI SDK 為 Univer 應用程式加入 Node.js CLI 與 AI Agent 入口。

- Human documentation: [https://docs.univer.ai/zh-TW/ai](https://docs.univer.ai/zh-TW/ai)

- Agent Markdown: [https://docs.univer.ai/zh-TW/ai.md](https://docs.univer.ai/zh-TW/ai.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [index.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/ai/index.zh-TW.mdx)

---

Univer Office SDK 包含三個 SDK：[Web SDK](https://docs.univer.ai/zh-TW/guides/sheets.md) 提供嵌入式編輯器和無頭內容處理能力，[Server SDK](https://docs.univer.ai/zh-TW/server.md) 提供協同與檔案匯入匯出能力，[AI SDK](https://docs.univer.ai/zh-TW/ai.md) 提供 Agent 工作流程能力。

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

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

## 建議的應用程式結構

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

```mermaid
flowchart LR
    Agent(["AI Agent / CLI 使用者"]) --> CLI["<b>AI SDK</b><br/>業務 CLI"]
    Human(["人類使用者"]) --> Web["<b>Web SDK</b><br/>Web"]
    CLI --> Server["<b>Server SDK</b><br/>協同 · 檔案轉換"]
    Web --> Server
    Server --> Storage["儲存"]
    classDef default rx:8,ry:8,stroke-width:1px
    classDef actor fill:transparent,stroke:none
    class Agent,Human actor
```

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

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

> [!NOTE: 也支援純 CLI 應用程式]
> AI SDK 可直接處理本機 Unit。可透過結構化輸出、AI Agent 視覺檢查或匯出的 Office 檔案檢查結果。即時 Web 頁面、共用修訂版本、History 與 Worktree 需要對應的 Web 及協同能力。

## 使用 Commander 組織 CLI

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

```ts
import { Command } from "commander";

const program = new Command("my-cli");

program.addCommand(presetCommand);
program.addCommand(applicationCommand);

await program.parseAsync();
```

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

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

## 逐步建立能力

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

```text
載入與編輯 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. [文件載入與內容操作](https://docs.univer.ai/zh-TW/ai/content-operations.md)
2. [Office 檔案匯入匯出](https://docs.univer.ai/zh-TW/server/import-export/node.md)
3. [視覺檢查](https://docs.univer.ai/zh-TW/ai/visual-inspection.md)
4. [Worktree：AI Agent 編輯與人類審閱](https://docs.univer.ai/zh-TW/ai/worktree.md)
5. [Runtime 重用與 Daemon](https://docs.univer.ai/zh-TW/ai/runtime-architecture.md)
6. [套件目錄](https://docs.univer.ai/zh-TW/ai/packages.md)
7. [範例](https://docs.univer.ai/zh-TW/ai/examples.md)

[^document-unit]: Unit 指一個文件實例，例如一個活頁簿或一篇文件。工作表是活頁簿的一部分，不是獨立的 Unit。

[^live-runtime]: 此處的 Runtime 指已載入文件的 Univer 實例及其操作 Unit 所需的執行資源，不是 Node.js 執行檔，也不是儲存至磁碟的文件快照。