Worktree

了解隔离草稿、版本基线和 OT 合入,以及 AI SDK 如何连接 Agent 编辑与人类审阅。

Worktree 为 Office 内容提供隔离的草稿,人和 Agent 仍可在草稿上协同编辑。Agent 可以修改预算、整理数据或重写方案,同时人继续编辑主文档,也就是 trunk。草稿经过验证和审阅之后,其修改才会合入主线。

隔离的对象是文档内容及其变更,而不是 Git 的工作目录。一个任务可以跨越多个 Unit(内容单元),例如一个工作簿、一篇文档和一份演示文稿。

隔离原理:从同一基线分别演进

为已有 Unit 创建 Worktree 时,服务端会把该 Unit 当前主线的 revision 记录为 Baseline(基线)。草稿从这一版本开始,拥有独立的 Snapshot、changeset、revision、Presence 和协同 Room。草稿中的修改不会进入主线。

100%
概念作用
Baseline草稿起始的主线版本,用于比较和合入。
Draft head草稿中最新的已确认版本,每次向草稿提交都会推进该版本。
Ready head标记 Ready 时冻结的草稿版本,决定本轮审阅和合入的内容。

主线和草稿独立演进。revision 只描述各自的提交序列,因此仅比较数字大小无法判断哪一方的内容更新。拉取草稿只会同步草稿自身的修改。主线上的新修改不会自行进入正在审阅的版本,需要由合入预览和正式合入进行协调。

AI SDK 如何连接同一份草稿

AI SDK 的 Collaboration Runtime 负责一个 Unit 的快照、changeset 和 revision。Worktree 的创建、生命周期与合入由 Server SDK 的 Worktree 服务负责。Runtime 不需要为 Worktree 再内置一套文档编辑引擎。

应用将 worktreeID + unitID 解析为草稿的 snapshot、submit、WebSocket 和 Session Ticket 地址,并交给 Runtime。这样,同一套检查和编辑工具既可以作用于主线,也可以作用于草稿。

100%

同一个 Unit ID 可以同时存在于主线和多个 Worktree 中,因此 target 必须指明它所在的 Worktree。inspect、execute、截图和 Web 预览都应使用同一个 target,否则工具可能从草稿读取,却向主线写入。Web 端使用与该草稿匹配的协同配置加载同一份草稿。

分工负责内容
Web SDK共用的内容引擎,既用于 Agent 在 Headless 中的操作,也用于在浏览器中编辑。
Server SDK隔离草稿、持久化 changeset 与 revision、管理生命周期,并执行 OT 合入。
AI SDK可组合的 Runtime、Inspection、API 查询、Facade 执行和视觉检查。
你的应用选择模型、映射 target、管理身份与授权,以及组织任务和审阅界面。

Agent 从编辑到交付

应用可以为每个 Agent 分配独立的 Worktree,从而并行执行任务。Agent 编辑草稿、检查结果,然后将草稿标记为 Ready。人再逐份审阅草稿,对需要进一步修改的草稿执行 Reopen,并把通过的草稿合入当前主线。

100%
  1. 创建 Worktree 并加载:选择任务涉及的 Unit,连接对应的 Worktree target,再 pull 最新的草稿内容。
  2. 使用 Inspection 了解结构和数据,按需查询 API,所有改动都通过 Facade 执行。
  3. 将修改提交到草稿,回读数据和计算结果,必要时截图。Slides 还可以运行 Layout Lint。如果检查发现问题,则继续修改草稿。
  4. 标记 Ready:冻结各 Unit 当前的草稿版本,停止编辑,等待审阅。
  5. 审阅:将通过的草稿 Merge;需要人或 Agent 继续修改的草稿先 Reopen 回 Draft;不需要的草稿则 Discard。
操作作用
runtime.commit()仅提交到草稿,并推进草稿的 revision。
markReady()固定待审阅的版本,不合入主线。
reopenWorktree()将草稿从 Ready 恢复为 Draft,以便继续编辑。
mergeWorktree()将冻结的草稿修改逐个 Unit 合入主线。

Commit、Ready 和 Merge 是三个相互独立的操作。草稿一旦进入 Ready,无论是人还是 Agent,都必须先 Reopen 才能继续编辑。Runtime 与 CLI 的配合方式见 AI SDK Worktree 工作流。

合入原理:把修改应用到最新主线

如果 Unit 来自主线,服务端会读取 Baseline 到 Ready head 之间的草稿 changeset,收集其中的 mutation,再提交给主线的 Collaboration Service。如果主线在此期间已经前进,协同引擎会使用 OT(操作转换),将这些 mutation 变换到其后的 trunk 修改上,再确认新的主线版本。

因此,合入是将修改应用到当前文档,而不是用旧快照覆盖整个最新文档。可以转换的并发修改会被协调。无法转换或已不适用的修改会作为冲突返回,由应用处理。OT 也不会自动解决所有业务分歧。

在 Worktree 中新建的 Unit 没有可合入的主线基线。合入时会在主线中创建该 Unit,但不会复制整段草稿 changeset 历史。

审阅两件事:改了什么,合入会怎样

  • 如需查看草稿做了哪些修改,可以使用内容比较对比基线与 Ready 草稿的完整内容,新增、删除和修改都会列出。
  • 如需了解当前合入的效果,可在 Ready 之后调用 evaluateUnitMerge()。主线已经前进时,该调用会在隔离的 Runtime 中将经 OT 转换的候选修改应用到当前主线,生成只读预览;它不提交 changeset,也不会修改主线或草稿。

预览只反映发起请求时的状态。主线之后仍可能变化,实际的 Merge 会按执行时读取到的主线状态重新计算。多个 Unit 的合入也不是一个原子事务,因此某个 Unit 失败时,已经合入的 Unit 会保留在主线中。需要逐个 Unit 展示结果,并逐个处理失败。

接入与范围

将 Worktree 的 Client、Service、Endpoint 和数据库适配器与协同核心组合。草稿使用独立存储,Session Ticket Store 与主线共用一份。草稿的访问权限与主线的写入权限由应用分别授权,隔离本身并不授予访问权限。

目前支持 Sheet、Doc、Slide、Canvases 和 Relational Table,不包含 PDF。Worktree 示例、扩展模块和 Agent 接入指南是建议的起点。

返回功能总览

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.