# @adonis-agora/collaboration 中文文档
规范地址：https://npmcn.com/package/%40adonis-agora/collaboration/
版本：0\.20\.2
npm 元数据更新时间：2026-11-04T01:46:28.727Z
中文译文更新时间：2026-11-06T22:37:43.186Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40adonis-agora/collaboration
原文对照：https://npmcn.com/package/%40adonis-agora/collaboration/?lang=original
项目主页：https://davidecarvalho.github.io/agora/docs/collaboration
源码仓库：https://github.com/DavideCarvalho/adonis-agora-collaboration
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：557 kB，153 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：7 个
- peer 依赖：@adonisjs/core ^7\.3\.0，@adonisjs/lucid ^22\.4\.0
- 首次发布：2026-08-25T02:53:22.125Z
- 最新版本发布：2026-11-04T01:46:28.293Z
- 近 30 天下载量：2243（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 44 个）
## 中文简介
合作编辑(CRDT)为AdonisJS 7-Yjs(Hocuspocus)和自动驱动,Redis后置存在,统一版本控制. 阿戈拉生态系统的一部分.
## 安装
```sh
npm install @adonis-agora/collaboration
```
也可以使用：`pnpm add @adonis-agora/collaboration`、`yarn add @adonis-agora/collaboration`、`bun add @adonis-agora/collaboration`
## README
# @ados-agora/协作
[](https://www.npmjs.com/package/@adonis-agora/collaboration) [](https://www.npmjs.com/package/@adonis-agora/collaboration) [](https://github.com/DavideCarvalho/adonis-agora-collaboration/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@adonis-agora/collaboration)
为AdonisJS——Yjs(Hocuspocus),Automerce和PartyKit(对接)驱动程序,Redis后置存在,统一版本控制,锚定评论,Ace代码和React客户端钩. 阿戈拉生态系统的一部分.
## 安装
```sh
node ace add @adonis-agora/collaboration
```
## 快开始
```sh
node ace configure @adonis-agora/collaboration # provider + config/collaboration.ts
node ace collaboration:init # REST routes, controller, migrations
node ace make:collab-document researches/writing # shared types per document
```
线 `config/collaboration.ts` 还有你的 `authorize()` ( lib 默认从不授权) 和存储后端(`LucidStorage`, (中文(简体) ), `FileSystemStorage` 或属于自己的).
### 发动机
| 发动机 | 同步运行 | 最好还是 |
| --- | --- | --- |
| `yjs` (默认) | Adonis HTTP 服务器上的嵌入式 Hocuspocus | 独立来源 |
| `automerge` | 在 Adonis 服务器上播放自定义房间 | 土著历史 |
| `partykit` | 云浮工人+持久物体(对接) | 全球延迟, 单独来源 |
缔约方 Kit 设置 :
```ts
// config/collaboration.ts
{
engine: 'partykit',
partykit: { roomHost: 'meu-app.partykit.dev', jwtSecret: process.env.COLLAB_JWT_SECRET },
}
```
然后运行 `collaboration:init --engine=partykit` 脚手架上工人 `partykit-worker/` 部署 `npx partykit deploy`。 。 。 .
### 接纳和东道主拥有的房间`yjs`(中文(简体) )
拥有房间耐用状态的应用软件有两个可选的钩子. 两者均适用于自主办 `yjs` 引擎; 其他引擎忽略它们(但 `persistDocument` 拒绝任何引擎上的麻黄室:
```ts
// config/collaboration.ts
{
// Opened after the token is verified and before `authorize`. It ends exactly once:
// `connected()` when the handshake completes, `closed()` when it never does
// (denied, authorize threw, socket dropped, shutdown). A later disconnect of a
// connected socket is not an admission event.
async beginAdmission(ctx, docName, socketId) {
return { connected: async () => {}, closed: async () => {} }
},
// Loaded through `storage.loadDocument`, but never seeded, stored, flushed on
// unload, versioned or restored by the driver — the app persists it its own way.
isEphemeralRoom: (docName) => docName.startsWith('projects/'),
}
```
## 服务器 API
```ts
import collaboration from '@adonis-agora/collaboration/services/main'
await collaboration.current.getDocumentText('researches/42/writing')
const version = await collaboration.current.createVersion('researches/42/writing', userId, 'v1')
collaboration.current.comments.list('researches/42/writing', 'text')
```
版本控制在引擎之间工作:全更新快照(Yjs/PartyKit)或原生头(Autocommerce). 每个空间都固定备注`text-range`, (中文(简体) ), `canvas-object`, (中文(简体) ), `timestamp`通过存储后端持续.
## 客户端钩子( 反应)
```sh
pnpm add @adonis-agora/collaboration-client
```
```tsx
import {
CollaborationProvider,
useCollabDoc,
useAwareness,
useComments,
useVersions,
} from '@adonis-agora/collaboration-client'
({ cookie })}>
function Editor({ docName }: { docName: string }) {
const { doc, status } = useCollabDoc(docName) // Y.Doc + connection status
const { peers } = useAwareness(docName)
const { comments, create, resolve } = useComments(docName, 'text')
const { versions, create: createVersion } = useVersions(docName)
// feed doc into Tiptap/y-prosemirror…
}
```
从引擎中自动选择运输 `GET /collaboration/token` (Hocuspocus Provider或YPartyKit提供).
## 代码
### 图标
- `collaboration:init` - 脚手架上文件目录、基准迁移(在配置数据库时)和党基特工人(`--engine=partykit`(中文(简体) )
- `collaboration:prune --keep=20 [--doc=] [--dry-run]` ——删除每个文档除N最新版本外的所有文本(呼号为: `collaboration.pruneVersions({ keep })`(中文(简体) )
- `make:collab-document ` ——生成共享文档类型 `app/collaboration/documents/` (空格 + 允许的主锚类型),可由前端导入
命令自动由 `configure`; 需要手动设置 `commands: ['@adonis-agora/collaboration/commands']` 内 `adonisrc.ts`。 。 。 .
### 已打入文档登记册
货包装有阿森布勒 `init` 钩( 注册于 `configure`扫描 `app/collaboration/documents/` 生成 `.adonisjs/collaboration/documents.ts`数字 :
```ts
import type { CollabDocumentName, CollabDocumentDefinition } from '.adonisjs/collaboration/documents.js'
function open(name: CollabDocumentName) { … } // autocomplete + exhaustiveness
```
刷新为 `node ace codegen`,dev服务器,测试或构建——与控制器/路由桶相同的生命周期.
## REST 终点
内置的十个端点( Ken, 注释 CRUD, 版本, 二进制状态) **自动注册** 脚下 `/collaboration`。 。 。 .
通过配置来保护他们——任何Adonis的中间软件或认证后卫的作品:
```ts
// config/collaboration.ts
routes: {
enabled: true,
prefix: '/collaboration',
middleware: [() => import('#middleware/auth_middleware')], // guards apply here
}
```
更喜欢完全控制? 手动禁用并注册到您想要的地方 :
```ts
// routes.enabled = false
import { collaborationRoutes } from '@adonis-agora/collaboration'
collaborationRoutes(router, {
prefix: '/api/collab',
middleware: [authMiddleware],
})
```
没有解析器, 符号端点会关闭( 401 ) : 通过 `routes.resolveUser` 或者先运行您的认证中间软件。 二进制 `state` POST为机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相机相.
> **路线类型安全警告**:自动注册的路线在供应商的 `ready()` 相位,它运行在编码热解后——所以它们可能不会出现在 `.adonisjs/server/routes.d.ts`。如果您的应用程序依赖于生成的路由类型(例如 Tuyau),则使用手动模式: set `routes.enabled = false` 打电话 `collaborationRoutes(router)` 内 `start/routes.ts`,其中总是取道.
## 编辑器绑定 (Tiptap)
客户会给你一个普通的 `Y.Doc` - 把它直接喂进Tiptap:
```tsx
import Collaboration from '@tiptap/extension-collaboration'
import CollaborationCursor from '@tiptap/extension-collaboration-cursor'
import { useEditor } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { useCollabDoc, useAwareness } from '@adonis-agora/collaboration-client'
function Editor({ docName, user }: { docName: string; user: { name: string; color: string } }) {
const { doc, status } = useCollabDoc(docName)
const { peers } = useAwareness(docName)
const editor = useEditor({
extensions: [
StarterKit,
Collaboration.configure({ document: doc }),
CollaborationCursor.configure({ user }),
],
editable: status === 'connected',
})
return (
<>
{peers.map((peer) => (
{peer.name ?? 'anon'}
))}
)
}
```
## 许可证
麻省理工学院
## 常见问题
### @adonis-agora/collaboration 是什么？
合作编辑\(CRDT\)为AdonisJS 7-Yjs\(Hocuspocus\)和自动驱动,Redis后置存在,统一版本控制\. 阿戈拉生态系统的一部分\.
### 如何安装 @adonis-agora/collaboration？
在项目目录运行 npm install @adonis-agora/collaboration，或使用 pnpm add / yarn add / bun add。
### @adonis-agora/collaboration 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @adonis-agora/collaboration 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @adonis-agora/collaboration 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @adonis-agora/collaboration 可以商用吗？
@adonis-agora/collaboration 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @adonis-agora/collaboration 的下载量有多少？
根据 npm 官方下载统计，@adonis-agora/collaboration 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,243 次，日均约 75 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @adonis-agora/collaboration 还在维护吗？
最新版本 0\.20\.2 发布于 2026/11/04（3 天前）；至今共发布 44 个版本，其中过去 12 个月发布了 44 个；首次发布于 2026/08/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。