Worktree:Agent 编辑与人类审阅
让 Agent 在隔离 Worktree draft 中编辑和检查 Unit,再由人类通过 Web 审阅并合入 trunk。
Worktree1 为 Agent 提供一块隔离的编辑空间。在 draft 中,Agent 可以反复执行 pull、inspect、execute、commit,完成结构化检查和视觉检查后将 Worktree 标记为 Ready;随后由人通过 Web 查看渲染后的页面,决定 Merge 或 Reopen。
创建 Worktree→ Agent 编辑 draft→ Agent 结构化与视觉检查→ Ready→ 人类通过 Web 审阅→ Merge / Reopen→ Trunk为什么使用 Worktree
- Agent 的中间修改不会进入 trunk;
- 每个 draft 都有独立的 Snapshot、changeset、revision、Presence 和实时房间;
- Agent 可以经过多轮同步、修改和自检后再提交结果;
- Ready 会冻结 draft 当前的 revision,建立明确的审阅边界;
- 人可以在 Web 中审阅、继续修改、Merge 或 Reopen;
- Merge 仍然经过 trunk Collaboration Service 自身的权限和提交边界。
完整工作流
创建 / 选择 Worktree→ 选择 Worktree Unit→ Collaboration Runtime load→ pull→ inspect→ api find / show→ execute(write)→ runtime.commit()→ inspect + screenshot + layout lint→ markReady→ Web 审阅→ merge / reopen文档内容加载与读写、Office 文件导入导出和视觉检查均可用之后,将同一组能力指向 Worktree target,即可得到推荐的 Agent 编辑流程。
Worktree Target
Collaboration Runtime 仍然只处理单个 Unit 的 Snapshot、changeset 和 revision,并不具备 Worktree 这个概念。Application adapter 负责把 worktreeID + unitID 映射为 Worktree Endpoint 的 Snapshot、Submit、WebSocket 和 Session Ticket URL,再把这组 URL 传给 Runtime backend。
worktreeID + unitID→ Application target adapter→ Worktree protocol URLs→ Collaboration Runtime同一套 Runtime 执行模型既可以接入 trunk,也可以接入隔离的 Worktree draft。
Agent 在 Draft 中操作 Unit
Agent 操作 Worktree Unit 与操作普通 Unit 使用的是同一个核心循环:
load → pull → inspect → execute(write) → commit@univer-cli/content-inspection-command 提供两个独立的 factory,作为现成的 Inspection 入口:
createContentInspectionCommand():作用于普通 Unit target;createWorktreeContentInspectionCommand():要求调用方明确选择--trunk或--worktree <id>。
Application 需要为 execute、screenshot 和其他命令加入同样的 target 选择,并负责获取与释放选中的 Runtime。
在 Commander 中选择 Worktree
Inspection 预设提供一个 Worktree 版本,要求调用方明确选择 --trunk 或 --worktree <id> 之一:
import type { WorktreeContentInspectionCommandDependencies } from "@univer-cli/content-inspection-command";import { createWorktreeContentInspectionCommand } from "@univer-cli/content-inspection-command";import { Command } from "commander";function addWorktreeCommands( program: Command, dependencies: { acquireRuntime: WorktreeContentInspectionCommandDependencies["acquireRuntime"]; markReady(worktreeID: string): Promise<void>; },): void { program.addCommand( createWorktreeContentInspectionCommand({ acquireRuntime: dependencies.acquireRuntime, }), ); const worktreeCommand = new Command("worktree"); worktreeCommand .command("ready") .argument("<worktree-id>") .action(async (worktreeID) => { await dependencies.markReady(worktreeID); }); program.addCommand(worktreeCommand);}acquireRuntime 和 markReady 都是此处显式声明的应用依赖,并非 AI SDK 内部隐藏的 helper。前者实现上一节所述的 Worktree target 到 Runtime 映射,后者调用 Collaboration SDK Worktree Client。
execute、screenshot、layout lint 这些命令需要使用同一个 target model,否则同一个 Unit ID 可能解析到不同的 trunk 或 draft target。Web 可以在同一个 Worktree Client 上提供 Reopen、Discard、Merge 和真实页面审阅;产品需要时,也可以将其中部分操作封装为额外的 Commander 子命令。
Agent 检查结果
Ready 之前,Agent 可以结合使用两类检查:
结构化检查:pull → inspect视觉检查:Unit → Render Runtime → screenshot / layout lint- Inspection 校验 Workbook、Worksheet、Range、Document、Paragraph、Presentation 或 Slide 的结构化内容;
- Screenshot 向 Agent 提供渲染后的页面;
- Layout Lint 诊断 Slide 上的布局问题;
- 检查发现问题时,Agent 可以继续 execute、commit,然后再次检查。
区分 Commit、Ready 与 Merge
| 操作 | 含义 |
|---|---|
runtime.commit() | 将当前 mutation 产生的 changeset 提交到 Worktree draft |
markReady() | 冻结各 Unit 当前的 draft revision,进入 ready 状态 |
reopenWorktree() | 从 ready 回到 draft,继续修改 |
mergeWorktree() | 将 Worktree 中的 Unit 逐个合入 trunk |
runtime.commit() 只推进 draft,不会合入 trunk。Ready 表示 Agent 的工作进入审阅阶段,但结果仍需经过一次 Worktree Merge 才能进入 trunk。
人类通过 Web 审阅
Web 使用 Worktree Client 和 Worktree Collaboration 配置加载同一个 draft,审阅界面可以展示:
- Worktree 的当前状态;
- draft 中 Unit 渲染后的页面;
- trunk 与 draft 之间的切换;
- 单个 Unit 的 merge preview;
- Ready、Reopen、Discard 和 Merge 操作。
Ready 状态的 draft 是只读的。无论人还是 Agent,如需继续修改,都要先 Reopen 回 Draft。审阅通过后执行 Merge,再切回 trunk 查看合入后的结果。
Collaboration SDK 边界
Worktree 的 Service、Endpoint、Client 和 Database Adapter 属于 Collaboration SDK。AI SDK 提供可组合的 Unit Runtime、Inspection、API Reference、Execution 和 Screenshot 能力。Worktree 生命周期命令、target 映射、身份和权限由应用负责。
服务端组装、生命周期和合入限制参见协同扩展模块。
Footnotes
-
这里的 Worktree 是文档内容的独立协同草稿,不是 Git worktree,也不是源码目录的检出副本。草稿修改需要经过审阅与合并流程才会进入主线。 ↩
你觉得这篇文档如何?