GSD-2 的 Git 与 Worktree 配置全解：隔离模式、Collapse Cadence 与自动化提交策略

人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载GSD-2GitHub 加速计划 / gsd-2是一套面向长时间自主运行的 spec-driven 开发系统它用 git 作为里程碑milestone隔离与顺序提交的载体。本文以官方配置文档 Git Worktrees 为骨架结合仓库内源码实现git-service.ts、slice-cadence.ts与偏好参考preferences-reference.md系统讲解三种隔离模式的取舍、全部git.*偏好项的语义、slice 粒度合并节奏以及 git 自愈机制让你能够在项目中按需配置、彻底理解 GSD 的提交与合并行为。为什么 GSD 需要一套自动化 git 策略GSD 的定位是让 Agent 长时间自主完成多个里程碑。里程碑之间存在明显的工作边界若直接在主分支上连续开发不同里程碑的改动会互相污染、历史无法回溯。因此 GSD 把「隔离」与「合并」做成了完全自动化的策略——你不需要手动建分支、切分支或 rebase只要通过偏好文件声明隔离模式与合并节奏GSD 会在里程碑生命周期内自动完成 worktree 创建、分支管理、squash 合并与清理。策略的核心可配置项全部收敛在git.isolation与git.collapse_cadence两个开关上其余参数负责细化推送到远程、PR、提交信息等行为。配置文件的完整字段语义见 preferences-reference.md 的git一节而每个字段的取值校验逻辑位于 preferences-validation.ts下面逐一展开。三种隔离模式git.isolationgit.isolation决定 Agent 执行工作时把文件写到哪里、把提交落在哪条分支上支持三个取值模式工作目录分支适用场景none默认项目根目录当前分支大多数项目——无隔离开销worktree.gsd/worktrees/MID/milestone/MID需要完全隔离的项目branch项目根目录milestone/MIDsubmodule 较多的仓库None 模式默认工作直接发生在你当前所在的分支上不创建 worktree、不创建里程碑分支。GSD 仍然按 conventional commit 格式提交。当文件隔离会破坏开发工具链文件监听器、热重载等时使用此模式。它的代价是没有隔离不同里程碑的改动直接落在同一分支上。Worktree 模式每个里程碑获得独立的 git worktree 与独立分支所有执行都发生在 worktree 内。里程碑完成后全部提交被 squash 合并为一条干净的提交回到 main随后 worktree 与分支被清理。该模式下一个里程碑的改动不会干扰你的主工作副本。有两个实现细节值得注意worktree 模式要求仓库至少存在一次提交。如果git.isolation: worktree配置在一个尚无HEAD的零提交仓库上GSD 会暂时降级按none运行直到首次提交存在。这一点在 preferences-reference.md 的git.isolation条目中也有明确说明。自动模式与手动模式的 worktree 分支命名不同。自动模式auto-mode创建的 worktree 使用milestone/MID分支而手动/worktree命令使用worktree/name分支两者的生命周期管理代码分开维护见 auto-worktree.ts 顶部的注释说明。Branch 模式工作在项目根目录、但提交落在milestone/MID分支上不创建 worktree 目录。当 worktree 在 submodule 或硬编码路径下引发问题时用它替代 worktree 模式。从源码看branch模式的价值在于那些「git 版本足够、但 worktree 语义会带来副作用」的仓库——submodule 的gitdir指针与相对路径在 worktree 中容易错位而 branch 模式始终在根目录操作规避了这类问题。分支模型worktree 模式的典型提交流如下main ──────────────────────────────────────────── │ ↑ └── milestone/M001 (worktree) ─────────────┘ commit: feat: core types commit: feat: markdown parser commit: feat: file writer → squash-merged to main关键点在于「集成分支」并不总叫main。从 git-service.ts 的getMainBranch()源码可以看出集成分支的解析顺序是显式配置的git.main_branch优先级最高里程碑启动时记录在.gsd/milestones/MID/MID-META.json里的 integration branchauto-mode 启动时通过writeIntegrationBranch()持久化worktree 基分支worktree/nameorigin/HEAD符号引用 →main/master回退 → 当前分支。这意味着如果用户在某条功能分支如f-123-new-thing上启动 GSD所有 slice 分支都会合并回该分支而非仓库默认分支。writeIntegrationBranch()还会主动拒绝把milestone/、slice 分支、quick-task 分支和 workflow 模板分支hotfix、bugfix、spike 等记录为集成目标防止合并落到错误分支上对应源码注释中的 #1293、#2498。Workflow 模式solo 与 team与其逐个配置mode提供了一套「合理默认值」mode: solo # 个人项目 mode: team # 共享仓库设置项soloteamgit.auto_pushtruefalsegit.push_branchesfalsetruegit.pre_merge_checkfalsetrueunique_milestone_idsfalsetrue源码 preferences-reference.md 补充了更完整的 mode 默认矩阵除了上表还包含git.merge_strategy: squash与git.isolation: none两种 mode 相同。mode 默认值优先级最低——任何显式偏好都会覆盖它。例如团队模式但想自己推送mode: team git: auto_push: true快速设置命令为/gsd mode全局与/gsd mode project项目级。Git 偏好完整参考以下是最全的git:偏好块所有字段都可省略省略即用默认值git: auto_push: false # push after commits push_branches: false # push milestone branch to remote remote: origin # git remote name snapshots: true # WIP snapshot commits during long tasks pre_merge_check: auto # validation before merge commit_type: feat # override conventional commit prefix main_branch: main # primary branch name merge_strategy: squash # squash or merge isolation: none # none (default), worktree, or branch commit_docs: true # commit .gsd/ artifacts to git manage_gitignore: true # let GSD manage .gitignore auto_pr: false # create PR on milestone completion pr_target_branch: develop # PR target branch collapse_cadence: milestone # milestone (default) or slice milestone_resquash: true # re-squash slice commits at milestone end (cadenceslice)逐字段语义结合 git-service.ts 的GitPreferences接口与偏好参考auto_push提交后自动推送到远程。默认false。push_branches提交后把里程碑分支推送到远程。默认false。启用auto_pr时要求它与已配置的 remote 同时成立。remote要推送的远程名。默认origin。snapshots长任务期间的 WIP 快照提交。从源码看createSnapshot()并非创建普通 commit而是写入refs/gsd/snapshots/label/timestamp引用指向当前 HEADgit-service.ts用于在破坏性操作前记录恢复点doctor 也会生成gsd snapshot:提交。设为false可抑制所有 doctor 发起的快照提交。pre_merge_check合并 worktree 回集成分支前是否运行校验。true总是运行、false从不运行、auto默认在检测到 CI 时运行。源码runPreMergeCheck()git-service.ts的行为是字符串时把它当作自定义命令执行auto时读取package.json若存在scripts.test则运行npm test否则跳过。⚠️ 安全细节该命令会经过 tokenizePreMergeCommand() 分词并以execFileSync无 shell 执行若命令串里含;、、|、反引号等未加引号的 shell 元字符会被直接拒绝Issue #4980 HIGH-2——复杂命令请放进脚本文件再引用脚本路径。commit_type覆盖 conventional commit 前缀合法值限定为feat, fix, refactor, docs, test, chore, perf, ci, build, style校验见 preferences-validation.ts。未设置时由 diff 内容自动推断源码inferCommitType()内置了关键词规则表fix/bug/hotfix→fixrefactor/restructure→refactordocs/readme/changelog→docstest/spec/coverage→testperf/optimize/cache→perfcleanup/deps/bump/config/ci→chore无命中默认feat。main_branch主分支名用于新 git 仓库初始分支也是getMainBranch()歧义时的首选。默认main。merge_strategysquash把所有提交合并为一条merge保留各提交。默认squash。isolation上文已述。commit_docs⚠️已弃用。该字段如今不再生效.gsd/始终由外部管理并被 gitignore见下文「保持.gsd/本地化」。preferences-validation.ts 对设置它的配置会输出 deprecation warning建议直接移除。同类的还有已弃用的merge_to_main。manage_gitignore为false时 GSD 完全不动.gitignore不添加基线模式、不做自愈适用于.gitignore被严格管理的项目。默认true。auto_pr里程碑完成后自动创建 GitHub PR默认false。需要ghCLI 已安装并完成认证。从源码看实际调用gh pr create --draft创建草稿PRcreateDraftPR()失败时静默返回nullbest-effort不阻断流程。pr_target_branchPR 的目标分支省略时默认回退到main_branch。collapse_cadence/milestone_resquash见下一节。worktree_post_createworktree 创建后执行的脚本见「Post-Worktree Hook」一节。Collapse Cadence何时把工作合并回 maingit.collapse_cadence控制里程碑分支上的工作何时被 squash 合并回 main取值main 何时更新孤儿窗口最佳适用milestone默认里程碑完成时一次整个里程碑小里程碑、干净的 PR 历史slice每个 slice 通过校验时一个 slice大里程碑、长时会话、并行工作Slice Cadence当collapse_cadence: slice时每个 slice 的提交一旦通过校验就立即 squash 合并回 main随后里程碑分支被 fast-forward 到 main使下一个 slice 从干净基线开始。源码 mergeSliceToMain() 的实现要点合并前拒绝脏 main——项目根存在未提交改动时直接抛错v1 不做自动 stashfail loudly如果里程碑分支没有领先 main 的提交返回skipped: true而不是静默 no-op避免污染遥测里的slicesMerged计数与冲突率分母合并提交信息带 slice 与里程碑上下文例如feat: Core API - S01 of M001 (slice-cadence)正文含Slice:、Milestone:、GSD-Slice:、GSD-Milestone:trailer对应测试 slice-cadence.test.ts 的断言集成分支解析支持 milestone 元数据里记录的 integration branch测试覆盖了合并到develop的场景。这套行为有完整的自动化测试保障src/resources/extensions/gsd/tests/slice-cadence.test.ts覆盖了「单 slice squash 分支前进」「worktree 中检出里程碑分支时的前进」「连续多 slice 顺序合并」「无领先提交时跳过」以及 resquash 的多个分支。优点更短的孤儿窗口——会话被打断时只有当前 slice 的工作处于风险中而不是整个里程碑增量式冲突——合并冲突按 slice 逐个暴露而不是在里程碑结束时一次性爆发对并行友好——多个里程碑可以安全地把通过校验的 slice 合并回 main无需等待最慢的那个。代价不做 re-squash 的话main 上每个里程碑会积累 N 条提交每 slice 一条而非一条。git: collapse_cadence: sliceMilestone Re-squash当collapse_cadence: slice且milestone_resquash: truecadence 为 slice 时默认开启时GSD 会在里程碑完成时把 main 上的逐 slice 提交折叠成一条里程碑提交。main 的历史形态与collapse_cadence: milestone完全一致——每个里程碑一条提交——但保留了 slice cadence 的孤儿窗口与增量冲突优势。源码 resquashMilestoneOnMain() 的策略是把 main soft-reset 到该里程碑首次 slice 合并前的startSha再一次性提交净变更。它带有fail-closed 守卫会校验startSha..HEAD区间内是否只包含该里程碑的 slice-cadence 提交提交信息须以(slice-cadence)结尾且包含of MID一旦发现并发工作、cherry-pick 或 hotfix 混入foreign 提交就跳过 resquash 并告警绝不盲目重写他人提交的归属。设置milestone_resquash: false可保留 main 上的逐 slice 提交适合需要 bisect 粒度、按 slice 回滚等场景git: collapse_cadence: slice milestone_resquash: false # keep slice commits in main history如何选择**默认milestone**对大多数项目已足够每个里程碑在 main 上产生一条提交。**slice**在里程碑有 5 个以上 slice、墙钟时间较长或遭遇过会话中断导致的孤儿问题时才值得启用。会话结束后运行/gsd forensics查看孤儿检测与合并遥测——其中的Worktree Telemetry区块会报告工作有多少次被搁浅orphansDetected、slicesMerged等统计来自 worktree-telemetry.ts据此判断 slice cadence 是否有帮助。自动 Pull Request对于使用 Gitflow 或分支式工作流的团队git: auto_push: true auto_pr: true pr_target_branch: develop里程碑完成时GSD 会推送分支并创建指向指定分支的 PR。前置条件是ghCLI 已安装并认证且按GitPreferences注释启用了push_branches与已配置 remote。实现上是gh pr create --draft失败不阻断里程碑完成。Post-Worktree Hookworktree 创建后运行一个脚本例如复制.env文件、符号链接资源git: worktree_post_create: .gsd/hooks/post-worktree-create示例 hook#!/bin/bash cp $SOURCE_DIR/.env $WORKTREE_DIR/.env ln -sf $SOURCE_DIR/assets $WORKTREE_DIR/assets实现细节来自 preferences-reference.md 的git.worktree_post_create条目脚本在自动模式与手动/worktree创建后都会运行接收SOURCE_DIR与WORKTREE_DIR两个环境变量路径可以是绝对路径或相对项目根带30 秒超时失败非致命仅记 warning。这一行为在 auto-worktree.ts 的 worktree 创建流程中被调用。保持.gsd/本地化对于只有部分成员使用 GSD 的团队旧版做法是git: commit_docs: false把.gsd/整体加入.gitignore从而在不影响不使用 GSD 的同事的前提下获得结构化规划能力。请注意当前版本中commit_docs已弃用.gsd/始终被外部管理并 gitignore见 preferences-validation.ts 的 deprecation warning因此该需求如今是默认行为无需配置。运行时路径.gsd/activity/、.gsd/runtime/、.gsd/worktrees/、.gsd/auto.lock、gsd.db*等的完整排除清单见 git-service.ts 的RUNTIME_EXCLUSION_PATHSsmart staging 用 pathspec 排除这些路径以避免大仓库上git add -A再 unstage 导致的卡死。Commit 格式提交采用带 GSD 元数据的 conventional commit 格式feat: core type definitions GSD-Task: M001/S01/T01生成逻辑在 buildTaskCommitMessage()主题为{type}: {description}description 优先取任务摘要 one-liner描述实际构建内容回退到任务标题描述计划内容主题按 UTF-8 字节数截断到 72 字节上限保证兼容性。GSD-Task:以 git trailer 形式放在正文末尾与Signed-off-by:、Co-Authored-By:同一约定正文还会包含最多 8 个关键文件清单、GSD context:下的 Milestone/Slice/Task 上下文行以及可选的Resolves #N关联 GitHub issue 时追加。手动 Worktree 管理在不使用 GSD 自动模式的场景用/worktree别名/wt进行独立的手动 worktree 操作/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]各命令语义list显示每个 worktree 的分支、路径、diff 统计、提交数与状态clean / unmerged / 有未提交改动。merge把 worktree 合并回检测到的 main 分支并在之后移除若 worktree 有脏文件GSD 会先尝试自动提交再合并。clean只移除已合并或空的 worktree保留任何有未决改动的工作树。remove拒绝丢弃未合并或未提交的工作除非传入--force。自愈从常见 git 问题中自动恢复GSD 会自动恢复以下常见 git 问题Detached HEAD——合并与 worktree 流程拒绝从游离的项目根继续而不是静默切换分支。先 checkout 预期的集成分支再恢复。Stale lock files——仅在.git/index.lock存在超过 5 分钟后才删除它避免打断大仓库上正在进行的 git 操作。中断的 git 操作——恢复流程可以从被 kill 的 worker 遗留的 rebase、cherry-pick、revert 状态中 abort然后才协调合并状态。不安全的 branch reset——worktree 与 branch 模式的设置阶段若 force-reset 里程碑分支会孤立无法从起点到达的提交则拒绝执行。Orphaned worktrees——检测并清理被遗弃的 worktree。源码 worktree-lifecycle.ts 中可看到SQUASH_MSG/MERGE_HEAD/MERGE_MSG残留清理、失败 squash 后的合并状态清理以及孤儿 worktree 的 bootstrap 合并对应 ADR-016 相关设计见 ADR-016-worktree-lifecycle-and-projection.md。运行/gsd doctor可手动检查 git 健康状态/gsd forensics可查看孤儿检测与合并遥测以决定是否切换 slice cadence。相关文档导航完整偏好字段参考preferences-reference.mdGit 服务与提交消息生成源码git-service.tsSlice cadence 合并与 re-squash 实现slice-cadence.tsSlice cadence 测试用例slice-cadence.test.ts偏好校验规则含弃用字段告警preferences-validation.ts自动模式 worktree 生命周期auto-worktree.ts用户文档中的配置说明docs/user-docs/configuration.md赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐gsd-core 中 Executor 的 git stash 禁令worktree 隔离模式下的共享 refs/stash 隐患与安全替代方案gsd core 中 Executor 的 git stash 禁令worktree 隔离模式下的共享 refs/stash 隐患与安全替代方案 导读 Gitgsd-core 代码修复 Agent 的同分支 worktree 隔离机制git worktree add -b 与事务化清理的工程实践gsd core 代码修复 Agent 的同分支 worktree 隔离机制 git worktree add b 与事务化清理的工程实践 导读 本文以 gAI4Animation 深度学习角色动画项目学术引用指南按研究方向选择对应论文AI4Animation 深度学习角色动画项目学术引用指南按研究方向选择对应论文 AI4Animation 是一个面向 Unity 的深度学习角色动画与运动控人工智能深度学习图形学游戏开发上一篇RenderDoc 的 SPIR-V 开源插件构建指南glslang / SPIRV-Cross / SPIRV-Tools 的跨平台分发构建下一篇Redux Thunk 项目推荐异步状态管理的革命性解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考