快速开始
通过编程 Agent 创建第一个 Office 应用,再了解如何接入和部署。
本文通过三个实例介绍表格联动、文档协同与供 Agent 使用的 CLI。选择一个实例,将其 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 文档复制到 Prompt 中。可以从下面的可复用模板开始,也可以直接粘贴三个完整实例中的一个。
一个需求模板
将 <…> 替换为你的需求。先描述一个可见的结果,再规划整套办公系统。
请用 Univer Office SDK 构建一个可在本地运行的<应用名称>。先阅读 https://docs.univer.ai/zh-CN/llms.txt 和相关完整示例,使用同一版本的 SDK 包。初始内容:<少量可以直接操作的数据或文字>。核心体验:<用户做一个动作,立即看到什么变化>。验收条件:<两到三个具体、可以操作验证的结果>。只完成这个最小流程,使用原生 Univer 编辑器与真实 SDK 能力。完成后实际启动,在浏览器中验证,并给我预览链接。如果缺少必要配置,请说明具体缺少什么。可选:安装应用构建 Skill
如果编程 Agent 支持 Skills,可以安装 build-with-univer,使其能够自行查阅 SDK 文档,并理清 Web SDK、Server SDK 和 AI SDK 在应用中的接入方式。
npx skills add dream-num/skills --skill build-with-univer在 Agent 当前打开的项目中运行该命令。用 npx skills list 确认安装完成,然后使用上面的模板或下面的实例。以当前文档和项目实际使用的 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。待工具构建完成且 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 可以查看完整接口。底层 API 见 AI SDK 内容操作,完整代码见 CLI SDK Examples。
把第一个流程接入你的应用
Web SDK 提供共用的内容运行时。需要多人共同编辑时加入 Server SDK,需要 Agent 操作内容时加入 AI SDK。各 SDK 的职责见 Office SDK 总览。
| 接入步骤 | 在你的应用中完成什么 | 继续阅读 |
|---|---|---|
| 挂载编辑器 | 挂载预设,通过 Facade API 连接业务交互,保存快照,并销毁实例。 | Web SDK 接入 |
| 连接后端 | 沿用现有的身份与权限,为共享文档配置数据库,并按需增加文件导入导出。 | 协同接入、文件转换 |
| 连接已有 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:startWeb 产物位于 dist/public,Server 代码位于 dist/server,由同一个 Node.js 进程同时提供静态页面和 API。
单进程无法满足需求时,可按照 Server SDK 部署指引 拆分服务。
继续探索开源项目
- Univer CLI:在本地工作区中通过 Agent 或终端创建、编辑和检查 Office 内容,再到 Viewer 中审阅修改。
- DeepSeek Harness:为已有的 Agent 对话加入 Office 工具、实时预览和草稿审阅。
全部示例 汇总了各项目的演示和仓库链接。
你觉得这篇文档如何?