企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

本篇文章围绕 gsd-2 项目的模型路由设计展开，系统讲解"为什么要按任务类型分级选择模型"、"如何在真实项目中实现能力感知的路由"以及"如何度量路由带来的成本收益"。读完你可以掌握一套可直接落地的成本-质量权衡框架：从任务分类、模型分级、能力档案评分，到 budget pressure 与 verbose 观测的完整闭环。

核心洞察：质量需求随任务变化，模型却一成不变

绝大多数 Agent 系统存在一个结构性的浪费：不同任务的质量要求差异极大，但系统对所有任务使用同一个模型。

• 一次架构评审出错，错误会级联传导到下游每一个子任务，产生数倍于任务本身的返工成本；
• 一个文档更新或样板代码生成出错，修正成本微乎其微。

用一个"最强的模型"处理全部任务，等价于用旗舰机型完成所有日常琐事；用一个"最便宜的模型"处理全部任务，则会在需要深度推理的关键节点反复烧掉迭代次数。两者都不是最优解。

正确的做法是：按任务类型对模型分层调度——让最强的模型只出现在错误代价最高的环节，让足够胜任的模型处理常规工作，让最小最快的模型处理可预测、低推理深度的任务。

最优模型路由策略：任务类型 → 模型层级对照表

gsd-2 的开发文档中，多套模型（building-coding-agents 系列）对路由策略达成了一致结论。其核心映射关系如下：

这条规则的本质是把模型能力与错误成本对齐：错误代价高的任务（规划、架构、歧义消解）永远走最强模型；错误代价低的任务（摘要、样板代码）用最便宜的模型即可。中段任务（实现、评审、测试）则使用"能力足够"的中层级模型。

非显而易见的成本优化：减少浪费的 Token 比降低 Token 单价更有杠杆

在预算优化的优先级上，原文档给出了一个常被忽略的关键洞察：

减少浪费的 Token 比降低 Token 单价更有杠杆。一个臃肿的上下文窗口在每一次调用上都会产生成本。从上下文组装中裁剪掉 500 个不必要的 Token，在整个项目周期内节省的成本，高于切换到便宜 10% 的模型。

这个结论的理由很直接：模型单价是"一次性谈判"的常量，而上下文体积是"每一次调用"都要付费的变量。一次调用省 500 Token 看似微小，但乘上项目生命周期内的调用次数，其收益会被放大成百上千倍。

因此成本优化应遵循两个方向并行：

1. 控制上下文体积（裁剪冗余内容、压缩历史、精简提示词组装）；
2. 按任务路由模型（让每一次调用都恰好使用"够用"的模型，而不是清一色用旗舰）。

gsd-2 仓库对此有专门的工程化支撑：src/resources/extensions/gsd/context-budget.ts、prompt-cache-optimizer.ts等模块负责上下文裁剪与提示词优化，而路由侧的实现则由能力感知的模型选择承担。

GSD 中的落地实现：能力感知模型路由

gsd-2 将上述策略实现在扩展目录 src/resources/extensions/gsd/model-router.ts 中，并经历了从"复杂度分层"到"能力感知"的演进（设计决策见 ADR-004-capability-aware-model-routing，用户手册见 dynamic-model-routing）。

早期路由器是一维的复杂度分层路由：按复杂度把任务归入 light / standard / heavy 三档，再在档内选最便宜模型。这在"同档模型可互换"的假设下成立，但当用户配置异构 Provider 池（Claude 强在架构与全新实现、Codex 强在调试与根因分析、Gemini 强在长上下文综合与研究型任务、小模型强在廉价验证与轻量 hook）时，同档内不同模型的差异就无法表达了。能力感知路由正是为了解决这一缺口而设计。

两阶段路由管线

每个由 auto-mode 派发的单元都要经过两级选择：

1. 阶段一：复杂度分类——决定任务的档位（light / standard / heavy）；
2. 阶段二：能力评分——在档位内，按"任务需求 × 模型能力"的匹配度对候选模型排序选优。

整条管线的关键不变量是downgrade-only 语义：用户配置的模型永远是天花板，路由只允许向下降级，绝不向上超出用户的配置。

实际解析流程在resolveModelForComplexity()中严格按序执行：

unit dispatch → classifyUnitComplexity(unitType, unitId, basePath, budgetPct) [复杂度分类：单位类型默认档位 → 元数据分析 → 自适应调整 → 预算压力] → resolveModelForComplexity(classification, phaseConfig, routingConfig, availableModelIds) → STEP 1: 过滤出该档位可用的模型（从用户天花板向下，仅降级） → STEP 2: 若启用能力路由且候选多于 1 个： → computeTaskRequirements(unitType, taskMetadata) 动态任务需求向量 → scoreEligibleModels(eligible, requirements) 对候选模型评分 → 选择最高分模型（2 分以内按成本决胜，成本相同按 ID 字典序） → STEP 3: 组装 fallback 链 → resolveModelId() → pi.setModel()

七维能力档案

每个模型都有一份 0–100 的能力档案，覆盖七个维度（MODEL_CAPABILITY_PROFILES）：

interface ModelCapabilities { coding: number; // 全新实现、代码生成 debugging: number; // 根因分析、错误诊断、重构 research: number; // 信息综合、调查、探索 reasoning: number; // 多步逻辑、规划、架构 speed: number; // 响应延迟（思考时间的倒数） longContext: number; // 大输入窗口的有效利用 instruction: number; // 指令遵循、结构化输出遵从 }

要点如下：

• 没有 costEfficiency 维度。成本不作为评分维度参与，而是作为约束条件在预算压力与档位经济性中单独处理；
• 无档案模型默认均匀 50 分。这使能力评分对这类模型退化为空操作，回退到"档内最便宜"的旧行为，实现优雅降级——不配置异构池的用户行为零变化；
• 档案是启发式排序，不是基准测试结果。仓库中明确注释了这一点，并允许用户通过modelOverrides覆盖。

内置档案覆盖 Claude 4.6/4.7 家族、OpenAI GPT-4.x 与 GPT-5.x 系列、o 系列推理模型（o1 / o3 / o4-mini 等）、Gemini 2.0/2.5 以及 deepseek-chat。例如：

const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = { "claude-opus-4-6": { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 }, "claude-sonnet-4-6": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 }, "claude-haiku-4-5": { coding: 60, debugging: 50, research: 45, reasoning: 50, speed: 95, longContext: 50, instruction: 75 }, "gpt-4o-mini": { coding: 55, debugging: 45, research: 40, reasoning: 45, speed: 90, longContext: 45, instruction: 70 }, "gemini-2.5-pro": { coding: 75, debugging: 70, research: 85, reasoning: 75, speed: 55, longContext: 90, instruction: 75 }, "deepseek-chat": { coding: 75, debugging: 65, research: 55, reasoning: 70, speed: 70, longContext: 55, instruction: 65 }, };

注意同一家族内 speed 与推理深度的反比关系：opus 系 speed 只有 30，haiku 系则高达 95——这正是"轻任务用小模型、重任务用大模型"的数据化表达。

动态任务需求向量

任务需求不是静态查表，而是由(unitType, TaskMetadata)动态计算，从而保留复杂度分类器已捕捉的细微差别。各单元类型的基础需求向量（BASE_REQUIREMENTS）：

const BASE_REQUIREMENTS: Record<string, Partial<Record<keyof ModelCapabilities, number>>> = { "execute-task": { coding: 0.9, instruction: 0.7, speed: 0.3 }, "research-milestone": { research: 0.9, longContext: 0.7, reasoning: 0.5 }, "research-slice": { research: 0.9, longContext: 0.7, reasoning: 0.5 }, "plan-milestone": { reasoning: 0.9, coding: 0.5 }, "plan-slice": { reasoning: 0.9, coding: 0.5 }, "replan-slice": { reasoning: 0.9, debugging: 0.6, coding: 0.5 }, "reassess-roadmap": { reasoning: 0.9, research: 0.5 }, "complete-slice": { instruction: 0.8, speed: 0.7 }, "run-uat": { instruction: 0.7, speed: 0.8 }, "discuss-milestone": { reasoning: 0.6, instruction: 0.7 }, "complete-milestone": { instruction: 0.8, reasoning: 0.5 }, };

对照上文的路由策略表可以看到完整映射：规划类（plan-、reassess-roadmap）重点押在 reasoning 上，对应"Frontier 始终"；研究类（research-）押在 research + longContext；执行类（execute-task）押在 coding + instruction；摘要与收尾类（complete-slice、run-uat、complete-milestone）押在 instruction + speed——对应"最轻的可行模型"。

computeTaskRequirements()还会对execute-task结合任务元数据进一步细化（src/resources/extensions/gsd/model-router.ts）：

• 文档/配置/重命名类任务（tags 命中docs|readme|comment|config|typo|rename）→ 提高 instruction、降低 coding；
• 调试类关键词（concurrency、compatibility）→ 提高 debugging 与 reasoning；
• 迁移/架构类关键词（migration、architecture）→ 提高 reasoning 与 coding；
• 大文件任务（fileCount ≥ 6 或 estimatedLines ≥ 500）→ 提高 coding 与 reasoning。

评分函数与决胜规则

评分是加权平均（scoreModel()，model-router.ts）：

score = Σ(weight × capability) / Σ(weights)

function scoreModel( model: ModelCapabilities, requirements: Partial<Record<keyof ModelCapabilities, number>>, ): number { let weightedSum = 0; let weightSum = 0; for (const [dim, weight] of Object.entries(requirements)) { const capability = model[dim as keyof ModelCapabilities] ?? 50; weightedSum += weight * capability; weightSum += weight; } return weightSum > 0 ? weightedSum / weightSum : 50; }

评分输出在 0–100 之间可直接横向比较。决胜规则（scoreEligibleModels()）是：

1. 按评分降序排列；
2. 若两个模型评分差≤ 2 分，取更便宜的（按MODEL_COST_PER_1K_INPUT内置成本表）；
3. 若成本相同，按模型 ID 字典序决胜（保证确定性）。

2 分阈值是关键设计：它防止微不足道的评分差异推翻成本优化，避免"看起来精确实则启发式"的分数产生误判。

配置实践：如何在项目中启用并按需调整

动态路由默认关闭，在 preferences 中开启（详见 dynamic-model-routing）：

--- version: 1 dynamic_routing: enabled: true ---

完整配置项：

dynamic_routing: enabled: true tier_models: # 显式指定每档模型（可选） light: claude-haiku-4-5 standard: claude-sonnet-4-6 heavy: claude-opus-4-6 escalate_on_failure: true # 任务失败时升档重试（默认 true） budget_pressure: true # 接近预算上限时自动降档（默认 true） cross_provider: true # 允许跨 Provider 选模型（默认 true） hooks: true # 对 post-unit hooks 也应用路由（默认 true） capability_routing: true # 档内启用能力评分（默认 true） allow_flat_rate_providers: false # 对包月订阅 Provider 启用路由（默认 false）

关键配置项的行为说明：

• tier_models：为每档显式锁定模型。未配置时使用内置能力映射自动选择（Light：claude-haiku-4-5、gpt-4o-mini、gpt-4.1-mini、gemini-2.0-flash 等；Standard：claude-sonnet-4-6、gpt-4o、gpt-4.1、gemini-2.5-pro、deepseek-chat 等；Heavy：claude-opus-4-6、gpt-5、gpt-5-pro、o1、o3、o4-mini 等）。

• escalate_on_failure：任务在某档失败后，重试时升档（Light → Standard → Heavy）。防止便宜模型在需要深度推理的任务上白白消耗重试次数。

• budget_pressure：接近预算上限时渐进降档。实现位于 complexity-classifier.ts 的applyBudgetPressure()，阈值如下：

  预算使用率	效果
  < 50%	不调整
  50–75%	Standard → Light
  75–90%	更激进的降档
  > 90%	几乎所有任务 → Light；仅 Heavy 保持 Standard

• allow_flat_rate_providers：默认情况下，当活跃 Provider 是包月订阅（claude-code、GitHub Copilot、外部 CLI Provider）时动态路由被抑制，因为每次请求成本相同、降档只会降低质量。设为true可以在单个订阅的 Token 预算内做智能按任务选择（例如研究用 haiku、架构用 opus），此时建议同时关闭cross_provider，避免路由器逃逸到未配置的 Provider。

覆盖能力档案

如果你对某个模型的实际表现有更好的判断，可通过modelOverrides深合并覆盖内置档案，只覆盖指定维度：

{ "providers": { "anthropic": { "modelOverrides": { "claude-sonnet-4-6": { "capabilities": { "debugging": 90, "research": 85 } } } } } }

覆盖是部分深合并：未指定的维度保留内置值。这为"模型家族演进、内置档案过期"提供了立即生效的逃生通道，而无需等待 GSD 发版。

观测与调试：让每次路由决策都可解释

每次路由决策都可通过 verbose 模式检查。当能力评分为胜出者时，日志包含完整评分明细：

Dynamic routing [S]: claude-sonnet-4-6 (capability-scored) — claude-sonnet-4-6: 82.3, gpt-4o: 78.1, deepseek-chat: 72.0

当为纯档位路由时（评分被禁用、只有一个候选、或路由守卫生效）：

Dynamic routing [S]: claude-sonnet-4-6 (standard complexity, multiple steps)

RoutingDecision中的selectionMethod字段（"capability-scored" | "tier-only"）明确标识走的是哪条路径；capabilityScores记录每个候选模型的得分，taskRequirements记录实际使用的需求向量，wasDowngraded标记是否发生了降级。管线各步骤的执行顺序也被显式保证：

1. 复杂度分类决定档位；
2. 预算压力可能降低档位；
3. 按档位过滤候选模型（仅从用户天花板向下）；
4. 能力评分对候选集排序；
5. 评分 2 分以内按成本决胜。

因此，当用户看到"预算压力导致高评分模型未被选中"时，reason 字符串中会包含budget pressure: 85%之类的明确说明，管线顺序先于评分运行，不存在逻辑冲突。

测量：追踪每次成功任务的成本，而非每次任务的成本

路由是否真正省钱，取决于你如何度量。原文档给出的测量原则是：

追踪 cost-per-successful-task（每次成功任务的成本），而不是 cost-per-task（每次任务的成本）。如果便宜的模型需要两倍的迭代次数才能完成任务，它实际上并不更便宜——省下的单价被加倍的重试次数吞掉了。

这一原则在 gsd-2 中有对应的工程机制：

• 自适应学习：路由历史（.gsd/routing-history.json）按档位、按单元类型记录成功/失败。某档失败率超过 20% 时，后续同类任务自动升档；用户反馈（over / under / ok）的权重是自动结果的 2 倍（详见 routing-history.ts 与 complexity-classifier.ts 中的getAdaptiveTierAdjustment()）。这正是"便宜模型若反复失败就应升档"的自动化版本；
• 失败升档：escalate_on_failure保证重试时进入更高档位，避免廉价模型在重试上烧钱；
• 成本表对比：内置的MODEL_COST_PER_1K_INPUT成本表（model-router.ts）用于跨 Provider 的成本对比与决胜，实际计费仍以 Provider 为准。

原文档同时引述了行业数据：Grok 在编排层执行路由时报告了 60–70% 的成本降低且零质量损失。该数字来自文档中转述的第三方报告，作为行业参考而非本项目实测；在 gsd-2 的官方文档中，动态路由自身的收益表述是"在封顶套餐上减少 20–50% 的 Token 消耗，且不牺牲关键环节的质量"（dynamic-model-routing）。

测试验证：评分逻辑的正确性由单测保障

能力路由不是黑盒。仓库在 tests/capability-router.test.ts 中对核心函数做了系统性单测覆盖：

• scoreModel：单维加权、双维加权、空需求向量返回 50、未知维度按 50 兜底；
• computeTaskRequirements：无元数据的 execute-task 返回基础向量、docs/readme 标签调整、concurrency/compatibility 关键词提升 debugging、migration/architecture 关键词提升 reasoning、fileCount ≥ 6 或 estimatedLines ≥ 500 触发大任务提升、未知单元类型回退到{ reasoning: 0.5 }；
• MODEL_CAPABILITY_PROFILES：所有已映射档位的模型都必须有档案，且七个维度齐全、取值均在 0–100 范围内。

这些测试保证了"加权平均公式正确、元数据细化行为稳定、档案数据表完整"这三条底线，也印证了 ADR-004 中"评分函数是适合确定性单测的纯函数"的设计判断。

边界与注意事项

落地这套策略时需要注意几个边界：

1. 档案是启发式，不是基准：内置能力分数表达的是模型间的相对强弱，不是实测基准。模型家族快速演进时档案会漂移，应通过modelOverrides修正，并关注仓库对"档案表完整性"的 lint 约束；
2. 未知模型默认均匀 50 分：自定义 Provider、本地模型或厂商别名若不在内置档案中，会以 50 分参与竞争（按档内成本排序）。如需让路由理解这些模型，请用modelOverrides补充档案；
3. 2 分决胜阈值：只有当评分差异超过 2 分时才让"更强"胜出，否则交给成本与确定性 ID 决胜——防止启发式分数过度覆盖成本优化；
4. 降级语义是硬约束：无论评分如何，路由都不会升到用户配置的模型之上；这是"用户控制权不可被路由绕过"的底线。

从"任务类型 → 模型层级"的策略表，到"复杂度分类 + 能力评分"的两阶段管线，再到 cost-per-successful-task 的度量原则，这套成本-质量权衡框架已经完整沉淀在 gsd-2 的源码、文档与测试之中，可直接作为同类 Agent 系统路由设计的参照实现。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用