企业官网建设流程全解析

本篇技术指南围绕 GSD Core（Git. Ship. Done - Core）的里程碑完成（/gsd:complete-milestone）自动化能力，深入讲解新增配置项git.create_tag：它用于控制 GSD 是否在里程碑完成时自动创建git tag -a v[X.Y]发布标签。阅读完本文，你将掌握该配置的默认行为、两种设置方式（/gsd:settings与gsd config-set）、其底层解析与门控实现原理，以及如何为自带发布流程的项目关闭自动打 Tag、避免重跑里程碑关闭时因 Tag 冲突而静默失败。

一、功能背景：为什么需要可关闭的里程碑 Tag

在 GSD Core 的规划流程中，每个里程碑（milestone）完成时，工作流默认会执行一次发布打标操作：对仓库创建形如v1.0、v1.1、v2.0的注解式 Git 标签（annotated tag），作为版本发布的历史记录点。这一步对大多数项目是合理的默认行为，但对于已有独立发布/Release 自动化流程（例如 CI/CD 平台自动打 Tag、npm/pypi 发布流程自带版本标记）的项目，GSD 再创建一个本地 Tag 反而会造成重复或干扰。

为此，GSD Core 引入了布尔配置项git.create_tag（默认true，保持向后兼容），让这类项目可以显式关闭 GSD 在里程碑完成时自动执行git tag -a v[X.Y]的行为；同时新增 Tag 冲突预检，防止在重跑里程碑关闭时因 Tag 已存在而静默失败（对应 PR #3508，配套测试与文档落地于 #3086、#2994 等系列改动）。

二、配置项速览

默认值来源（三处一致）

该默认值在仓库中由多处共同维护，保证“缺省即true”这一向后兼容语义：

• 配置 Schema 默认表 src/config.cts#L106-L113：SCHEMA_DEFAULTS中注册'git.create_tag': true，当config-get查询时键缺失也返回true而非 “Key not found”；
• 配置对象内置默认 src/config.cts#L361-L367：git分组下硬编码create_tag: true；
• 项目配置模板 gsd-core/templates/config.json#L32-L34：新项目初始化时写入"git": { "create_tag": true }。

在文档侧，docs/CONFIGURATION.md#L1264 的配置参考表中亦有对应描述：git.create_tag（boolean，默认true）——在里程碑完成时创建 git tag（v[X.Y]），自带发布流程的项目可设为false。

三、两种设置方式与验证

配置存放在项目级文件.planning/config.json（项目的规划配置）中。设置git.create_tag有两种方式：

方式一：通过/gsd:settings交互命令

在支持 GSD 的 AI 编程环境中，直接运行：

/gsd:settings

在设置界面中定位git.create_tag并切换为关闭。该命令会回写项目配置文件，适合不想记忆 CLI 参数的使用者。相关设置流程可参考 gsd-core/workflows/settings.md。

方式二：通过gsd config-set命令行

在仓库根目录执行（gsd为 GSD Core 的 CLI 入口）：

# 关闭里程碑自动打 Tag gsd config-set git.create_tag false # 重新开启（默认值） gsd config-set git.create_tag true

校验是否生效

gsd config-get git.create_tag # 关闭后输出：false # 默认/开启时输出：true

取值约束

git.create_tag只接受布尔值。配置校验器在 src/config.cts#L958-L963 中对git.create_tag做了专门校验（对应 Issue #3086）：传入非布尔值（如字符串"maybe"）会直接报错：

Invalid git.create_tag 'maybe'. Must be a boolean (true or false).

四、底层原理：fail-open 解析与 config-gate 提升

从源码结构看，git.create_tag的解析经历了两次演进：

演进前（#2994 之前）：工作流文件complete-milestone.md的git_tag步骤顶部内嵌了一个<config-check>子标签，内部通过 shell 兜底解析：

gsd-tools.cjs query config-get git.create_tag 2>/dev/null || echo "true"

即以“查询失败也输出true”的方式实现 fail-open（缺失即创建 Tag）。但这样做的缺陷是：步骤自身的开关由该步骤自己计算的同一个事实来决定，职责耦合在流程文档里，难以被测试与复用。

演进后（#2994）：解析被提升（hoist）到源码层，职责分离：

1. 解析函数detectGitCreateTag（src/init.cts#L665-L678）读取项目配置：

   function detectGitCreateTag(cwd: string): boolean { return readConfigJsonValue(cwd, ['git', 'create_tag']) !== false; }

   注意这里的判定是!== false而不是=== true，这正是 fail-open 语义的代码化：只要键缺失或未设置为字面量false，结果就是“创建 Tag”，与旧 shell 兜底|| echo "true"的行为完全一致。源码注释明确说明这是刻意与 fail-closed 默认值相反的极性（对照detectFallowConfig）。

2. 专用 init 入口cmdInitCompleteMilestone（src/init.cts#L3329-L3408）把该事实作为git_create_tag字段输出，并同时输出section_manifest——它不再携带任何阶段列举逻辑，唯一职责就是为git_tag步骤提供配置门控事实。

这一提升保证了“配置事实”与“工作流消费事实”同源，且可以被 CLI 直接查询与测试（见第六节）。

五、工作流门控：section 机制与 Tag 冲突预检

5.1 用 gsd:section 门控整个 git-tag 步骤

在 gsd-core/workflows/complete-milestone.md#L633-L635，git_tag步骤不再内嵌<config-check>，而是被一个节标记包裹：

<!-- gsd:section id="git-tag" when="state:git-create-tag" -->

其语义为：当section_manifest为null（未启用分段）或"git-tag"位于其included列表时，读取并执行gsd-core/workflows/complete-milestone/steps/git-tag.md；否则跳过整个步骤文件，直接进入git_commit_milestone。也就是说，关闭git.create_tag后，工作流会连git-tag步骤文件都不再读取，从而保证“禁用 Tag 创建不会跳过里程碑归档”（对应需求 REQ-MILESTONE-TAG-03）。

工作流成功标准清单也同步标注了该条件性：gsd-core/workflows/complete-milestone.md#L722 中“Git tag created (v[X.Y])”一项注明(if git.create_tag enabled)。

5.2 git-tag 步骤本身：冲突预检与注解式 Tag

gsd-core/workflows/complete-milestone/steps/git-tag.md 中的git_tag步骤是实际打 Tag 的执行体。它首先进行Tag 冲突预检（对应需求 REQ-MILESTONE-TAG-02，防止重跑里程碑关闭时静默失败）：

# Pre-check: skip if tag already exists (prevents silent failure on retry) if git rev-parse "v[X.Y]" >/dev/null 2>&1; then echo "Tag v[X.Y] already exists, skipping"; exit 0; fi git tag -a v[X.Y] -m "v[X.Y] [Name] Delivered: [One sentence] Key accomplishments: - [Item 1] - [Item 2] - [Item 3] See .planning/MILESTONES.md for full details."

随后确认输出Tagged: v[X.Y]，并询问用户是否推送远端：

git push origin v[X.Y]

此前（#3508 之前）若 Tag 已存在，git tag -a会直接报fatal: tag 'v[X.Y]' already exists，而工作流不一定能把这次失败显式呈现给用户——这正是“静默失败”场景。引入预检后，重跑里程碑关闭会明确打印Tag v[X.Y] already exists, skipping并干净退出。

六、验证与测试：行为如何被锁定

该功能的回归测试位于 tests/config.test.cjs#L2113-L2222，对应 Issue #3086，覆盖四个维度：

其中 D2 用例（#3508 引入）刻意不读取init.cts源码文本，而是通过真实 CLI 驱动配置键两种取值来观察init complete-milestone的git_create_tag输出字段，从而证明解析函数确实绑定的是git.create_tag这一配置键本身。同时 tests/resolver-hoist-guard.test.cjs#L83 还记录了state:git-create-tag与git.create_tag之间的映射关系，防止解析器被意外改动。

七、行为约束与边界情况

综合 docs/features/milestone-tag-creation-toggle.md（Feature id 141）与上述源码，git.create_tag的行为约束可归纳为三条需求：

• REQ-MILESTONE-TAG-01：配置缺失必须保持默认行为。未配置或键缺失等价于true（fail-open），老项目升级后行为不变；
• REQ-MILESTONE-TAG-02：已存在的 Tag 冲突必须显式失败而非覆盖。通过git rev-parse预检提前发现冲突并明确跳过；
• REQ-MILESTONE-TAG-03：关闭 Tag 创建不得跳过里程碑归档。归档（milestones/v[X.Y]-ROADMAP.md、milestones/v[X.Y]-REQUIREMENTS.md、MILESTONES.md 条目、STATE.md 更新等）由milestone.completeCLI 负责，与git-tag步骤相互独立，关闭打 Tag 只影响 Tag 这一项。

典型使用场景

• 自带 Release 自动化：CI/CD 已接管打 Tag 与发布，将git.create_tag设为false，避免本地产生多余的注解 Tag 与远端推送重复；
• 多工作流共享仓库：不希望每个子项目/工作流的里程碑关闭都创建全局 Tag 时，按项目关闭该能力；
• 重跑里程碑关闭：启用预检后，重复执行/gsd:complete-milestone遇到已存在的v[X.Y]会得到明确的 skip 提示而非底层 git 报错。

需要注意，该配置作用域是项目级（.planning/config.json），影响的是当前项目内所有里程碑完成操作；关闭后 GSD 不再询问“Push tag to remote?”，但其余归档、审计、回顾、分支处理等步骤照常执行。