人工智能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点击查看免费下载GSDGitHub 加速计划 / 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偏好项选择一种隔离模式它决定工作发生在哪里模式工作目录分支适用场景none默认项目根目录当前分支无里程碑分支大多数项目——无隔离开销worktree.gsd/worktrees/MID/milestone/MID需要在里程碑之间完全隔离文件的项目branch项目根目录milestone/MIDworktree 不适用的 submodule 密集型仓库三种模式在 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分支上所有执行都发生在 worktree 内部里程碑完成后worktree 被squash-merge到主线作为一个干净的提交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-merge1. 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 commitbranch模式下流程相同只是工作在项目根目录而非独立 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 commitGSD 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 Modeauto 模式自动创建并管理 worktree里程碑开始时在.gsd/worktrees/MID/创建 worktree分支为milestone/MID项目根目录的 SQLite 数据库保持为规范运行时状态artifact/projection 文件在 active worktree 内的.gsd/下渲染而执行发生在该 worktree 中。SQLite WAL 协调仅限单主机——不要在机器间共享此运行时协调约束详见src/resources/extensions/gsd/docs/COORDINATION.md所有执行都在 worktree 内部进行里程碑完成时worktree squash-merge 到集成分支integration branchworktree 与分支被移除。其中集成分支的解析顺序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.tslist显示每个 worktree 的分支、路径、diff 统计、提交数以及其状态clean / unmerged / 有未提交变更merge把 worktree 合并回检测到的主分支并随后移除若 worktree 有脏文件GSD 会尝试在合并前自动提交它们。若主分支未检出命令会提示先切换到主分支再重试clean只移除已合并或空的 worktree保留任何有待处理变更的 worktreeremove除非传入--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设置soloteamgit.auto_pushtruefalsegit.push_branchesfalsetruegit.pre_merge_checkfalsetruegit.merge_strategysquashsquashgit.isolationnonenonegit.commit_docstruetrueunique_milestone_idsfalsetrue模式默认值优先级最低——任何显式偏好都会覆盖它。例如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提交后是否自动推送到 remotepush_branches默认false提交后是否推送里程碑分支到 remoteremote默认origin推送目标 remote 名称snapshots默认true是否创建 WIP 快照提交pre-dispatch 快照、doctor 的安全提交gsd snapshot:。设为false可抑制所有 doctor 发起的 snapshot 提交。注意快照也可以以refs/gsd/snapshots/label/timestamp引用形式创建createSnapshot()并不总是产生提交pre_merge_checktrue/false/auto默认auto合并 worktree 回集成分支前是否运行预合并检查。true总是运行false从不运行auto在检测到 CI 时运行。实现上runPreMergeCheck()git-service.ts在设为字符串时会直接执行该命令例如npm test未设置时自动从package.json的 test script 检测命令经过tokenizePreMergeCommand()词法化后无 shell 执行含 shell 元字符;、、|、反引号等的命令会被拒绝以避免仓库内PREFERENCES.md的提权面Issue #4980commit_type覆盖 conventional commit 类型前缀合法值限定为feat, fix, refactor, docs, test, chore, perf, ci, build, style默认从 diff 内容推断main_branch默认main新仓库的主分支名也是getMainBranch()在自动检测歧义时的首选分支merge_strategy默认squashsquash把所有提交合并为一条merge保留逐条提交历史isolation默认nonenone/worktree/branch决定 auto-mode 的 git 隔离策略见上文三种模式manage_gitignore默认true设为false时 GSD 完全不触碰.gitignore适合有严格管理的.gitignore的项目worktree_post_createworktree 创建后运行的脚本auto-mode 与手动/worktree均生效接收SOURCE_DIR与WORKTREE_DIR环境变量30 秒超时失败非致命仅记 warningauto_pr默认false里程碑分支合并后自动创建 GitHub PR需要安装ghCLIpr_target_branchauto_pr启用时的 PR 目标分支省略时默认主分支absorb_snapshot_commits默认true是否把连续的gsd snapshot:提交吸收进下一条真实提交设为false保留快照历史供取证collapse_cadencemilestone/slice何时把 worktree 提交折叠回主线。milestone默认在里程碑完成/切换时 squash-merge 一次slice在每个 slice 通过验证后立即 squash-merge把孤立窗口从里程碑级缩小到 slice 级冲突逐 slice 暴露milestone_resquashcollapse_cadence: slice时可选在里程碑结束时把 main 上的逐 slice 提交再压成一条里程碑提交保持「main 上每个里程碑一条提交」的历史形态默认true。已废弃项commit_docs与merge_to_main均不再生效——.gsd/始终被外部管理gitignore 处理里程碑级合并始终执行。请从配置中移除。1. 自动 Pull Request面向使用 Gitflow 或分支式工作流的团队GSD 可在里程碑完成时自动创建 PRgit: 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: solo默认isolation: none里程碑之间需要完整文件隔离git.isolation: worktree仓库需至少一个提交submodule 密集 / 硬编码路径仓库git.isolation: branch多人协作、需要唯一里程碑 ID 与预合并检查mode: teamGitflow 团队、里程碑完成要自动开 PRgit.auto_push: truegit.auto_pr: truegit.pr_target_branch: develop公司要求仓库干净、只有部分成员用 GSD保留默认.gsd/gitignore 行为commit_docs已废弃配置始终遵循「显式优先于模式默认值」先用mode获得合理基线再按需逐项覆盖即可在零手动分支管理的前提下获得适合你工作流的 Git 自动化。赞分享人工智能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点击查看免费下载相关推荐FreeCAD CAM 输出生成全解G-code 流水线与差距清单FreeCAD CAM 输出生成全解G code 流水线与差距清单 本文以 FreeCAD CAM 工作台的输出生成路标为基准对照后处理器源码逐项核对。桌面应用3D建模图形学工业制造用 gsplat 在 COLMAP 数据上训练 3D Gaussian Splatting从数据解析到实时预览的完整实战用 gsplat 在 COLMAP 数据上训练 3D Gaussian Splatting从数据解析到实时预览的完整实战 gsplat 仓库自带的 examp人工智能AI Agent代码智能体Agent 编排CLIAI 应用gsd-core 修复 gsd-code-fixer 同分支检出冲突基于 git worktree add -b 的 gsd-reviewfix 隔离分支机制gsd core 修复 gsd code fixer 同分支检出冲突基于 git worktree add b 的 gsd reviewfix 隔离分支机制上一篇实战指南SuperDuperDB测试覆盖率分析与质量提升策略下一篇LeetCode 140 Word Break II 全解法解析从回溯、Trie 到动态规划的多语言实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
