# CLI SDK 概览

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

- Human documentation: [https://office.univer.ai/zh-CN/cli/overview](https://office.univer.ai/zh-CN/cli/overview)

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

- Language: `zh-CN`

- Source file: `content/docs/cli/overview.zh-CN.mdx`

- Upstream source: [https://github.com/dream-num/univer-cli-sdk/blob/main/README.md](https://github.com/dream-num/univer-cli-sdk/blob/main/README.md)

---

**Univer CLI SDK** 是一套用于构建 Office CLI 的 TypeScript SDK。它为 Agent 和自动化程序提供 Node.js
入口，用于加载、理解、修改和检查 Univer Unit。

CLI SDK 是可组合能力，不是固定形态的产品 CLI。业务应用决定命令名称、参数、目标、身份权限、输出和部署方式。

## 推荐的应用形态

本文以 `CLI + Web + Server` 为主线：

```mermaid
flowchart LR
    Agent([Agent / CLI 用户]) --> CLI[业务 CLI]
    Human([人类用户]) --> Web[Web]
    CLI --> Server[Collaboration Server]
    Web --> Server
    Server --> Storage[(Storage)]
```

* CLI 是 Agent 或用户操作 Unit 的入口；
* Web 展示实际页面，支持交互式编辑和人类审阅；
* Server 保存 CLI 与 Web 共享的 Unit、revision 和协同状态。

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

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

## 使用 Commander 组织 CLI

CLI 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。

## 按能力逐步构建

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

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

### 1. 加载与读写 Unit

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

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

使用 Univer Pro 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://office.univer.ai/zh-CN/cli/content-operations.md)
2. [Office 文件导入导出](https://office.univer.ai/zh-CN/cli/file-exchange.md)
3. [视觉检查](https://office.univer.ai/zh-CN/cli/visual-inspection.md)
4. [Worktree：Agent 编辑与人类审阅](https://office.univer.ai/zh-CN/cli/worktree.md)
5. [Runtime 复用与 Daemon](https://office.univer.ai/zh-CN/cli/runtime-architecture.md)
6. [Package 概览](https://office.univer.ai/zh-CN/cli/packages.md)
7. [示例](https://office.univer.ai/zh-CN/cli/examples.md)