# AI SDK

> 了解 AI SDK 如何为 Univer 应用增加 Node.js CLI 与 Agent 操作入口。

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

Univer Office SDK 包含三个 SDK：[Web SDK](https://docs.univer.ai/zh-CN/guides/sheets.md) 提供嵌入式编辑器和无头内容处理能力，[Server SDK](https://docs.univer.ai/zh-CN/server.md) 提供协同与文件导入导出能力，[AI SDK](https://docs.univer.ai/zh-CN/ai.md) 提供 Agent 工作流能力。

**AI SDK** 是一套用于构建 Office CLI 的 TypeScript SDK。它为 Agent 和自动化程序提供 Node.js
入口，用于加载、理解、修改和检查 Univer 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 是 Agent 或用户操作 Unit 的入口；
* Web 展示实际页面，支持交互式编辑和人类审阅；
* Server 保存 CLI 与 Web 共享的 Unit、revision 和协同状态。

CLI、Web 与 Server 可以分别部署，也可以全部运行在本地。先使用 Collaboration SDK 构建 Web + Server，
再增加 CLI 入口，是推荐的学习路径，不是部署限制。

> [!NOTE: 也可以只构建 CLI 应用]
> AI SDK 支持直接处理本地 Unit。此时可以通过结构化结果、Agent 视觉检查或导出的 Office
> 文件查看结果； 实时 Web 页面、共享 revision、History 和 Worktree 需要相应的 Web 与 Collaboration
> 能力。

## 使用 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();
```

* **预设命令**提供默认参数、help、文本或 JSON 输出；
* **应用级命令**组合 Runtime、业务 target、身份、提交或文件策略；
* 两者都是普通 Commander `Command`，可以在同一个根程序中混合使用。

后续每个主题都会先介绍基础功能 API，再说明如何接入 Commander。

## 按能力逐步构建

AI SDK 文档从最核心的 Unit 内容操作开始，再逐步增加文件、视觉、协作和进程能力：

```text
加载与读写 Unit
→ Office 文件导入导出
→ 视觉检查
→ Worktree 隔离编辑与审阅
→ Runtime 复用与 Daemon
```

### 1. 加载与读写 Unit

首先建立 Agent 操作 Unit 的最小闭环：使用 Collaboration Runtime 加载 Unit，通过 Inspection 理解内容，
执行 Univer Facade 代码，并在需要时查询 Facade API。

### 2. 连接 Office 文件边界

使用 Exchange 在 Office 文件与 UnitData 之间转换。导入后的 Unit 继续由 Collaboration Server
保存；导出先通过 Collaboration Runtime 取得最新 UnitData。

### 3. 增加视觉检查

结构化结果无法完整表达页面布局。Screenshot 为 Agent 提供渲染后的图像，Layout Lint 提供结构化布局诊断。

### 4. 使用 Worktree 隔离修改

Agent 可以在 Worktree draft 中多轮编辑和检查。完成后标记 Ready，由人类在 Web 中审阅并选择 Merge 或 Reopen。

### 5. 复用昂贵的 Runtime

从短生命周期 Runtime 开始；当启动成本、并发或跨 CLI 进程复用成为问题时，再增加 pool、worker 或 daemon。

## 推荐阅读顺序

1. [文档内容加载与读写](https://docs.univer.ai/zh-CN/ai/content-operations.md)
2. [Office 文件导入导出](https://docs.univer.ai/zh-CN/server/import-export/node.md)
3. [视觉检查](https://docs.univer.ai/zh-CN/ai/visual-inspection.md)
4. [Worktree：Agent 编辑与人类审阅](https://docs.univer.ai/zh-CN/ai/worktree.md)
5. [Runtime 复用与 Daemon](https://docs.univer.ai/zh-CN/ai/runtime-architecture.md)
6. [Package 概览](https://docs.univer.ai/zh-CN/ai/packages.md)
7. [示例](https://docs.univer.ai/zh-CN/ai/examples.md)