Univer Workspace
一个让人类与 AI Agent 共同创作、协作和审阅的开源 Office 工作空间。
Univer 文档 · Office SDK 文档 · CLI 指南 · Workspace Agent · Issues
English | 简体中文
Univer Workspace 是一个基于 Univer Office SDK 构建、可独立部署的知识管理与
团队协作产品。你可以使用 Workspace Browser 直接编辑，通过 Workspace Agent 对话并审查变更，
也可以使用 CLI 自动化处理任务。三个入口连接同一个负责文档存储和权限的 Workspace Server，
让人类与 AI Agent 共同处理 Sheet、Doc、Slide、Base 与 Board。
Agent 在隔离的 Worktree 中工作、验证修改，再把结果交给人类审阅；只有经过确认的内容才会合入
共享 trunk。
为什么选择 Univer Workspace
| 面向人类 | 面向 Agent | 面向运维 |
|---|---|---|
| 使用个人与团队 Space 组织内容 | 通过 Univer Facade API 创建、修改丰富的 Office 内容 | 部署一套 Browser 与 Server 应用 |
| 共同编辑 Sheet、Doc、Slide、Base 与 Board | 检查数据、渲染截图/PDF 并执行布局检查 | 自主管理产品数据、协同数据与 Blob 数据 |
| 通过角色与 Node 级权限控制分享和访问 | 离线发现版本匹配的 Skill 与 API | 接入密码、GitHub、Discord 或应用 OAuth 登录 |
| 使用最近访问、回收站、文件导入导出与审阅视图 | 多轮修改而不影响 trunk | 运行具备明确恢复边界、文档完备的 HTTP API |
基于电子表格的 Mini App · 观看演示
- Agent 可以生成基于电子表格的 Mini App，例如决策看板、交互式报告和业务看板。
- 网页上的指标、图表和控件与单元格绑定，支持数据读取、写入和协同更新。
选择操作入口
| 入口 | 适用场景 | 开始使用 |
|---|---|---|
| Workspace Browser | 直接编辑文档、协同、组织 Space 和审阅变更 | 启动 Workspace |
| Workspace Agent | 在文档旁与 Agent 对话、引用本地或远程文件与文件夹、审查 Worktree 变更 | 安装和使用 Agent |
| Workspace CLI | 从终端、脚本或已有 Agent 环境自动化处理文档 | CLI 安装与使用 |
Workspace Agent 是基于 DSH（DeepSeek Harness）的本地 Web 应用。
它的本地文件引用指向运行 Agent 的机器，Workspace 文档仍由连接的服务管理。
Agent 和 CLI 都可以连接现有的 Workspace 部署，或在本地启动的 Workspace。
工作原理
flowchart LR
Human([人类]) --> Browser[Workspace Browser]
Agent([AI Agent]) --> CLI[Workspace CLI]
Human --> AgentApp[Workspace Agent：本地对话与审查]
AgentApp --> Server
Browser --> Server[Workspace Server]
CLI --> Server
Server --> Product[(产品数据)]
Server --> Collaboration[(协同数据)]
Server --> Blobs[(Blob 与 Asset 字节)]
Browser 提供直接编辑和协同界面；Workspace Agent 将对话、文档预览和 Worktree 审查放在一起；
CLI 为 Agent 提供加载、理解、修改、验证和渲染同一份内容的结构化入口。
Server 解析权威身份与权限、拥有 Workspace 产品 workflow，并组合 Univer Collaboration SDK。
Worktree 将 Agent 编辑转化为边界清晰的审阅流程：
创建 Worktree
→ Agent 编辑并验证隔离草稿
→ Ready
→ 人类在 Browser 或 Workspace Agent 中审阅
→ Merge 或 Reopen
→ trunk
在人类接受之前，中间修改不会进入共享内容。完整产品 workflow 见
CLI 指南。
快速开始
以下命令启动 Workspace 服务与 Browser。如需对话界面，继续按照
Workspace Agent 指南安装。
环境要求
- Node.js 24 或更高版本
- pnpm 11
安装依赖并准备应用配置：
pnpm install
cp apps/workspace/.env.example apps/workspace/.env
启动 Server：
pnpm workspace:dev:server
在另一个终端启动 Browser 开发服务器：
pnpm workspace:dev:web
打开 。Vite 提供热更新，并将 API 与 WebSocket 流量代理到
的 Server。
当 apps/workspace/dist/public 存在时，Server 也可以在 3020 端口提供最近一次构建的 Browser。
产品 API 文档位于 和
。
配置、认证、存储、Docker 与数据库迁移的详细说明见
Workspace 应用指南。
使用 Workspace Agent
Workspace Agent 是基于 DSH、专为 Univer Workspace 构建的桌面应用。通过 @ 引用 Workspace 文件，在对话中创建和编辑文档，审核改动并决定合入或丢弃。
Agent 指南提供可以直接交给编程 Agent 的安装提示词，
尚未克隆仓库也能使用，同时包含手动安装与使用说明。
指南会引导你选择或启动自己的 Workspace 服务、注册 OAuth 回调、配置模型凭据，
并打开本地启动器打印的完整 token URL。
使用 Workspace CLI
如果想配合 Claude、Codex、Kimi Work 等现有 Agent 软件使用，请在 Agent 的运行环境中安装 CLI 和 Workspace CLI Skill：
npm install --global univer-workspace-cli@latest
npx skills add dream-num/univer-workspace --skill univer-workspace-cli -g
先把 CLI 指向你自己的 Workspace 部署，再开始需要 Browser 确认的登录流程：
uvw config set workspace.origin
uvw auth login
用户确认命令输出的 URL 与验证码后，完成一次性交换：
uvw auth login --complete
安装包包含版本匹配的 Skill、结构化 JSON 输出、Facade API 发现、内容检查、PNG/PDF 渲染、Office
文件交换与 Worktree workflow。完整用法和登录合同见 CLI 指南。
仓库结构
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 本地发布工具
本仓库是产品的 composition root，不重新实现上游 SDK。Univer Runtime 拥有 Unit 模型、渲染、
Facade API 与 Office 内容能力；Univer Collaboration SDK 拥有 snapshot、revision、OT、实时协同与
Worktree 协议合同；Univer CLI SDK 拥有可复用的 headless runtime、执行、检查与渲染能力。
Workspace 拥有产品身份、Space、目录层级、ACL、分享、回收站、最近访问、Blob 存储策略、远程
workflow 与部署。Client Core 在仓库应用之间共享存储无关的认证、Workspace workflow、本机
Node-hosted Blob/Asset 传输与 worker-backed 内容 runtime，包括 Node-hosted Office exchange、Typst
编译/materialize/apply、render Unit 装配、截图、PNG/PDF 输出、Slide layout lint、render-page 源码与
SVG 编译/测量/apply workflow；reference-provider package 仍只供 Browser 使用。两者都是私有实现
模块，不是额外的公开应用或 SDK。
架构原则
- 一个权威 Server。 不把客户端提供的 User、Role、Resource、Unit、Worktree 或 revision
当作权威信息。 - 分离存储边界。 产品数据、协同状态与 Blob 字节各有明确所有者，并通过持久化、幂等的
Operation 协调。 - 只使用已发布的 SDK 合同。 仓库只消费 package 的公开 export，不依赖相邻源码 checkout。
- 一个精确 SDK baseline。 所有版本耦合的
@univer-cli/*、@univerjs/*与
@univerjs-pro/*package 始终一起升级。 - HTTP contract first。 OpenAPI 源文件、生成类型、Server route、Browser 与 CLI 必须描述
同一行为。
修改这些边界前，请阅读技术架构、
应用层设计与数据模型。
开发与验证
开发过程中先运行最小相关检查；在宣称完整变更前，运行合适的仓库级验证：
pnpm typecheck
pnpm test
pnpm build
pnpm --filter @univerjs/univer-workspace test:production-import
pnpm package:workspace-cli
修改 HTTP contract 时还需要运行：
pnpm --filter @univerjs/univer-workspace api:verify
升级 Univer SDK 时使用仓库脚本一次性更新所有版本耦合依赖与 lockfile，不要单独编辑 manifest：
pnpm update:univer-sdk --sdk_version
交付模型
CLI 与 Workspace 部署基于同一份源码，但各自独立交付：
- 在
main包含的稳定vX.Y.Ztag 上手动触发 CLI 发布 workflow，
并显式设置dry_run=false，才会发布univer-workspace-cli@X.Y.Z。创建、推送 tag 不触发 CI 或发布。 - Workspace 使用独立的手动部署 workflow，构建已有稳定 tag，或把精确 commit 标记为
sha-。推送 release tag 不会部署 Server。
稳定版 CLI 发布会检查整个仓库的 SDK baseline，并在发布前验证实际 package artifact。
文档
| 资源 | 范围 |
|---|---|
| Univer Runtime 文档 | Browser Runtime、Preset、Plugin、Facade API 与编辑器能力 |
| Univer Office SDK 文档 | Office SDK 技术栈：Runtime、Collaboration、CLI 与 Worktree |
| Workspace 应用指南 | 配置、认证、存储、Docker 与升级 |
| Workspace CLI 指南 | 安装、登录、Agent workflow 与 package 合同 |
| Workspace Agent 指南 | 本地 Profile、浏览器 OAuth、会话、文件、Worktree 与身份切换 |
| Client Core package | 私有 Node-hosted client 能力边界 |
| 技术架构 | Browser、Server、存储、OpenAPI 与模块边界 |
| HTTP contract | 产品 API 源文件与生成流程 |
| Reference-provider package | Browser 私有 referenced-Unit policy |
参与贡献
欢迎提交 Issue 与 Pull Request。修改代码前，请阅读 AGENTS.md 和目标附近的 README
或设计文档；保留无关改动，不手工编辑生成文件，并完成受影响边界要求的验证。
Runtime 开发 License
Browser 与 CLI 包含内容同步、经过批准的 runtime 开发凭据，用于本地开发。该凭据每 90 天轮换
一次，并不是本仓库的软件许可证。Browser 构建可以通过 VITE_UNIVER_LICENSE 覆盖，CLI 可以
通过 UNIVER_LICENSE 覆盖。
License
Univer Workspace 使用 Apache-2.0 许可证。
