GSD 的 Git 策略完全指南：隔离模式、worktree 生命周期与自愈机制

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

GSD（GitHub 加速计划 / gsd-2）是一个面向长时间自主运行的 meta-prompting 与 spec-driven 开发系统，其 Git 策略决定了里程碑（milestone）在仓库中的落地方式：提交如何产生、在哪里产生、何时合并回主线，以及遇到异常如何自愈。本文围绕 docs/user-docs/git-strategy.md 展开，结合src/resources/extensions/gsd/下的真实实现（git-service、worktree-lifecycle、preferences 等），系统讲解git.isolation三种隔离模式、solo/team两种工作流模式、全部 Git 偏好项、手动 worktree 命令、自动 PR、自愈能力与原生 git 操作，帮助你在项目实践中正确配置并理解其底层原理。

一、核心思想：用 Git 做里程碑隔离与顺序提交

GSD 使用 Git 实现里程碑隔离（milestone isolation）与里程碑内顺序提交（sequential commits）。你不需要手动管理分支——整个策略完全自动化：每个里程碑在专属分支上按任务顺序提交，完成后一次性合并回主线。

你可以通过git.isolation偏好项选择一种隔离模式，它决定工作发生在哪里：

三种模式在 git-service.ts 的GitPreferences接口中被定义为isolation?: "worktree" | "branch" | "none"，默认"none"。

1.none模式（默认）

工作直接发生在你当前的分支上：不创建 worktree，不创建里程碑分支。GSD 仍然使用 conventional commit 格式顺序提交，但没有分支层面的隔离。

适用场景：

• 热重载工作流：文件隔离会破坏开发工具链（例如只监听项目根目录的文件监听器）；
• 小项目：分支开销不值得。

从源码看，none模式下 auto-mode 的提交流水线依然完整——git-service.ts 的autoCommit()负责把工作树变更智能暂存并提交，只是所有提交直接落在当前分支。

2.worktree模式

每个里程碑获得一个独立的 git worktree（位于.gsd/worktrees/<MID>/），运行在milestone/<MID>分支上：

1. 所有执行都发生在 worktree 内部；
2. 里程碑完成后，worktree 被squash-merge到主线，作为一个干净的提交；
3. worktree 与分支随后被清理。

这提供了完整的文件隔离——一个里程碑的变更不会干扰你的主工作副本。WorktreeLifecycle类在 worktree-lifecycle.ts 中实现了enterMilestone/exitMilestone：进入时创建/复用 worktree，退出时按opts.merge执行「合并+拆除」或「仅自动提交+拆除」。

重要前提：worktree 模式要求仓库至少有一个提交。如果git.isolation: worktree配置在一个没有任何提交（无 committedHEAD）的仓库中，GSD 会临时以none模式运行以让启动继续；一旦第一个提交存在，同一偏好将解析为worktree。

3.branch模式

工作在项目根目录的milestone/<MID>分支上进行，不创建 worktree。完成后，分支按merge_strategy合并回主线（squash 或普通 merge）。

适用于 worktree 会引发问题的仓库：

• submodule 密集型仓库；
• 有硬编码路径的仓库；
• worktree 符号链接行为异常的环境。

二、分支模型：从里程碑分支到 squash-merge

1. worktree 模式的分支流动

main ───────────────────────────────────────────────────────── │ ↑ └── milestone/M001 (worktree) ────────────────────────┘ commit: feat: core types commit: feat: markdown parser commit: feat: file writer commit: docs: workflow docs ... → squash-merged to main as single commit

branch模式下流程相同，只是工作在项目根目录而非独立 worktree 目录；none模式下提交直接落在当前分支，不创建里程碑分支，也无需合并步骤。

2. 并行 worktree

启用 parallel orchestration 后，多个里程碑可以在独立 worktree 中同时运行：

main ────────────────────────────────────────────────────────── │ ↑ ↑ ├── milestone/M002 (worktree) ─────────┘ │ │ commit: feat: auth types │ │ commit: feat: JWT middleware │ │ → squash-merged first │ │ │ └── milestone/M003 (worktree) ────────────────────────┘ commit: feat: dashboard layout commit: feat: chart components → squash-merged second

每个 worktree 在自己的分支上操作、拥有自己的提交历史；合并按顺序执行以避免冲突。

3. 关键属性

• 单分支顺序提交——不创建 per-slice 分支，里程碑内部不会产生合并冲突；
• squash-merge 回主线——在 worktree 与 branch 模式下，所有提交被压缩为一条干净提交（可通过merge_strategy配置）。

4. 提交格式

提交使用 conventional commit 格式，并在 trailer 中携带 GSD 元数据：

feat: core type definitions GSD-Task: M001/S01/T01 feat: markdown parser for plan files GSD-Task: M001/S01/T02

这条格式由 git-service.ts 的buildTaskCommitMessage()生成：主题是「{type}: {description}」的干净 conventional commit（GSD ID 不进主题），元数据放在正文末尾的GSD-Task:trailer（与Signed-off-by:同一约定）。描述优先取任务摘要的 one-liner（描述实际构建了什么），缺失时回退到任务标题；主题按字节数截断到 72 字节上限。若任务关联了 GitHub issue，还会追加Resolves #Ntrailer。

提交类型由inferCommitType()（git-service.ts）从标题与 one-liner 关键词推断：fix/refactor/docs/test/perf/chore等都有关键词映射（见COMMIT_TYPE_RULES），无匹配时默认feat。若你设置了git.commit_type，则直接覆盖推断结果。

三、Worktree 管理

以下特性仅适用于worktree 模式。

1. 自动管理（Auto Mode）

auto 模式自动创建并管理 worktree：

1. 里程碑开始时，在.gsd/worktrees/<MID>/创建 worktree，分支为milestone/<MID>；
2. 项目根目录的 SQLite 数据库保持为规范运行时状态；artifact/projection 文件在 active worktree 内的.gsd/下渲染，而执行发生在该 worktree 中。SQLite WAL 协调仅限单主机——不要在机器间共享此运行时，协调约束详见src/resources/extensions/gsd/docs/COORDINATION.md；
3. 所有执行都在 worktree 内部进行；
4. 里程碑完成时，worktree squash-merge 到集成分支（integration branch）；
5. worktree 与分支被移除。

其中集成分支的解析顺序（getMainBranch()，git-service.ts）为：显式main_branch偏好（最高优先级）→ 里程碑元数据文件记录的集成分支（auto-mode 启动时写入.gsd/milestones/<MID>/<MID>-META.json）→ worktree 基分支 →origin/HEAD→main/master→ 当前分支。注意writeIntegrationBranch()会拒绝把milestone/、slice、quick-task、workflow-template 分支记录为集成目标，避免合并落到错误分支。

2. 手动管理

独立的 worktree 管理使用/worktree（或/wt）命令：

/worktree create /worktree switch /worktree merge /worktree remove

在活跃的 GSD TUI 会话内，使用/gsd worktree（或/gsd wt）执行可通过会话 UI 汇报结果的 worktree 命令：

/gsd worktree list /gsd worktree merge [name] /gsd worktree clean /gsd worktree remove <name> [--force]

各子命令行为（实现于 commands-worktree.ts）：

• list：显示每个 worktree 的分支、路径、diff 统计、提交数，以及其状态（clean / unmerged / 有未提交变更）；
• merge：把 worktree 合并回检测到的主分支并随后移除；若 worktree 有脏文件，GSD 会尝试在合并前自动提交它们。若主分支未检出，命令会提示先切换到主分支再重试；
• clean：只移除已合并或空的 worktree，保留任何有待处理变更的 worktree；
• remove：除非传入--force，否则拒绝丢弃未合并或未提交的工作（commands-worktree.ts）。

四、工作流模式：solo与team

与其逐项配置每个 git 设置，不如设置mode获得适合你工作流的合理默认值：

mode: solo # personal projects — auto-push, squash, simple IDs mode: team # shared repos — unique IDs, push branches, pre-merge checks

模式默认值优先级最低——任何显式偏好都会覆盖它。例如mode: solo配合git.auto_push: false，你获得 solo 的一切默认值，唯独关闭 auto-push。

模式默认值在 preferences-types.ts 的MODE_DEFAULTS中硬编码，可看到solo.pre_merge_check实际是"auto"、team.pre_merge_check是true。已有的不含mode的配置完全按原样工作——不会注入任何默认值。快速设置方式：/gsd mode（全局）或/gsd mode project（项目级）。

五、Git 偏好项完整参考

在偏好文件中配置 Git 行为：

git: auto_push: false # push after commits push_branches: false # push milestone branch remote: origin snapshots: false # WIP snapshot commits pre_merge_check: false # pre-merge validation commit_type: feat # override commit type prefix main_branch: main # primary branch name commit_docs: true # commit .gsd/ to git isolation: none # "none" (default), "worktree", or "branch" auto_pr: false # create PR on milestone completion pr_target_branch: develop # PR target branch (default: main)

全部字段可选，省略即使用默认值。每个字段的精确语义（与 docs 及 preferences-validation.ts 对照）：

• auto_push（默认false）：提交后是否自动推送到 remote；
• push_branches（默认false）：提交后是否推送里程碑分支到 remote；
• remote（默认"origin"）：推送目标 remote 名称；
• snapshots（默认true）：是否创建 WIP 快照提交（pre-dispatch 快照、doctor 的安全提交gsd snapshot:）。设为false可抑制所有 doctor 发起的 snapshot 提交。注意：快照也可以以refs/gsd/snapshots/<label>/<timestamp>引用形式创建（createSnapshot()），并不总是产生提交；
• pre_merge_check（true/false/"auto"，默认"auto"）：合并 worktree 回集成分支前是否运行预合并检查。true总是运行，false从不运行，"auto"在检测到 CI 时运行。实现上runPreMergeCheck()（git-service.ts）在设为字符串时会直接执行该命令（例如"npm test"），未设置时自动从package.json的 test script 检测；命令经过tokenizePreMergeCommand()词法化后无 shell 执行，含 shell 元字符（;、&&、|、反引号等）的命令会被拒绝，以避免仓库内PREFERENCES.md的提权面（Issue #4980）；
• commit_type：覆盖 conventional commit 类型前缀，合法值限定为feat, fix, refactor, docs, test, chore, perf, ci, build, style，默认从 diff 内容推断；
• main_branch（默认"main"）：新仓库的主分支名；也是getMainBranch()在自动检测歧义时的首选分支；
• merge_strategy（默认"squash"）："squash"把所有提交合并为一条，"merge"保留逐条提交历史；
• isolation（默认"none"）："none"/"worktree"/"branch"，决定 auto-mode 的 git 隔离策略（见上文三种模式）；
• manage_gitignore（默认true）：设为false时 GSD 完全不触碰.gitignore（适合有严格管理的.gitignore的项目）；
• worktree_post_create：worktree 创建后运行的脚本（auto-mode 与手动/worktree均生效），接收SOURCE_DIR与WORKTREE_DIR环境变量，30 秒超时，失败非致命（仅记 warning）；
• auto_pr（默认false）：里程碑分支合并后自动创建 GitHub PR，需要安装ghCLI；
• pr_target_branch：auto_pr启用时的 PR 目标分支，省略时默认主分支；
• absorb_snapshot_commits（默认true）：是否把连续的gsd snapshot:提交吸收进下一条真实提交；设为false保留快照历史供取证；
• collapse_cadence（"milestone"/"slice"）：何时把 worktree 提交折叠回主线。"milestone"（默认）在里程碑完成/切换时 squash-merge 一次；"slice"在每个 slice 通过验证后立即 squash-merge，把孤立窗口从里程碑级缩小到 slice 级，冲突逐 slice 暴露；
• milestone_resquash：collapse_cadence: "slice"时，可选在里程碑结束时把 main 上的逐 slice 提交再压成一条里程碑提交，保持「main 上每个里程碑一条提交」的历史形态（默认true）。

已废弃项：commit_docs与merge_to_main均不再生效——.gsd/始终被外部管理（gitignore 处理），里程碑级合并始终执行。请从配置中移除。

1. 自动 Pull Request

面向使用 Gitflow 或分支式工作流的团队，GSD 可在里程碑完成时自动创建 PR：

git: auto_push: true auto_pr: true pr_target_branch: develop

这会把里程碑分支推送出去，并创建指向develop（或你指定的任意分支）的 PR。需要已安装并认证ghCLI。底层由createDraftPR()（git-service.ts）调用gh pr create --draft实现，失败时非致命（best-effort）。详细说明见 configuration.md。

2. 关于commit_docs: false

该偏好已废弃。当前行为是：.gsd/目录始终被加入.gitignore，规划产物默认留在本地，不会提交到仓库——这与旧版「提交.gsd/到 git」的行为相反。适用于只有部分成员使用 GSD 的团队，或公司要求仓库干净整洁的场景。运行时产物（.gsd/activity/、.gsd/runtime/、.gsd/worktrees/、.gsd/gsd.db*等）由 git-service.ts 的RUNTIME_EXCLUSION_PATHS在智能暂存时通过 pathspec 排除，绝不会进入提交。

六、自愈机制

GSD 内置针对常见 git 问题的自动恢复：

• Detached HEAD——merge 与 worktree 流程会拒绝从 detached 的项目根目录继续，而不是静默切换分支。请先检出预期的集成分支再恢复（相关校验见doctor-git-checks.ts与git-service.ts的集成分支解析）；
• 过期的锁文件——仅当.git/index.lock存在时间超过 5 分钟时才移除，避免打断大仓库上活跃的 git 操作（检测见 auto-start.ts 的index.lock探测）；
• 被中断的 git 操作——恢复流程可在协调 merge 状态前，中止被 kill 的 worker 遗留的 rebase、cherry-pick、revert 状态；
• 不安全的分支重置——worktree 与 branch 模式在设置里程碑分支时，若强制重置会孤立掉无法从起点到达的提交，则拒绝执行（worktree-safety.ts 提供该安全模块）；
• 孤儿 worktree——检测并提议清理被遗弃的 worktree（仅 worktree 模式）。doctor的孤儿审计会区分 doctor 自身写出的 worktree 作用域路径，避免误报（见 doctor-git-checks.ts）。

运行/gsd doctor手动检查 git 健康状态。

七、原生 Git 操作

自 v2.16 起，GSD 在 dispatch 热路径的读密集型操作中使用 libgit2 原生绑定（见 native-git-bridge.ts 中的nativeGetCurrentBranch、nativeDetectMainBranch、nativeHasChanges、nativeCommit等）。这消除了每个 dispatch 周期约70 次 git 进程派生，显著提升 auto-mode 吞吐量。

值得注意的设计细节：smartStage()使用 pathspec 排除运行时路径进行git add -A（而不是先全量暂存再取消暂存），避免在大型未跟踪 artifact 树上的挂死问题；autoCommit()在 pre-commit hook 重写文件导致首次提交失败时会自动重试一次暂存+提交；快照吸收逻辑会先检查快照提交是否已推送（通过merge-base --is-ancestor），已推送则绝不重写历史。

八、快速决策指南

配置始终遵循「显式优先于模式默认值」：先用mode获得合理基线，再按需逐项覆盖，即可在零手动分支管理的前提下，获得适合你工作流的 Git 自动化。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用