# Workspace
> 以 Univer Office SDK 建構的開源工作區：雲端試用、私有部署，透過 Workspace CLI 接入既有 Agent，或在 Desktop 中進行對話式辦公。
- Human documentation: [https://docs.univer.ai/zh-TW/overview/examples/workspace](https://docs.univer.ai/zh-TW/overview/examples/workspace)
- Agent Markdown: [https://docs.univer.ai/zh-TW/overview/examples/workspace.md](https://docs.univer.ai/zh-TW/overview/examples/workspace.md)
- Requested language: `zh-TW`
- Content language: `zh-TW`
- Documentation version: `1.3.0`
- Source: [examples/workspace.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/examples/workspace.zh-TW.mdx)
---
**Univer Workspace** 是以 **[Univer Office SDK](https://docs.univer.ai/zh-TW/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 線上版
編輯 · 協作 · 審閱"] --> S["Workspace Server
空間 · 內容 · 權限 · 版本"]
A["既有 Agent"] --> C["Workspace CLI
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 資料產生互動頁面。
- **邊看邊改：** 在側邊預覽內容、檢查公式與版面，再透過對話要求具體修改。
- **審閱後交付：** 原生 Office 變更留在 Worktree，由人查看差異並確認合入共享空間。
### 從需求到可審閱的辦公成果
在一般會話產生、修改 Office 文件與 Web App，再到 Space 統一管理與分享。原生 Office 變更經 Worktree 審閱後合入；HTML 發佈與綁定寫回使用各自的儲存與授權流程。後續會話可引用同一份檔案或資料。
```mermaid
flowchart LR
A["一般會話
需求與資料"]
B["Office 文件
Worktree 與變更審閱"]
C["Web App
HTML 頁面與資料綁定"]
D["Space
管理 · 分享 · 協作"]
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 管理與分享產生的檔案。
Agent 也能在一般會話產生互動報告、業務頁面與資料看板。後續會話依已發布的預算表建立 **06 Launch Dashboard**：三張指標卡顯示預算、實際支出與差額，比較圖透過 HTML View 即時綁定六個工作方向的資料。本例唯讀同一份原生試算表，不寫回資料。[雙向綁定](https://docs.univer.ai/zh-TW/overview/features/shared/binding.md)仍為實驗性能力，後續可能變更。
#### 在 Space 中管理、分享與協作
會話產生的五份原生發布檔案與 **06 Launch Dashboard** 都集中在 **Aurora Launch Studio**。在同一個 Space 整理預算、文件、三頁簡報、任務台帳、流程畫布和 Web App，管理存取權限並分享給團隊。團隊繼續協同編輯原生 Office 內容，綁定頁面隨來源資料更新。Web 與 Desktop 使用同一份檔案；Agent 對原生內容的後續修訂保留在獨立 Worktree 等待審閱。
#### 在 Desktop 中瀏覽內容與審閱草稿
下方記錄真實 Desktop 操作：瀏覽本機 Space 的發布檔案，開啟各產品的原生編輯器，再回到真實 Agent 對話。內容始終可在應用程式內繼續編輯。
#### 在 Desktop 中協作編輯共享內容
Web 與 Desktop 使用同一個本機帳號開啟 **01 Launch Budget**。從 Web 輸入的備註出現在真實 Desktop 編輯器；從 Desktop 輸入的確認也同步回 Web。截圖顯示兩則備註與已同步狀態，展示同帳號跨用戶端同步；Agent 草稿仍隔離在 Worktree。
#### 透過對話產生、修改並交付文件
Agent 在獨立 Worktree 修訂 **02 Launch Brief**：補充兩週核准檢查點與負責人任務，將回訪率目標從 40% 調整為 45%，並記錄風險及緩解措施。截圖展示實際對話和原生文件預覽，共享主線維持不變。
#### Worktree 與 Compare：在桌面檢查草稿
從文件的 Review changes 開啟審閱，原生文件畫面並排顯示共享內容與 Worktree 提案稿。可以逐段捲動檢查內容與差異，再決定接受哪些修改。圖中的桌面整合預覽為唯讀，本例保留尚未合併的草稿。
#### 在 Desktop 中查看分享設定
Desktop 的分享空間面板展示團隊空間的成員角色與連結存取規則。成員依照空間角色存取共享內容；複製連結不會額外授予存取權限。截圖過程中未修改分享權限。
### 在同一個桌面中使用五種原生內容
英文 Aurora 發布專案以虛構資料串聯預算、文件、簡報投影片、任務台帳和流程畫布。以下都是 Desktop 內的原生 Office 編輯器，使用者可繼續編輯 Agent 操作的同一份內容。
截圖來自桌面整合預覽，Univer 品牌介面透過宿主擴充點接入。預覽由可擴充的 Agent 宿主與 Space 能力外掛組合；預覽外掛的交付狀態以專案發布內容為準。
#### Sheets：可計算的業務模型
發布預算包含六個工作方向，以公式計算 Budget、Actual 和 Variance，並搭配原生比較圖表。預算合計 USD 102,000，實際支出 USD 100,000，結餘 USD 2,000。Agent 透過 Facade API 驗證計算結果。
#### Docs：從證據到決策
標題、段落樣式、清單和原生表格組織發布目標、計畫、成功指標與負責人。後續對話可在 Worktree 中針對這份可編輯文件進行局部修訂。
#### Slides：清楚呈現業務邏輯
三頁簡報以可編輯文字、圖形及一致的視覺樣式串聯發布主張、四階段計畫、成功指標與負責人。使用者可在同一應用程式調整版面並播放簡報。
#### Relational Table：組織協作與交付
六筆發布任務包含狀態、優先順序、負責人、截止日期與備註等型別化欄位。彩色選項清楚呈現進度和優先順序，形成共享任務台帳。
#### Canvases：連接策略與執行
原生圖形、文字與連接線呈現 **Align → Activate → Share → Learn** 四個階段，簡短備註連接各階段的發布行動與依據。
### 安裝並連接工作區
已有可擴充 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) | 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) 是探索入口，說明如何連接、定位目標並載入指引。完整執行階段 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 ` 讀取所需文件，或用 `--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
Headless 操作與驗證"]
D["Workspace 服務
檔案、協同與版本"]
E["桌面預覽
原生編輯器與 Web App"]
F["Worktree 與內容比較
人類審閱"]
A --> B --> C --> D
D <--> E
D --> F
F --> E
```
| 組成部分 | 職責 |
| --- | --- |
| [Web SDK](https://docs.univer.ai/zh-TW/guides/sheets.md) | 統一內容模型、Office 編輯介面、渲染、公式與 Headless Facade 操作。 |
| [Server SDK](https://docs.univer.ai/zh-TW/server.md) | 協同、版本與 Worktree 等能力，整合應用後端。 |
| [AI SDK](https://docs.univer.ai/zh-TW/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)，或接入自有宿主與服務。
### 依自己的業務流程繼續擴充
| 目標 | 起點 |
| --- | --- |
| 產業文件與專屬任務 | 增加產業 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-TW/overview/examples.md)
[Office Lab](https://docs.univer.ai/zh-TW/overview/examples/office-lab.md)