# Git Multi Agent > Worktree-first Git automation for every repository task, especially concurrent editing by multiple AI agents. MUST use isolated Git worktrees so each AI has a separate filesystem, index, and HEAD; never use branch switching in a shared checkout as isolation. Automatically provision session worktrees, commit owned changes, validate and merge through a temporary integration worktree, update the local default branch, and clean up. Only remote or cloud writes require fresh user confirmation. - Skill: `xiaobo121388/git-multi-agent` (Agent Skill) - Install (CLI): `npx skillmds@latest add xiaobo121388/git-multi-agent` - Raw SKILL.md: https://api.skillmd.com/api/skills/xiaobo121388/git-multi-agent/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: xiaobo121388 (https://skillmd.com/u/xiaobo121388) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/xiaobo121388/git-multi-agent --- # 多 AI Git 自动化 每次进入工作区或仓库任务时都加载本 Skill，不以用户是否提到 Git 为前提。并行隔离的基本单位是 **worktree**：每个 AI 会话拥有独立目录、索引和 HEAD，任何开发读写、测试和提交都只在自己的 worktree 中进行。分支只是 worktree 必需的内部提交引用，不得用“在共享目录里切换分支”代替隔离。 ## 强制触发与收尾 - 每个工作区任务开始时都加载本 Skill；SessionStart Hook 在 Git 仓库中自动创建本会话 worktree，并注入其精确绝对路径。 - 加载本 Skill 表示用户已持续明确授权任务范围内的本地 worktree、内部引用、暂存、commit、本地集成和安全清理；不需要再次询问。该授权不适用于任何远端或云端写入。 - 只读分析、答疑或未产生文件变化的任务不修改 Git，但仍遵守本 Skill 的归属与远端安全规则。 - 首次仓库读写前确认当前操作路径就是 Hook 注入的会话 worktree。所有搜索、读取、编辑、生成、测试和 Git 命令都以该目录为根；原项目目录只作为默认分支的集成入口。 - 任务完成且验证通过后，在会话 worktree 内显式暂存 `owned-paths` 并创建本地 commit，再通过一次性集成 worktree 合入本地默认分支。 - 合并成功后自动清理本会话任务 worktree、集成 worktree及其内部引用，不把用户留在临时目录或 `ai/...` 引用上。 - 只有三种情况不自动提交：用户明确要求本次不要提交；没有本会话文件变化；验证失败或变更归属无法安全确定。此时保留现场并说明原因。 - 目标分支无法唯一确定、默认分支 worktree 不干净、发生冲突、组合验证失败或默认分支在验证期间前进时，不强行更新；保留本会话 worktree并报告或重建集成 worktree重试。 - `commit` 成功不代表任务完成。除非存在明确阻塞，否则发送最终答复前必须确认任务提交可从默认分支到达，且本会话 worktree 已清理。 - 不得把“是否需要本地提交”作为例行问题询问用户。真正无法自动判断的变更归属或冲突属于阻塞，可请求用户决定，但不能先猜测或破坏现有改动。 ## 核心规则 1. **worktree 是隔离边界。** 每个 AI 会话必须使用不同的已注册 worktree；多个 AI 不得编辑同一个目录，即使它们声称负责不同文件。 2. **分支不是工作空间。** 内部 `ai/...` 引用只承载 worktree 的提交历史；禁止在原项目目录中通过 `switch`/`checkout` 来轮换 AI 任务。 3. **只操作本会话目录。** 只提交本会话 worktree 中由本会话产生的路径；始终显式暂存，禁止 `git add .`、`git add -A` 和 `git commit -a`。 4. **默认分支目录是集成通道。** 不在其中开发；只在组合结果已于集成 worktree 验证后执行短暂的 `ff-only` 更新。 5. **不接管既有改动。** 不 stash、不还原、不覆盖、不删除用户或其他 AI 的未提交内容和 worktree。 6. **提交前验证。** 在任务 worktree 验证单项行为；在集成 worktree 再验证组合结果。 7. **本地操作自动，云端操作确认。** worktree、内部引用、commit、merge 和安全清理无需确认；任何 `push`、远端引用、PR/MR 或 release 写入必须逐次确认。 8. **保留会话归属。** 沿用仓库 Git 身份，并用 commit trailer 记录 AI 会话；不修改全局身份配置。 ## 操作分类 无需额外确认，但只能在用户请求所涵盖的仓库和任务内执行： - 为每个 AI 会话创建、使用并清理独立 worktree - 在本会话 worktree 内检查、暂存、提交和验证改动 - 查看状态、日志、diff、分支、worktree 和远端配置 - 创建一次性集成 worktree，合并并验证组合结果 - 将已验证的集成结果快进到本地默认分支 - 删除已安全集成且干净的本会话 worktree 和内部引用 - `fetch` 远端引用；优先用 `fetch` 加显式 merge/rebase，避免隐式 `pull` ## 提交信息规范 - 默认使用 Conventional Commits 结构：`: `。 - `type` 必须使用英文小写前缀，例如：`feat`、`fix`、`refactor`、`perf`、`docs`、`test`、`build`、`ci`、`chore`、`revert`。 - `subject` 使用中文，简洁描述本次改动结果，不写英文长句。 - 若仓库已有更严格约定（如作用域、长度、Issue 关联），在不冲突前提下优先遵循仓库约定。 - 可选作用域时使用：`(): <中文 subject>`，其中 `scope` 保持英文标识。 必须在执行前单独确认的云端写操作： - `git push`，包括新分支、现有分支和标签 - `git push --delete`、删除远端标签或分支 - 任何 force push；默认禁用 `--force`，只有用户明确批准时才可使用 `--force-with-lease` - 创建、更新、关闭或合并 PR/MR - 创建 release 或通过托管平台 API/CLI 改写远端状态 确认只适用于展示过的精确远端、源引用、目标引用和命令。命令或提交发生变化后必须重新确认；“以后都可以”“帮我全自动”不能永久豁免云端确认。 ## 标识约定 首次进入任务时生成并报告： - `agent-id`：稳定的代理名，例如 `copilot` - `session-id`：优先使用 SessionStart Hook 注入的 `Git session token`；Hook 不可用时回退为 `-` - 项目分类目录：`D:\Documents\git_worktrees\`，其中 `` 取默认主 worktree 的目录名 - 任务 worktree：`D:\Documents\git_worktrees\\` - 任务内部引用：`ai//` - 集成 worktree：`D:\Documents\git_worktrees\\-integrate` - 集成内部引用：`ai/integrate/` 名称只使用小写 ASCII 字母、数字和连字符。只复用 Hook 明确分配给当前 `session-id` 的 worktree；上一会话或其他 AI 的 worktree 即使目录可见也不得使用。 每个 AI 提交追加 trailer： ```text AI-Agent: AI-Session: AI-Branch: ``` 优先使用 `git commit --trailer` 添加 trailer。若当前 Git 不支持该参数，再使用仓库兼容的提交消息方式；不要为了 trailer 修改全局 Git 配置。 ## 工作流 ### 1. 预检仓库 先运行并阅读： ```powershell git rev-parse --show-toplevel git status --short --branch git branch --show-current git worktree list --porcelain git remote -v git symbolic-ref --quiet --short refs/remotes/origin/HEAD git log -5 --pretty=format:"%h %s" ``` 然后判断： - 不是 Git 仓库：只有用户已要求初始化时才执行 `git init`，否则说明阻塞。 - HEAD detached：从当前 HEAD 创建本会话分支后再修改。 - 存在未提交改动：将其视为他人所有，不 stash、不重置、不纳入提交。 - 存在未合并状态、rebase、cherry-pick、revert 或 index lock：停止自动操作，先报告当前操作，不擅自继续或中止。 - 仓库没有首个提交：可在当前工作树内创建本会话分支并显式提交；多 worktree 隔离通常要等首个提交后再启用。 - 记录任务起始提交、起始分支和默认主分支，供完成后的安全回并与并发移动检查使用。 - 在创建任务分支前先按“自动回并默认主分支”的优先级确定本地目标分支；任务基线使用该目标分支 tip，不使用当前恰好检出的旧 AI/feature 分支 HEAD。 读取仓库内适用的贡献说明和 Git 约定。只检查与当前任务直接相关的文件，不把预检扩大成全仓审计。 ### 2. 建立会话 worktree 在 Git 仓库中，每个会话都使用独立 worktree，不等待检测到第二个 AI。SessionStart Hook 默认执行等价操作： ```powershell git worktree add -b ai// "D:\Documents\git_worktrees\\" ``` 创建基线必须是任务开始时识别出的默认主分支 tip，不得从当前恰好打开的 feature/旧 AI 引用派生。创建后验证： ```powershell git -C "" status --short --branch git worktree list --porcelain ``` - 后续所有仓库搜索、读取、编辑、生成、测试和 Git 命令必须使用 `` 的绝对路径或将终端 cwd 切到该目录。 - 禁止继续编辑原项目目录，也禁止编辑 `git worktree list` 中属于其他会话的路径。 - PreToolUse Hook 会拒绝写入本会话 worktree 之外的同仓库路径。 - 每个终端命令都显式锚定会话 worktree，例如先执行 `Set-Location -LiteralPath ''`；不要依赖终端上一条命令遗留的 cwd。 - 若工具无法对该绝对路径工作，报告阻塞并停止编辑；不得退回共享目录。 非 Git 目录不创建 worktree，也不自动执行 Git 操作。 ### 3. 记录本会话路径 在工作过程中维护明确的 `owned-paths` 清单：只加入本会话 worktree 内由本会话实际创建、修改、移动或删除的路径。 以下情况不能自动认领： - 会话 worktree 创建前已存在的来源不明内容 - 会话 worktree 外部的任何路径 - 工具未曾编辑但随后出现在 status 中的路径 - 生成器顺带改动且尚未检查内容的路径 格式化器或生成器修改多个文件后，逐个检查 diff，只有确属本任务且内容合理的文件才能加入清单。出现来源不明的改动时保留现场并报告，不做清理。 ### 4. 选择提交时机 只要任务产生 `owned-paths` 且验证通过，就必须在最终答复前自动创建本地提交，不等待用户提出 Git 要求，也不请求本地提交确认。以下时机还可创建中间阶段提交： - 一个可独立回滚的逻辑阶段完成，下一阶段会明显扩大改动范围 - 执行本地 rebase、merge、cherry-pick 或分支清理前需要稳定检查点 - 用户明确要求 checkpoint 或 commit 不要为每次文件保存制造提交，也不要把互不相关的改动塞入同一提交。若任务未完成、验证失败或归属不明，保留本地改动并报告，不创建伪装成完成状态的提交。用户明确要求本次不要提交时服从该要求。 ### 5. 提交前检查 按顺序执行： 1. 运行任务范围内最小且有效的测试、lint、类型检查或构建。 2. 用 `git diff --check -- ` 检查空白错误。 3. 查看 `git diff --stat -- ` 和完整 `git diff -- `。 4. 检查 `git status --short`，识别 owned-paths 之外的变化。 5. 检查 staged 区；若已有非本会话 staged 内容，停止，不改动其 staged 状态。 6. 检查 owned-paths 中是否含密钥、令牌、`.env`、凭据、私钥、大型二进制或意外生成物。 测试命令可能产生新的文件。提交前重新检查 status，不自动把测试产物纳入提交。 ### 6. 显式暂存并提交 仅暂存 owned-paths： ```powershell git add -- git diff --cached --name-status git diff --cached ``` 暂存后必须确认 cached 路径集合是 owned-paths 的子集。发现额外路径时停止提交并报告，不通过 reset/restore 擅自改写他人的暂存区。 提交主题遵循仓库最近历史和贡献规范，描述一个具体结果。示例： ```powershell git commit -m "feat: 新增多 AI 并行分支隔离流程" --trailer "AI-Agent: " --trailer "AI-Session: " --trailer "AI-Branch: " ``` 提交后立即验证： ```powershell git show --stat --oneline --decorate HEAD git status --short --branch ``` 报告 commit hash、主题、分支、worktree、包含的路径、验证命令与结果，以及尚未提交且不属于本会话的改动。 ### 7. 通过集成 worktree 回并 任务 worktree 完成提交后，使用一次性集成 worktree 构造组合结果。不要直接在原项目目录中解决冲突或运行合并后的修改。 这是任务的强制完成阶段，不是可选建议。除非回并条件明确阻塞，否则不得在创建 commit 后直接结束，也不得把“请用户稍后自行合并”作为正常完成结果。 按以下优先级确定目标分支： 1. 用户为本任务明确指定的本地目标分支。 2. 默认远端 HEAD 指向的本地分支，例如将 `origin/main` 解析为 `main`。 3. 仓库中唯一存在的常见默认分支：`main`、`master` 或 `trunk`。 无法唯一确定时停止回并，不猜测目标。任务分支本身就是目标分支，或任务提交已经可从目标分支到达时，不重复合并。 创建集成 worktree 前确认任务 worktree已提交、单项验证通过且干净。记录当前目标 tip 为 `integration-base`，然后执行： ```powershell git worktree add -b ai/integrate/ "D:\Documents\git_worktrees\\-integrate" git -C "" merge --no-ff --no-commit ai// ``` 若 Git 报 `Already up to date`，无需创建 merge commit。否则在集成 worktree 解决仅属于本任务的明确冲突，并运行覆盖组合结果的测试、lint、类型检查或构建；验证通过后创建 `chore: 合并本次 AI 任务到默认分支`，并追加本会话 trailer。随后： 1. 确认默认分支仍等于 `integration-base`，且承载默认分支的 worktree 干净、无进行中的 Git 操作。 2. 在默认分支 worktree执行 `git merge --ff-only ai/integrate/`。该步骤只发布已经验证的提交，不在此目录开发或解冲突。 3. 若默认分支已被其他 AI 推进，删除并重建本会话集成 worktree，从新的目标 tip 重新合并和验证；不得跳过组合验证。 4. 验证 `git merge-base --is-ancestor ai// ` 成功，才算回并完成。 并行 AI 可以同时在各自任务 worktree 开发，也可以在各自集成 worktree 预合并；默认分支的最终快进天然串行。先完成的会话推进默认分支后，其他会话必须基于新 tip 重建集成结果。 Stop Hook 会检查当前会话 worktree 对应提交是否已从默认分支可达。未回并或仍有未提交内容时阻止一次结束；已回并且 worktree 干净时，Hook 自动移除本会话任务/集成 worktree和内部引用。 ### 8. 集成其他 AI 分支 每个 AI worktree按上一节独立集成；只有用户明确要求批量收尾时，才接管其他会话留下的 worktree。不得在某个 AI 的任务 worktree 中直接合并另一个 AI 的未完成内容。 1. 用 `git worktree list --porcelain` 列出候选会话目录和内部引用。 2. 只选择工作树干净、提交完整、`AI-Session` trailer 可核对的会话。 3. 每个会话仍单独创建集成 worktree，并按顺序合入最新默认分支。 4. 每次默认分支推进后，后续会话都从新 tip 构造和验证，不复用过期集成结果。 5. 冲突或验证失败时保留对应会话 worktree，不影响其他 AI 继续开发。 不要仅凭“最新提交”判断归属；使用分支名、worktree、owned-paths、commit hash 和 trailer 交叉确认。不要 squash 掉会话归属，除非用户明确要求压缩历史，并在新提交正文中保留来源 commit hash。 ### 9. 云端写入确认门 准备执行远端写操作时，先展示： ```text 远端： 本地源： @ 远端目标： 操作：<完整命令或等价 API 动作> 风险：<新建 / 更新 / 删除 / force-with-lease / 合并 PR> 验证：<已运行的检查及结果> ``` 然后提出可明确回答“确认执行”或“取消”的问题。未得到明确肯定答复前不得执行；沉默、模糊同意、先前对其他命令的同意都不算确认。 推送前再次确认本地 HEAD 未变化。若 hash、remote、目标 ref 或命令变化，原确认失效。禁止默认使用 `--all`、`--mirror`、`--tags` 或通配 refspec。凭据、令牌和密码只能由用户直接输入安全提示，不通过聊天收集。 ### 10. 安全清理 仅清理本会话创建的资源。删除 worktree 前确认： - 工作树干净 - 所有本会话提交均已从默认分支可达 - 本会话提交已可从默认主分支或用户指定目标分支到达 - 没有 rebase、merge、cherry-pick 或测试进程占用 优先删除集成 worktree，再删除任务 worktree，最后用 `git branch -d` 删除对应内部引用。不得使用 `--force` 或 `-D`，不得删除其他会话的 worktree。Hook 可在 Stop 阶段自动清理已回并且干净的本会话资源；清理失败时报告路径并保留现场。远端清理仍需新的云端写入确认。 ## 冲突与异常分支 - **原项目目录已有脏文件：** 不触碰；任务开发仍可在独立 worktree进行，但最终更新默认分支前必须等待该目录恢复干净。 - **会话 worktree创建失败：** 不在共享目录降级编辑；报告路径、引用和 Git 错误。 - **写入路径不在本会话 worktree：** PreToolUse Hook 拒绝操作；改用 Hook 注入的绝对路径。 - **别的 AI 改了本会话 worktree：** 来源无法证明时停止；保留 worktree并报告。 - **提交钩子修改文件或拒绝提交：** 检查钩子输出与新 diff，验证后重新显式暂存；不使用 `--no-verify` 绕过。 - **测试失败：** 保留改动和输出，不创建完成提交；只修复当前任务引起的失败。 - **集成冲突或组合验证失败：** 只处理/中止本会话集成 worktree中的 merge；默认分支不受影响，任务 worktree保留。 - **默认分支在验证期间前进：** 丢弃本会话过期的集成 worktree，基于新 tip 重建并重新验证。 - **默认分支 worktree不干净：** 不 stash、不覆盖、不强行切换；保留已验证任务 worktree并报告阻塞路径。 - **需要 force push：** 优先改用新分支；确实必要时说明原因和 lease 保护，并为该精确命令单独确认。 - **用户要求提交所有改动：** 先逐项展示来源；只有用户明确把现有改动转交给本会话后，才能加入 owned-paths。 - **用户要求自动推送：** 可以自动准备和验证，但每一次实际云端写入仍必须停在确认门。 ## 完成标准 任务结束前必须能回答： - 本会话 ID、任务 worktree、集成 worktree和内部引用是什么 - 哪些路径由本会话拥有，提交中是否只包含这些路径 - 创建了哪些 commit，hash 和主题是什么 - 本会话提交是否已通过集成 worktree进入本地默认主分支 - 运行了哪些验证，结果如何 - 还存在哪些未提交或来源不明的改动 - 是否执行过云端写入，以及对应的用户确认是哪一次 - 集成或清理是否完成，保留分支在哪里 最终交接使用简洁格式： ```text 会话： 任务 worktree：（内部引用：） 集成 worktree： / 已清理 提交： 回并： -> -> @ / 未回并及原因 改动： 验证： -> 遗留：<未提交/冲突/来源不明内容，或“无”> 远端：未写入 / 已按本次确认推送到 ```