快速开始
通过编程 Agent 创建第一个 Office 应用,再了解如何接入和部署。
本文通过表格联动、文档协同和 CLI 三个实例介绍 Office SDK 的用法。选择一个实例,将对应的 Prompt 交给编程 Agent,再按后续步骤接入应用并部署。
先确定你要构建什么
Office SDK 支持电子表格、文档、演示文稿、关系型表格、画布和 PDF。根据你的应用目标,找到相应的接入路径。
| 你的目标 | 从哪里开始 | 第一个完成标准 |
|---|---|---|
| 在应用中嵌入 Office 编辑器 | Web SDK 安装与基础用法 | 创建内容,完成编辑、保存和重新打开。 |
| 让 Office 内容与业务界面联动 | Facade API | 页面输入与单元格双向同步,业务界面读取真实计算结果。 |
| 为编辑器增加多人协同 | Server SDK 协同快速开始 | 两个独立会话编辑同一份内容,修改互相同步。 |
| 导入、处理并导出 Office 文件 | 文件转换 | 使用真实文件完成导入、修改、导出,并检查结果。 |
| 让 Agent 或 CLI 读写内容 | AI SDK 内容操作 | 加载内容、检查结构、执行修改,并验证提交或输出。 |
| 构建人类与 Agent 共用的工作空间 | Worktree 与审阅流程 | Agent 的修改留在独立草稿,经人类比较、审阅后合入。 |
这些能力可以组合使用。查看功能总览核对产品支持范围;下方三个实例帮助你先体验其中一段完整流程。
让 Agent 帮你开始
将需求和 llms.txt 文档索引链接交给编程 Agent 即可,无需复制完整 SDK 文档。下面是一个可复用的模板,以及三个可以直接粘贴使用的完整实例。
一个需求模板
将 <…> 替换为你的需求。不必先规划整个办公系统,先描述一个能看见结果的功能。
请用 Univer Office SDK 构建一个可在本地运行的<应用名称>。先阅读 https://docs.univer.ai/zh-CN/llms.txt 和相关完整示例,使用同一版本的 SDK 包。初始内容:<少量可以直接操作的数据或文字>。核心体验:<用户做一个动作,立即看到什么变化>。验收条件:<两到三个具体、可以操作验证的结果>。只完成这个最小流程,使用原生 Univer 编辑器与真实 SDK 能力。完成后实际启动,在浏览器中验证,并给我预览链接。如果缺少必要配置,请说明具体缺少什么。实例一:表格联动
将页面上的数量输入框与表格单元格双向绑定,并在页面中显示公式计算的报价总额。
请用 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 安装与基础用法和 Facade API。
实例二:文档协同
使用两个独立会话编辑同一份文档,验证两侧的修改能否实时同步。
请用 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 协同快速开始。
实例三:构建自己的 you-cli
让当前 Agent 使用你自己的 Office 工具。支持 Sheet、Doc、Slide、Relational Table 和 Canvases,先用一份 Doc 体验“生成 → 预览 → 继续对话修改”。
请用 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。构建完成并读取项目使用说明后,在同一个对话中说:
用 you-cli 创建一份项目周报,包含本周进展、风险和下周计划,打开 Web 预览。看到内容后继续说:
在刚才那份周报中增加一条风险:交付可能延期,负责人小林。更新已打开的预览。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 内容操作,完整源码参考 CLI SDK Examples。
把第一个流程接入你的应用
Web SDK 提供共同的内容运行时。需要共享编辑或 Agent 操作时,在这个基础上继续接入 Server SDK 与 AI SDK。具体分工见 Office SDK 总览。
| 接入步骤 | 在你的应用中完成什么 | 继续阅读 |
|---|---|---|
| 挂载编辑器 | 将预设挂载到页面,用 Facade API 连接业务交互;处理快照保存和实例销毁。 | Web SDK 接入 |
| 连接后端 | 接入现有身份与权限,为共享文档配置数据库;按需增加文件导入导出。 | 协同接入、文件转换 |
| 连接已有 Agent | 将内容读写、计算与验证封装为 Agent 可调用的工具或 CLI;需要审阅时再接入 Worktree。 | AI SDK 内容操作、Worktree |
应用架构
已有的应用与 Agent 可以共用 Office 内容。界面负责交互,Agent 通过工具执行操作,业务服务沿用你的身份、权限和存储。
蓝色节点由你提供和管理: 应用界面、已有 Agent、业务 API(含身份与权限)、数据库与文件存储。其余标有 SDK 的节点表示集成到应用中的 Univer 能力。
仅嵌入编辑器时可以从本地快照开始;共享编辑再连接后端。Agent 继续使用已有的模型和任务编排,通过 AI SDK 操作内容;需要隔离修改、比较和审阅时,再组合 Worktree。
以 Workspace 为例构建与部署
Univer Workspace展示如何将三个 SDK 组成完整的办公空间。下面的命令在 Workspace 仓库根目录运行,环境准备以其 README为准。
- 本地开发。 安装依赖后,在两个终端分别运行
pnpm workspace:dev:server和pnpm workspace:dev:web,打开http://127.0.0.1:5173。Web 开发服务把 API 与 WebSocket 请求转发给后端。 - 构建并运行。 只构建 Workspace 应用,再启动生产入口:
pnpm --filter @univerjs/univer-workspace buildpnpm workspace:start构建后,Web 产物位于 dist/public,Server 产物位于 dist/server,由一个 Node.js 进程提供静态页面与 API。
应用规模扩大后,再参考 Server SDK 部署指引拆分服务。
继续探索开源项目
- Univer CLI:在本地工作区中通过 Agent 或终端创建、编辑和检查 Office 内容,并通过 Viewer 审阅修改。
- DeepSeek Harness:在已有 Agent 对话中接入 Office 工具、实时预览与草稿审阅。
查看全部示例,获取各项目的演示和仓库链接。
你觉得这篇文档如何?