get-shit-done 配置自愈迁移实战顶层branching_strategy不再触发 “unknown config key” 误报【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done这篇技术指南围绕 get-shit-doneGSD修复记录.changeset/sunny-pandas-dance.mdPR #3527展开剖析.planning/config.json读取管线中“旧式顶层键branching_strategy”被误报为未知配置键的根因、自愈式磁盘迁移的修复设计以及 CJS 与 SDK 双层配置模型的一致性保障。读完你将掌握 GSD 配置加载loadConfig的完整调用链、遗留键规范化normalizeLegacyKeys与去重告警机制并能在自己的项目中复现验证与正确书写branching_strategy配置。问题背景branching_strategy的规范位置与遗留形态在 GSD 中项目级配置存放于项目根目录的.planning/config.json。Git 分支创建策略的规范位置是嵌套键git.branching_strategy其取值与含义参见 docs/CONFIGURATION.md取值行为none默认永不创建分支适合单人开发、简单项目phase在execute-phase开始时为一个 Phase 创建分支粒度小、可回滚milestone在首次execute-phase时为整个 Milestone 创建分支在complete-milestone时合并适合发布分支 / 按版本提 PR该键决定分支模板是否启用如phase_branch_template: gsd/phase-{phase}-{slug}因此其能否被正确读取直接决定分支行为。一个常见的历史遗留写法是把该键放在顶层{ branching_strategy: phase, git: { base_branch: main } }而规范写法为{ git: { branching_strategy: phase, base_branch: main } }问题恰恰出在loadConfig确实在积极读取这个遗留顶层键却同时会向用户打印“该键会被忽略”的警告——一句与事实相悖的误报。这正是 PR #3527 修复的核心缺陷对应 issue #3523。缺陷根因KNOWN_TOP_LEVEL允许清单由“点号路径首段”推导GSD 的 CJS 侧配置加载入口是 get-shit-done/bin/lib/core.cjs 中的loadConfig(cwd)。它承担两类工作读取键值通过get(branching_strategy, { section: git, field: branching_strategy })core.cjs同时支持顶层键与git.*嵌套回退——即遗留顶层值会被真正使用并非“被忽略”告警未知顶层键从配置模式清单VALID_CONFIG_KEYS真实来源是 sdk/shared/config-schema.manifest.json 中的git.branching_strategy等点号路径推导出KNOWN_TOP_LEVEL允许集合再对parsed的顶层键逐一比对。根因在于推导方式本身const KNOWN_TOP_LEVEL new Set([ ...[...VALID_CONFIG_KEYS].map(k k.split(.)[0]), // ... ]);VALID_CONFIG_KEYS中记录的是点号嵌套路径如workflow.research、git.branching_strategy经split(.)[0]取首段后得到的是workflow、git这样的段容器名而永远无法得到branching_strategy这个键本身。于是当一个遗留配置文件把branching_strategy写在顶层时它既不在容器名集合中也不在后续补充的弃用键名单里被判为“未知配置键”触发gsd-tools: warning: unknown config key(s) in .planning/config.json: branching_strategy — these will be ignored这句话是误导性的——该值实际上被core.cjs中第 455 行的嵌套回退逻辑读取并生效了。正如仓库内漂移记录 docs/agents/cjs-sdk-seam.md 所记载此前 #3055 曾出现“顶层branching_strategy被静默丢弃而回退到none”的严重缺陷阶段提交错误地落在了操作者当前分支而非gsd/phase-{N}#3116 先在 SDK 侧mergeDefaults()补上了遗留键规范化而 CJS 路径在 #3527 之前仍残留着这一不正确的告警。修复方案自愈式磁盘迁移self-healing on-disk migrationPR #3527 没有选择“只静默告警名单”或“只允许键存在”而是复用了仓库中既有的multiRepo → planning.sub_repos迁移先例实施自愈迁移option 3首次loadConfig时把顶层branching_strategy的取值**接枝graft**进git.branching_strategy同时删除过时的顶层条目通过写回逻辑将结果持久化到磁盘此后磁盘上的配置文件即为规范形态。这一归一化逻辑被收敛到共享的 Configuration Module见 docs/adr/3524-cjs-sdk-hard-seam.mdnormalizeLegacyKeys(parsed) → { parsed, normalizations[] }一次调用即可覆盖depth → granularity、multiRepo → planning.sub_repos、sub_repos → planning.sub_repos、branching_strategy → git.branching_strategy四类遗留键迁移core.cjs 内联注释。由于该模块的migrateOnDisk是异步的而loadConfig是同步函数写回在调用点以既有的platformWriteSync模式同步完成且只写磁盘文件本身、绝不把合并后的默认值污染回磁盘core.cjs。与此同时KNOWN_TOP_LEVEL的“弃用但仍接受”名单中也加入了branching_strategy与depth、multiRepo并列见 core.cjs作为安全网——即使首次读取尚未发生写回告警也永远不会触发。迁移过程中的覆盖语义与 SDK 的mergeDefaults()保持严格一致当规范嵌套值git.branching_strategy已存在时嵌套值胜出遗留顶层值不得覆盖它冗余的顶层键仍会被移除。这样既完成了形态自愈又不改变用户已表达的配置意图。去重保护同一警告一进程内最多出现一次修复还顺带处理了告警的“二次发射”问题。loadConfig在一次 CLI 调用中可能被执行多次——例如单次init phase-op N会先为子命令初始化、再为 git 配置解析各调用一次。若不加防护同一未知键警告会重复打印。解决方式是模块级去重集合_warnedUnknownConfigKeyscore.cjsconst _warnedUnknownConfigKeys new Set(); // 告警发射点第 407-419 行附近 const unknownKeys Object.keys(parsed).filter(k !KNOWN_TOP_LEVEL.has(k)); if (unknownKeys.length 0) { const warnKey unknownKeys.join(,); if (!_warnedUnknownConfigKeys.has(warnKey)) { _warnedUnknownConfigKeys.add(warnKey); process.stderr.write( gsd-tools: warning: unknown config key(s) in .planning/config.json: ${unknownKeys.join(, )} — these will be ignored\n ); } }它以“未知键组合”为去重键保证同一进程内同一组未知键最多告警一次——对真正未知的键依然如实提示不会因去重而掩盖问题。契约测试CJS 与 SDK 对遗留形态保持一致该修复的价值不止于消除一条告警更在于堵住了双层实现之间的漂移。SDK 侧 sdk/src/config.ts 中项目配置读取在mergeDefaults()前先调用normalizeLegacyKeys(parsed)再由canonicalMergeDefaults完成深合并早已正确处理顶层遗留键#3116CJS 侧则通过共享 Configuration Module 取得同等行为。回归测试 tests/bug-3523-cjs-loadconfig-branching-strategy-warning.test.cjs 从四个维度锁定了修复无告警以resolve-model planner内部调用loadConfig的最小 CJS 入口触发读取断言 stderr 为空值仍被透出触发迁移写回后用config-get git.branching_strategy能读到milestone等正确取值磁盘迁移生效断言迁移后磁盘上config.json中git.branching_strategy已存在、顶层键已删除嵌套值存在时不被顶层覆盖nested wins且GSD_WORKSTREAMalpha的工作流加载场景下根配置同样能自愈并持久化CJS↔SDK 契约一致性使用 SDKmergeDefaults已能处理的同一遗留 fixture断言 CJS 侧产出相同的branching_strategy值。其中“去重”断言使用了一个确属未知的哨兵键__gsd3523_dedup_sentinel__验证未知键警告出现且仅出现一次——不会因loadConfig被多次调用而翻倍也不会因修复而变为零次。验证方法与配置实操在本地项目中复现与验收该修复非常简单# 1. 写入一个遗留形态的配置 cat .planning/config.json EOF { branching_strategy: milestone, git: { base_branch: main } } EOF # 2. 触发 loadConfigresolve-model 是最小入口stderr 应无告警 node get-shit-done/bin/gsd-tools.cjs resolve-model planner # 3. 读取规范键应输出 milestone node get-shit-done/bin/gsd-tools.cjs config-get git.branching_strategy # 4. 检查磁盘.planning/config.json 已被自愈为规范形态 cat .planning/config.json首次读取后磁盘文件应已迁移为{ git: { base_branch: main, branching_strategy: milestone } }此后无论使用gsd config-set git.branching_strategy none|phase|milestone写入还是直接编辑config.json都不再产生误导性告警。若你同时在使用多工作流GSD_WORKSTREAMalpha模式根配置文件同样会在工作流读取过程中被自愈参见上述测试第三条。小结PR #3527 表面上只修掉了一条告警实际上完成了三件事修正事实错误杜绝“键正在被读取却提示将被忽略”的自相矛盾输出建立自愈路径以multiRepo → planning.sub_repos为先例把遗留顶层branching_strategy在首次读取时自动迁移为规范git.branching_strategy并持久化统一双实现语义CJSloadConfig与 SDKmergeDefaults通过共享 Configuration Module 与契约测试bug-3523 测试对齐遗留形态的处理结果嵌套值优先、冗余键清理、告警去重的行为保持一致。对使用或扩展 GSD 的开发者而言这篇变更记录是理解.planning/config.json迁移管线的最佳切片从 config-schema.cjs模式清单适配器、configuration 模块 到 loadConfig 的同步写回再到 配置文档 中git.branching_strategy的枚举语义整条链路环环相扣——这也是“配置不仅被正确读取还会自我修复到规范形态”的设计体现。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
