快速开始

通过编程 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 中。可以从下面的可复用模板开始,也可以直接粘贴三个完整实例中的一个。

一个需求模板

将 <…> 替换为你的需求。先描述一个可见的结果,再规划整套办公系统。

text
请用 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 在应用中的接入方式。

Bash
npx skills add dream-num/skills --skill build-with-univer

在 Agent 当前打开的项目中运行该命令。用 npx skills list 确认安装完成,然后使用上面的模板或下面的实例。以当前文档和项目实际使用的 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 安装与基础用法 和 Facade API。

实例二:文档协同

使用两个独立会话编辑同一份文档,确认两侧的修改能够互相同步。

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 协同快速开始。

实例三:构建自己的 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。待工具构建完成且 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 可以查看完整接口。底层 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 能力。

100%

仅嵌入编辑器时,本地快照即可满足需求;共享编辑需要后端。Agent 的模型和任务编排保持不变,内容操作交由 AI SDK 处理;需要隔离修改、对比和审阅时再加入 Worktree。

以 Workspace 为例构建与部署

Univer Workspace 将三个 SDK 组成一个完整的办公空间。以下命令在 Workspace 仓库根目录执行,前置条件参见其 README。

  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 buildpnpm workspace:start

Web 产物位于 dist/public,Server 代码位于 dist/server,由同一个 Node.js 进程同时提供静态页面和 API。

  1. 准备部署。 配置许可证、身份和数据目录,持久化业务数据、协同数据和上传资源,然后重启服务并确认数据恢复。容器化运行参见 Docker 部署,模块划分参见 架构说明。

单进程无法满足需求时,可按照 Server SDK 部署指引 拆分服务。

继续探索开源项目

  • Univer CLI:在本地工作区中通过 Agent 或终端创建、编辑和检查 Office 内容,再到 Viewer 中审阅修改。
  • DeepSeek Harness:为已有的 Agent 对话加入 Office 工具、实时预览和草稿审阅。

全部示例 汇总了各项目的演示和仓库链接。

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.