GSD 动态模型路由深度解析：以任务复杂度分级为核心的长时段自主 Token 优化方案

人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本文以 GSD 仓库中的设计方案文档 .plans/issue-575-dynamic-model-routing.md 为主体骨架系统讲解其核心概念——按任务复杂度将工作路由到不同档位模型的动态模型路由Dynamic Model Routing机制。文章覆盖问题背景、复杂度三级分级、分类信号、路由流水线、六大设计决策、分阶段实现路线、PREFERENCES 配置、风险缓解与预估节省并结合仓库中已落地的源码实现complexity-classifier.ts、model-router.ts、routing-history.ts等与测试用例进行印证。读完本文你将掌握该方案从设计蓝图到源码落地的完整脉络并能够独立理解与配置dynamic_routing相关偏好项。一、问题背景固定套餐下的 Token 消耗失衡方案文档开篇直指一个真实的痛点使用 Claude Pro 等固定额度套餐capped plans的用户在 GSD 上持续运行 15-20 小时后就会耗尽每周 Token 额度。其根因在于当前的模型选择是粗粒度静态的单一模型贯穿整个阶段GSD 在每个阶段research / planning / execution / completion只使用一个静态配置的模型简单任务与复杂任务消耗相同一个读取文件 汇总的轻量单位unit与一个跨多文件重构的重型单位使用同一个模型费用自然没有差异。于是简单任务浪费昂贵 Token、复杂任务又得不到更强模型成为主要矛盾。动态模型路由正是为解决该矛盾而设计在每个单位调度前先评估任务复杂度再路由到匹配档位的模型。二、现有架构基础动态路由的天然落地点方案文档首先盘点既有能力说明动态路由并非从零建设而是架设在以下基础设施之上现有能力位置按计划文档角色阶段级模型配置PREFERENCES.mdresearch/planning/execution/completion 各阶段独立模型路由的天花板来源回退链 fallbacks每个阶段支持fallbacks: [model1, model2]错误恢复时的候选序列预调度钩子PreDispatchResult.model字段已定义但从未生效现成的扩展点计划文档特别强调ready-made extension point模型注册表ModelRegistry.getAvailable()提供全部已配置模型及其元数据单位级指标每个单位记录 input/output/cacheRead/cacheWrite、成本与模型供节省统计与观测预算执行实时成本跟踪75%/90%/100% 告警供预算压力感知路由复用关键伏笔计划文档明确指出PreDispatchResult上的model字段defined but unused将其列为 1e 阶段的工作项。这一设计在后续实现中演化为before_model_select扩展钩子见后文源码落地章节。三、核心设计任务复杂度三级分级动态路由的枢纽是一个复杂度分类器。在每个单位调度之前将任务划分为三个复杂度档位再据此路由模型档位复杂度典型任务默认模型Tier 1 — Light轻量低认知负荷、结构化输出文件读取、搜索聚合、简单摘要、completion/summary 单位Haiku 或当前可用最便宜模型Tier 2 — Standard标准中等推理、一定创造性研究综合、计划格式化、常规代码生成、UAT 检查Sonnet 或中档模型Tier 3 — Heavy重型复杂推理、架构设计、全新代码复杂执行任务、重新规划replan、多文件重构、调试Opus 或用户配置的主模型分类器位于偏好解析与模型调度之间其最关键约束是它只能降级downgrade绝不能突破用户配置的模型向上升级——用户的偏好永远是天花板。四、分类信号无需 LLM 调用的纯启发式设计决策第 4 条明确提出分类不调用 LLM——为了省 Token 反而多一次 LLM 调用是南辕北辙。分类依赖三类可在调度前获得的启发式信号1. 单位类型最强信号单位类型归入档位complete-slice、run-uatTier 1结构化总结research-milestone、research-sliceTier 2综合plan-milestone、plan-sliceTier 2-3视范围而定execute-taskTier 2-3视任务复杂度而定replan-sliceTier 3需要理解失败原因2. 任务元数据针对执行类单位预计改动的代码行数来自任务计划涉及的文件数量依赖数量是否新建文件 vs 修改既有文件存在时读取标签/标记如refactor、test、docs。3. 历史表现自适应学习Phase 2若此前在相似任务上 Tier 2 模型失败并升级过则默认提升至 Tier 3按档位 × 单位类型模式跟踪成功率。五、路由流水线架构计划文档给出了完整的处理流程User Preferences (phase → model) │ ▼ resolveModelWithFallbacksForUnit() ← 既有逻辑 │ ▼ classifyUnitComplexity() ← 新增返回 Tier 1/2/3 │ ▼ resolveModelForTier() ← 新增档位 → 可用模型映射 │ ▼ maybeDowngradeModel() ← 新增只能从用户配置模型向下降级 │ ▼ Model dispatch (既有 auto 调度逻辑)这一流水线在源码中的真实形态src/resources/extensions/gsd/auto-model-selection.ts与此高度一致先resolveDynamicRoutingConfig()读取配置再classifyUnitComplexity()分类、resolveModelForComplexity()路由最终得到带routing: { tier, modelDowngraded }元数据的ModelSelectionResult交给调度层。六、六大关键设计决策仅降级Downgrade-only分类器只能选择比用户配置更便宜的模型用户偏好是上限默认关闭、显式开启Opt-in新增偏好键dynamic_model_routing: true|false默认false。想省 Token 的用户显式开启最终落地时偏好键采用dynamic_routing见后文配置章节失败自动升级Escalation on failure低档模型失败工具错误、输出不完整、超过重试次数时自动升档重试该单位分类不调用 LLM仅用启发式避免为省 Token 反而烧 Token尊重既有回退链动态路由与现有fallbacks集成——动态选出的模型失败时先走既有回退链再考虑升档对用户透明Dashboard 展示选中模型与原因进度组件中显示档位徽标。七、实现路线图四个阶段Phase 1地基——复杂度分类器与路由核心子项文件内容1a 类型与配置src/resources/extensions/gsd/types.tsComplexityTierlight | standard | heavyDynamicRoutingConfig接口enabled、tier_models.{light,standard,heavy}、escalate_on_failure1a 偏好src/resources/extensions/gsd/preferences.ts增加dynamic_routing偏好 schema、配置校验、loadDynamicRoutingConfig()1b 分类器新文件complexity-classifier.tsclassifyUnitComplexity(unitType, unitId, metadata?)单位类型映射任务计划解析文件数、预估范围依赖数 ≥ 3 → heavy导出getClassificationReason()供 Dashboard 展示1c 路由新文件model-router.tsresolveModelForComplexity(tier, phaseConfig, availableModels)先取用户配置模型作天花板有tier_models则用档位专属模型否则按light 取最便宜、standard 取中档、heavy 取配置模型的智能默认校验可用性返回回退链[tier_model, ...configured_fallbacks, configured_primary]1d 接入调度auto.ts模型解析块中先resolveModelWithFallbacksForUnit()再调用分类器开启时经路由降级记录档位与模型到 metrics单位失败时若使用了降级模型则升档重试1e 启用未用的钩子auto.ts应用preDispatchResult.model返回值让钩子可以覆盖动态路由决策配套测试计划列出三份新测试文件complexity-classifier.test.ts各单位类型的档位分配、元数据调整文件数、依赖数、边界情况缺失元数据、未知单位类型model-router.test.ts仅降级行为绝不超出配置模型、多模型集合下的档位映射、回退链构造、关闭动态路由时的直通passthroughdynamic-routing-integration.test.ts完整链路 单位→分类→路由→调度、失败升级、偏好加载与校验。Phase 2可观测性与 Dashboardmetrics 增强metrics.tsUnitMetrics增加tier、model_downgraded、escalation_count字段新增aggregateByTier()与formatTierSavings()展示降级节省估算Dashboard 集成auto-dashboard.ts单位进度显示档位徽标[L]/[S]/[H]完成统计中输出Dynamic routing saved ~$X.XX (N units downgraded)Token 组件中按档位着色。Phase 3自适应学习未来按档位 × 单位类型模式跟踪成败存储于项目级.gsd/routing-history.json简单结构示例{ execute-task:docs: { light: { success: 12, fail: 1 }, ... } }某档位对某模式的失败率 20% 时自动提升默认档位旧数据按最近 50 个单位的滚动窗口衰减用户可在偏好中设dynamic_routing_reset: true重置学习数据。Phase 4任务计划内省未来解析任务计划 Markdown 提取复杂度信号新建文件 vs 修改既有文件、计划中的代码块数量、关键词refactor/migration/architecture/test/docs/config、估算变更行数与单位类型启发式加权融合。八、用户侧配置PREFERENCES 中的 dynamic_routing计划文档给出的完整配置示例--- version: 1 models: research: claude-sonnet-4-6 planning: claude-opus-4-6 execution: claude-sonnet-4-6 completion: claude-sonnet-4-6 dynamic_routing: enabled: true tier_models: light: claude-haiku-4-5 standard: claude-sonnet-4-6 # heavy: 继承自阶段配置天花板 escalate_on_failure: true ---注计划正文中偏好键写作dynamic_model_routing而配置示例与实际落地统一采用dynamic_routing仓库偏好参考文档 src/resources/extensions/gsd/docs/preferences-reference.md 中的定义即以dynamic_routing为准。tier_models中的模型 ID 支持provider/model前缀形式如openrouter/minimax/minimax-m2.5实际匹配时会剥离前缀做兼容比较。在计划中四个追加设计决策全部以 YES 采纳纳入扩展范围形成更新后的配置形态--- version: 1 models: research: claude-sonnet-4-6 planning: claude-opus-4-6 execution: claude-sonnet-4-6 completion: claude-sonnet-4-6 dynamic_routing: enabled: true tier_models: light: claude-haiku-4-5 standard: claude-sonnet-4-6 # heavy: 继承自阶段配置天花板 escalate_on_failure: true budget_pressure: true # 预算越接近上限降级越激进 cross_provider: true # 跨提供商按成本选模型 hooks: true # 钩子单位也参与分类 ---九、风险缓解矩阵计划文档为每个主要风险都给出了对治手段风险缓解措施便宜模型产出低质量结果仅降级设计失败即升档用户可随时关闭分类带来额外延迟纯启发式、无 LLM 调用分类耗时 1ms复杂偏好把用户绕晕默认关闭开启后零配置即可工作用智能默认值用户提供商没有目标模型偏好加载时校验缺失则回退到配置模型升级死循环每个单位最多升级 1 次之后直接用配置模型十、预估 Token 节省基于典型 GSD 会话模式的结构估算约 30% 单位属于 completion/summaryTier 1 候选约 40% 属于 research/常规 planningTier 2 候选约 30% 属于复杂执行Tier 3不降级。若 Haiku 约为 Opus 的 1/10 价格、Sonnet 约为 Opus 的 1/5保守估计开启动态路由后成本降低 20-30%激进估计对含大量小任务的项目可达 40-50%。仓库配套的官方用户文档 docs/user-docs/dynamic-model-routing.md 亦给出在固定套餐上减少 20-50% Token 消耗的目标描述作为对照。十一、四个追加设计决策Resolved Design Decisions1. 钩子单位也参与分类 —— YES钩子获得独立的复杂度分类。多数钩子是轻量操作校验、文件检查应默认归入 Tier 1PostUnitHookConfig上既有的model字段成为天花板与单位阶段的模型语义一致。实现上扩展classifyUnitComplexity()以接受钩子元数据并接入钩子调度路径。2. 预算压力感知路由 —— YES随着预算使用率上升分类器对降级变得激进预算使用行为 50%正常分类50-75%尽可能将 Tier 2 候选压到 Tier 175-90%只有 Tier 3 任务用配置模型其余全部用最便宜可用模型 90%除replan-slice外全部降级到最便宜实现上classifyUnitComplexity()接收budgetPct参数复用既有getBudgetAlertLevel()逻辑新增applyBudgetPressure(tier, budgetPct)调整档位。3. 多提供商成本路由 —— YES配置了多个提供商如 Anthropic 与 OpenRouter 并存时路由器应比较成本差异为解析出的档位挑选最便宜选项。实现要点为模型注册表补充cost_per_1k_tokens元数据或维护已知模型查询表新文件model-cost-table.ts——已知模型的静态成本表可通过偏好更新resolveModelForComplexity()在档位能力范围内按成本排序可用模型偏好键dynamic_routing.cross_provider: true|false开启时默认true风险成本数据会过期——通过随 GSD 版本更新的内置成本表 用户覆盖能力缓解。4. 用户反馈闭环 —— YES每个单位完成后用户可标记输出质量以改进后续分类单位后提示/gsd:rate-unit [over|under|ok]over 本可用更简单的模型 → 记录降级信号under 本需要更好的模型 → 记录升级信号ok 确认当前档位合适反馈与结果数据一并存入.gsd/routing-history.json分类器对反馈信号的权重是自动成败检测的2 倍。十二、源码级实现印证从计划到落地这份计划文档并非停留在纸面——仓库中已能找到完整实现与配套测试可以作为理解计划的最佳参照物。12.1 复杂度分类器complexity-classifier.ts类型与计划完全一致export type ComplexityTier light | standard | heavyClassificationResult携带tier、reason、downgraded、taskMetadata单位类型映射表UNIT_TYPE_TIERS在落地时做了更精细的取舍run-uat→ lightcomplete-slice→ standard注释说明 #4520slice 完成可能携带大量内联上下文默认不应路由到最便宜的 light 模型plan-milestone/plan-slice/replan-slice/reassess-roadmap→ heavyexecute-task默认 standard、由元数据升级任务复杂度分析阈值依赖数 ≥ 3、文件数 ≥ 6、估算行数 ≥ 500、复杂度关键词 ≥ 2、计划代码块 ≥ 5 → heavy单个复杂度关键词 → standarddocs/readme/comment/config/typo/rename标签、单文件修改 → light计划级分析milestone 级规划恒为 heavyRESEARCH.md超过 200 行 → heavy钩子单位hook/*前缀默认 light全程调用applyBudgetPressure(result, budgetPct)施加预算压力tierLabel()输出L/S/H对应 Dashboard 徽标tierOrdinal()提供档位排序比较。12.2 模型路由器model-router.tsDynamicRoutingConfig在计划基础上增加了capability_routing与allow_flat_rate_providers后者默认false保留 #3453 的绕过逻辑——按请求计费一致的固定费率提供商如 claude-code、GitHub Copilot默认不参与路由因为降级只会损失质量而省不下钱需要按任务跨模型选择如 haiku 做研究、opus 做架构时经 #4386 显式开启MODEL_CAPABILITY_TIER把已知模型 ID 映射到档位如claude-haiku-4-5→ light、claude-sonnet-4-6→ standard、claude-opus-4-6→ heavy供未显式配置 tier_models 时选档MODEL_COST_PER_1K_INPUT内置成本表近似 USD/1K input tokens用于跨提供商成本比较MODEL_CAPABILITY_PROFILES每个模型的 7 维能力画像0-100——coding、debugging、research、reasoning、speed、longContext、instructionBASE_REQUIREMENTS每类单位对能力维度的权重需求如execute-task为 coding 0.9 / instruction 0.7 / speed 0.3research-*为 research 0.9 / longContext 0.7 / reasoning 0.5resolveModelForComplexity()完整实现了计划中的仅降级语义无阶段配置或路由关闭 → 直通配置模型不在已知档位表中 →尊重显式配置、不擅自降级#2192 的回归修复请求档位 ≥ 配置档位 → 原样使用配置模型若配置模型在当前 provider 不可用则按cross_provider在同档位内找跨提供商等价物请求档位低于配置档位 → 取档位内可用模型集开启capability_routing且候选多于一个时做能力打分选优否则取最便宜回退链恒为[选中模型, ...用户配置的 fallbacks, 配置主模型]buildFallbackChain去重保序escalateTier()light → standard → heavy → null落实每个单位最多升档一次scoreModel()加权平均公式score Σ(weight × capability) / Σ(weights)scoreEligibleModels()排序时两分以内取便宜者、成本相同按模型 ID 字典序决胜确定性computeTaskRequirements()execute-task结合元数据细化需求向量——docs/config/readme标签提升 instruction 权重concurrency/compatibility关键词提升 debugging 与 reasoningmigration/architecture提升 reasoning 与 coding文件数 ≥ 6 或行数 ≥ 500 提升 coding 与 reasoning。12.3 自适应学习routing-history.ts数据文件.gsd/routing-history.jsonversion: 1按模式键如execute-task:docs存储 light/standard/heavy 三档的{ success, fail }常量与计划逐条对应ROLLING_WINDOW 50每模式最近 50 条、FAILURE_THRESHOLD 0.2020% 失败率触发升档、FEEDBACK_WEIGHT 2反馈信号权重 2 倍recordOutcome()同时记录基础模式与标签模式getAdaptiveTierAdjustment()供分类器在分类时查询历史加成仅在调整后的档位更高时才生效用户反馈命令落地于 commands-rate.ts/gsd rate over|ok|under对最近完成的单位调用recordFeedback()写入routing-history.json。12.4 观测与指标metrics.tsUnitMetrics携带tier?: string与modelDowngraded?: booleanaggregateByTier()按档位聚合单位数、Token、成本与降级数formatTierSavings()输出类似Dynamic routing: N/M units downgraded (X%), cost: $Y的节省摘要与计划中 Dashboard 文案设计一致。12.5 测试验证仓库测试目录中已有与本方案一一对应的测试model-router.test.ts覆盖关闭时直通、档位匹配时不降级、Opus → Haiku 降级light 档、Opus → Sonnet 降级standard 档、回退链包含配置主模型兜底等核心语义dynamic-routing-default.test.ts验证defaultRoutingConfig()默认开启enabled、escalate_on_failure、budget_pressure、cross_provider、hooks——即开启后零配置即可工作的设计另有capability-router.test.ts、routing-history.test.ts、flat-rate-routing-guard.test.ts、interactive-routing-bypass.test.ts、auto-model-selection.test.ts等分别覆盖能力打分、学习逻辑、固定费率守卫与调度接线。说明计划文档中标注的auto.ts内联行号如 1791-1879、936-946属于当时的草稿参照在当前仓库中模型选择逻辑已收敛到独立的 auto-model-selection.tsresolveDynamicRoutingConfig()、classifyUnitComplexity()、resolveModelForComplexity()、escalateTier()、filterToolsForProvider()在此完成装配并受session-model-override.ts、blocked-models.ts、UOK 模型策略等旁路约束。12.6 扩展钩子计划未生效字段的最终形态计划 Phase 1e 设想的启用PreDispatchResult.model字段在实现中进化为before_model_select扩展钩子详见 docs/user-docs/dynamic-model-routing.md触发时机档位过滤之后、能力打分之前此时eligibleModels已知、分数尚未计算事件载荷含unitType、unitId、classification、taskMetadata、eligibleModels、phaseConfig返回{ modelId }即覆盖选择返回undefined则继续走能力打分多个扩展注册时首个非 undefined 返回生效。十三、与 Token Profiles 的协同计划之外的配套文档进一步厘清了定位动态路由与 token profiles 互补——token profilesbudget/balanced/quality控制阶段跳过与上下文压缩动态路由控制阶段配置模型之内的单位级模型选择。两者同时启用时profiles 设定基线模型动态路由在基线内进一步优化budgetprofile 动态路由组合提供最大成本节省。此外token profiles 与动态路由共用同一套档位映射profile 声明的档位意图会解析到当前已配置提供商实际可用的模型因此一个budgetprofile 也可能最终解析到 OpenAI、Gemini 而非 Claude 家族默认值。参考文件方案文档.plans/issue-575-dynamic-model-routing.md官方用户文档docs/user-docs/dynamic-model-routing.md偏好参考含完整配置示例src/resources/extensions/gsd/docs/preferences-reference.md核心实现complexity-classifier.ts、model-router.ts、routing-history.ts、auto-model-selection.ts、metrics.ts用户反馈命令commands-rate.ts测试model-router.test.ts、dynamic-routing-default.test.ts赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐Viewer.js图像查看器完全指南7个高频需求逐个拆解Viewer.js图像查看器完全指南7个高频需求逐个拆解 网页上放一张 img 很简单但用户点开后常常看不过瘾想放大看细节要自己写缩放逻辑想切换下人工智能AI Agent代码智能体Agent 编排CLIAI 应用GoogleTranslateIpCheck算法复杂度分析IP段解析的时间复杂度优化GoogleTranslateIpCheck算法复杂度分析IP段解析的时间复杂度优化 还在为Google翻译访问缓慢而烦恼GoogleTranslateIpCLI网络深度解析DolphinScheduler任务优先级公平调度核心机制深度解析DolphinScheduler任务优先级公平调度核心机制 你是否曾遇到过数据任务拥堵、关键流程迟迟不执行的情况在大规模数据处理场景中任务调度的公任务调度大数据后端前端上一篇终极mpv播放器配置指南如何快速打造专业级命令行媒体播放体验下一篇B站视频下载神器BiliDownloader3分钟掌握下载技巧与常见问题解决创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考