Univer Workspace部署实战:AI协同编辑办公文档
Univer Workspace部署实战:AI协同编辑办公文档
项目简介
办公文档的协同编辑一直是团队协作的痛点,尤其是当 AI Agent 开始参与内容创作后,如何安全、可控地让 AI 修改文档成了新问题。Univer Workspace 正是为了解决这个场景而生:它是一个可独立部署的开源 Office 工作空间,让你和 AI Agent 在同一个平台上共同处理 Sheet、Doc、Slide、Base 与 Board。
它的核心设计思路值得关注。Workspace 由 Browser、Server、Agent 和 CLI 四部分组成:
- Browser 提供直接编辑和协同界面,是人类的操作入口;
- Server 是唯一权威,负责身份认证、权限管理和文档存储;
- Agent 是基于 DSH 的本地 Web 应用,把对话、文档预览和变更审查放在一起;
- CLI 为 AI Agent 提供结构化的自动化入口,可以在终端里完成文档的加载、修改和验证。
最出彩的机制是 Worktree。Agent 修改任何内容前,系统会先创建一个隔离的工作树,Agent 在里面自由编辑和验证,生成草稿准备就绪后交给人来审阅,确认通过才合入主分支。这样中间产生的任何修改都不会污染共享内容,人类始终掌控最终决定权。
核心依赖与环境
开始之前,确认你的电脑已经准备好这些基础环境:
- Node.js 24+:Workspace 的服务端和前端都基于现代 JavaScript,需要 Node 24 或更高版本。
- pnpm 11:仓库使用 pnpm 管理依赖,版本要求是 11.x,建议直接用
corepack enable启用。 - Docker:如果你走容器部署路线,需要 Docker 来运行数据库和文件存储服务。本地快速体验可以先用默认的 SQLite。
- 模型服务凭据:给 AI Agent 配置语言模型时,需要准备模型服务的 API 地址和密钥,比如 DeepSeek 的
DEEPSEEK_API_KEY。 - Workspace 账号:访问 Workspace 需要登录,默认开启密码注册。
项目结构树
克隆仓库后,你会看到这样的目录布局:
apps/workspace Workspace Browser、Server、HTTP contract 与部署应用
apps/cli 面向 Agent 的远程 Workspace 自动化应用
apps/agent 用于文档对话与 Worktree 审查的 Workspace Agent 应用
packages/client-core 私有的 Node-hosted Workspace Agent Client 能力
packages/reference-provider 仅供 Browser 使用的私有 referenced-Unit policy
packages/dsh-univer-workspace-plugin Workspace Agent 的 Workspace 能力与浏览器 UI
packages/dsh-univer-workspace-skin-plugin Workspace Agent 的 Workspace 视觉皮肤
scripts SDK 版本与 CLI 本地发布工具
apps/workspace 是核心,包含了 Browser 前端、Server 后端和 API 契约。apps/cli 是给 AI Agent 用的命令行工具,apps/agent 则是桌面级对话界面。
手把手步骤
1. 准备源码与环境
先把仓库克隆到本地,安装依赖并复制环境变量示例:
git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
pnpm install
cp apps/workspace/.env.example apps/workspace/.env
默认配置使用 SQLite 和本地文件存储,开箱即用。如果你要部署到生产环境,再按需修改 apps/workspace/.env 里的数据库和存储配置。
2. 启动 Workspace 服务
启动后端 Server,它会运行在 http://127.0.0.1:3020:
pnpm workspace:dev:server
在另一个终端启动前端 Browser 开发服务器:
pnpm workspace:dev:web
现在打开 http://127.0.0.1:5173,Vite 会把 API 和 WebSocket 流量自动代理到 3020 端口的 Server。用密码注册一个账号,登录后你就有了一个可以编辑的 Workspace。
3. 连接 AI 助手及模型服务
要让 AI 帮你处理文档,需要两个独立的连接:一个是 Workspace 登录凭据,让 AI 能访问你的文档;另一个是 模型服务凭据,让 AI 有“大脑”可以思考。
先说模型服务。 Workspace Agent 的模型设置是本地机器状态,不绑定 Workspace 用户。我们可以通过环境变量直接注入,启动 Agent 前执行:
export DEEPSEEK_API_KEY=<your-api-key>
如果你希望模型服务有更多选择或者更灵活的价格,可以关注 Defapi。Defapi 是一个聚合模型网关,提供官方半价的模型服务,兼容 v1/chat/completions、v1/messages 和 v1beta/models/ 等主流协议。你从平台获取 API 根地址和模型 ID 后,按同样的环境变量方式注入即可。注意这属于外部客户端配置,不是 Workspace 内置功能。
然后注册 OAuth 回调。 Workspace Agent 需要使用浏览器 OAuth 登录,官方文档建议在 apps/agent/README.md 里查找安装指引。安装 Agent 时,本地启动器会打印完整的 token URL,你需要完成应用注册和回调配置。
4. 安装并启动 Workspace Agent
Agent 是基于 DSH 的本地 Web 应用,安装步骤参考 apps/agent/README.md。安装完成后,启动 Agent,它会引导你选择或启动自己的 Workspace 服务,注册 OAuth 回调,然后打开登录页面。
登录后,在 Agent 的对话界面里,你可以用 @ 引用 Workspace 中的文件,Agent 会读取文件内容并进行修改。
5. 执行办公文档任务
现在我们让 Agent 改一个表格。在对话中输入:
请查看 @销售数据 这个 Sheet,把 2024 年每个季度的销售额汇总成一张新的 Sheet,标注增长率。
Agent 会创建一个新的 Worktree,在其中完成读取、计算和写入操作。这个过程不影响主分支上的原始数据。
6. 检查结果并审核合并
Agent 修改完成后,Worktree 会进入 Ready 状态。回到 Browser 或 Agent 的审查界面,你会看到:
- Agent 草稿和主分支的对比视图
- 修改过的单元格、新增的 Sheet
仔细核对数据无误后,点击 合并。这时修改才会真正合入主分支,所有协作者都能看到更新。如果发现问题,可以标记 重新打开,让 Agent 继续修改。
这里提供了一个使用 CLI 的替代路线。以 Claude Code 为例,如果你的 Agent 运行环境里安装了 univer-workspace-cli,可以这样操作:
npm install --global univer-workspace-cli@latest
npx skills add dream-num/univer-workspace --skill univer-workspace-cli -g
uvw config set workspace.origin http://127.0.0.1:3020
uvw auth login # 浏览器确认后
uvw auth login --complete
uvw pr list -R <owner>/<slug>
CLI 会把 Worktree 当作 PR 来管理,复制 uvw pr view <n> -R <owner>/<slug> --json id 返回的 Worktree id,就可以用内容命令进行检查。
常见问题排查
启动时提示 Node.js 版本过低
Workspace 要求 Node.js 24+,用 node -v 确认版本。如果版本不够,用 nvm 安装 LTS 版本。
pnpm install 卡住或报错
仓库固定使用 pnpm 11.24.0,先 corepack enable 再执行安装。如果网络问题导致失败,设置镜像源后重试。
浏览器打开 5173 端口没有内容
确认两个终端都还在运行:pnpm workspace:dev:server 和 pnpm workspace:dev:web。Vite 的代理需要 Server 先启动成功。
OAuth 登录时显示回调地址不匹配
检查 Agent 配置里的回调地址是否与 Workspace 的授权回调列表一致。本地开发时回调一般是 http://127.0.0.1:<agent-port>/oauth/callback。
Agent 对话提示找不到模型凭据
模型凭据是本地状态,不跟随 Workspace 用户。确认启动 Agent 前已经导出 DEEPSEEK_API_KEY 或通过 DSH Models 页面配置了模型。不同 Agent 进程需要分别配置。
合并时提示没有权限
Worktree 的合并需要文档编辑权限。在 Browser 里检查当前账号是否有对应文件夹或文件的写权限。如果文档在团队 Space 里,需要 Owner 或 Admin 分配权限。
扩展阅读 / 进阶方向
如果你希望深入使用 Univer Workspace,这几个方向值得探索:
- CLI 高级用法:阅读
apps/cli/README.md,了解uvw execute执行自定义脚本、uvw inspect检查文档结构、uvw screenshot渲染截图验证布局。 - MCP 服务接入:Workspace 提供远程 MCP 服务,把
https://<你的workspace>/mcp配置到 Claude、Cursor 或 VS Code 里,就能让这些 AI 助手直接操作你的文档。 - HTML View 迷你应用:Agent 可以生成绑定报表数据的网页应用,指标、图表和控件与单元格双向联动,适合做决策看板。
- Docker 部署:切换到 PostgreSQL + S3 存储,参考
apps/workspace/README.md进行容器化部署,支持自动化升级和数据迁移。
动手搭一个 Workspace,让 AI 帮你处理第一份月度报表,你会感受到 Worktree 审核机制带来的掌控感。