# Workspace

> 基于 Univer Office SDK 的开源工作区：云端试用、私有部署，通过 Workspace CLI 接入已有 Agent，或在 Desktop 中完成对话式办公。

- Human documentation: [https://docs.univer.ai/zh-CN/overview/examples/workspace](https://docs.univer.ai/zh-CN/overview/examples/workspace)

- Agent Markdown: [https://docs.univer.ai/zh-CN/overview/examples/workspace.md](https://docs.univer.ai/zh-CN/overview/examples/workspace.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.3.0`

- Source: [examples/workspace.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/examples/workspace.zh-CN.mdx)

---

**Univer Workspace** 是基于 **[Univer Office SDK](https://docs.univer.ai/zh-CN/overview.md)** 构建的开源办公空间。它把可编辑的 Office 内容和与数据联动的 Web App 放进个人与团队 Space，连接分享、协同、版本和变更审阅。[开源仓库](https://github.com/dream-num/univer-workspace)提供应用、部署方案、CLI 和桌面客户端。

你可以把 Workspace 私有部署在自己的环境，也可以先用[云端在线试用](https://space.univer.ai)。已有 Agent 通过 Workspace CLI 操作这个工作区；Workspace Desktop 则把 Agent 对话和同一套工作区整合进本地客户端。它们围绕同一个服务、同一批文件工作。

[云端试用](#entry-points) · [连接已有 Agent](#cli-start) · [私有部署](#self-host) · [Desktop 体验](#desktop-start) · [仓库与定制](#build-your-own)

## 先在云端体验完整的 Workspace



打开[云端在线试用](https://space.univer.ai)，登录后进入个人空间或有权限访问的团队 Space。创建或打开文档，体验直接编辑、文件整理和分享。这是已经部署好的 Workspace 服务，下面也可以用 CLI 把 Agent 连接到它。试用请使用示例数据，数据可能重置。

**Workspace Server** 管理身份、空间、权限、存储、协同与版本；**Web** 是浏览器中的编辑和审阅界面。私有部署运行的也是这套 Server 与 Web 应用。

```mermaid
flowchart LR
H["团队成员"] --> W["Web 在线版<br/>编辑 · 协作 · 审阅"] --> S["Workspace Server<br/>空间 · 内容 · 权限 · 版本"]
A["你已有的 Agent"] --> C["Workspace CLI<br/>Skills · 内容操作"] --> S
```



## 让已有 Agent 连接云端 Workspace

在 Agent 的运行环境中安装 CLI 和发现入口 Skill。需要 Node.js 22.12 或更新版本，推荐 Node.js 24。具备命令执行能力的 Agent 可以直接使用这些工具，模型和对话仍由它自己提供。先明确设置云端服务地址，让浏览器和 Agent 操作同一个 Workspace：

```bash
npm install --global univer-workspace-cli@latest
npx skills add dream-num/univer-workspace --skill univer-workspace-cli -g
uvw --version
uvw config set workspace.origin https://space.univer.ai
```

#### 首次连接：完成一次浏览器登录

已有有效会话时可跳过。需要登录时执行：

```bash
uvw auth login
```

打开返回的链接，在浏览器中登录并确认验证码。用户确认完成后，再执行：

```bash
uvw auth login --complete
```

这一步只在需要建立会话时进行。完整命令与认证说明见 [Workspace CLI 指南](https://github.com/dream-num/univer-workspace/blob/main/apps/cli/README.md)。

首次浏览器授权后，CLI 会在后续任务中复用会话，不需要为每种 Agent 编写登录页面或单独的鉴权集成。给已连接的 Agent 下达任务，打开它返回的链接，就能在 Web 中查看同一份内容，并在合入前审阅原生 Office 的修改。

### 从一份可计算、可审阅的文档开始

```text
在我的 Workspace 个人空间中创建一个英文月度开销表，包含日期、类别、金额和 5 条示例数据，添加总额公式及分类图表。
把修改放在独立草稿中，检查数据、公式和显示效果，给我预览或审阅链接，在我确认前不要合入。
```

在已连接的 Agent 或 Desktop 中都可以发送这个任务。Agent 负责创建与检查，你可以继续修改、审阅，再决定合入；你也可以从在线版打开同一份内容。

## 把同样的工作流程迁到私有部署

[开源仓库](https://github.com/dream-num/univer-workspace)包含 Server 和 Web。按照[部署指南](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/README.md#docker)构建应用，配置自己的域名、登录方式、持久化存储和运行环境。源码开发使用 Node.js 24 与 pnpm 11，生产部署细节以该指南为准。

继续使用同一个 CLI，把服务地址切换为自己的部署，再授权该服务中的账号。下面的示例地址需要替换成你的实际服务地址：

```bash
uvw config set workspace.origin https://workspace.example.com
uvw auth login
```

Agent 使用的工具和 Skills 不变，操作的目标变成你私有服务中的文件和权限。Desktop 也可以连接这个服务；客户端注册和回调配置参考 [Agent 连接指南](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/README.md#connect-to-a-local-workspace)。

## 把 Workspace 装进本地 Desktop 客户端

**Workspace Desktop** 将 Workspace、Agent 运行时、Office 工具和内容预览整合进一个本地客户端，带来类似 Codex 或 Cowork 的办公体验：描述目标，在对话旁查看文档或 Web App，继续提出修改，再审阅成果。

Desktop 可以连接刚才试用的云端 Workspace、私有部署，也可以连接本机运行的 Workspace 服务。模型和对话由配置好的 Agent 宿主驱动，文件和访问权限由所连接的 Workspace 管理。下面用真实桌面案例，展示创作、管理与协作如何连成一条工作流。

[安装并连接工作区](#desktop-install) · [体验任务：用两份原生内容完成预算审阅](#desktop-first-task)

### 把 Agent 工作方式带进日常办公

办公任务的成果需要持续编辑、公式计算、团队协作和变更审阅。Desktop 将这些环节放到同一个工作环境中，让对话直接围绕可编辑、可计算、可协作的内容展开。

- **上下文连贯：** 对话、文件、工作区资料和本地引用随手可用。
- **生成 Office 内容与 Web App：** 创建可编辑的电子表格、文档、演示文稿、Relational Table（关系型表格）和 Canvases（画布），也可以基于 Office 数据生成交互式页面。
- **边看边改：** 右侧直接预览内容，检查公式和排版，再通过对话提出具体修改。
- **审阅后交付：** Agent 对原生 Office 内容的修改保留在 Worktree 中，由人类查看差异、确认后合入共享空间。



### 从需求到可审阅的办公成果

在正常会话中生成、修改 Office 文档与 Web App，再到 Space 统一管理与分享。原生 Office 变更经 Worktree 审阅后合入；HTML 页面发布和绑定写回使用各自的保存与授权流程。继续对话时，可引用同一份文件或数据。

```mermaid
flowchart LR
A["正常会话<br/>需求与资料"]
B["Office 文档<br/>Worktree 与变更审阅"]
C["Web App<br/>HTML 页面与数据绑定"]
D["Space<br/>管理 · 分享 · 协作"]
A --> B --> D
A --> C --> D
D -->|引用同一份内容继续完善| A
```

### 一个桌面应用中有哪些能力

| 能力 | 使用体验 |
| --- | --- |
| Agent 会话 | 保留对话和任务上下文，在本机配置模型服务商、模型及凭据。 |
| 文件与资料引用 | 浏览有权限访问的空间，通过 @ 引用 Workspace 文件、文件夹和本地资料。 |
| 内容预览 | 在会话旁打开原生 Office 文件或 Web App，直接查看内容、交互与数据。 |
| 审阅与交付 | 查看 Worktree 中新增、修改、删除的文档，继续调整，或合入、放弃草稿。 |
| 本地与在线空间 | 连接团队已部署的在线服务，也可以连接本机运行的 Workspace 服务。 |
| Space 管理与协作 | 集中整理会话生成的文件，管理分享权限，与团队编辑同一份内容。 |

### 工作区与 Agent 的实际配合

以下截图和操作片段均录自已安装的 macOS 桌面应用，连接全新建立的本地 Workspace。账号、空间、文件名、正文和 Agent 对话均使用英文虚构演示资料。

#### 在正常会话中生成内容并查看结果

**Build Five-File Launch Demo** 是一个正常 Agent 会话，在其中创建了电子表格、文档、演示文稿、Relational Table 和画布。下图展示真实会话的成果交接，以及 Desktop 浏览器面板中可继续编辑的 **02 Launch Brief**。用户可以在这个会话中继续提出修改，再到 Space 管理和分享生成的文件。

![在正常会话中生成内容并查看结果](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-chat-creation.jpg)



Agent 也能在正常会话中生成交互报告、业务页面和数据看板。后续会话基于已发布的预算表创建了 **06 Launch Dashboard**：三张指标卡展示预算、实际支出和差额，对比图通过 HTML View 实时绑定六个工作方向的数据。本例只读取同一份原生表格，不写回数据。[双向绑定](https://docs.univer.ai/zh-CN/overview/features/shared/binding.md)仍为实验性能力，后续可能发生变化。

![Launch Dashboard](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-web-app.jpg)

#### 在 Space 中管理、分享和协作

会话中生成的五份原生发布文件与 **06 Launch Dashboard** 都集中在 **Aurora Launch Studio**。在同一个 Space 中整理预算、简报、三页演示、任务台账、流程画布和 Web App，管理访问权限并分享给团队。团队继续协同编辑原生 Office 内容，绑定页面随源数据更新。Web 与 Desktop 使用同一份文件；Agent 对原生内容的后续修订保留在独立 Worktree 中，等待审阅。

![在 Space 中管理、分享和协作](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-space-overview.jpg)

#### 在 Desktop 中浏览内容与审阅草稿

下面记录真实 Desktop 操作：浏览本地 Space 的发布文件，打开各产品的原生编辑器，再回到真实 Agent 对话。内容始终可以在应用内继续编辑。

![在 Desktop 中浏览内容与审阅草稿](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-space-walkthrough.gif)

#### 在 Desktop 中协作编辑共享内容

Web 与 Desktop 使用同一个本地账号打开 **01 Launch Budget**。从 Web 输入的备注出现在真实 Desktop 编辑器中；从 Desktop 输入的确认也同步回 Web。截图显示两条备注和已同步状态，展示同账号跨端同步；Agent 草稿仍隔离在 Worktree 中。

![在 Desktop 中协作编辑共享内容](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-collaboration.jpg)

#### 通过对话生成、修改并交付文档

Agent 在独立 Worktree 中修订 **02 Launch Brief**：补充两周审批检查点和负责人任务，将回访率目标从 40% 调整为 45%，并记录风险与缓解措施。截图展示实际对话与原生文档预览，共享主线保持不变。

![通过对话生成、修改并交付文档](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-agent-conversation.jpg)



#### Worktree 与 Compare：在桌面检查草稿



从文档的 Review changes 打开审阅，原生文档视图并排展示共享内容与 Worktree 提议稿。可以逐段滚动检查内容与差异，再决定接受哪些修改。图中的桌面集成预览为只读，本例保留未合入的草稿。

![Worktree 与 Compare：在桌面检查草稿](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-compare.jpg)

#### 在 Desktop 中查看分享设置

Desktop 的分享空间面板展示团队空间的成员角色与链接访问规则。成员按照空间角色访问共享内容；复制链接不会额外授予访问权限。截图过程中未修改分享权限。

![在 Desktop 中查看分享设置](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-sharing.jpg)

### 在同一个桌面中使用五种原生内容

英文 Aurora 发布项目使用虚构资料，串联预算、简报、演示文稿、任务台账和流程画布。下面都是 Desktop 内的原生 Office 编辑器，人类可以继续编辑 Agent 操作的同一份内容。

截图来自桌面集成预览，Univer 品牌界面通过宿主扩展点接入。该预览由可扩展的 Agent 宿主与 Space 能力插件组合而成；预览插件的交付状态以项目发布内容为准。

#### Sheets：可计算的业务模型

发布预算包含六个工作方向，以公式计算 Budget、Actual 和 Variance，并配有原生对比图表。合计预算 USD 102,000，实际支出 USD 100,000，结余 USD 2,000。Agent 通过 Facade API 校验计算结果。

![Sheets：可计算的业务模型](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-sheets.jpg)

#### Docs：从证据到决策

标题、段落样式、列表与原生表格组织发布目标、计划、成功指标和负责人。后续对话可以在 Worktree 中定向修订这份可编辑文档的一部分。

![Docs：从证据到决策](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-docs.jpg)

#### Slides：把业务逻辑讲清楚

三页演示用可编辑文字、形状和统一视觉样式串联发布主张、四阶段计划、成功指标与负责人。用户可以在同一应用中调整排版并播放演示。

![Slides：把业务逻辑讲清楚](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-slides.jpg)

#### Relational Table：组织协作与交付

六条发布任务包含状态、优先级、负责人、截止日期和备注等类型化字段。彩色选项直观展示进度和优先级，形成共享任务台账。

![Relational Table：组织协作与交付](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-relational-table.jpg)

#### Canvases：连接策略与执行

原生形状、文字和连接线展示 **Align → Activate → Share → Learn** 四个阶段，简短备注连接各阶段的发布行动与依据。

![Canvases：连接策略与执行](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/local-canvases.jpg)

### 安装并连接工作区

已有可扩展 Agent 桌面时，也可以安装并启用 Space 能力插件，从 Space 连接服务、配置模型，再接入品牌皮肤。本页截图采用这一组合。完整 Workspace Desktop 发行版与插件预览的交付路径不同，请按所安装版本的发布内容或仓库说明操作。

1. 从 [GitHub Releases](https://github.com/dream-num/univer-workspace/releases) 选择 Desktop 安装包。桌面版本使用 agent-v 标签，按平台选择 Windows x64、macOS Apple Silicon 或 Linux x64。当前为实验性桌面交付，版本与平台以已发布内容为准。

2. 在 **Settings → Workspace** 中选择服务地址，经浏览器登录并授权。可以连接已部署的在线服务，也可以按照[本地运行说明](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/README.md#connect-to-a-local-workspace)准备本机服务。

3. 在 Models 设置中配置支持的模型服务商、模型与凭据。Workspace 登录和模型访问分别配置，详见[模型配置说明](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/README.md#model-credentials)。

4. 添加有权限访问的个人或团队空间，创建会话，通过 @ 引用资料。尝试下面的任务，再打开内容预览与变更审阅。

安装包包含 Agent 应用与 Office 工具。Workspace 服务独立运行在本机或服务器上；模型访问使用你配置的服务商。

### 体验任务：用两份原生内容完成预算审阅

```text
在当前空间创建英文 Budget Review 电子表格，包含 8 行部门示例数据：Department、Budget、Actual、Variance。差异和合计使用公式，添加预算与实际支出的对比图。
再创建一份简短文档，总结超支情况，并链接到这份表格。原生 Office 内容的修改放在同一个 Worktree 中，检查数据、公式与结果，打开预览和变更审阅，等待我确认后再合入。
```

随后可以说：“将 Marketing 的预算减少 10%，同步更新总结。”查看调整后的数值和文档差异，再决定是否接受草稿。

#### 真实会话：从运营模型到决策简报

Aurora 桌面会话串联了读取源文件、修订原生文档与后续审阅请求。Agent 将现有草稿保持为 Ready，等待人类确认。可以查看上方的[真实桌面对话](#conversation-preview)与[原生 Worktree 比较](#workspace-review)。

## 基于仓库构建适合自己的 Workspace

前面体验到的产品，就是 Office SDK 的一套应用组合。可以从 [Workspace 仓库](https://github.com/dream-num/univer-workspace)出发，复用内容运行时与协同能力，把工作流程、Skills、业务工具和界面改造成适合自己团队的工作区。

### 找到你要改造的部分

| 仓库位置 | 负责什么 |
| --- | --- |
| [`apps/workspace`](https://github.com/dream-num/univer-workspace/tree/main/apps/workspace) | Server、Web、产品 API 与部署配置。 |
| [`apps/cli`](https://github.com/dream-num/univer-workspace/tree/main/apps/cli) | 将已有 Agent 接入部署好的 Workspace。 |
| [`apps/agent`](https://github.com/dream-num/univer-workspace/tree/main/apps/agent) | Agent 宿主、连接生命周期和原生 Desktop 外壳。 |
| [`skills/univer-workspace-cli`](https://github.com/dream-num/univer-workspace/tree/main/skills/univer-workspace-cli) | 安装到已有 Agent 的发现入口 Skill。 |
| [`packages/client-core`](https://github.com/dream-num/univer-workspace/tree/main/packages/client-core) | Node 宿主共用的 Workspace 内容操作。 |
| [`packages/dsh-univer-workspace-plugin`](https://github.com/dream-num/univer-workspace/tree/main/packages/dsh-univer-workspace-plugin) | Agent 宿主中的 Office 工具、原生预览和任务指引。 |
| [`packages/dsh-univer-workspace-skin-plugin`](https://github.com/dream-num/univer-workspace/tree/main/packages/dsh-univer-workspace-skin-plugin) | Workspace 品牌外观与视觉令牌。 |
| [`packages/workspace-html-viewer`](https://github.com/dream-num/univer-workspace/tree/main/packages/workspace-html-viewer) | Web App 的 HTML View 沙箱与数据绑定宿主。 |

### Skills：让 Agent 理解工作区并完成任务

#### 让已有 Agent 学会使用 Workspace

安装给已有 Agent 的 [`univer-workspace-cli` Skill](https://github.com/dream-num/univer-workspace/blob/main/skills/univer-workspace-cli/SKILL.md) 是发现入口，告诉它如何连接 Workspace、定位目标并加载操作指引。完整的运行时 Skills 随 CLI 发布，与命令和 Facade API 版本配套；Desktop 的内置能力插件也提供面向任务的指引和工具。

| 指引 | 覆盖内容 |
| --- | --- |
| `core` | 空间与文件定位、任务草稿、内容检查和审阅交付。 |
| `sheet` · `doc` · `slide` · `base` · `board` | 电子表格、文档、演示文稿、关系型表格（Relational Table）与画布（Canvases）。 |
| `blob` | 原始文件上传、下载与替换。 |
| `html-view` | 生成并管理实时 HTML 页面，构建可交互的 Web App。 |
| `embed` · `cross-unit-formula` | 嵌入其他内容，以及跨内容的数据引用与公式。 |

```bash
uvw skills list
uvw skills get core
uvw skills get sheet
uvw skills get html-view
```

先加载 `core`，再按任务读取产品或主题。`skills get` 会列出参考路径，使用 `uvw skills read <name> <path>` 读取所需文档，或用 `--full` 一并读取。已有 Agent 通过 CLI 使用这些能力，Desktop 则把相关工具和指引整合进对话流程。



#### Desktop 内置的任务指引

Desktop 的能力插件内置 **univer** Skill 及参考资料，告诉 Agent 如何定位空间与文档、使用 Office API，以及创建、检查和交付 Worktree。这些指引与实际工具配合：Agent 可以先查 API，再在原生内容上执行操作并检查结果。

[能力插件](https://github.com/dream-num/univer-workspace/blob/main/packages/dsh-univer-workspace-plugin/README.md)组合了文件发现、Headless Facade 编辑、结构化检查、导入导出与 Worktree 生命周期工具。当前预览将草稿准备到可审阅状态；正式发布使用所部署应用的审阅与合入流程。构建自己的产品时，可在同一 Office 运行时加入行业 Skills、模板和业务工具。

预览插件内置九个 Skills。通用 Skill 说明内容发现、身份与交付流程；各产品 Skill 提供 API 和验证指引，Agent 按当前任务读取需要的内容。

| Skill | 操作指引 |
| --- | --- |
| `univer` | 空间、文件、草稿生命周期与交付 |
| `univer-sheet` | 公式、样式、图表与表格验证 |
| `univer-doc` | 文档结构、段落与表格 |
| `univer-slide` | 演示文稿创作与视觉布局检查 |
| `univer-base` | 字段、记录与视图 |
| `univer-board` | 形状、连接线与画布布局 |
| `univer-embed` | 在一个 Office 产品中嵌入另一个产品 |
| `univer-cross-unit-formula` | 跨 Unit 引用与计算 |
| `univer-html-view` | 构建和检查绑定 Office 数据的 HTML 页面 |





### 将 Agent 执行循环与 Office 能力分开组装

Skills 提供任务指引，工具通过 Headless 运行时操作结构化内容，原生编辑器负责给人类展示和编辑。Workspace 提供文件与协同上下文。因此可以更换模型、增加业务工具或替换品牌界面，而不必重新实现 Office 引擎。

```mermaid
flowchart LR
A["Agent 与模型"]
B["Skills 与工具"]
C["Office SDK<br/>Headless 操作与验证"]
D["Workspace 服务<br/>文件、协同与版本"]
E["桌面预览<br/>原生编辑器与 Web App"]
F["Worktree 与内容比较<br/>人类审阅"]
A --> B --> C --> D
D <--> E
D --> F
F --> E
```

| 组成部分 | 承担的职责 |
| --- | --- |
| [Web SDK](https://docs.univer.ai/zh-CN/guides/sheets.md) | 统一内容模型、可编辑的 Office 界面、渲染、公式，以及 Headless Facade 内容操作。 |
| [Server SDK](https://docs.univer.ai/zh-CN/server.md) | 协同、版本与 Worktree 等能力，与应用后端集成。 |
| [AI SDK](https://docs.univer.ai/zh-CN/ai.md) | 面向 Agent 的内容操作、检查与验证能力。 |
| Agent 运行时与 Skills | DSH 提供会话、模型调用、工具编排与审批；Workspace 能力插件接入 Office 工具和任务指引。 |
| Workspace 与 Desktop | 应用提供空间、文件、身份接入和审阅界面；Electron 桌面交付将这些能力带到一个桌面应用中。 |

值得复用的是这条完整链路：需求 → 工具 → 可编辑内容 → 预览 → 审阅 → 共享交付。Office SDK 提供办公能力层，Agent 宿主提供对话与执行循环。可以直接扩展现有的[应用与插件](https://github.com/dream-num/univer-workspace/tree/main/apps/agent)，也可以把 SDK 接入自己的宿主与业务服务。

### 沿着自己的业务流程继续扩展

| 你想实现的目标 | 从哪里开始 |
| --- | --- |
| 行业文档与专属任务 | 增加行业 Skills、模板和工具指引，保留内容与视觉检查。 |
| 自己的身份、存储与分享方式 | 扩展 Workspace 应用及服务端的产品策略。 |
| 自己的 Agent 办公客户端 | 组合 Agent 宿主、能力插件和品牌皮肤，接入选定的模型与业务工具。 |



### 继续查看实现

[Desktop 构建与交付](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/desktop/README.md) · [Agent 应用与配置](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/README.md) · [全部示例](https://docs.univer.ai/zh-CN/overview/examples.md)

[Office Lab](https://docs.univer.ai/zh-CN/overview/examples/office-lab.md)