# 快速開始

> 透過編程 Agent 建立第一個 Office 應用，再了解如何整合和部署。

- Human documentation: [https://docs.univer.ai/zh-TW/overview/get-started](https://docs.univer.ai/zh-TW/overview/get-started)

- Agent Markdown: [https://docs.univer.ai/zh-TW/overview/get-started.md](https://docs.univer.ai/zh-TW/overview/get-started.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.3.0`

- Source: [get-started.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/get-started.zh-TW.mdx)

---

本文透過試算表連動、文件協作和 CLI 三個實例介紹 Office SDK 的用法。選擇一個實例，將對應的 Prompt 交給編程 Agent，再依後續步驟整合應用並部署。

## 先確定你要建立什麼

Office SDK 支援試算表、文件、簡報、關聯式表格、畫布與 PDF。依應用目標找到對應的接入方式。

| 你的目標 | 從哪裡開始 | 第一個完成標準 |
| --- | --- | --- |
| 在應用中嵌入 Office 編輯器 | [Web SDK 安裝與基礎用法](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/installation.md) | 建立內容，完成編輯、儲存與重新開啟。 |
| 讓 Office 內容與業務介面連動 | [Facade API](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/facade.md) | 頁面輸入與儲存格雙向同步，介面讀取真實計算結果。 |
| 為編輯器加入多人協作 | [Server SDK 協作快速開始](https://docs.univer.ai/zh-TW/server/collaboration/quick-start.md) | 兩個獨立工作階段編輯同一份內容，修改互相同步。 |
| 匯入、處理並匯出 Office 檔案 | [檔案轉換](https://docs.univer.ai/zh-TW/server/import-export/node.md) | 使用真實檔案完成匯入、修改、匯出並檢查結果。 |
| 讓 Agent 或 CLI 讀寫內容 | [AI SDK 內容操作](https://docs.univer.ai/zh-TW/ai/content-operations.md) | 載入內容、檢查結構、執行修改並驗證提交或輸出。 |
| 建立人類與 Agent 共用的工作空間 | [Worktree 與審閱流程](https://docs.univer.ai/zh-TW/ai/worktree.md) | Agent 修改保留於獨立草稿，經人類比較、審閱後合併。 |

這些能力可以組合使用。查看[功能總覽](https://docs.univer.ai/zh-TW/overview/features.md)確認產品支援範圍；下方三個實例協助你先體驗一段完整流程。

## 讓 Agent 協助你開始

將需求和 [llms.txt](/llms.txt) 文件索引連結交給程式設計 Agent 即可，不必複製完整 SDK 文件。以下提供一個可重複使用的範本，以及三個可以直接貼上使用的完整實例。

### 一個需求範本

將 `<…>` 替換為你的需求。不必先規劃整個辦公系統，先描述一個看得見結果的功能。

```text
請用 Univer Office SDK 建立可在本機執行的<應用程式名稱>。
先閱讀 https://docs.univer.ai/zh-TW/llms.txt 和相關完整範例，
SDK 套件使用相同版本。

初始內容：<少量可以直接操作的資料或文字>。
核心體驗：<使用者做一個動作，立即看到什麼變化>。
驗收條件：<兩到三個具體、可以操作驗證的結果>。

只完成這個最小流程，使用原生 Univer 編輯器與真實 SDK 能力。
完成後實際啟動，在瀏覽器中驗證，並提供預覽連結。
若缺少必要設定，請說明具體缺少什麼。
```

### 實例一：試算表連動

將頁面上的數量輸入欄位與試算表儲存格雙向綁定，並在頁面中顯示公式計算的報價總額。

```text
請用 Univer Office SDK 製作可在本機執行的單頁報價工作台。
先閱讀 https://docs.univer.ai/zh-TW/llms.txt 和相關完整範例，
SDK 套件使用相同版本。

使用基礎 Sheets 預設，嵌入可編輯的原生試算表，預設三項商品：
顯示器 2 台 × 1200 元，鍵盤 5 個 × 300 元，耳機 3 個 × 200 元。
每項金額與合計都使用試算表公式計算。

旁邊放「顯示器數量」輸入框與「報價總額」卡片。
輸入框與對應儲存格雙向同步，卡片讀取真實公式結果；
頁面不要重複計算報價。支援儲存至瀏覽器，重新整理後還原。

實際驗證：初始合計 4500 元，數量改為 3 後為 5700 元；
直接在試算表修改數量，輸入框與總額也更新；儲存後重新整理仍保留修改。
只完成這些功能，實際執行驗證後提供預覽連結。
```

**體驗方式：** 將顯示器數量從 2 改為 3，看到合計從 4500 變為 5700；再直接編輯試算表，觀察頁面跟隨變化。儲存並重新整理，確認資料還原。接入方式見 [Web SDK 安裝與基礎用法](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/installation.md)與 [Facade API](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/facade.md)。

### 實例二：文件協作

使用兩個獨立工作階段編輯同一份文件，驗證兩側的修改能否即時同步。

```text
請用 Univer Office SDK 製作可在本機執行的雙人文件協作展示。
先閱讀 https://docs.univer.ai/zh-TW/llms.txt，並參考
https://github.com/dream-num/univer-collaboration-examples
的目前版本範例，前後端 SDK 套件保持相同版本。

左右各放一個原生 Univer 現代文件編輯器，代表「小林」和「小陳」。
兩側使用獨立執行環境與線上工作階段，連接真實的 Server SDK 協作服務，
依官方範例明確載入伺服器建立的同一份文件，預設幾句簡短文字。

左側輸入一句話，右側即時出現；右側繼續輸入，左側也更新。
透過 SDK 協作協定同步。只使用固定的兩位展示使用者與記憶體儲存，
前後端共用一個本機服務，不加入登入、檔案管理或 AI 對話。
Pro License 從環境變數讀取；未設定時保留 SDK 預設行為與提示。

實際驗證：雙向輸入後內容一致，伺服器確實提交更新，
重新整理後可讀回內容。說明服務重新啟動後記憶體資料會重設。
只完成這些功能，實際執行驗證後提供預覽連結。
```

**體驗方式：** 在左側正文輸入一句話，再在右側繼續編輯，觀察雙向同步；重新整理後確認文字保留。此展示使用記憶體儲存，服務重新啟動會重設；部署應用時須接入持久化資料庫。接入方式見 [Server SDK 協作快速開始](https://docs.univer.ai/zh-TW/server/collaboration/quick-start.md)。

### 實例三：建立自己的 you-cli

讓目前的 Agent 使用你自己的 Office 工具。支援 Sheet、Doc、Slide、Relational Table 與 Canvases，先用一份 Doc 體驗「產生 → 預覽 → 繼續對話修改」。

```text
請用 Univer Office SDK，在目前專案建立自己的 you-cli 與 Web 預覽。
先閱讀 https://docs.univer.ai/zh-TW/llms.txt，並參考
https://github.com/dream-num/univer-cli-examples 的完整內容操作範例。
前後端與 AI SDK 套件使用相容的相同版本，API 以安裝套件型別為準。

支援 Sheet、Doc、Slide、Relational Table、Canvases，先用 Doc 完成流程。
約定命令：./you-cli create <type> --name <name>、inspect --unit <id>、
execute --unit <id> --file <path>、open --unit <id>，並提供 --help。
工具放在目前專案，提供使用說明或 Skill，讓目前 Agent 讀取後呼叫。
回傳 JSON，包含對應的 unitId、類型、提交結果與預覽 URL。

CLI 與 Web 連接同一份真實協作內容，提交後更新已開啟的原生編輯器。
寫入後等待提交確認並讀回驗證，內容與清單使用持久化儲存。
open 回傳 URL，由 Agent 透過宿主預覽能力開啟；支援時在右側顯示。
模型與自然語言理解沿用目前 Agent；授權從環境讀取並保留必要提示。

驗收：對話產生專案週報並開啟預覽；接著增加風險與負責人，
沿用同一 unitId，預覽自動更新；重新整理與服務重啟後內容仍保留。
實際執行驗證，提供預覽連結與用法；僅啟動本例需要的服務。
```

#### 透過對話使用

先把上方 Prompt 交給程式設計 Agent。建立工具並讀取專案說明後，在同一個對話中說：

```text
用 you-cli 建立專案週報，包含本週進展、風險與下週計畫，開啟 Web 預覽。
```

看到內容後繼續說：

```text
在剛才那份週報增加一項風險：交付可能延遲，負責人小林。更新已開啟的預覽。
```

Agent 會沿用原文件的 `unitId`。支援預覽面板的宿主可在右側顯示，其他環境使用回傳的瀏覽器連結。

#### you-cli 命令參考

以下為上方 Prompt 約定的專案內命令。將 `UNIT_ID` 替換為 `create` 回傳的 `unitId`；`edit.js` 由 Agent 依 Facade API 編寫。

| 操作 | 命令 | 結果 |
| --- | --- | --- |
| 建立 | `./you-cli create doc --name "專案週報"` | 建立文件並回傳 `unitId`；也可選 `sheet`、`slide`、`base`、`board`。 |
| 檢查 | `./you-cli inspect --unit UNIT_ID` | 讀取真實內容與目前版本。 |
| 修改 | `./you-cli execute --unit UNIT_ID --file edit.js` | 執行修改，等待提交並回傳結果。 |
| 預覽 | `./you-cli open --unit UNIT_ID` | 回傳同一份文件的 Web URL，由 Agent 開啟。 |

也可執行 `./you-cli --help`。操作流程見 [AI SDK 內容操作](https://docs.univer.ai/zh-TW/ai/content-operations.md)，完整程式碼見 [CLI SDK Examples](https://docs.univer.ai/zh-TW/overview/examples/cli-sdk.md)。

## 將第一個流程接入你的應用

Web SDK 提供共同的內容執行環境。需要共享編輯或 Agent 操作時，在此基礎上接入 Server SDK 與 AI SDK。具體分工見 [Office SDK 總覽](https://docs.univer.ai/zh-TW/overview.md)。

| 接入步驟 | 在應用中完成什麼 | 繼續閱讀 |
| --- | --- | --- |
| 掛載編輯器 | 將預設掛載至頁面，以 Facade API 連接業務互動；處理快照儲存與實例銷毀。 | [Web SDK 接入](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/installation.md) |
| 連接後端 | 沿用身分與權限，為共享文件設定資料庫；按需加入檔案匯入匯出。 | [協作接入](https://docs.univer.ai/zh-TW/server/collaboration/quick-start.md)、[檔案轉換](https://docs.univer.ai/zh-TW/server/import-export/node.md) |
| 連接既有 Agent | 將內容讀寫、計算與驗證封裝為工具或 CLI；需要審閱時再接入 Worktree。 | [AI SDK 內容操作](https://docs.univer.ai/zh-TW/ai/content-operations.md)、[Worktree](https://docs.univer.ai/zh-TW/ai/worktree.md) |

## 應用架構

既有應用與 Agent 可以共用 Office 內容。介面負責互動，Agent 透過工具執行操作，業務服務沿用你的身分、權限與儲存。

**藍色節點由你提供與管理：** 應用介面、既有 Agent、業務 API（含身分與權限）、資料庫與檔案儲存。其餘標有 SDK 的節點代表整合至應用的 Univer 能力。

```mermaid
%%{init: {"themeVariables":{"fontSize":"13px"},"flowchart":{"padding":10,"nodeSpacing":20,"rankSpacing":20}}}%%
flowchart TB
    UI["你的應用介面"]
    UI --> Editor["Web SDK · 編輯器"]
    Agent["你的既有 Agent"] --> Tools["AI SDK · Office 工具"]
    Editor <-->|共享編輯| App["你的業務 API · 身分與權限"]
    Tools <-->|內容讀寫與提交| App
    App --> Server["Server SDK · 協作與檔案轉換"]
    Tools --> Runtime["Web SDK · Headless 內容執行環境"]
    Server --> Runtime
    Server --> Storage[("你的資料庫與檔案儲存")]
    classDef appOwned fill:#e8f0ff,stroke:#4771c4,color:#163d75,stroke-width:2px
    class UI,Agent,App,Storage appOwned
```

僅嵌入編輯器時可從本機快照開始，共享編輯再連接後端。Agent 繼續使用既有模型與任務編排，透過 AI SDK 操作內容；需要隔離修改、比較與審閱時，再組合 Worktree。

## 以 Workspace 為例建置與部署

[Univer Workspace](https://github.com/dream-num/univer-workspace)展示如何將三個 SDK 組成完整的辦公空間。以下指令在 Workspace 儲存庫根目錄執行，環境準備以 [README](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/README.md)為準。

1. **本機開發。** 安裝相依套件後，在兩個終端機分別執行 `pnpm workspace:dev:server` 與 `pnpm workspace:dev:web`，開啟 `http://127.0.0.1:5173`。Web 開發服務將 API 與 WebSocket 請求轉送至後端。
2. **建置並執行。** 僅建置 Workspace 應用，再啟動正式入口：

```bash
pnpm --filter @univerjs/univer-workspace build
pnpm workspace:start
```

Web 產物位於 `dist/public`，Server 產物位於 `dist/server`，由一個 Node.js 程序提供靜態頁面與 API。

3. **準備部署。** 設定授權、身分與資料目錄，持久化業務資料庫、協作資料庫及上傳資源，並檢查重新啟動後能否還原。見 [Docker 部署](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/README.md#docker)與[架構說明](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/docs/architecture.md)。

規模擴大後，再參考 [Server SDK 部署指引](https://docs.univer.ai/zh-TW/server/deployment.md)拆分服務。

## 繼續探索開源專案

- [Univer CLI](https://docs.univer.ai/zh-TW/overview/examples/cli.md)：在本機工作區透過 Agent 或終端機建立、編輯與檢查 Office 內容，並透過 Viewer 審閱修改。
- [DeepSeek Harness](https://docs.univer.ai/zh-TW/overview/examples/deepseek-harness.md)：在既有 Agent 對話接入 Office 工具、即時預覽與草稿審閱。

查看[全部範例](https://docs.univer.ai/zh-TW/overview/examples.md)，取得各專案的展示與儲存庫連結。