【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载导读本文围绕 gsd-core 的dynamic_routing配置块位于项目根目录.planning/config.json讲解如何实现默认使用廉价模型、仅在编排器检测到软失败时自动升级到更强模型的成本控制策略。读完本文你将掌握dynamic_routing的完整配置语法、三级light / standard / heavy分层规则、升级链路与封顶机制、与model_overrides/models.phase_type的优先级组合方式以及从源码层理解新解析器resolveModelForTier(cwd, agent, attempt)的工作原理。功能背景为什么需要按失败升级的模型路由gsd-core 是一个多 Agent 编排系统见 docs/explanation/multi-agent-orchestration.md在规划、研究、执行、验证等各阶段会多次派生出不同职责的 Agentgsd-executor、gsd-codebase-mapper、gsd-planner等。传统做法是为所有 Agent 固定一个模型档位但这存在明显浪费大量低风险任务代码库扫描、文档分类、模式映射只需廉价模型即可完成只有验证结论存疑、计划检查返回 FLAG 等软失败场景才需要更强模型重试。dynamic_routing正是为此设计先按廉价档位起跑编排器发现软失败后逐级升级从而在保持结果质量的同时压低模型成本。该特性源自 issue #3024其变更说明记录于 .changeset/archived/dynamic-routing.md完整功能文档见 docs/features/dynamic-routing-with-failure-tier-escalation.md。配置总览.planning/config.json中的dynamic_routing块dynamic_routing配置块必须写在项目根目录的.planning/config.json中完整示例来自 docs/CONFIGURATION.md{ dynamic_routing: { enabled: true, tier_models: { light: haiku, standard: sonnet, heavy: opus }, escalate_on_failure: true, max_escalations: 1 } }该块的核心行为可概括为enabled: false默认值或整块缺失时特性完全关闭所有 Agent 沿用原有解析链路行为零变化向后完全兼容enabled: true时解析器为首次派生first spawn选取tier_models[default_tier]当编排器检测到软失败后每次重试向上一档升级升级次数由max_escalations封顶。配置项说明类型、默认值与取值范围Key类型默认值说明dynamic_routing.enabledbooleanfalse总开关。为true时启用动态路由解析器进行档位选择dynamic_routing.tier_models.lightenum无light 档模型别名通常为haikudynamic_routing.tier_models.standardenum无standard 档模型别名通常为sonnetdynamic_routing.tier_models.heavyenum无heavy 档模型别名通常为opusdynamic_routing.escalate_on_failurebooleantrue置为false时禁用升级无论尝试次数如何每次重派生都使用默认档模型dynamic_routing.max_escalationsinteger1每次 Agent 调用的升级硬上限。超过上限后解析器返回上限档模型同时约束下方的 provider 阶梯dynamic_routing.provider_escalationstring[]无可选配额/限流时按顺序尝试的备用模型 ID 列表v1.43 新增配置默认值同时固化在 src/configuration.ctsCONFIG_DEFAULTS中dynamic_routing: null并在 docs/CONFIGURATION.md 的参数表中逐一登记方便查阅。三层档位与 Agent 默认档light / standard / heavy每个 Agent 在模型目录中声明一个默认路由档位routingTier。首次派生时解析器取tier_models[default_tier]。当前仓库中的 Agent 默认档位分布依据 gsd-core/bin/shared/model-catalog.json 与 docs/CONFIGURATION.md 的整理档位代表 Agent适用场景lightgsd-codebase-mapper、gsd-doc-classifier、gsd-doc-verifier、gsd-integration-checker、gsd-intel-updater、gsd-nyquist-auditor、gsd-pattern-mapper、gsd-plan-checker、gsd-research-synthesizer、gsd-ui-auditor、gsd-ui-checker廉价/快速——纯映射、扫描、低风险审计standardgsd-advisor-researcher、gsd-ai-researcher、gsd-code-fixer、gsd-code-reviewer、gsd-doc-synthesizer、gsd-doc-writer、gsd-domain-researcher、gsd-eval-auditor、gsd-executor、gsd-phase-researcher、gsd-project-researcher、gsd-ui-researcher、gsd-verifier默认主力——研究、写作、常规验证heavygsd-assumptions-analyzer、gsd-debug-session-manager、gsd-debugger、gsd-eval-planner、gsd-framework-selector、gsd-planner、gsd-roadmapper、gsd-security-auditor、gsd-user-profiler深度推理——已处于顶级无法再升级档位与模型别名的映射在 gsd-core/bin/shared/model-catalog.json 中由adaptiveTierMap声明heavy → opus、standard → sonnet、light → haiku。运行时代默认值如 claude 下的claude-opus-4-8等完整模型 ID由runtimeTierDefaults提供。在源码层这些映射被加载为可用的数据结构src/model-catalog.cts 中VALID_AGENT_TIERSL88、AGENT_DEFAULT_TIERSL118、MODEL_PROFILESL105全部由该 JSON 目录推导生成保证目录与解析器档位门槛永不失配。升级流程从首次派生到软失败重试升级链路可抽象为以下流程来自 docs/CONFIGURATION.md 的 Escalation flow1. Orchestrator spawns agent → resolver returns tier_models[default_tier] 2. Soft failure? ├─ no → ✓ done (cheap path) └─ yes → orchestrator re-spawns at attempt1 → resolver returns tier_models[next_tier_up] → cap at max_escalations 3. Hard failure (exception/crash) → bypass escalation, surface immediately关键规则说明**软失败soft failure**包括验证结论存疑verification inconclusive、计划检查返回 FLAG 等编排器可检测到的非致命失败硬失败异常/崩溃则绕过升级链路立即上报升级步长固定为一档light → standard → heavy → heavyheavy 已到顶不再上移该顺序由 src/model-catalog.cts 的nextTier()L223-L228实现export function nextTier(currentTier: string): string | null { const order [light, standard, heavy]; const idx order.indexOf(String(currentTier)); if (idx -1) return null; return order[Math.min(idx 1, order.length - 1)]; }escalate_on_failure: false是杀开关即使enabled: true软失败也不会推进档位每次重派生仍使用tier_models[default_tier]max_escalations封顶整个升级链防止成本失控。在 src/model-resolver.cts 的dynamicRoutingModel()L772-L804中attempt被Math.min(attempt, maxEscalations)截断后再逐档上移因此超过上限的尝试会停留在上限档模型。解析优先级dynamic_routing在模型解析链中的位置dynamic_routing不是独立的解析体系而是插入到既有解析链的固定位置。完整优先级高 → 低model_overrides[agent]——支持完整模型 ID是逐 Agent 的定点例外永远最高优先dynamic_routing.tier_models[tier]——当enabled: true时生效models[phase_type]——按阶段类型的粗粒度调优model_profile——按活跃 profile 的逐 Agent 档位列运行时代默认值。即model_overrides始终胜出dynamic_routing.tier_models[tier]高于models.phase_type与model_profile。该组合关系在 docs/features/dynamic-routing-with-failure-tier-escalation.md 中被明确文档化并在 src/model-resolver.cts 的resolveModelInternal()中以第 4.75 步的形式落地L673-L691它位于model_overrides第 1 步、model_policy预设第 2.5 步、运行时档位表第 3 步、resolve_model_ids:omit门第 4 步、claude 档位覆盖第 4.5 步之后而位于 profile 查询第 5 步之前。这一精确插位是刻意的dynamicRoutingModel()返回的档位模型必须仍然尊重所有更高优先级层例如resolve_model_ids:omit门在非 claude 运行时本应返回空串避免动态路由绕过既有护栏。核心解析器resolveModelForTier(cwd, agent, attempt)dynamic_routing为编排器集成新增的解析器是resolveModelForTier(cwd, agent, attempt)。其实现位于 src/model-resolver.ctsL809-L835调用关系如下读取项目配置loadConfig(cwd)对attempt做归一化非正整数视为 0即首次派生先检查model_overrides[agent]——若存在则直接返回映射后的模型claude 运行时将完整 ID 映射回 Agent 工具别名若配置了model_policy且当前活动运行时非 claude则回退到resolveModelInternal的既有逻辑否则调用dynamicRoutingModel(config, agentType, attemptN)命中则返回对应档位模型未命中未启用/无档位表/Agent 无默认档时回退到resolveModelInternal行为与关闭动态路由时完全一致。值得强调的是attempt 0表示尚未升级对应文档化的首次派生场景而不是跳过动态路由。resolveModelForTier是编排器集成的唯一调用点保证了首次派生值与升级值来自同一实现不会出现生成式修复发散generative fix divergence。与编排器的集成resolve-execution命令与测试验证编排器侧的实际调用体现在gsd-tools resolve-execution命令中。src/commands.cts 的cmdResolveExecution通过resolveModelForTier(cwd, agentType, opts.attempt)解析模型从而使--attempt参数不仅影响推理努力effort也能驱动模型档位升级。这一行为由 tests/resolve-execution-dynamic-routing.test.cjs 提供回归覆盖gsd-executor默认档standardattempt 0 → sonnet、attempt 1 → opus一次升级到 heavy、attempt 2/3 → opus默认max_escalations: 1封顶gsd-codebase-mapper默认档light升级链更长attempt 0 → haiku、attempt 1 → sonnet、attempt 2 → opus恰好达到max_escalations: 2、attempt 3 → opus不越过上限未配置dynamic_routing时attempt对模型解析无影响验证了向后兼容性dynamic_routing启用但未传--attempt时模型仍走经典 profile 路径sonnet与 effort 的语义对称。进阶provider 配额升级阶梯v1.43档位阶梯只在同一提供商内部升级当提供商本身被限流quota/rate limit时更高档位仍被限流。为此 v1.43 引入provider_escalation一个独立的、可选的备用模型 ID 列表见 docs/CONFIGURATION.md{ dynamic_routing: { enabled: true, tier_models: { light: haiku, standard: sonnet, heavy: opus }, provider_escalation: [gpt-5, nvidia/llama-3.3], max_escalations: 2 } }当执行器失败且gsd-tools agent classify-failure将错误分类为quota-exceeded时execute-phase从该列表重新解析模型记录切换日志如sonnet → gpt-5并遵循提供商返回的Retry-After阶梯上限为min(max_escalations, provider_escalation.length)耗尽后 GSD 会报告所有尝试过的模型并回退到人工恢复提示而不是静默重试最后一个该阶梯是可选的不配置时配额失败保持原有的等待重置提示仅针对配额类失败其他失败类别classify-handoff-bug、unknown-failure不咨询此阶梯escalate_on_failure: false同样禁用此阶梯空白与非字符串条目会被丢弃其余顺序保持不变src/model-resolver.cts 的sanitizeProviderEscalation()L859-L862。选型建议四种模型策略如何抉择你的诉求使用所有 Agent 统一档位策略model_profile按阶段类型的粗粒度调优models.phase_type逐 Agent 精确控制支持完整 IDmodel_overrides默认廉价、仅失败时升级dynamic_routingdynamic_routing在结构上是一个成本杠杆只有当难题真正需要强模型时才付出 opus 级成本。它可与model_overrides组合使用override 永远胜出适合为个别 Agent 钉死例外。由于默认关闭存量项目无需任何迁移即可保持既有解析行为完全不变。引用与进一步阅读变更说明.changeset/archived/dynamic-routing.md功能文档docs/features/dynamic-routing-with-failure-tier-escalation.md配置手册docs/CONFIGURATION.mdDynamic Routing 一节核心实现src/model-resolver.ctsresolveModelForTier、dynamicRoutingModel、resolveProviderEscalation目录与档位定义src/model-catalog.cts、gsd-core/bin/shared/model-catalog.json回归测试tests/resolve-execution-dynamic-routing.test.cjs赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐Cloudflare AI Gateway 动态路由Dynamic Routing实战用路由名编排流量、回退与限额Cloudflare AI Gateway 动态路由Dynamic Routing实战用路由名编排流量、回退与限额 动态路由Dynamic Routin人工智能AI 技能AI 插件Mermaid Live Editor免费版在线图表编辑器3 分钟从文本到成品流程图Mermaid Live Editor免费版在线图表编辑器3 分钟从文本到成品流程图 Mermaid Live Editor 是一款免费的在线图表编辑器基前端开发者工具数据可视化Routing Grok CLI through Claude Code RouterProfile 配置、模型路由与多实例实战指南Routing Grok CLI through Claude Code RouterProfile 配置、模型路由与多实例实战指南 Grok CLI 是 x后端API网关LLM 网关大模型上一篇Logisim-evolution项目导出与导入完整教程团队协作最佳实践下一篇Karpenter-Provider-AWS认证准备获取云原生认证的学习资源创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考