【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载导读本文讲解 GSD-CoreGit. Ship. Done - Core自 v1.41 引入的**按阶段类型选择模型Per-Phase-Type Model Selection**能力通过.planning/config.json中的models配置块你可以不记忆 30 个 Agent 的完整分类体系直接用planning、research、execution、verification等阶段槽位粗粒度地调整每个阶段使用的模型档位。读完本文你将掌握models.phase_type六个合法槽位、opus/sonnet/haiku/inherit四种取值、与model_overrides/model_profile/dynamic_routing组合时的五层解析优先级并能从源码与测试层面理解其底层解析链路、校验规则与向后兼容保证。该特性由 issue #3023 与 settings-management 文档源码实现集中在 src/model-resolver.cts 与 src/model-catalog.cts回归测试见 tests/model-resolver.test.cjs。一、为什么需要按阶段类型选择模型GSD-Core 的每个阶段由多个专用 Agent 协作完成例如规划阶段由gsd-planner、gsd-roadmapper、gsd-pattern-mapper承担验证阶段由gsd-verifier、gsd-plan-checker、gsd-code-reviewer等八个 Agent 承担。在引入本特性之前调整模型档位只有两条路按 Agent 的model_overrides精确但啰嗦。你必须记住gsd-codebase-mapper属于 research、gsd-doc-writer属于 execution才能写出针对单个 Agent 的覆盖全局model_profile粗放且一刀切。一个档位策略作用于全部 Agent无法表达规划用强模型、执行用标准模型这类典型成本分配诉求。models配置块恰好填补两者之间的空档以阶段类型为粒度planning / research / execution / verification无需学习完整 Agent 分类体系即可表达规划阶段用 Opus、其余阶段用 Sonnet这样的意图代码量只要两行 JSON。从源码结构看src/model-catalog.cts 中的AGENT_TO_PHASE_TYPE正是把每个 Agent 静态映射到唯一阶段类型的真相来源取自model-catalog.json中每个 Agent 的phaseType字段VALID_PHASE_TYPES则是合法阶段槽位的集合二者共同支撑了阶段级调参这一抽象。二、配置项.planning/config.json中的models块2.1 配置键与存放位置特性对应的配置键为models位于项目的.planning/config.json工作流/项目级覆盖路径由planningDir解析可参考 src/planning-workspace.cts。models是动态键模式dynamic key pattern合法槽位由 schema manifest 严格约束。在 config-schema.manifest.json 的动态键模式中可以找到该特性的校验规则{ topLevel: models, source: ^models\\.(planning|discuss|research|execution|verification|completion)$, description: models.planning|discuss|research|execution|verification|completion }也就是说只有六个命名槽位被接受planning、discuss、research、execution、verification、completion。任何其他阶段类型如models.deployment都会被 schema 拒绝见下文校验规则。该 manifest 由 src/config-schema.cts 经 src/configuration.cts 加载是isValidConfigKey校验与config-set命令的单一事实来源。2.2 完整配置示例沿用官方文档 docs/CONFIGURATION.md 中的示例一个同时使用model_profile、models与model_overrides的完整配置如下{ model_profile: balanced, models: { planning: opus, discuss: opus, research: sonnet, execution: opus, verification: sonnet, completion: sonnet }, model_overrides: { gsd-codebase-mapper: haiku } }该配置的效果所有 research 阶段 Agent 解析为sonnet除了gsd-codebase-mapper被按 Agent 覆盖钉死为haikuplanning / discuss / execution 阶段全部为opusverification 与 completion 为sonnet。2.3 阶段类型 → Agent 映射表models.phase_type的每个槽位会应用到一组 Agent。下表与 docs/CONFIGURATION.md 及特性文档 docs/features/per-phase-type-model-selection.md 保持一致阶段类型Slot归属 Agentplanninggsd-planner、gsd-roadmapper、gsd-pattern-mapperdiscussgsd-assumptions-analyzerresearchgsd-phase-researcher、gsd-project-researcher、gsd-research-synthesizer、gsd-codebase-mapper、gsd-ui-researcherexecutiongsd-executor、gsd-debugger、gsd-doc-writerverificationgsd-verifier、gsd-plan-checker、gsd-integration-checker、gsd-nyquist-auditor、gsd-ui-checker、gsd-ui-auditor、gsd-doc-verifier、gsd-code-reviewercompletion保留给未来子 Agent当前无映射注意discuss与completion两个槽位目前被 schema 接受但尚无 Agent 映射到它们——今天设置它们是一个 no-op不会报错也不产生效果这是为未来子 Agent 预留的向前兼容槽位对应需求 REQ-PHASE-MODELS-03。从实现层面看这张表不是手写的两份文档而是由model-catalog.json中每个 Agent 的phaseType元数据统一驱动src/model-catalog.cts 通过export const AGENT_TO_PHASE_TYPE: Recordstring, string Object.fromEntries( Object.entries(_catalog.agents).map(([agent, meta]) [agent, meta.phaseType]) );生成映射因此文档与代码不会漂移。测试 tests/model-resolver.test.cjs 中的#3023 phase-type schema测试组还专门断言MODEL_PROFILES中每个 Agent 都必须有 phase-type 赋值且赋值必须是六个合法槽位之一。2.4 合法取值models.phase_type只接受档位别名tier alias不接受完整模型 ID取值效果opus标准档位——运行时解析会将该阶段 Agent 映射到当前活跃运行时的 Opus 档模型sonnet标准档位——映射到活跃运行时的 Sonnet 档模型haiku标准档位——映射到活跃运行时的 Haiku 档模型inherit该阶段 Agent 跟随会话模型语义与model_profile: inherit一致重要限制如果你需要完整模型 ID例如openai/gpt-5、google/gemini-2.5-pro不要写在models.*里而应使用按 Agent 的model_overrides。models.*刻意设计为仅档位目的是保证在 Codex / OpenCode / Antigravity CLI 等非 Claude 运行时上运行时感知runtime-aware的档位映射依然正确——完整 ID 会破坏这种跨运行时可移植性。该限制在源码中有对应的硬性守卫computeProfileTiersrc/model-resolver.cts读取config[models][phaseType]后用VALID_TIERS.has(phaseTypeTier)校验——VALID_TIERS由model-catalog.json的adaptiveTierMapheavy→opus、standard→sonnet、light→haiku加inherit派生而来。因此非法档位值会落入 profile 兜底解析不会污染运行时档位解析链。三、解析优先级五层从上到下依次生效models.phase_type处于解析链的第三层。完整的解析优先级从高到低为1. model_overrides[agent] ← 按 Agent可写完整 ID定向例外 2. dynamic_routing.tier_models[tier] ← 启用时生效见 Dynamic Routing 3. models[phase_type] ← 粗粒度阶段级档位本特性 4. model_profile每个 Agent 一列 ← 全局档位策略 5. Runtime default ← 兜底五层自上而下组合model_profile是基础档位models[phase_type]在阶段层面覆盖之dynamic_routing启用时在软失败时按尝试次数升级档位model_overrides[agent]在最顶层雕刻按 Agent 的例外当没有任何一层生效时回落到运行时默认档位。在 2.2 的示例中五个 research Agent 全部解析为sonnet唯独gsd-codebase-mapper被按 Agent 覆盖钉为haiku。dynamic_routing默认关闭——当enabled: false或整块省略时本节行为与未引入该特性之前完全一致。3.1 优先级在源码中的落地位置resolveModelInternalsrc/model-resolver.cts严格按上述顺序实现Step 1读取config[model_overrides]命中即返回Claude 运行时还会经mapClaudeOverrideForRuntime把完整 Claude ID 折叠回档位别名Step 2computeProfileTier(config, agentType)计算基础档位——其中正是读取config[models][phaseType]并做VALID_TIERS校验、命中则直接返回的阶段级档位未命中才回落到MODEL_PROFILES[agent][profile]Step 2.5model_policy预设provider 中立策略解析Step 3非 Claude 运行时的运行时感知档位映射_resolveRuntimeTierStep 4 / 4.5 / 4.75resolve_model_ids: omit门、Claude 档位覆盖、dynamic_routing.tier_models查询Step 5profile 兜底查询最终输出档位别名或inherit。其中步骤 4.75 的注释明确引用了特性文档的优先级约定model_overrides永远优先dynamic_routing.tier_models[tier]解析在models.phase_type与model_profile之上。因此dynamic_routing.tier_models恰好落在本特性与 profile 之间与 3 的优先级表完全对应。3.2 关键语义细节phase-type 优先于 profileinherit一个容易被忽视的语义models[phase_type]优先于model_profile: inherit。修复前的缺陷是当model_profileinherit且models.executionopus时profile 的短路逻辑先于阶段级覆盖触发导致gsd-executor错误解析为inherit违反models[phase_type] 高于 model_profile的文档约定。该缺陷在测试 tests/model-resolver.test.cjs 中以CR Major级别回归锁定test(phase-type override wins over profileinherit (CR Major) — model resolver, () { writeConfig(projectDir, { model_profile: inherit, models: { execution: opus }, }); // gsd-executor (execution) must get the phase-type opus, not inherit. assert.equal(resolveModelInternal(projectDir, gsd-executor), opus); });同时没有设置槽位的 Agent 在model_profile: inherit下仍然继承会话模型两条规则互不干扰。四、校验规则schema 拒绝、解析器宽容4.1config-set命令侧严格校验通过gsd config-set写入配置时schema 严格拒绝未知阶段类型$ gsd config-set models.deployment opus Error: models.deployment is not a valid config key # 合法写法 $ gsd config-set models.research sonnet错误信息来自config-schema的isValidConfigKey校验对应需求 REQ-PHASE-MODELS-01六个命名models.*槽位被config-schema接受config-set拒绝未知阶段类型。4.2 直接编辑配置文件侧宽容兜底直接手改.planning/config.json则宽松得多解析器遇到不认识的取值会静默忽略并回落到 profile 档位而不是报错中断。因此一个笔误如haiku3不会悄悄破坏档位解析。这是文档与测试共同确认的行为测试unrecognized tier value falls through to profile (typo safety)models: { research: haiku3 }落到balanced档位的sonnet测试full model ID in models.phase_type is rejected; falls through to profilemodels: { research: openai/gpt-5 }同样回落不会把完整 ID 注入运行时档位解析链。两种校验策略各有分工CLI 入口config-set严格到拒绝即报错配置文件入口宽容到坏值即回落保证既有配置在升级后行为不变。五、向后兼容保证没有models块时行为逐字节不变特性需求 REQ-PHASE-MODELS-02 明确要求未包含models块的配置行为与 v1.41 之前逐字节一致。这一点由源码的读取方式与测试双重保证computeProfileTier中configModels为空或phaseType未命中时phaseTypeTier为undefinedVALID_TIERS.has(undefined)为 false直接进入 profile 查询分支——整体行为等同于没有models配置测试empty models block is a no-op与no models block at all is a no-op分别验证models: {}和完全省略models两种情形下gsd-phase-researcher仍解析为sonnet、gsd-planner仍解析为opus与balancedprofile 默认一致。这一缺省即无感的设计让存量项目无需任何迁移即可升级到 v1.41。六、实战如何选择配置粒度官方文档给出了一张按需求选工具的对照表可直接作为日常决策依据你的诉求使用一个全局档位策略处处 balancedmodel_profile粗粒度阶段级调参规划用 Opusmodels.phase_type按 Agent 精确控制强制 codebase mapper 用 haikumodel_overrides[agent]为某个特定 Agent 指定完整模型 IDmodel_overrides[agent]: openai/gpt-5这些方式可以自由混用——只要符合第三节的五层优先级规则任何重叠都会被确定性地解析不存在歧义。典型成本分配实践规划与讨论阶段是需要深度推理的重脑力环节gsd-planner、gsd-roadmapper、gsd-assumptions-analyzer等 Agent 在model-catalog.json中本就归属heavy默认档位可以用models.planning: opus、models.discuss: opus保证质量research / verification 属于高吞吐的标准负载用models.research: sonnet、models.verification: sonnet控制成本如果某个高频低风险的 Agent如gsd-codebase-mapper想进一步省钱再用model_overrides钉到haiku。三层配合即可在质量—成本—精确度三角中自由取点。七、相关能力与阅读路径本文的权威长文档Per-Phase-Type Modelsdocs/CONFIGURATION.md包含完整的配置示例、取值表、优先级表与校验示例配置项速查表settings-managementdocs/features/settings-management.md实现源码src/model-resolver.ctscomputeProfileTier、resolveModelInternal为核心读取与解析点、src/model-catalog.ctsAGENT_TO_PHASE_TYPE、VALID_PHASE_TYPES、VALID_TIERS的派生来源、gsd-core/bin/shared/model-catalog.jsonphaseTypes、每个 Agent 的phaseType元数据Schema 校验来源gsd-core/bin/shared/config-schema.manifest.jsonmodels.phase_type动态键模式回归测试tests/model-resolver.test.cjs#3023系列阶段级覆盖、per-agent 优先、typo 回落、inherit 语义、空块 no-op、CR Major 修复等。如果你需要与失败时自动升级档位组合使用可进一步阅读 Dynamic Routing with Failure-Tier Escalationdocs/CONFIGURATION.md 中的dynamic_routing章节——它定义了tier_models[tier]如何在models.phase_type之上生效以及max_escalations、escalate_on_failure等配套参数。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core 按阶段类型Phase-Type配置模型选择.planning/config.json 的 models 块深入解析gsd core 按阶段类型Phase Type配置模型选择 .planning/config.json 的 models 块深入解析 导读 gsd coGSD 模型选择与动态路由完全指南按阶段选模型、配置兜底与跨供应商成本优化GSD 模型选择与动态路由完全指南按阶段选模型、配置兜底与跨供应商成本优化 本篇技术指南围绕 GSDspec driven development 系统的人工智能AI Agent代码智能体Agent 编排CLIAI 应用gsd-core 分阶段粒度覆盖granularities.phaseType配置指南按阶段类型精细调控规划粒度gsd core 分阶段粒度覆盖granularities.phaseType 配置指南按阶段类型精细调控规划粒度 本指南围绕 gsd core 的 g文档教程上一篇Rampart安全审计深入分析系统的隐私保护能力和局限性下一篇Nightwatch.js 跨平台测试Windows/macOS/Linux 兼容性保障创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考