# 示例

> 按能力运行 Collaboration SDK 示例，并直达每个示例的说明、Server 与 Web 入口源码。

- Human documentation: [https://office.univer.ai/zh-CN/collaboration/examples](https://office.univer.ai/zh-CN/collaboration/examples)

- Agent Markdown: [https://office.univer.ai/zh-CN/collaboration/examples.md](https://office.univer.ai/zh-CN/collaboration/examples.md)

- Language: `zh-CN`

- Source file: `content/docs/collaboration/examples.zh-CN.mdx`

- Upstream source: [https://github.com/dream-num/office.univer.ai/blob/main/content/docs/collaboration/examples.zh-CN.mdx](https://github.com/dream-num/office.univer.ai/blob/main/content/docs/collaboration/examples.zh-CN.mdx)

---

所有示例都位于
[univer-collaboration-examples](https://github.com/dream-num/univer-collaboration-examples)，使用相同的
`web/main.ts + server/main.ts` 最小结构并可独立运行。先完成 Quick Start，再根据接入任务选择
其他示例。

| 示例                                    | 重点概念        | 运行命令                            |
| ------------------------------------- | ----------- | ------------------------------- |
| [Quick Start](#quick-start)           | 核心协同链路      | `pnpm example:quick-start`      |
| [Database Adapter](#database-adapter) | 数据持久化边界     | `pnpm example:database-adapter` |
| [Permissions](#permissions)           | 身份与权限       | `pnpm example:permissions`      |
| [History](#history)                   | 派生版本历史      | `pnpm example:history`          |
| [Comments](#comments)                 | 独立评论能力      | `pnpm example:comments`         |
| [Worktree](#worktree)                 | 隔离编辑与合入     | `pnpm example:worktree`         |
| [Exchange](#exchange)                 | Office 文件交换 | `pnpm example:exchange`         |

## Quick Start

组装 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&type=2`。

* [示例说明](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/quick-start/README.zh-CN.md)
* [Server 入口](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://office.univer.ai/zh-CN/collaboration/quick-start.md)

## Database Adapter

对照自定义 Memory、PostgreSQL 与内置 SQLite Adapter，重点展示 transaction、revision CAS、
批次原子性和 `customData` 事务边界。

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

打开 `http://127.0.0.1:3010/?unit=database-adapter-sheet&type=2`。

* [示例说明](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/database-adapter/README.zh-CN.md)
* [Server 入口](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)

## Permissions

展示应用如何从 Cookie 建立可信身份，并分别保护 Unit HTTP 读取、实时 JOIN 和 changeset
提交。页面可在 `editor` 与只读 `viewer` 两个教学账号之间切换。

```bash
pnpm example:permissions
```

打开 `http://127.0.0.1:3010`。

* [示例说明](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/permissions/README.zh-CN.md)
* [Server 入口](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://office.univer.ai/zh-CN/collaboration/identity-and-authorization.md)

## History

在 Core 之外增加 History Service、独立 Adapter、History Endpoint 与浏览器历史入口。History
由 Unit 创建和 changeset commit Event 建立，是可重建的派生索引。

```bash
pnpm example:history
```

打开 `http://127.0.0.1:3010/?unit=history-sheet&type=2`，编辑后点击页面上方的 `History`。

* [示例说明](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/history/README.zh-CN.md)
* [Server 入口](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)

## Comments

增加 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&type=2`，选择单元格并使用评论入口。

* [示例说明](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/comments/README.zh-CN.md)
* [Server 入口](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

展示独立 draft、Ready、Reopen 与逐 Unit Merge 的完整生命周期。可以在 trunk 与 draft 之间
切换，观察 Agent 修改如何在合入前保持隔离。

```bash
pnpm example:worktree
```

打开
`http://127.0.0.1:3010/?unit=worktree-sheet&type=2&worktree=demo-worktree`。

* [示例说明](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/worktree/README.zh-CN.md)
* [Server 入口](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://office.univer.ai/zh-CN/cli/worktree.md)

## Exchange

组合 `@univerjs-pro/exchange-node` 与 Collaboration Service，展示 Sheet 的服务端导入导出、任务
轮询、snapshot 导入与 confirmed revision 导出。

```bash
pnpm example:exchange
```

打开 `http://127.0.0.1:3010/?unit=exchange-sheet&type=2`，通过 **File → Open (File)** 导入，
通过 **File → Save As** 导出。

* [示例说明](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/exchange/README.zh-CN.md)
* [Server 入口](https://github.com/dream-num/univer-collaboration-examples/blob/main/examples/exchange/server/main.ts)
* [Exchange 工作流](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)

> **示例不是生产应用**
>
> 固定用户、演示授权、Memory Adapter、本地密钥、内存文件和任务存储只用于教学。应用仍然负责自己的
> 身份、权限、持久化、密钥、文件、部署与产品交互。