Worktree
了解隔离草稿、版本基线和 OT 合入,以及 AI SDK 如何连接 Agent 编辑与人类审阅。
Worktree 为 Office 内容提供隔离的草稿,人和 Agent 仍可在草稿上协同编辑。Agent 可以修改预算、整理数据或重写方案,同时人继续编辑主文档,也就是 trunk。草稿经过验证和审阅之后,其修改才会合入主线。
隔离的对象是文档内容及其变更,而不是 Git 的工作目录。一个任务可以跨越多个 Unit(内容单元),例如一个工作簿、一篇文档和一份演示文稿。
隔离原理:从同一基线分别演进
为已有 Unit 创建 Worktree 时,服务端会把该 Unit 当前主线的 revision 记录为 Baseline(基线)。草稿从这一版本开始,拥有独立的 Snapshot、changeset、revision、Presence 和协同 Room。草稿中的修改不会进入主线。
| 概念 | 作用 |
|---|---|
| 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。这样,同一套检查和编辑工具既可以作用于主线,也可以作用于草稿。
同一个 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,并把通过的草稿合入当前主线。
- 创建 Worktree 并加载:选择任务涉及的 Unit,连接对应的 Worktree target,再
pull最新的草稿内容。 - 使用 Inspection 了解结构和数据,按需查询 API,所有改动都通过 Facade 执行。
- 将修改提交到草稿,回读数据和计算结果,必要时截图。Slides 还可以运行 Layout Lint。如果检查发现问题,则继续修改草稿。
- 标记 Ready:冻结各 Unit 当前的草稿版本,停止编辑,等待审阅。
- 审阅:将通过的草稿 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 接入指南是建议的起点。
你觉得这篇文档如何?