# 範例

> 按能力執行 Collaboration SDK 範例，查看各範例指南、服務端與 Web 入口。

- Human documentation: [https://docs.univer.ai/zh-TW/server/collaboration/examples](https://docs.univer.ai/zh-TW/server/collaboration/examples)

- Agent Markdown: [https://docs.univer.ai/zh-TW/server/collaboration/examples.md](https://docs.univer.ai/zh-TW/server/collaboration/examples.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [collaboration/examples.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/server/collaboration/examples.zh-TW.mdx)

---

所有範例位於 [univer-collaboration-examples](https://github.com/dream-num/univer-collaboration-examples)，採用相同的最小 `web/main.ts + server/main.ts` 結構並獨立執行。先完成快速開始，再依整合任務選擇其他範例。

| 範例                          | 主要概念        | 命令                              |
| --------------------------- | ----------- | ------------------------------- |
| [快速開始](#quick-start)        | 核心協同流程      | `pnpm example:quick-start`      |
| [資料庫配接器](#database-adapter) | 資料庫配接器      | `pnpm example:database-adapter` |
| [權限](#permissions)          | 身分與授權       | `pnpm example:permissions`      |
| [歷史](#history)              | 衍生版本歷史      | `pnpm example:history`          |
| [留言](#comments)             | 獨立留言        | `pnpm example:comments`         |
| [Worktree](#worktree)       | 隔離編輯與合併     | `pnpm example:worktree`         |
| [檔案轉換](#exchange)           | Office 檔案轉換 | `pnpm example:exchange`         |
| [多節點部署](#multi-node)        | 水平擴展        | `pnpm example:multi-node`       |

## 快速開始

組合 Collaboration Client、Transport、Endpoint、Service 與 Memory Adapter。使用兩個瀏覽器驗證同一 Sheet 的 HTTP 載入、WebSocket Session、Room、ACK 與廣播。

```bash
pnpm example:quick-start
```

開啟 `http://127.0.0.1:3010/?unit=quick-start-sheet`。

* [範例指南](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/quick-start/README.md)
* [服務端入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/quick-start/server/main.ts)
* [Web 入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/quick-start/web/main.ts)
* [本站逐步指南](https://docs.univer.ai/zh-TW/server/collaboration/quick-start.md)

## 資料庫配接器

展示內建 SQLite Adapter 的用法，以及自訂 Database Adapter 的實作。

```bash
pnpm example:database-adapter
```

開啟 `http://127.0.0.1:3010/?unit=persistent-sheet`。

* [範例指南](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/database-adapter/README.md)
* [服務端入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/database-adapter/server/main.ts)
* [Web 入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/database-adapter/web/main.ts)

## 權限

從 Cookie 建立可信身分，分別保護 Unit HTTP 讀取、即時 JOIN 與變更集提交。頁面可切換教學用 **Alice · Editor** 與唯讀 **Bob · Viewer**。

```bash
pnpm example:permissions
```

開啟 `http://127.0.0.1:3010`。

* [範例指南](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/permissions/README.md)
* [服務端入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/permissions/server/main.ts)
* [Web 入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/permissions/web/main.ts)
* [身分與授權指南](https://docs.univer.ai/zh-TW/server/collaboration/identity-and-authorization.md)

## 歷史

在核心之外加入 History Service、獨立 Adapter、History Endpoint 與瀏覽器歷史入口。透過 Unit 建立及變更集提交 Events，將 History 建為可重建的衍生索引。

```bash
pnpm example:history
```

開啟 `http://127.0.0.1:3010/?unit=history-sheet`，編輯 Sheet，再選取頁面頂部的 `History`。

* [範例指南](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/history/README.md)
* [服務端入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/history/server/main.ts)
* [Web 入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/history/web/main.ts)

## 留言

加入 Thread Comment Service、獨立 Adapter、Comment Endpoint 與前端留言入口。Comment Endpoint 重用主協同 Endpoint 的 Session 和 Unit Room。

```bash
pnpm example:comments
```

開啟 `http://127.0.0.1:3010/?unit=comments-sheet`，選取儲存格並使用留言入口。

* [範例指南](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/comments/README.md)
* [服務端入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/comments/server/main.ts)
* [Web 入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/comments/web/main.ts)

## Worktree

展示隔離草稿、Ready、Reopen 與逐 Unit Merge 的完整生命週期。切換主幹與草稿，觀察 AI Agent 的變更在合併前如何保持隔離。

```bash
pnpm example:worktree
```

開啟 `http://127.0.0.1:3010/?unit=worktree-sheet&worktree=demo-worktree`。

* [範例指南](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/worktree/README.md)
* [服務端入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/worktree/server/main.ts)
* [Web 入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/worktree/web/main.ts)
* [CLI 與人工審閱流程](https://docs.univer.ai/zh-TW/ai/worktree.md)

## 檔案轉換

組合 `@univerjs-pro/exchange-node` 與 Collaboration Service，實現服務端 Sheet 匯入匯出、任務輪詢、快照匯入與已確認修訂版本匯出。

```bash
pnpm example:exchange
```

開啟 `http://127.0.0.1:3010/?unit=exchange-sheet`。透過 **File → Open (File)** 匯入，透過 **File → Save As** 匯出。

* [範例指南](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/exchange/README.md)
* [服務端入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/exchange/server/main.ts)
* [檔案轉換流程](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/exchange/server/exchange.ts)
* [Web 入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/exchange/web/main.ts)

## 多節點部署

在 Nginx 後執行兩個協同服務節點。Redis 在節點之間轉送即時更新並共用 Session Ticket，任何節點都能處理任何請求。需要 Docker Compose。

```bash
pnpm example:multi-node
```

開啟 `http://127.0.0.1:3010/`，點選 **New Sheet** 建立檔案。將完整 URL 複製到另一個分頁，
驗證同一文件的協同編輯；再建立幾份檔案，觀察它們在不同節點上的分配情況。

* [範例指南](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/multi-node/README.md)

> [!NOTE: 範例不是正式應用]
> 固定使用者、教學授權、Memory Adapter、本機密鑰及記憶體檔案與任務儲存僅供教學。身分、授權、持久化、密鑰、檔案、部署與產品互動仍由應用負責。