multi-agent-vcs

用途

Multi-Agent Version Control 是一套工具无关（tool-agnostic）的模式，用于在并行 AI 智能体之间协调 Git 操作。它适用于以下场景：派发子智能体进行并行工作、规划多分支实现、从并行智能体造成的 Git 损坏中恢复，以及任何多个智能体同时触碰文件系统的工作流。

要解决的问题

当并行的子智能体各自独立执行 Git 操作时，会出现一系列问题：

内容混杂：多个功能被写进错误的分支。
堆栈断裂：分支本应是父子关系，却变成了兄弟关系。
PR 标签错误：PR 标题与分支内容不匹配。
需要数小时恢复：必须人工介入才能修复结构。

产生这些问题的原因是：每个智能体看到相同的起始状态，并各自独立创建分支，结果生成的是兄弟分支，而不是正确的堆栈结构。

核心策略

子智能体不得执行 Git 操作。只有编排者（orchestrator）负责 Git 状态管理。子智能体只把代码写入文件系统，然后报告完成情况。

必须做到：

编排者在派发子智能体之前创建分支
子智能体只写入文件系统
子智能体报告其创建/修改了哪些文件
编排者负责暂存（stage）、提交（commit）和推送（push）

绝对禁止：

子智能体提交、推送或创建分支
来自不同智能体的并行 Git 操作
后台智能体管理分支状态

正确的工作流

流程分为两个阶段。第一阶段由编排者（主智能体）管理 Git 状态、分支和提交，并派发子智能体，子智能体只负责写代码：

subagent-1 写 feature-a.ts → 仅文件系统
subagent-2 写 feature-b.ts → 仅文件系统
subagent-3 写 feature-c.ts → 仅文件系统

第二阶段由编排者收集结果并提交：

暂存 feature-a.ts → 提交到 branch-a
暂存 feature-b.ts → 提交到 branch-b
暂存 feature-c.ts → 提交到 branch-c

子智能体提示模板

在派发并行工作时，把以下内容加入子智能体的提示中：

IMPORTANT: Do NOT perform any git operations (commit, push, branch creation). Write code to the filesystem only. The orchestrator handles all git state. Report which files you created/modified when done.

任务清单集成

在任务列表中显式跟踪 Git 操作，用 ORCHESTRATOR: 前缀标明哪些任务涉及 Git 操作：

Stage: Parallel Implementation

[ ] [engineer] Implement config module (filesystem only)
[ ] [engineer] Implement logging module (filesystem only)
[ ] [engineer] Implement state module (filesystem only)
[ ] ORCHESTRATOR: Stage and commit implementations
- Stage config/ → commit to feature/config
- Stage logging/ → commit to feature/logging
- Stage state/ → commit to feature/state

Graphite 专用命令

当使用 Graphite 管理堆叠 PR 时，所有 Git 操作由编排者处理。子智能体完成后，编排者逐个分支提交：

For feature/config branch

gt checkout feature/config git add packages/config/ gt modify -am "feat(config): implement module"

For feature/logging branch

gt checkout feature/logging git add packages/logging/ gt modify -am "feat(logging): implement module"

Alternative: Use absorb from top of stack

Graphite routes staged files to the branch that owns them

gt top git add . gt absorb

Restack and submit

gt restack gt submit --stack

完整的 Graphite 工作流请参见 graphite-stacks。

GitButler 专用命令

当使用 GitButler 虚拟分支时：

Subagents write files, orchestrator assigns to virtual branches

but branch create feature-a but branch create feature-b

Move files to appropriate branches

but move path/to/file.ts --to feature-a but move path/to/other.ts --to feature-b

Commit within each branch

but commit feature-a -m "feat: implement feature-a" but commit feature-b -m "feat: implement feature-b"

恢复流程

当并行智能体破坏了 Git 状态时：

停止所有智能体——防止进一步破坏
评估破坏程度——检查分支结构（gt status 或 git log --graph）
暂存工作——保存未提交的更改
修复关系——把分支移到正确的父分支下
重新分配文件——把文件提交到正确的分支
验证——检查结构是否符合预期

Graphite 专用的恢复方法请参见 recovery.md。

顺序执行与并行执行

不同模式下的 Git 处理方式不同：

顺序（Sequential）：适用于有依赖的任务，每个智能体可以提交（交接式）。
并行（Parallel）：适用于独立任务，仅由编排者提交。
后台（Background）：即发即忘，永不提交。

顺序执行的智能体可以安全提交，因为它们显式交接状态；并行执行的智能体不能，因为它们看不到彼此的更改。

执行保障

目前该策略依赖显式指令来落实。在以下情况始终包含 Git 策略：派发并行子智能体、使用后台智能体、协调多分支工作。未来可能通过基于钩子（hook）的执行机制拦截并阻止来自子智能体上下文的 Git 操作。

技能介绍

用途