get-shit-done 模型解析单一事实源改造：Model Catalog 模块如何终结 resolve-model 的 SDK/CLI 模型漂移（3229）

get-shit-done 模型解析单一事实源改造Model Catalog 模块如何终结 resolve-model 的 SDK/CLI 模型漂移#3229【免费下载链接】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-done 项目面向 Claude Code 的轻量 meta-prompting、上下文工程与规范驱动开发系统中的一次关键架构修复把模型选择数据收敛进一个共享的 Model Catalog 模块从根上修复resolve-model在 SDK 与 CLI/CJS 两侧的注册表漂移issue #3229。读者读完将掌握漂移 bug 的症状与根因、sdk/shared/model-catalog.json的数据结构与配置字段语义、共享模块被双端消费的实现方式以及resolve-model面向未知 agent 的配置档语义化回退策略与对应的回归测试。背景resolve-model 为什么会在 SDK 与 CLI 之间各说各话get-shit-done 的模型解析链路存在两条入口一条是面向现代 AI 编程工具Claude Code、Codex 等的 SDKTypeScript 实现位于 sdk/另一条是兼容 CommonJS 环境的 CLI 包位于 get-shit-done/bin/。resolve-model是这条链路上被调用最频繁的查询之一——它根据当前工作区配置的model_profilequality / balanced / budget / adaptive / inherit把某个具体 agent例如gsd-planner、gsd-code-reviewer解析成最终要调用的模型标识符。在变更前SDK 侧维护了一份独立的 agent→模型映射而 CLI/CJS 侧又有自己的解析逻辑。当仓库中的 agent 数量持续增长时两侧的注册表就不可避免开始漂移。症状合法 agent 被当成未知 agent修复前issue #3229 所描述的一类问题表现为SDK 侧只认识 18 个 agent而磁盘上实际已经随发行版提供了 33 个 agent。当工作流尝试解析第二梯队的合法 agent如gsd-code-reviewer、gsd-security-auditor时SDK 的resolve-model因为查不到记录会静默返回{ unknown_agent: true, model: sonnet }这类返回的两层危害在于语义失真agent 明明合法对应文件真实存在于 agents/却被标记为unknown_agent: true调用方可能据此走未知 agent降级或告警路径模型错配回退到写死的sonnet完全无视当前model_profile的语义。若用户处于budget预算档期望的是 haiku 级别的廉价模型却拿到了 sonnet若处于quality档又拿不到 opus。这一修复的 changeset 记录在 .changeset/fix-3229-model-catalog-source-of-truth.mdPR #3230其核心理念一句话即可概括模型选择数据只允许存在一份其余都是消费方。单一事实源sdk/shared/model-catalog.json的数据结构修复的第一步是把所有模型选择数据收敛到一个 JSON 文件sdk/shared/model-catalog.json。它现在拥有整个决策所需的五类数据顶层结构一览顶层键作用取值样例profiles合法配置档集合[quality,balanced,budget,adaptive,inherit]phaseTypesagent 所属的工序阶段类型[planning,discuss,research,execution,verification,completion]adaptiveTierMap自适应档下路由层级→模型别名换算heavy→opus、standard→sonnet、light→haikuruntimeTierDefaults各运行时在 opus/sonnet/haiku 三档下的默认模型claude.sonnet.model claude-sonnet-4-6agents完整 33-agent 注册表见下文agents 注册表每条 agent 的五元组元数据agents下每个 key 都是一个真实存在的 gsd-* agent对应 agents/ 中的同名.md文件。以gsd-code-reviewer为例gsd-code-reviewer: { golden: opus, balanced: sonnet, budget: sonnet, phaseType: verification, routingTier: standard }字段语义如下golden/balanced/budget分别对应 quality、balanced、budget 三档配置档下该 agent 应该使用的模型别名opus/sonnet/haikuphaseTypeagent 归属的工序阶段供按阶段统一覆盖模型时使用例如verification阶段统一调整routingTierlight/standard/heavy用于adaptive自适应档的派生计算——adaptive 档不写死模型而是读取该映射经adaptiveTierMap换算成模型别名。注册表中前 18 个条目为gsd-planner、gsd-roadmapper、gsd-executor、gsd-phase-researcher、gsd-project-researcher、gsd-research-synthesizer、gsd-debugger、gsd-codebase-mapper、gsd-verifier、gsd-plan-checker、gsd-integration-checker、gsd-nyquist-auditor、gsd-pattern-mapper、gsd-ui-researcher、gsd-ui-checker、gsd-ui-auditor、gsd-doc-writer、gsd-doc-verifier随后以空行分隔追加了gsd-advisor-researcher、gsd-ai-researcher、gsd-assumptions-analyzer、gsd-code-fixer、gsd-code-reviewer、gsd-debug-session-manager、gsd-doc-classifier、gsd-doc-synthesizer、gsd-domain-researcher、gsd-eval-auditor、gsd-eval-planner、gsd-framework-selector、gsd-intel-updater、gsd-security-auditor、gsd-user-profiler共 15 个扩展 agent。两组合计恰好 33 个与 issue #3229 中磁盘上有 33 个 agent的事实对齐——此前 SDK 恰好只内置了前一组 18 个后一组 15 个全部落入查无此 agent黑洞。runtimeTierDefaults全运行时三档模型映射针对每个受支持运行时runtimeTierDefaults给出opus/sonnet/haiku三档对应的默认模型。当前文件中配置了 15 个运行时其中 7 个 Group A 运行时带有内建默认模型运行时opus 档sonnet 档haiku 档备注claudeclaude-opus-4-7claude-sonnet-4-6claude-haiku-4-5—codexgpt-5.4reasoning_effort: xhighgpt-5.3-codexmediumgpt-5.4-minimedium附带reasoning_effortgeminigemini-3-progemini-3-flashgemini-2.5-flash-lite—qwenqwen3-max-2026-01-23qwen3-coder-plusqwen3-coder-next—opencodeanthropic/claude-opus-4-7anthropic/claude-sonnet-4-6anthropic/claude-haiku-4-5带 provider 前缀copilotclaude-opus-4-7claude-sonnet-4-6claude-haiku-4-5—hermesanthropic/claude-opus-4-7anthropic/claude-sonnet-4-6anthropic/claude-haiku-4-5带 provider 前缀其余 Group B 运行时kilo、cline、cursor、windsurf、augment、trae、codebuddy、antigravity三档值均为null即没有内建默认——resolve 时应依赖用户侧显式覆盖或 profile 覆盖而不应静默捏造模型名。这一显式留空的设计尤其重要它可以被 SDK 与 CLI 双向用于校验运行时若在KNOWN_RUNTIMES中但查不到档位默认就能明确判定该运行时需要外部配置。双端共享同一份 JSON 如何同时驱动 SDK 与 CLI/CJS单一数据源能否成立取决于两端是否真的从同一份文件加载。源码中能看到两套独立的加载器但指向的都是同一份数据。SDK 端sdk/src/model-catalog.tsSDK 加载器在模块加载期用readFileSync读取../shared/model-catalog.json即仓库根下的sdk/shared/model-catalog.json并一次性派生出全部派生表MODEL_PROFILES把每条 agent 的golden/balanced/budget/routingTier展开成{ quality, balanced, budget, adaptive }四档别名映射其中adaptive由routingTier经adaptiveTierMap换算而来AGENT_TO_PHASE_TYPEagent → phaseType 映射AGENT_DEFAULT_TIERSagent → 默认 routing tier 映射getAgentToModelMapForProfile(profile)给定配置档产出全量 agent→模型别名的映射inherit档透传inherit未知档回退balancedresolveRuntimeTierDefault(runtime, alias)查询某运行时某档位的默认模型条目runtimesWithReasoningEffort()检测哪些运行时带reasoning_effort当前实现下即codex。也就是说SDK 侧对 agent 集合的认知不再是硬编码数组而是对目录 JSON 的一次Object.keys推导——新增 agent 只要落进 JSONSDK 与 CLI 就同时可见彻底消除了两边各维护一份清单的漂移土壤。CLI/CJS 端get-shit-done/bin/lib/model-catalog.cjsCommonJS 侧没有import.meta.url且要同时适配源码仓库开发态与安装后的运行态两种布局因此 model-catalog.cjs 采用了一个优先级候选路径解析策略同目录安装态install/bin/shared/model-catalog.json——这是bin/install.js在安装期写入的规范化位置issue #3288 修复各运行时Claude Code、Codex、OpenCode 等安装后都从这里加载源码仓库开发态从bin/lib/向上三级找到sdk/shared/model-catalog.json支持直接在仓库克隆目录内运行环境变量覆盖GSD_MODEL_CATALOG指向任意自定义目录文件供测试夹具与特殊部署使用。与 SDK 端一一对应CJS 侧导出MODEL_PROFILES、AGENT_TO_PHASE_TYPE、AGENT_DEFAULT_TIERS、MODEL_ALIAS_MAP、RUNTIME_PROFILE_MAP、KNOWN_RUNTIMES、RUNTIMES_WITH_REASONING_EFFORT、nextTier、formatAgentToModelMapAsTable、getAgentToModelMapForProfile等符号。值得注意的错误处理细节加载失败时它只把MODULE_NOT_FOUND/ENOENT视为可换下一个候选路径重试的缺失类错误其余解析错误、权限错误会直接抛出而非被吞掉若全部候选都失败则抛出列出所有已尝试路径的诊断信息。GSD_MODEL_CATALOG的存在也让安装路径回归测试可以低成本地在临时目录内模拟各种安装布局相关背景可进一步参考 ADR-0003model-catalog-module 与 ADR-0005SDK 架构接缝图。resolve-model 的解析顺序与配置档语义化未知回退有了单一数据源还要把resolve-model的行为做对——尤其是面对真正未知的 agent如拼写错误、未来新增但目录未更新时回退模型必须尊重配置档语义而不是硬编码。在 SDK 查询层 config-query.ts 中resolveModelhandler 的执行顺序是读取配置经由loadConfig加载当前工作区可附带 workstream配置profile config.model_profile缺省balanced小写化逐 agent 覆盖优先若config.model_overrides[agentType]存在则直接命中覆盖值——若该 agent 不在目录中会附加unknown_agent: true标记无配置文件项目尚无配置时返回空model与 CJS 行为保持 parity目录未命中则同样带unknown_agent: true查表命中在MODEL_PROFILES[agentType]中按agentModels[profile] || agentModels[balanced] || sonnet取别名目录未命中真正未知进入配置档语义化回退。其中第 5 步正是本次修复的另一半——未知 agent 回退从一律 sonnet改为按 profile 语义推导当前 profile回退模型别名语义qualityopus追求质量budgethaiku追求成本/速度balanced/adaptivesonnet均衡默认inheritinherit透传继承语义对应源码片段位于 config-query.ts#L261-L268。这样即使遇到目录外的 agentbudget档也不会再被错误地推向 sonnet 级别的开销。从别名到真实模型 id 的落盘拿到别名opus/sonnet/haiku之后还有最后一步换算若命中phaseType且配置中存在models[phaseType]字符串档位则以阶段档位覆盖 agent 别名随后调用运行时解析resolveRuntimeTier得到真实的模型 id——例如claude sonnet 档得到claude-sonnet-4-6若运行时条目带reasoning_effort如 codex 的xhigh/medium该字段也会一并透传到结果中见 config-query.ts#L274-L286。最后再根据resolve_model_ids的取值决定是否返回完整模型 id 或省略。这也意味着用户最终拿到的是运行时语义完整的模型字符串而非裸别名避免别名泄漏到下游消费方。回归测试与验证证据本次修复在 SDK 测试与仓库级测试两个层面都固化了断言sdk/src/query/config-query.test.ts#L125-L135明确以gsd-code-reviewer作为曾随发行提供但旧 SDK 缺失的代表断言resolve-model结果不再带unknown_agent属性直接对照 issue #3229 的症状sdk/src/query/config-query.test.ts#L138-L154对真正未知agent 断言返回unknown_agent: true并分别验证quality → opus、budget → haiku的语义化回退tests/bug-3288-model-catalog-install-path.test.cjs验证安装后 CJS 侧能从 co-located 的bin/shared/model-catalog.json读到同一份目录tests/model-catalog-runtime-defaults.test.cjs验证各运行时的三档默认模型与reasoning_effort存在性配套的配置覆盖链路tests/bug-3227-config-set-model-overrides.test.cjs与 inherit 配置档语义tests/bug-1829-inherit-model-profile.test.cjs也持续守护着这条解析链路的相邻行为。从本次修复可复用的工程经验把 issue #3229 的修复拆开看它其实给同类多入口代码库提供了三条可复用的准则凡是跨进程、跨语言入口都要共享的决策数据必须收敛为单一 JSON 事实源而不是在每侧各自维护一份看起来相同的常量或映射——两侧各自演进的清单迟早会以最隐晦的方式静默回退、未知标记暴露分歧留空优于捏造对尚无内建默认的运行时Group B 的 8 个运行时显式null宁可让上层判定为需要外部配置也不要悄悄填一个可能错配的模型名同理未知 agent 的兜底值也必须服从配置档语义让降级行为可预测修复必须以回归测试锚定具体症状gsd-code-reviewer不再返回unknown_agent: true、budget未知 agent 回退haiku——这类断言把抽象的数据一致翻译成了任何人可以运行的验收标准。如今只要向 sdk/shared/model-catalog.json 增补一条 agent 记录SDK 与 CLI/CJS 两侧的resolve-model都会在下一个加载周期自动感知同样地新增运行时或调整某运行时的默认模型也只需改动这一份文件。这正是 ADR-0003 所定义的 Model Catalog 模块希望长期维持的状态一份数据、双端消费、全程可测。【免费下载链接】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），仅供参考