Univer Workspace Worktree深度解析AI改稿隔离、双栏对比审阅与人工合并机制是怎么实现的【免费下载链接】univer-workspaceAn open-source Office workspace where people and AI agents create, collaborate, and review together.项目地址: https://gitcode.com/gh_mirrors/un/univer-workspace在Univer Workspace里当 AI 代理Agent帮你修改文档、表格或幻灯片时你希望改动先在一个隔离区里进行、能被并排对比审阅并最终由人来决定是否合并回正式版本。这套能力就是Worktree工作树。本文带你完整理解 Worktree 如何做到「AI 改稿隔离 → 双栏对比审阅 → 人工合并」以及背后的状态机、对比引擎与幂等合并是如何落地的。一、Worktree 是什么给文档的“分支”Worktree 借鉴了代码仓库里“分支 / 工作树”的思想在不动正式版本主干 / trunk的前提下开辟一个独立的草稿空间进行编辑。它由两部分组成User Worktree个人工作树默认private只有创建者可见适合让 AI 单独改稿。Team Worktree团队工作树挂在某个团队空间下可见性为space成员可协作审阅。每个 Worktree 内部由若干Unit文档单元构成覆盖sheet、doc、slide、board、base五种类型。每个单元都有明确的来源与变更状态这是隔离审阅的基础sourcetrunk引用一份现有文档或worktree在草稿里新建changemodified/added/deleted/unchanged二、隔离改稿状态机如何守护一次改动Worktree 的生命周期是一条受控状态机源码定义在 worktrees.types.tsdraft草稿中 → ready待审阅 → merging合并中 → merged已合并 │ └→ discarded已废弃 └→ reopen 重新打开回 draft隔离的核心在于只有draft状态、且具备编辑能力的创建者才能写入见 worktrees.service.ts。权限通过一套capabilities能力位精确计算——editDraft、addUnit、markReady、reopen、merge、discard各自对应状态与角色条件确保“谁能在哪个阶段做什么”一目了然。AI 改稿正是走这条路代理在草稿里通过submitChangeset提交增量变更集changeset含 baseRev → revision 的严格校验而不会直接污染正式文档。 关键设计草稿写入与正式写入是两条隔离的协作通道collaborationScope分别为worktree与trunk从根上保证了“改稿不影响主干”。三、双栏对比审阅把“改动前 / 改动后”并排放审阅环节由独立的对比查看器包 unit-comparison-viewer 驱动前端路由在 worktrees_.$worktreeId_.units.$unitId.$mode.tsx 中以双栏只读视图呈现。对比数据的编排逻辑在 unit-comparison.ts其要点左栏Base主干在“共同基线 revision”时的快照trunk侧。右栏DraftWorktree 的当前草稿头draftHeadRevision或合并后 / 预览态。三种视图draft草稿、merged已合并结果、preview合并预览。// 视图与状态的强约束节选自 unit-comparison.ts if (view merged worktree.status ! merged) throw CONFLICT if (view preview worktree.status ! ready) throw CONFLICT保真度HISTORY 优先SNAPSHOT 兜底对比引擎支持两种保真度UnitComparisonFidelityHISTORY若存在共同基线 revision会分别拉取主干与草稿两侧的changesets增量历史做精确的历史级 diff见 loadComparisonHistory。SNAPSHOT拿不到历史时退回快照级对比保证“总能看到差异”。表格类还会并行加载sheetBlocks分块工作表数据确保大表格也能完整对比——这是它区别于普通文本 diff 的关键。四、人工合并幂等、可恢复、需审批合并是高风险操作Univer Workspace 用三重机制保障它安全可控逻辑集中在 worktrees.service.ts幂等 Operation-Key每次merge/discard都带一个Idempotency-Key重复提交不会二次执行网络重试也安全。逐单元校验目标合并前调用validateAllTargets确认每个单元仍有编辑/删除权限避免“合并时才发现无权”。只激活成功单元activateSuccessfulUnits仅把merged/unchanged的单元转正conflict/failed的保持待处理不阻塞整体。// 状态推进merged → markProcessed删除的 trunk 单元走回收站 if (data.status merged) { /* 逐单元处理 removed / 激活 */ }AI 场景下的“人在环”审批在 AI 插件里Worktree 由单个工具 univer_worktree 驱动action支持create / ready / reopen / merge / discard。工具描述明确写道“Merge and discard require user approval.”合并与废弃需用户审批也就是说AI 只能“准备”合并最终“按下合并按钮”的永远是人——通过tools/pre-execute瀑布钩子强制走人工确认。这就是“人工合并机制”在 Agent 协作中的落点。五、一图看懂整体流程AI/用户 创建 Worktree(draft) │ 在草稿中 submitChangeset隔离改稿 │ markReady → ready进入审阅 │ 双栏对比审阅trunk 基线 vs 草稿 / 合并预览 │ ┌────┴─────────────┐ 人工审批 reopen 继续改 │ merge幂等逐单元激活 │ merged / discarded小结Worktree 把“分支”理念搬进了 Office 协作状态机保证改稿隔离、双栏对比引擎HISTORY/SNAPSHOT 双保真让差异一目了然、幂等合并 人工审批确保高危操作由人拍板。三者配合构成了 Univer Workspace 中人与 AI 安全协作的闭环。 主要源码位置供深入阅读状态机与权限worktrees.types.ts合并/审阅服务worktrees.service.ts对比引擎编排unit-comparison.ts双栏查看器packages/unit-comparison-viewerAI 工具与审批worktree.ts【免费下载链接】univer-workspaceAn open-source Office workspace where people and AI agents create, collaborate, and review together.项目地址: https://gitcode.com/gh_mirrors/un/univer-workspace创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考