# 快速开始

> 通过编程 Agent 创建第一个 Office 应用，再了解如何接入和部署。

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.3.0`

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

---

本文通过表格联动、文档协同和 CLI 三个实例介绍 Office SDK 的用法。选择一个实例，将对应的 Prompt 交给编程 Agent，再按后续步骤接入应用并部署。

## 先确定你要构建什么

Office SDK 支持电子表格、文档、演示文稿、关系型表格、画布和 PDF。根据你的应用目标，找到相应的接入路径。

| 你的目标 | 从哪里开始 | 第一个完成标准 |
| --- | --- | --- |
| 在应用中嵌入 Office 编辑器 | [Web SDK 安装与基础用法](https://docs.univer.ai/zh-CN/guides/sheets/getting-started/installation.md) | 创建内容，完成编辑、保存和重新打开。 |
| 让 Office 内容与业务界面联动 | [Facade API](https://docs.univer.ai/zh-CN/guides/sheets/getting-started/facade.md) | 页面输入与单元格双向同步，业务界面读取真实计算结果。 |
| 为编辑器增加多人协同 | [Server SDK 协同快速开始](https://docs.univer.ai/zh-CN/server/collaboration/quick-start.md) | 两个独立会话编辑同一份内容，修改互相同步。 |
| 导入、处理并导出 Office 文件 | [文件转换](https://docs.univer.ai/zh-CN/server/import-export/node.md) | 使用真实文件完成导入、修改、导出，并检查结果。 |
| 让 Agent 或 CLI 读写内容 | [AI SDK 内容操作](https://docs.univer.ai/zh-CN/ai/content-operations.md) | 加载内容、检查结构、执行修改，并验证提交或输出。 |
| 构建人类与 Agent 共用的工作空间 | [Worktree 与审阅流程](https://docs.univer.ai/zh-CN/ai/worktree.md) | Agent 的修改留在独立草稿，经人类比较、审阅后合入。 |

这些能力可以组合使用。查看[功能总览](https://docs.univer.ai/zh-CN/overview/features.md)核对产品支持范围；下方三个实例帮助你先体验其中一段完整流程。

## 让 Agent 帮你开始

将需求和 [llms.txt](/llms.txt) 文档索引链接交给编程 Agent 即可，无需复制完整 SDK 文档。下面是一个可复用的模板，以及三个可以直接粘贴使用的完整实例。

### 一个需求模板

将 `<…>` 替换为你的需求。不必先规划整个办公系统，先描述一个能看见结果的功能。

```text
请用 Univer Office SDK 构建一个可在本地运行的<应用名称>。
先阅读 https://docs.univer.ai/zh-CN/llms.txt 和相关完整示例，
使用同一版本的 SDK 包。

初始内容：<少量可以直接操作的数据或文字>。
核心体验：<用户做一个动作，立即看到什么变化>。
验收条件：<两到三个具体、可以操作验证的结果>。

只完成这个最小流程，使用原生 Univer 编辑器与真实 SDK 能力。
完成后实际启动，在浏览器中验证，并给我预览链接。
如果缺少必要配置，请说明具体缺少什么。
```

### 实例一：表格联动

将页面上的数量输入框与表格单元格双向绑定，并在页面中显示公式计算的报价总额。

```text
请用 Univer Office SDK 做一个可在本地运行的单页报价工作台。
先阅读 https://docs.univer.ai/zh-CN/llms.txt 和相关完整示例，
使用同一版本的 SDK 包。

使用基础 Sheets 预设，嵌入可编辑的原生表格，预置三项商品：
显示器 2 台 × 1200 元，键盘 5 个 × 300 元，耳机 3 个 × 200 元。
每项金额与合计都用表格公式计算。

表格旁放“显示器数量”输入框和“报价总额”卡片。
输入框与对应单元格双向同步，卡片读取真实公式结果；
页面不要重复计算报价。支持保存到浏览器，刷新后恢复。

实际验证：初始合计 4500 元，数量改为 3 后为 5700 元；
直接在表格改数量，输入框与总额也更新；保存后刷新仍保留修改。
只完成这些功能，实际运行验证后给我预览链接。
```

**体验方式：** 将显示器数量从 2 改成 3，看到合计从 4500 变为 5700；再直接编辑表格，观察页面跟随变化。保存并刷新，确认数据恢复。接入说明见 [Web SDK 安装与基础用法](https://docs.univer.ai/zh-CN/guides/sheets/getting-started/installation.md)和 [Facade API](https://docs.univer.ai/zh-CN/guides/sheets/getting-started/facade.md)。

### 实例二：文档协同

使用两个独立会话编辑同一份文档，验证两侧的修改能否实时同步。

```text
请用 Univer Office SDK 做一个可在本地运行的双人文档协同演示。
先阅读 https://docs.univer.ai/zh-CN/llms.txt，并参考
https://github.com/dream-num/univer-collaboration-examples
中当前版本的示例，前后端 SDK 包保持同一版本。

页面左右各放一个原生 Univer 现代文档编辑器，代表“小林”和“小陈”。
两侧使用独立运行环境和在线会话，连接真实的 Server SDK 协同服务，
按官方示例显式加载服务端创建的同一份文档。预置几句简短文字。

在左侧输入一句话，右侧实时出现；在右侧继续输入，左侧也更新。
通过 SDK 协同协议同步内容。只用固定的两位演示用户和内存存储，
不加入登录、文件管理或 AI 对话。前后端共用一个本地服务。
Pro License 从环境变量读取，未配置时保留 SDK 默认行为和提示。

实际验证：双向输入后两侧内容一致，服务端确实提交了更新，
刷新后还能读回内容。说明内存存储会在服务重启后重置。
只完成这些功能，实际运行验证后给我预览链接。
```

**体验方式：** 在左侧正文输入一句话，再在右侧接着编辑，观察双向同步；刷新后确认文字保留。此演示使用内存存储，服务重启会重置；部署应用时需要接入持久化数据库。接入说明见 [Server SDK 协同快速开始](https://docs.univer.ai/zh-CN/server/collaboration/quick-start.md)。

### 实例三：构建自己的 you-cli

让当前 Agent 使用你自己的 Office 工具。支持 Sheet、Doc、Slide、Relational Table 和 Canvases，先用一份 Doc 体验“生成 → 预览 → 继续对话修改”。

```text
请用 Univer Office SDK，在当前项目构建自己的 you-cli 和 Web 预览。
先阅读 https://docs.univer.ai/zh-CN/llms.txt，并参考
https://github.com/dream-num/univer-cli-examples 中的完整内容操作示例。
前后端与 AI SDK 包使用兼容的同一版本，API 以安装包类型为准。

支持 Sheet、Doc、Slide、Relational Table、Canvases，先用 Doc 跑通。
约定命令：./you-cli create <type> --name <name>、inspect --unit <id>、
execute --unit <id> --file <path>、open --unit <id>，并提供 --help。
工具放在当前项目，提供使用说明或 Skill，让当前 Agent 读取后调用。
返回 JSON，包含 unitId、类型、提交结果和预览 URL 等对应信息。

CLI 与 Web 连接同一份真实协同内容，提交后更新已打开的原生编辑器。
写入后等待提交确认并读回验证，内容与列表使用持久化存储。
open 返回 URL，由当前 Agent 用宿主的预览能力打开；支持时在右侧显示。
模型与自然语言理解沿用当前 Agent；许可证从环境读取并保留必要提示。

验收：对话生成项目周报并打开预览；继续对话增加风险和负责人，
复用同一 unitId，预览自动更新；刷新和服务重启后内容仍保留。
实际运行验证，给我预览链接和用法；只启动本例需要的服务。
```

#### 通过对话使用

先把上面的 Prompt 交给编程 Agent。构建完成并读取项目使用说明后，在同一个对话中说：

```text
用 you-cli 创建一份项目周报，包含本周进展、风险和下周计划，打开 Web 预览。
```

看到内容后继续说：

```text
在刚才那份周报中增加一条风险：交付可能延期，负责人小林。更新已打开的预览。
```

Agent 会复用原文档的 `unitId`。支持预览面板的宿主可以在右侧展示，其他环境使用返回的浏览器链接。

#### you-cli 命令参考

以下是上方 Prompt 约定的项目内命令。将 `UNIT_ID` 替换为 `create` 返回的 `unitId`；`edit.js` 是 Agent 按 Facade API 编写的修改脚本。

| 操作 | 命令 | 结果 |
| --- | --- | --- |
| 创建 | `./you-cli create doc --name "项目周报"` | 创建文档并返回 `unitId`；类型还可选 `sheet`、`slide`、`base`、`board`。 |
| 检查 | `./you-cli inspect --unit UNIT_ID` | 读取真实内容与当前版本。 |
| 修改 | `./you-cli execute --unit UNIT_ID --file edit.js` | 执行修改，等待提交并返回结果。 |
| 预览 | `./you-cli open --unit UNIT_ID` | 返回同一份文档的 Web URL，由 Agent 打开。 |

也可以运行 `./you-cli --help` 查看接口。操作流程见 [AI SDK 内容操作](https://docs.univer.ai/zh-CN/ai/content-operations.md)，完整源码参考 [CLI SDK Examples](https://docs.univer.ai/zh-CN/overview/examples/cli-sdk.md)。

## 把第一个流程接入你的应用

Web SDK 提供共同的内容运行时。需要共享编辑或 Agent 操作时，在这个基础上继续接入 Server SDK 与 AI SDK。具体分工见 [Office SDK 总览](https://docs.univer.ai/zh-CN/overview.md)。

| 接入步骤 | 在你的应用中完成什么 | 继续阅读 |
| --- | --- | --- |
| 挂载编辑器 | 将预设挂载到页面，用 Facade API 连接业务交互；处理快照保存和实例销毁。 | [Web SDK 接入](https://docs.univer.ai/zh-CN/guides/sheets/getting-started/installation.md) |
| 连接后端 | 接入现有身份与权限，为共享文档配置数据库；按需增加文件导入导出。 | [协同接入](https://docs.univer.ai/zh-CN/server/collaboration/quick-start.md)、[文件转换](https://docs.univer.ai/zh-CN/server/import-export/node.md) |
| 连接已有 Agent | 将内容读写、计算与验证封装为 Agent 可调用的工具或 CLI；需要审阅时再接入 Worktree。 | [AI SDK 内容操作](https://docs.univer.ai/zh-CN/ai/content-operations.md)、[Worktree](https://docs.univer.ai/zh-CN/ai/worktree.md) |

## 应用架构

已有的应用与 Agent 可以共用 Office 内容。界面负责交互，Agent 通过工具执行操作，业务服务沿用你的身份、权限和存储。

**蓝色节点由你提供和管理：** 应用界面、已有 Agent、业务 API（含身份与权限）、数据库与文件存储。其余标有 SDK 的节点表示集成到应用中的 Univer 能力。

```mermaid
%%{init: {"themeVariables":{"fontSize":"13px"},"flowchart":{"padding":10,"nodeSpacing":20,"rankSpacing":20}}}%%
flowchart TB
    UI["你的应用界面"]
    UI --> Editor["Web SDK · 编辑器"]
    Agent["你的已有 Agent"] --> Tools["AI SDK · Office 工具"]
    Editor <-->|共享编辑| App["你的业务 API · 身份与权限"]
    Tools <-->|内容读写与提交| App
    App --> Server["Server SDK · 协同与文件转换"]
    Tools --> Runtime["Web SDK · Headless 内容运行时"]
    Server --> Runtime
    Server --> Storage[("你的数据库与文件存储")]
    classDef appOwned fill:#e8f0ff,stroke:#4771c4,color:#163d75,stroke-width:2px
    class UI,Agent,App,Storage appOwned
```

仅嵌入编辑器时可以从本地快照开始；共享编辑再连接后端。Agent 继续使用已有的模型和任务编排，通过 AI SDK 操作内容；需要隔离修改、比较和审阅时，再组合 Worktree。

## 以 Workspace 为例构建与部署

[Univer Workspace](https://github.com/dream-num/univer-workspace)展示如何将三个 SDK 组成完整的办公空间。下面的命令在 Workspace 仓库根目录运行，环境准备以其 [README](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/README.md)为准。

1. **本地开发。** 安装依赖后，在两个终端分别运行 `pnpm workspace:dev:server` 和 `pnpm workspace:dev:web`，打开 `http://127.0.0.1:5173`。Web 开发服务把 API 与 WebSocket 请求转发给后端。
2. **构建并运行。** 只构建 Workspace 应用，再启动生产入口：

```bash
pnpm --filter @univerjs/univer-workspace build
pnpm workspace:start
```

构建后，Web 产物位于 `dist/public`，Server 产物位于 `dist/server`，由一个 Node.js 进程提供静态页面与 API。

3. **准备部署。** 配置许可证、身份和数据目录，持久化业务数据库、协同数据库及上传资源；重启后检查内容能否恢复。容器运行方式见 [Docker 部署](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/README.md#docker)，模块组织见[架构说明](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/docs/architecture.md)。

应用规模扩大后，再参考 [Server SDK 部署指引](https://docs.univer.ai/zh-CN/server/deployment.md)拆分服务。

## 继续探索开源项目

- [Univer CLI](https://docs.univer.ai/zh-CN/overview/examples/cli.md)：在本地工作区中通过 Agent 或终端创建、编辑和检查 Office 内容，并通过 Viewer 审阅修改。
- [DeepSeek Harness](https://docs.univer.ai/zh-CN/overview/examples/deepseek-harness.md)：在已有 Agent 对话中接入 Office 工具、实时预览与草稿审阅。

查看[全部示例](https://docs.univer.ai/zh-CN/overview/examples.md)，获取各项目的演示和仓库链接。