Univer Workspace: 部署与AI表格实战
AI 生成的表格内容如果只停留在聊天窗口,后续修改、协作和审查都会断掉。Univer Workspace 把文档、表格和 AI 操作放进同一个工作空间,让 Agent 在隔离的 Worktree 中修改,我们审阅后再合入。今天我们一起完成本地部署,并用销售表格跑通 Agent 生成汇总与公式。
项目简介
Univer Workspace 是一个基于 Univer Office SDK 构建、可独立部署的开源 Office 工作空间。它解决的核心问题是:AI 生成的办公内容需要人工搬运到编辑器,后续修改难以协作和审查。
项目把 Browser、Agent、CLI 三个入口接到同一个 Workspace Server,让人与 AI 共同处理 Sheet、Doc、Slide、Base 与 Board。Agent 在隔离的 Worktree 中工作并验证修改,只有经过我们确认的内容才会合入共享 trunk。你可以在 Workspace Browser 里直接编辑,也可以让 Workspace Agent 在文档旁对话、生成内容,再像审查代码一样审查表格改动。
适用场景与前置基础
典型场景是销售数据分析。团队把销售明细表放进 Workspace,让 Agent 按区域汇总并生成公式,我们像审查代码一样审查表格改动。
开始前需要准备:
- 能操作终端,会看 JavaScript/TypeScript 配置
- 已安装 Git
- Node.js 24 或更高版本
- pnpm 11.24.0
- 一份模型 API Key,用于 Agent 对话
- 要跑截图或布局检查时,准备 Chrome/Chromium
Workspace 登录和模型凭据是两回事:浏览文档不需要模型请求,和 Agent 对话才需要模型凭据。
核心依赖与环境
仓库的 .npmrc 把 @univer-cli、@univerjs、@univerjs-pro、@univerjs-labs 指向 https://insider-npm-registry.univer.work/。安装时需要访问这个私有 Registry,也需要访问公共 npm Registry。
DSH Runtime 由 packages/dsh-runtime 固定到 @deepseek-ai/[email protected]。源码使用 Apache-2.0,但 Univer SDK 的使用条件不完全等于源码许可证:内置 runtime 开发凭据每 90 天轮换,服务端 Collaboration/Exchange SDK 需要 license key,缺少任一值时降级免费额度。
项目结构树
apps/workspace Workspace Browser、Server、HTTP 契约与部署应用
apps/agent 用于文档对话与 Worktree 审查的 Workspace Agent
apps/cli 面向 Agent 的远程 Workspace 自动化应用
packages/client-core 私有 Node-hosted Workspace Agent Client 能力
packages/dsh-runtime 固定 DSH 运行时版本与依赖图
scripts SDK 版本与发布工具
手把手步骤
1. 克隆固定版本并安装依赖
先固定到教程使用的 commit,避免后续改动影响命令。
git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
git checkout c1a5fb3dc9d5951cbf618f76639466feac5da4d7
pnpm install --frozen-lockfile
这一步会访问私有 Registry 和公共 npm Registry。网络受限时先看文末的常见问题。
2. 配置模型接入
在启动 Agent 之前,先理解登录与模型凭据的分工。Workspace 登录只授权数据访问;和 Agent 对话时,DSH 会把模型请求发到我们配置的 chat completions 端点。如果计划让 Agent 分析销售表并生成公式,就要先准备好模型可用的 baseURL、API Key 和 model。
DSH 的 deepseek-official 适配器会向 baseURL + /chat/completions 发请求,所以 baseURL 要填到 /v1 这一层,不要重复拼接路径。
如果希望控制模型成本,可以接 Defapi 这类 OpenAI 兼容网关。Defapi 提供统一模型接入,主打约官方半价的计费,具体模型与价格以控制台为准。官网 https://defapi.org 有明确入口,它基本兼容 v1/chat/completions、v1/messages、v1beta/models/ 协议。配置时把 baseURL 指向 Defapi 控制台给出的 chat completions 基址即可。
export DEEPSEEK_API_KEY="<Defapi 控制台创建的 API Key>"
export DEEPSEEK_BASE_URL="<Defapi 控制台显示的 chat completions 基址,例如 https://xxx/v1>"
export UWH_MODEL_SETTINGS_ENABLED=true
模型 ID 以控制台实际可用目录为准。如果 DSH 默认模型 ID 与 Defapi 控制台不一致,可以在 DSH Models 页面的模型列表里改成控制台可用的 ID。生产环境默认隐藏 Models 页面,需要设置 UWH_MODEL_SETTINGS_ENABLED=true 才会显示;本地没有设置 NODE_ENV=production 时,原生 DSH Models 页面可以直接打开。
3. 创建 Workspace 环境配置,注册 Agent OAuth 客户端
Workspace 默认不会注册 Agent OAuth 客户端,只复制 .env.example 不够。
cp apps/workspace/.env.example apps/workspace/.env
然后编辑 apps/workspace/.env,加入未注释的单行配置:
OAUTH_CLIENTS_JSON={"clients":[{"clientId":"univer-workspace-harness","clientType":"public","requiresConsent":true,"redirectUris":["http://127.0.0.1:3101/auth/oauth/callback"],"scopes":["identity","session"]}]}
如果已有 OAUTH_CLIENTS_JSON,把上面的客户端追加到 clients 数组,始终只保留一个配置项。
4. 启动 Workspace Server 与 Browser
在第一个终端启动 Server:
pnpm workspace:dev:server
在第二个终端启动 Browser 开发服务器:
pnpm workspace:dev:web
打开 http://127.0.0.1:5173,注册本地 Workspace 账号或登录现有账号。本地注册不需要 GitHub/Discord OAuth。保持两个进程运行。
5. 构建 DSH Runtime 和 Agent Profile,启动本地 Agent
Agent 是本地 Web 应用,需要先从源码组装 DSH 运行时。下面的命令会构建 client-core、三个 bundle,并把 Profile 装到隔离目录。
export UWH_LOCAL_ROOT="${XDG_CACHE_HOME:-$HOME/.cache}/univer-workspace-harness"
export UWH_DSH_BOOTSTRAP="$UWH_LOCAL_ROOT/dsh-cli"
export DSH_HOME="$UWH_LOCAL_ROOT/install"
export UWH_DSH_DATA_HOME="$UWH_LOCAL_ROOT/data"
mkdir -p "$UWH_DSH_BOOTSTRAP" "$DSH_HOME/internal-packages"
export UWA_PACKAGES="$(mktemp -d "$DSH_HOME/internal-packages/build.XXXXXX")"
pnpm --dir packages/dsh-runtime install --frozen-lockfile
pnpm --dir packages/dsh-runtime deploy --legacy \
--filter @univerjs/univer-workspace-dsh-runtime \
--prod --config.node-linker=hoisted "$UWH_DSH_BOOTSTRAP"
export DSH_BIN="$UWH_DSH_BOOTSTRAP/node_modules/@deepseek-ai/dsh/lib/bin.js"
pnpm --filter @univerjs/univer-workspace-client-core build
pnpm --filter @univerjs/workspace-agent build
pnpm --filter dsh-univer-workspace-plugin build
pnpm --filter dsh-univer-workspace-skin-plugin build
pnpm --filter @univerjs/workspace-agent pack \
--pack-destination "$UWA_PACKAGES"
pnpm --filter dsh-univer-workspace-plugin pack \
--pack-destination "$UWA_PACKAGES"
pnpm --filter dsh-univer-workspace-skin-plugin pack \
--pack-destination "$UWA_PACKAGES"
export DSH_PLUGINS="file:$UWA_PACKAGES/univerjs-workspace-agent-0.1.0.tgz file:$UWA_PACKAGES/dsh-univer-workspace-plugin-0.1.0.tgz file:$UWA_PACKAGES/dsh-univer-workspace-skin-plugin-0.1.0.tgz"
NPM_CONFIG_USERCONFIG="$PWD/.npmrc" ./apps/agent/scripts/build-profile.sh
export UWH_RENDER_PAGE_ROOT="$PWD/packages/client-core/dist/render-runtime"
export UWH_RENDER_BROWSER="${UWH_RENDER_BROWSER:-$(command -v google-chrome || command -v chromium || true)}"
node apps/agent/scripts/start-local.mjs --port 3101 \
--no-open --trusted-host 127.0.0.1
命令会停在 start-local.mjs 前台,这是正常的。等到 stderr 出现 dsh web: 开头的一行,复制整行 URL。
如果 3101 被占用,换一个明确端口,并同步修改第 3 步的 redirectUris。
6. 连接 Workspace 并完成 OAuth
在浏览器打开 dsh web: 打印的完整 URL,里面包含一次性 ?token=...。DSH 会设置 HttpOnly Cookie 并重定向到根地址。
# 复制启动器输出的完整地址,例如:
# http://127.0.0.1:3101/?token=<one-time-token>
然后在 Agent 界面进入 设置 → Workspace,填写本地服务地址:
http://127.0.0.1:5173
点击 Sign in to Workspace,在 Workspace 授权页批准访问。Workspace 会重定向到本地 Agent 回调,Agent 用 PKCE 交换授权码。返回后侧栏应出现账号和个人 Space。
如果连接页面一直等待,点击 Check again,并保持 start-local.mjs 运行。
7. 创建示例销售表并让 Agent 生成汇总与公式
在侧栏打开 文件,选择个人或团队 Space,新建一个表格,填入销售明细:
日期,区域,销售额
2025-01-05,华东,12800
2025-01-06,华南,9600
2025-01-07,华东,15100
2025-01-08,华南,14200
回到 会话,新建会话,在输入框键入 @ 选择刚创建的表格,然后发送:
@销售明细 请按区域汇总销售额,并在表格中新增一列计算每个区域的平均销售额。
发送后 Agent 会基于当前 Workspace 校验引用,并把修改写到 Worktree,不会直接改动共享 trunk。
8. 查看 Worktree 差异,合入或丢弃
打开 Worktree 页签,找到正在进行的任务。审查视图默认展示“修改效果”,可以切换到“差异”查看新增、修改和删除的文档。确认结果正确后点“合入”;不满意可以转为草稿或丢弃。只有合入后共享 trunk 才会更新。
创建 Worktree
→ Agent 编辑并验证隔离草稿
→ Ready
→ 人工审阅
→ Merge 或 Reopen
→ trunk
如果 Agent 执行了 univer_lint 或 univer_screenshot,需要有版本匹配的静态渲染页面和 Chrome/Chromium。缺少 UWH_RENDER_PAGE_ROOT 或浏览器时,工具会明确报告前置条件错误,不会把视觉验证标记为通过。
常见问题排查
1. pnpm install 访问私有 Registry 失败
安装时需要访问私有 Registry,也需要访问公共 npm Registry,缺一不可。如果卡住或 401,先确认网络可以访问 https://insider-npm-registry.univer.work/,再确认 Node 和 pnpm 版本。不要删除 .npmrc 里的 registry 行。
2. 出现 OAUTH_CLIENT_UNAVAILABLE
Workspace 服务端没有加载 Agent OAuth 客户端。检查 apps/workspace/.env 里的 OAUTH_CLIENTS_JSON 是否包含 univer-workspace-harness,修改后重启 Server。只复制 .env.example 不会注册这个客户端。
3. 出现 INVALID_REDIRECT_URI
回调地址必须精确匹配。localhost 和 127.0.0.1 属于不同注册。如果 Agent 换了端口,要同步修改 redirectUris 并重启 Workspace 后端。这项注册控制的是 OAuth 回调,不是对 3101 端口的通用 CORS 放行。
4. 打开根地址返回 401
没有先打开带 token 的完整 URL,浏览器就没有会话 Cookie。重新打开启动器打印的 dsh web: 地址完成兑换,之后可以用不带参数的根地址。一次性 token 不要重复使用。
5. Workspace 登录成功但模型消息失败
Workspace OAuth 只授权数据访问,模型凭据需要单独配置。检查 DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL 和模型 ID。使用 Defapi 时,baseURL 填控制台给出的 chat completions 基址,不要重复拼接 /chat/completions。
6. Agent 连接页面一直等待
保持 start-local.mjs 运行。连接状态变化后会做就绪检查,如果账号服务加载失败,查看启动器日志。授权请求过期后,从 设置 → Workspace 重新登录。这个流程使用浏览器 OAuth,不需要输入设备码。
7. 截图/布局检查报前置条件错误
univer_lint 和 univer_screenshot 需要 UWH_RENDER_PAGE_ROOT 指向静态渲染页面,并且 UWH_RENDER_BROWSER 指向兼容的 Chrome/Chromium。没有浏览器时,把可执行文件路径赋值给 UWH_RENDER_BROWSER 再启动 Agent。
扩展阅读 / 进阶方向
- Docker 部署:Workspace 提供独立部署应用,可以按官方应用指南构建镜像,把 Server、Browser 和存储放到服务器。
- CLI 自动化:安装
univer-workspace-cli,接入 Claude、Codex、Kimi Work 等现有 Agent 环境,用 CLI 处理文档和 Worktree。 - MCP 接入:Workspace 暴露远程 MCP 服务,支持 Streamable HTTP 和 OAuth,Cursor、VS Code、Claude Desktop 等客户端可以直接连接。
- 官方文档与固定版本:Univer Web SDK 文档、Server SDK 文档、Workspace 配置文档。本教程基于
c1a5fb3dc9d5951cbf618f76639466feac5da4d7编写,后续版本以官方文档为准。