架构定位

基础认知

建立模型输入、上下文和工程基础，让后续系统拥有清楚、可验证的起点。

模型接收什么信息，开发者如何建立可靠输入与工程基础？

概念校准

Agent

它是什么: 围绕目标和状态，在约束下选择动作、执行、观察并验证结果的运行系统。
它不是什么: 不是独立人格，也不是把模型放进无限循环。

工具

它是什么: Agent 可通过明确参数、权限和结果合同调用的受约束能力。
它不是什么: 工具不等于 MCP；本地函数、命令或 HTTP 客户端也可以是工具。

验证与评测

它是什么: 用测试、Schema、引用、状态和验收规则检查单次结果，并用数据集衡量系统表现。
它不是什么: 不等于让模型对自己的输出再给一次意见；验证必须落到外部可检查证据。

AI 工具、模型与任务判断

用基准任务比较模型、工具、成本、延迟和上下文边界。

本章只做一件事实现可解释的任务—模型路由器。

开始前，Forge 已经具备已完成 Module 01 的“入学诊断与证据地图”，其通过验收的 solution 是本章起点。

完成后，Forge 将能够实现任务—模型路由器和可解释选择报告。

卡住时的最小恢复点只保留一个文本模型和确定性 Mock，先跑通选择报告。

下载本章实验仓库Python 3.12 · pytest · Pydantic · SQLite · deterministic Mock

阶段能力链

01根据输出合同和证据要求区分抽取、生成、检索与执行任务02把候选模型的模态、结构化输出和工具调用能力与任务要求逐项匹配03在最低质量门内按预计成本选择候选，而不是只选最贵或最便宜模型04用上下文容量、输出余量和延迟预算淘汰不可行候选05把推理、外部事实读取和副作用执行分配给不同受控部件06用同一组带权测试比较候选并拒绝缺失关键任务结果的模型07输出包含入选理由、淘汰原因、假设和复测条件的确定性选择报告

每一步只增加一种可验证能力；后一步建立在前一步已经通过的代码和测试上。

概念校准\n\n在开始操作代码前，先把本章涉及的概念放回正确的工程边界。\n\n
\n\n### Agent agent\n\n- 它是什么: 围绕目标和当前状态，在约束下选择动作、执行、观察并验证结果的运行系统。核心运行环是：目标/状态 → 选择动作 → 执行工具 → 观察结果 → 验证 → 停止或重新规划。\n- 它不是什么: 它不是独立人格，也不是让模型无期限循环。模型只是决策组件，动作、权限、状态和停止条件由外部运行环境共同约束。\n- 与相邻概念的关系: Context 提供可见信息，Tool 提供动作，Harness 控制权限和副作用，Verification 判断结果，Planning 只在复杂任务需要时加入。\n- 在 HeatStack Forge 中的位置: Forge 读取任务合同与状态，选择一个受许可动作，记录工具结果，再用测试、Schema 或验收规则决定成功、失败、预算耗尽、重复动作、人工介入或重新规划。\n- 典型误用与修正: 误用是把“模型继续生成”当成进展。修正方法是让每轮产生可观察的状态变化，并为所有停止原因建立确定性检查。\n\n### 工具 tool\n\n- 它是什么: Agent 可通过明确参数、权限、执行边界和结果合同调用的受约束能力，例如函数、命令、数据库查询或 HTTP 客户端。\n- 它不是什么: 工具不等于 MCP，也不等于任意脚本。协议可以暴露能力，但 Harness 仍决定是否允许调用及如何处理副作用。\n- 与相邻概念的关系: Agent Loop 选择工具，Schema 约束参数，Harness 执行权限检查和隔离，Verification 检查结果是否推进目标。\n- 在 HeatStack Forge 中的位置: Forge 的 tool registry 保存合同与风险等级；执行前生成变更计划，高风险写操作等待确认，执行后记录结果与恢复信息。\n- 典型误用与修正: 误用是让模型根据工具名称自由拼参数。修正方法是严格 Schema、确定性校验、超时、幂等键和拒绝分支测试。\n\n### 验证与评测 evaluation\n\n- 它是什么: Verification 用测试、Schema、引用、状态或验收规则检查一次结果；Evaluation 用数据集和指标衡量多次运行表现。\n- 它不是什么: 它不是让模型对自己的回答再给一次意见；通过与否必须落到外部可检查证据。\n- 与相邻概念的关系: Agent Loop 依赖 Verification 决定停止，RAG 需要分层评测，Planning 需要节点验收，Observability 提供运行记录。\n- 在 HeatStack Forge 中的位置: Forge 为单次运行保存合同测试与 evidence，再用固定场景集比较质量、延迟、成本、权限和恢复能力。\n- 典型误用与修正: 误用是把一个综合分数当成全部结论。修正方法是定义分层指标、失败样本和版本基线，并结合产品风险评审。\n\n

STAGE 01

根据输出合同和证据要求区分抽取、生成、检索与执行任务

先看一个具体问题

如何仅凭三个布尔特征对任务进行分类？

你正在构建一个任务路由器，它需要根据任务的客观属性决定后续处理方式。当前仓库中还没有 forge/task_types.py 文件，因此测试无法导入 classify_task 函数。

测试要求 classify_task 接收三个布尔参数：mutates_state（是否改变状态）、needs_sources（是否需要来源证据）、output_schema（是否要求结构化输出），并返回正确的 TaskType 枚举成员。

关键决策在于：当多个特征同时为真时，必须确定优先级。例如，一个任务既改变状态又需要来源，应该被分类为 ACT 而不是 RETRIEVE。

先做判断

如果 classify_task 收到 mutates_state=True、needs_sources=True、output_schema=True，它应该返回哪个 TaskType？

TaskType.ACT
TaskType.RETRIEVE
TaskType.EXTRACT
TaskType.GENERATE

判断依据: 正确答案是 TaskType.ACT。因为 mutates_state 表示任务会改变外部状态，这类任务具有副作用，必须优先识别为执行类任务，即使它同时需要来源和结构化输出。

它是什么

任务分类是一个纯函数决策树

classify_task 是一个纯函数：给定三个布尔输入，它按照固定顺序检查条件并返回一个 TaskType 枚举值。

决策顺序是：先检查 mutates_state，再检查 needs_sources，然后检查 output_schema，最后默认返回 GENERATE。

这个顺序体现了任务的风险等级：改变状态的任务风险最高，需要优先处理；仅需要来源的任务次之；仅要求结构化输出的任务再次之；其余任务归为生成类。

它不是什么

任务分类不依赖模型能力或用户意图

分类只依据三个布尔输入，不涉及模型选择、成本、延迟或用户偏好。

它不判断任务是否“困难”或“重要”，也不考虑执行任务的具体工具或环境。

分类结果不包含任何置信度或概率，它是一个确定性的映射。

它与相邻概念的关系

TaskType 枚举与 classify_task 的关系

TaskType 定义了四个可能的类别：EXTRACT、GENERATE、RETRIEVE、ACT。

classify_task 根据输入特征返回其中一个枚举成员，测试使用 is 运算符验证返回的是同一个枚举对象。

枚举继承自 str，因此每个成员既是枚举又是字符串，便于序列化和比较。

本阶段的边界决定: 当 mutates_state 为 True 时，无论其他特征如何，都返回 TaskType.ACT；否则，如果 needs_sources 为 True，返回 TaskType.RETRIEVE；否则，如果 output_schema 为 True，返回 TaskType.EXTRACT；否则返回 TaskType.GENERATE。

实验 ID: model-task-judgment-01-task-classification
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/model-task-judgment/01-task-classification/
验收: 待验收

教师示范

目标: 演示 classify_task 在 mutates_state=True 时返回 TaskType.ACT，即使同时存在 needs_sources 和 output_schema。

假设你收到一个任务：更新数据库中的用户记录，并且需要引用外部数据源，同时输出必须符合 JSON Schema。

这个任务同时满足三个特征：mutates_state=True（更新数据库）、needs_sources=True（引用外部数据源）、output_schema=True（输出 JSON Schema）。

根据优先级规则，mutates_state 首先被检查，因此 classify_task 返回 TaskType.ACT。

实施步骤

创建 forge/task_types.py 文件。
定义 TaskType 枚举，包含 EXTRACT、GENERATE、RETRIEVE、ACT 四个成员。
实现 classify_task 函数，首先检查 mutates_state 参数。
如果 mutates_state 为 True，立即返回 TaskType.ACT。
运行测试验证。

真实 solution 代码: forge/task_types.py

from enum import Enum

class TaskType(str, Enum):
    EXTRACT = "extract"
    GENERATE = "generate"
    RETRIEVE = "retrieve"
    ACT = "act"


def classify_task(*, mutates_state: bool, needs_sources: bool, output_schema: bool) -> TaskType:
    if mutates_state:
        return TaskType.ACT
    if needs_sources:
        return TaskType.RETRIEVE
    if output_schema:
        return TaskType.EXTRACT
    return TaskType.GENERATE

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

在 classify_task 中，mutates_state 检查位于最前面，因此当它为 True 时，函数直接返回 TaskType.ACT，不会继续检查其他条件。

这确保了任何具有副作用的操作都被归类为执行任务，避免被误判为检索或提取任务。

带提示练习

补全 classify_task 中缺失的 RETRIEVE 分支：当 mutates_state=False 且 needs_sources=True 时返回 TaskType.RETRIEVE。

在 classify_task 函数中，在 mutates_state 检查之后添加 needs_sources 检查。
如果 needs_sources 为 True，返回 TaskType.RETRIEVE。
运行测试 test_evidence_and_schema_change_non_mutating_classification 验证。

逐级提示

注意检查顺序：mutates_state 优先于 needs_sources。
使用 if needs_sources: 条件语句。
返回 TaskType.RETRIEVE 枚举成员。

完成标准

classify_task(mutates_state=False, needs_sources=True, output_schema=False) 返回 TaskType.RETRIEVE。
classify_task(mutates_state=False, needs_sources=False, output_schema=True) 返回 TaskType.EXTRACT。

故障注入与排查

故障夹具 fixtures/failure.json 中注入了一个缺陷：classify_task 函数缺少 mutates_state 优先级规则。运行测试 test_state_changing_work_is_classified_as_action 时，一个改变状态的任务被错误分类为 RETRIEVE。

本阶段已经建立了任务分类的决策树模型，学习者知道 mutates_state 必须优先检查。通过观察故障现象，学习者能够识别出缺失的优先级规则，并按照正确顺序修复 classify_task 函数。

已验证的故障合同

目标测试: test_state_changing_work_is_classified_as_action
故障文件: forge/task_types.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_state_changing_work_is_classified_as_action，观察断言失败。
查看 forge/task_types.py 中的 classify_task 实现，发现没有检查 mutates_state。
对比预期行为：mutates_state=True 时应返回 TaskType.ACT。

修复原则: 在 classify_task 函数开头添加 if mutates_state: return TaskType.ACT，确保状态改变任务优先分类为 ACT。

python -m pytest -q ../tests/test_stage.py::test_state_changing_work_is_classified_as_action

迁移挑战

办公研究场景：你需要从一批文档中提取结构化数据，但不修改任何文档，并且输出必须符合预定义的 Schema。

改变的条件: 将输入特征从 mutates_state=True 改为 mutates_state=False，同时保持 needs_sources=False 和 output_schema=True，以测试 EXTRACT 分类。

使用 TaskType 和 classify_task 处理该场景：调用 classify_task(mutates_state=False, needs_sources=False, output_schema=True)，并解释为什么返回 TaskType.EXTRACT。

完成标准

classify_task(mutates_state=False, needs_sources=False, output_schema=True) 返回 TaskType.EXTRACT。
解释：任务不改变状态（mutates_state=False），不需要外部来源（needs_sources=False），但要求结构化输出（output_schema=True），因此符合 EXTRACT 的定义。
说明决策顺序：由于 mutates_state=False，跳过 ACT；needs_sources=False，跳过 RETRIEVE；output_schema=True，所以返回 EXTRACT。
验证：运行 python -m pytest -q tests/test_stage.py 并确认测试通过，或直接调用函数并检查返回值。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么 mutates_state 的优先级最高？请从任务风险和执行安全的角度解释。

一个有力回答应包含

改变状态的任务具有副作用，可能影响系统一致性或造成不可逆操作。
如果先检查其他特征，可能会将执行任务误判为检索或提取，导致错误的处理流程。
优先识别执行任务可以确保后续步骤采取适当的权限控制和验证措施。

掌握证据

test_state_changing_work_is_classified_as_action 测试通过，证明改变状态的任务会被归为执行类。
test_evidence_and_schema_change_non_mutating_classification 测试通过，证明非写入任务会按来源与结构化输出要求分类。
classify_task 正确实现了 mutates_state 优先级规则，并通过全部分类测试。

STAGE 02

把候选模型的模态、结构化输出和工具调用能力与任务要求逐项匹配

先看一个具体问题

为什么一个不支持工具调用的模型会被错误地选中？

在 Stage 01 中，我们已经能够把任务分类为不同的类型，例如需要工具调用的动作任务。现在我们需要为每个任务选择一个合适的模型，但候选模型的能力各不相同。

假设我们有一个文本模型，它只支持文本模态，不支持工具调用。如果我们把任务需求定义为包含 modality:text 和 tool_calls，那么当前代码会错误地认为这个模型满足需求，因为它只检查了模态，而忽略了工具调用能力。

这种错误会导致系统选择一个无法执行动作的模型，最终任务失败。我们需要实现一个能力匹配函数，确保模型声明的能力覆盖所有任务需求。

先做判断

在下面的代码中，supports 函数目前只检查了 structured_output 和模态需求。如果需求集合包含 tool_calls，但模型 tool_calls=False，函数会返回什么？

返回 True，因为模态检查通过了
返回 False，因为缺少工具调用能力
抛出异常，因为需求无法识别
返回 None，因为函数没有处理该情况

判断依据: 正确答案是“返回 True，因为模态检查通过了”。当前代码没有检查 tool_calls 需求，所以只要模态匹配就会返回 True。这会导致不支持工具调用的模型被错误地认为满足需求。

它是什么

能力匹配是集合覆盖检查

能力匹配的核心是检查模型声明的能力集合是否覆盖任务需求集合。每个需求都是一个字符串，例如 modality:text 表示需要文本模态，tool_calls 表示需要工具调用能力。

模型能力由 ModelCapability 数据类表示，包含 modalities（模态集合）、structured_output（是否支持结构化输出）和 tool_calls（是否支持工具调用）。

supports 函数遍历需求集合，对每个需求检查模型是否具备相应能力。如果所有需求都满足，返回 True；否则返回 False。

它不是什么

能力匹配不评估质量、成本或延迟

能力匹配只关心模型是否具备完成任务所需的基本能力，不涉及模型输出的质量、推理速度、成本或其他非功能性指标。

例如，一个模型支持工具调用，但工具调用的准确率可能很低，这不在能力匹配的考虑范围内。能力匹配只回答“能不能做”，不回答“做得好不好”。

同样，能力匹配不检查模型是否适合特定领域，例如医学或法律，除非这些领域要求被显式地表示为需求。

它与相邻概念的关系

能力匹配与任务分类、模型选择的关系

任务分类（Stage 01）确定了任务的需求集合，例如动作任务需要 tool_calls。能力匹配使用这个需求集合来筛选候选模型。

模型选择是在通过能力匹配的候选模型中进一步考虑质量、成本等因素。能力匹配是模型选择的前置过滤步骤。

ModelCapability 数据类封装了模型的静态能力声明，supports 函数是能力匹配的具体实现。两者共同构成了能力矩阵的基础。

本阶段的边界决定: 能力匹配只检查模型声明的能力是否覆盖需求集合，不涉及质量、成本或延迟。如果需求包含 tool_calls，模型必须显式声明 tool_calls=True 才能通过匹配。

实验 ID: model-task-judgment-02-capability-matrix
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/model-task-judgment/02-capability-matrix/
验收: 待验收

教师示范

目标: 演示 supports 函数如何检查 tool_calls 需求：给定一个 tool_calls=False 的模型和包含 tool_calls 的需求集合，返回 False。

我们从一个具体的失败案例开始：一个文本模型 text_only 只支持文本模态，不支持工具调用。任务需求是 {"modality:text", "tool_calls"}。

当前代码只检查了模态需求，没有检查 tool_calls，所以错误地返回 True。我们需要添加一个检查，当需求包含 tool_calls 且模型不支持时返回 False。

这个检查应该放在模态检查之前，因为工具调用是一个独立的能力维度。

实施步骤

打开 forge/capabilities.py 文件。
在 supports 函数中，在 structured_output 检查之后添加 tool_calls 检查。
检查逻辑：如果 "tool_calls" 在需求集合中，并且 model.tool_calls 为 False，则返回 False。
运行测试 test_tool_call_requirement_is_enforced 验证修复。

真实 solution 代码: forge/capabilities.py

from dataclasses import dataclass

@dataclass(frozen=True)
class ModelCapability:
    name: str
    modalities: frozenset[str]
    structured_output: bool
    tool_calls: bool


def supports(model: ModelCapability, requirements: set[str]) -> bool:
    if "structured_output" in requirements and not model.structured_output:
        return False
    if "tool_calls" in requirements and not model.tool_calls:
        return False
    modalities = {item.removeprefix("modality:") for item in requirements if item.startswith("modality:")}
    return modalities <= model.modalities

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

添加 tool_calls 检查后，当需求包含 tool_calls 且模型不支持时，函数会提前返回 False，不再继续检查模态。

这个检查确保了工具调用能力被正确视为模型能力的一部分，而不是提示技巧。

测试通过表明修复有效，模型选择不会再错误地接受不支持工具调用的模型。

带提示练习

补全 supports 函数中缺失的模态检查：确保所有 modality: 前缀的需求都被模型的 modalities 集合覆盖。

在 forge/capabilities.py 中，找到 supports 函数。
在函数末尾，提取所有以 modality: 开头的需求，去掉前缀得到模态名称集合。
检查这个模态名称集合是否是模型 modalities 集合的子集。如果不是，返回 False。
运行测试 test_all_required_modalities_must_be_supported 验证。

逐级提示

使用集合推导式提取模态需求：{item.removeprefix("modality:") for item in requirements if item.startswith("modality:")}。
使用集合的 <= 运算符检查子集关系。
注意：如果需求中没有模态需求，提取出的集合为空集，空集是任何集合的子集，所以不会影响结果。

完成标准

supports(vision, {"modality:text", "modality:image"}) 返回 True。
supports(vision, {"modality:audio"}) 返回 False。
测试 test_all_required_modalities_must_be_supported 通过。

故障注入与排查

故障夹具 fixtures/failure.json 描述了一个具体缺陷：一个不支持工具调用的模型被错误地接受用于动作任务。在 forge/capabilities.py 中，supports 函数忽略了 tool_calls 需求，导致 test_tool_call_requirement_is_enforced 测试失败。

本阶段的核心是能力匹配，我们已经学习了如何检查 tool_calls 和模态需求。故障夹具中的缺陷正是缺少 tool_calls 检查，我们可以通过添加这个检查来修复。

已验证的故障合同

目标测试: test_tool_call_requirement_is_enforced
故障文件: forge/capabilities.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_tool_call_requirement_is_enforced，观察测试失败。
查看测试代码，发现它创建了一个 tool_calls=False 的模型，并期望 supports 返回 False。
检查 forge/capabilities.py 中的 supports 函数，发现没有检查 tool_calls 需求。
确认根因：工具调用被当作提示技巧，而不是模型能力。

修复原则: 在 supports 函数中添加 tool_calls 检查：如果 "tool_calls" 在需求集合中且 model.tool_calls 为 False，则返回 False。修复后的代码与最终解决方案一致。

python -m pytest -q ../tests/test_stage.py::test_tool_call_requirement_is_enforced

迁移挑战

音乐创作场景：你需要为一个音乐生成任务选择模型。任务需求包括文本和音频模态、结构化输出和工具调用。创建一个模型，使其支持这些能力，并验证它满足需求。

改变的条件: 将场景从通用软件交付改为音乐创作，需求集合包含 modality:audio 和 tool_calls，模型需要支持音频模态和工具调用。

创建一个新的 Python 脚本（例如 scratch/music_model_check.py），导入 ModelCapability 和 supports，创建一个名为 music_model 的模型，其模态集合为 {"text", "audio"}，structured_output=True，tool_calls=True。然后调用 supports 函数，传入需求集合 {"modality:text", "modality:audio", "structured_output", "tool_calls"}，验证返回 True。不要修改 forge/capabilities.py。

完成标准

脚本成功创建 music_model，其 modalities 为 {"text", "audio"}，structured_output 为 True，tool_calls 为 True。
脚本调用 supports(music_model, {"modality:text", "modality:audio", "structured_output", "tool_calls"}) 并验证返回 True。
脚本不修改 forge/capabilities.py。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么工具调用必须作为模型能力而不是提示技巧？请解释如果工具调用只是提示技巧，能力匹配会如何失效。

一个有力回答应包含

工具调用需要模型在训练时学习特定的输出格式或 API 调用模式，不是简单的提示就能可靠实现的。
如果工具调用只是提示技巧，那么任何模型都可能被提示去调用工具，但实际执行时可能产生无效的工具调用，导致系统错误。
能力匹配必须基于模型声明的实际能力，否则会错误地选择无法执行任务的模型。

掌握证据

测试 test_tool_call_requirement_is_enforced 通过，证明 supports 函数正确检查了 tool_calls 需求。
测试 test_all_required_modalities_must_be_supported 通过，证明 supports 函数正确检查了模态需求。
在 forge/capabilities.py 中实现了完整的 supports 函数，包括 structured_output、tool_calls 和模态检查。

STAGE 03

在最低质量门内按预计成本选择候选，而不是只选最贵或最便宜模型

先看一个具体问题

为什么最便宜的模型不一定是最佳选择？

在任务路由中，如果只按成本选择模型，可能会选到质量不达标的候选，导致任务失败或输出不可用。

本阶段需要实现一个函数，它先过滤掉质量分数低于最低质量门的候选，再从剩余候选中选择预计成本最低的模型。

当前起始代码中 forge/economics.py 文件不存在，因此测试在导入 CandidateScore 和 choose_with_quality_floor 时会直接报错。

你需要创建该文件并实现数据类和选择函数，使两个测试通过：一个测试验证低于质量门的便宜候选被拒绝，另一个测试验证没有候选满足质量门时抛出明确异常。

先做判断

在实现 choose_with_quality_floor 时，以下哪种顺序是正确的？

先按成本排序，再检查质量是否达标
先过滤质量低于质量门的候选，再按成本选择
同时按质量和成本加权排序
随机选择一个候选

判断依据: 正确顺序是先过滤质量低于质量门的候选，再按成本选择。如果先按成本排序，可能会选到质量不达标的便宜模型，违反质量约束。

它是什么

质量成本前沿是什么

质量成本前沿是一种决策方法：在满足最低质量要求的前提下，选择预计成本最低的候选。

它由两个步骤组成：可行性过滤（质量 >= 质量门）和优化（最小化预计成本）。

可行性过滤确保所有进入成本比较的候选都满足质量约束，优化则在可行集合中寻找成本最低者。

它不是什么

质量成本前沿不是什么

它不是单纯的成本最小化，因为成本最低的候选可能质量不达标。

它也不是质量最大化，因为质量最高的候选可能成本过高，超出预算。

它不涉及上下文窗口或延迟等其他约束，本阶段只考虑质量分数和成本估算。

它与相邻概念的关系

与其他概念的关系

CandidateScore 数据类封装了模型名称、质量分数、输入成本和输出成本，并提供 estimated_cost 方法计算预计成本。

choose_with_quality_floor 函数接收候选列表、质量门、输入 token 数和输出 token 数，返回选中的候选。

质量过滤必须在成本计算之前进行，否则优化可能选择不可行的候选。

本阶段的边界决定: 当没有候选满足质量门时，函数必须抛出 ValueError，而不是返回 None 或任意候选，因为调用方需要明确知道没有可行选项。

实验 ID: model-task-judgment-03-quality-cost-frontier
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/model-task-judgment/03-quality-cost-frontier/
验收: 待验收

教师示范

目标: 演示 choose_with_quality_floor 如何先过滤质量低于 0.8 的候选，再从剩余候选中选择预计成本最低的 balanced。

假设有三个候选：cheap（质量 0.4，成本低）、balanced（质量 0.85，成本中）、premium（质量 0.95，成本高）。

质量门设为 0.8，因此 cheap 被过滤掉，因为 0.4 < 0.8。

在剩余候选中，balanced 的预计成本低于 premium，所以选择 balanced。

实施步骤

定义 CandidateScore 数据类，包含 model、quality、input_cost、output_cost 字段。
实现 estimated_cost 方法，根据输入和输出 token 数计算成本。
实现 choose_with_quality_floor 函数，先过滤质量低于质量门的候选，再按预计成本选择最低者。
运行测试验证结果。

真实 solution 代码: forge/economics.py

from dataclasses import dataclass

@dataclass(frozen=True)
class CandidateScore:
    model: str
    quality: float
    input_cost: float
    output_cost: float

    def estimated_cost(self, input_tokens: int, output_tokens: int) -> float:
        return self.input_cost * input_tokens / 1_000_000 + self.output_cost * output_tokens / 1_000_000


def choose_with_quality_floor(items: list[CandidateScore], quality_floor: float, input_tokens: int, output_tokens: int) -> CandidateScore:
    eligible = [item for item in items if item.quality >= quality_floor]
    if not eligible:
        raise ValueError("no candidate meets quality floor")
    return min(eligible, key=lambda item: (item.estimated_cost(input_tokens, output_tokens), -item.quality, item.model))

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

过滤步骤使用列表推导式 [item for item in items if item.quality >= quality_floor] 得到可行候选。

如果可行候选为空，抛出 ValueError，消息包含 “quality floor”。

成本最小化使用 min 函数，键为 (estimated_cost, -quality, model)，确保成本相同时优先质量更高者，再按模型名排序。

带提示练习

补全 choose_with_quality_floor 中缺失的质量过滤步骤：在计算成本之前，先移除 quality < quality_floor 的候选。

创建 forge/economics.py 文件。
定义 CandidateScore 数据类，包含 model、quality、input_cost、output_cost 字段。
实现 estimated_cost 方法，返回 input_cost * input_tokens / 1_000_000 + output_cost * output_tokens / 1_000_000。
实现 choose_with_quality_floor 函数，先过滤质量低于质量门的候选，再按预计成本选择最低者。
运行 python -m pytest -q tests/test_stage.py 验证。

逐级提示

使用列表推导式过滤候选：eligible = [item for item in items if item.quality >= quality_floor]。
如果 eligible 为空，抛出 ValueError("no candidate meets quality floor")。
使用 min(eligible, key=lambda item: (item.estimated_cost(input_tokens, output_tokens), -item.quality, item.model)) 选择成本最低者。

完成标准

test_cheapest_candidate_below_quality_floor_is_rejected 通过。
test_empty_quality_frontier_is_explicit 通过。

故障注入与排查

故障夹具 fixtures/failure.json 中的代码移除了质量过滤步骤，导致 choose_with_quality_floor 直接按成本选择，忽略了质量门。

本阶段的核心机制就是先过滤质量再优化成本，因此学习者能够识别出缺少过滤步骤是导致测试失败的根本原因，并知道如何修复。故障夹具中的 forge/economics.py 缺少 eligible 过滤列表，直接对全部候选调用 min，所以 test_cheapest_candidate_below_quality_floor_is_rejected 会选中质量 0.4 的 cheap。修复该缺陷需要重新引入质量过滤，这正是本阶段教学的重点。

已验证的故障合同

目标测试: test_cheapest_candidate_below_quality_floor_is_rejected
故障文件: forge/economics.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_cheapest_candidate_below_quality_floor_is_rejected，观察断言失败。
检查 forge/economics.py 中的 choose_with_quality_floor 函数，发现没有质量过滤步骤。
确认 cheap 候选的质量为 0.4，低于质量门 0.8，但被选中。
修复：在成本最小化之前添加质量过滤。

修复原则: 在 choose_with_quality_floor 函数中添加 eligible = [item for item in items if item.quality >= quality_floor]，并在 eligible 为空时抛出 ValueError，然后从 eligible 中选择成本最低者。

python -m pytest -q ../tests/test_stage.py::test_cheapest_candidate_below_quality_floor_is_rejected

迁移挑战

办公研究场景：需要从三个候选模型中选择一个用于生成决策简报，质量门为 0.85。

改变的条件: 候选模型的质量分数和成本数据发生变化，但候选数量保持三个，质量门从 0.8 变为 0.85。

使用 CandidateScore 和 choose_with_quality_floor 处理以下候选：basic（质量 0.7，输入成本 0.5，输出成本 1.0）、standard（质量 0.88，输入成本 1.0，输出成本 2.0）、premium（质量 0.95，输入成本 4.0，输出成本 8.0）。在质量门 0.85 下，输入 token 数 1000，输出 token 数 500，选择成本最低的模型。

完成标准

basic 因质量 0.7 < 0.85 被过滤，不会出现在结果中。
最终选择的模型是 standard，因为它的预计成本低于 premium。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么必须先过滤质量再最小化成本？如果反过来先选成本最低的候选再检查质量，会导致什么问题？

一个有力回答应包含

先过滤质量可以确保所有进入成本比较的候选都满足最低质量要求，避免选择不可行的候选。
如果先选成本最低的候选再检查质量，可能会选到质量不达标的模型，导致任务失败或输出不可用。
质量过滤是可行性约束，成本优化是目标函数，约束必须优先于目标。

掌握证据

test_cheapest_candidate_below_quality_floor_is_rejected 通过，证明低于质量门的便宜候选被正确拒绝。
test_empty_quality_frontier_is_explicit 通过，证明没有候选满足质量门时抛出明确的 ValueError。
能够解释质量过滤必须先于成本优化的原因，并识别出缺少过滤步骤的故障。

STAGE 04

用上下文容量、输出余量和延迟预算淘汰不可行候选

先看一个具体问题

为什么一个看似可行的模型会被上下文窗口拒绝？

在 Stage 03 中，你根据质量和成本筛选出了候选模型，但还没有检查它们是否真的能处理给定的请求。

一个模型即使质量高、成本低，如果它的上下文窗口装不下输入和输出，或者延迟超过预算，也不能用于该任务。

本阶段你将实现 is_feasible 函数，它根据上下文容量和延迟预算判断模型是否可行。

当前 forge/constraints.py 文件尚未创建，因此测试在导入时失败，你需要从零开始实现该模块。

先做判断

在实现 is_feasible 之前，请预测：如果 input_tokens=3800，output_reserve=500，而模型的 context_tokens=4096，该模型是否可行？

可行，因为输入 token 数 3800 小于上下文窗口 4096
不可行，因为输入加输出预留的总 token 数 4300 超过上下文窗口 4096
可行，因为输出预留不占用上下文窗口
不可行，因为输出预留必须单独计算，不能与输入相加

判断依据: 正确答案是“不可行，因为输入加输出预留的总 token 数 4300 超过上下文窗口 4096”。上下文窗口必须同时容纳输入和输出，输出预留是模型生成响应所需的空间，必须计入总 token 数。

它是什么

可行性检查是什么

可行性检查是一个二元判断：给定模型配置和请求参数，模型是否能在约束内完成推理。

它只考虑硬性约束：上下文窗口容量和延迟预算，不涉及质量或成本。

is_feasible 函数接收 RuntimeProfile（包含 context_tokens 和 p95_latency_ms）以及请求参数 input_tokens、output_reserve 和 latency_budget_ms，返回布尔值。

它不是什么

可行性检查不是什么

它不是质量评估：即使模型可行，也可能输出质量差，但这由其他阶段处理。

它不是成本计算：可行性检查不关心价格，只关心能否在约束内完成。

它不是概率判断：可行性是确定性的，只要违反任一约束就返回 False。

它与相邻概念的关系

与其他概念的关系

可行性检查是模型选择流程中的一道过滤器，位于质量-成本前沿之后。

它使用 RuntimeProfile 数据类，该数据类封装了模型的运行时属性。

is_feasible 的结果会影响后续的路由决策，只有可行的模型才能进入最终选择。

本阶段的边界决定: 可行性检查只回答“能否在约束内完成”，不回答“是否值得选择”。如果上下文窗口或延迟预算不满足，模型必须被淘汰，即使它在其他方面很优秀。

实验 ID: model-task-judgment-04-latency-context-constraints
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/model-task-judgment/04-latency-context-constraints/
验收: 待验收

教师示范

目标: 演示 is_feasible 如何检查上下文窗口：给定 context_tokens=4096、input_tokens=3800、output_reserve=500，返回 False，因为总和超过窗口。

假设你有一个模型，其上下文窗口为 4096 token，p95 延迟为 800ms。

现在有一个请求，输入为 3800 token，需要预留 500 token 的输出空间，延迟预算为 1000ms。

我们调用 is_feasible(profile, 3800, 500, 1000)，其中 profile 是 RuntimeProfile("small", 4096, 800)。

函数首先检查上下文容量：input_tokens + output_reserve = 3800 + 500 = 4300，而 4300 > 4096，所以 fits 为 False。

然后检查延迟：p95_latency_ms = 800 <= 1000，所以 timely 为 True。

最终返回 fits and timely，即 False and True，结果为 False。

实施步骤

创建 RuntimeProfile 实例，设置 context_tokens=4096 和 p95_latency_ms=800。
调用 is_feasible(profile, input_tokens=3800, output_reserve=500, latency_budget_ms=1000)。
在函数内部，计算 fits = input_tokens + output_reserve <= profile.context_tokens。
计算 timely = profile.p95_latency_ms <= latency_budget_ms。
返回 fits and timely。

真实 solution 代码: forge/constraints.py

from dataclasses import dataclass

@dataclass(frozen=True)
class RuntimeProfile:
    model: str
    context_tokens: int
    p95_latency_ms: int


def is_feasible(profile: RuntimeProfile, input_tokens: int, output_reserve: int, latency_budget_ms: int) -> bool:
    fits = input_tokens + output_reserve <= profile.context_tokens
    timely = profile.p95_latency_ms <= latency_budget_ms
    return fits and timely

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

这个测试失败是因为当前实现只比较了 input_tokens 和 context_tokens，忽略了 output_reserve。

正确的实现应该将 input_tokens 和 output_reserve 相加后再与 context_tokens 比较。

修复后，fits 将为 False，因为 4300 > 4096，从而测试通过。

带提示练习

创建 forge/constraints.py 并实现 is_feasible 函数，同时检查上下文容量和延迟预算。

创建 forge/constraints.py 文件。
定义 RuntimeProfile 数据类，包含 model、context_tokens、p95_latency_ms 字段。
实现 is_feasible 函数，计算 fits = input_tokens + output_reserve <= profile.context_tokens 和 timely = profile.p95_latency_ms <= latency_budget_ms，返回 fits and timely。
运行测试 python -m pytest -q tests/test_stage.py 验证。

逐级提示

延迟检查使用 profile.p95_latency_ms 和 latency_budget_ms 参数。
timely 变量应该是一个布尔值，表示延迟是否在预算内。
最终返回时，需要同时满足上下文容量和延迟两个条件。

完成标准

test_latency_budget_is_enforced 测试通过。
test_output_reserve_counts_against_context_window 测试通过。

故障注入与排查

在故障实验室中，我们模拟了一个常见的实现错误：可行性检查只比较输入 token 与上下文窗口，而忽略了输出预留。这导致一个需要 4300 token 的请求被错误地接受进 4096 token 的窗口。可执行故障夹具修改 forge/constraints.py，并由 test_output_reserve_counts_against_context_window 稳定复现；根本原因是路由预算未包含模型输出容量。

本阶段的核心机制是同时检查上下文容量和延迟预算。故障夹具中的缺陷正是缺少输出预留的检查，而你已经通过工作示例和引导练习掌握了正确的实现方式。通过诊断这个故障，你将巩固对上下文窗口约束的理解，并学会如何定位和修复此类问题。具体来说，注入缺陷是“只比较输入 token 与上下文限制”，观察到的症状是“一个需要 4300 总 token 的请求被接受进 4096 token 的窗口”，根本原因是“路由预算未包含模型输出容量”。

已验证的故障合同

目标测试: test_output_reserve_counts_against_context_window
故障文件: forge/constraints.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_output_reserve_counts_against_context_window，观察测试失败。
查看 forge/constraints.py 中的 is_feasible 实现，发现 fits = input_tokens <= profile.context_tokens 没有加上 output_reserve。
解释为什么这个缺陷会导致测试失败：因为输入 3800 加上输出预留 500 等于 4300，超过了上下文窗口 4096，但当前实现只检查输入 3800 <= 4096，因此错误地返回 True。

修复原则: 将 fits 的计算改为 input_tokens + output_reserve <= profile.context_tokens，确保输出预留计入上下文窗口。

python -m pytest -q ../tests/test_stage.py::test_output_reserve_counts_against_context_window

迁移挑战

办公研究场景：你需要为一个实时交互任务选择模型。模型 B 的上下文窗口为 8192 token，p95 延迟为 1200ms。请求的输入为 7000 token，输出预留为 1000 token，延迟预算为 1500ms。

改变的条件: 改变模型配置：从工作示例中的小上下文窗口模型（context_tokens=4096, p95_latency_ms=800）变为大上下文窗口且高延迟的模型（context_tokens=8192, p95_latency_ms=1200），同时请求的输入和输出预留也相应增加。学习者需要应用相同的可行性检查逻辑，并认识到尽管参数变化，但两个约束都得到满足，因此模型是可行的。

使用 RuntimeProfile 和 is_feasible 判断模型 B 是否可行。创建 RuntimeProfile 实例，设置 context_tokens=8192 和 p95_latency_ms=1200，然后调用 is_feasible(profile, 7000, 1000, 1500)，并解释结果。特别关注上下文容量和延迟预算两个约束的满足情况。

完成标准

调用 is_feasible 后返回 True，因为上下文容量满足（7000+1000=8000 <= 8192）且延迟满足（1200ms <= 1500ms）。
解释结果时正确说明 is_feasible 返回 True 表示模型 B 在给定的上下文窗口和延迟预算下可行。
展示 RuntimeProfile 和 is_feasible 的正确用法，并说明该判断仅基于上下文容量和延迟预算，不涉及其他约束。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么输出预留必须计入上下文窗口？如果忽略输出预留，会导致什么后果？

一个有力回答应包含

输出预留是模型生成响应所需的空间，必须与输入一起占用上下文窗口。
如果忽略输出预留，可能会接受一个输入看似可行但实际无法生成完整响应的请求，导致运行时截断或错误。

掌握证据

test_output_reserve_counts_against_context_window 测试通过，证明输出预留被正确计入上下文窗口。
test_latency_budget_is_enforced 测试通过，证明延迟预算检查生效。
在故障实验室中成功修复了 context-overflow 缺陷，并解释了根因。

STAGE 05

把推理、外部事实读取和副作用执行分配给不同受控部件

先看一个具体问题

一个需要新鲜数据且会改变外部状态的任务，应该交给谁执行？

在上一阶段，你已经能够根据延迟和上下文约束筛选模型；现在要决定的是：一个任务到底应该由模型直接推理，还是调用只读工具，或者调用写工具。

当前代码库中还没有 forge/boundaries.py，因此测试文件 tests/test_stage.py 在导入 Executor 和 choose_executor 时会直接失败，错误为 ModuleNotFoundError: No module named 'forge.boundaries'。

你需要创建这个模块，并实现 choose_executor 函数：它接收两个布尔参数 needs_fresh_data 和 changes_external_state，返回一个 Executor 枚举成员。

关键决策是：当任务既需要新鲜数据又改变外部状态时，必须优先考虑副作用，返回 Executor.WRITE_TOOL，而不是 READ_TOOL。

先做判断

如果 needs_fresh_data=True 且 changes_external_state=True，choose_executor 应该返回哪个执行者？

Executor.READ_TOOL，因为需要新鲜数据
Executor.WRITE_TOOL，因为改变外部状态必须由写工具执行
Executor.MODEL，因为模型可以同时处理两者
直接抛出异常，因为两个条件冲突

判断依据: 正确答案是 Executor.WRITE_TOOL。改变外部状态意味着任务会产生副作用，必须由具备写权限的工具执行；只读工具无法安全地完成这类任务，即使它也需要新鲜数据。

它是什么

执行者选择是一个优先级决策

choose_executor 是一个纯函数，它根据任务的两个布尔属性决定执行者类型：是否改变外部状态、是否需要新鲜数据。

决策顺序是：先检查副作用，再检查数据新鲜度，最后默认使用模型。这样保证任何有副作用的操作都不会被错误地分配给只读工具或模型。

它不是什么

它不是具体工具实现或权限系统

本阶段只返回一个枚举值，表示应该使用哪类执行者；它不负责实际调用工具、检查权限或处理错误。

Executor 枚举只是标签，不代表具体的函数或 API；真正的工具实现和权限控制由后续阶段或外部 Harness 完成。

它与相邻概念的关系

与已有模块的关系

forge/boundaries.py 依赖之前阶段定义的 task_types.py、capabilities.py、economics.py 和 constraints.py 中的概念，但本阶段只使用两个布尔输入，不直接导入那些模块。

测试文件 tests/test_stage.py 从 forge.boundaries 导入 Executor 和 choose_executor，因此模块必须存在且函数签名正确。

本阶段的边界决定: 本阶段只决定执行者类型（模型、读工具、写工具），不涉及具体工具实现或权限；如果任务改变外部状态，无论是否需要新鲜数据，都必须返回 Executor.WRITE_TOOL。

实验 ID: model-task-judgment-05-model-tool-boundary
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/model-task-judgment/05-model-tool-boundary/
验收: 待验收

教师示范

目标: 演示 choose_executor 如何优先处理副作用：当 changes_external_state=True 时，即使 needs_fresh_data=True，也返回 Executor.WRITE_TOOL。

假设有一个任务：更新用户数据库中的邮箱地址。这个任务需要读取当前邮箱（新鲜数据），但更重要的是它会修改数据库（改变外部状态）。

如果错误地返回 READ_TOOL，只读工具无法完成写入，任务会失败或产生不一致。因此，函数必须先检查 changes_external_state。

实施步骤

创建 forge/boundaries.py 文件。
定义 Executor 枚举，包含 MODEL、READ_TOOL、WRITE_TOOL 三个成员。
实现 choose_executor 函数，先判断 changes_external_state，若为真则返回 Executor.WRITE_TOOL。
运行测试 python -m pytest -q tests/test_stage.py，确认两个测试都通过。

真实 solution 代码: forge/boundaries.py

from enum import Enum

class Executor(str, Enum):
    MODEL = "model"
    READ_TOOL = "read_tool"
    WRITE_TOOL = "write_tool"


def choose_executor(*, needs_fresh_data: bool, changes_external_state: bool) -> Executor:
    if changes_external_state:
        return Executor.WRITE_TOOL
    if needs_fresh_data:
        return Executor.READ_TOOL
    return Executor.MODEL

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

在 choose_executor 中，第一个 if 检查 changes_external_state，如果为真立即返回 WRITE_TOOL，这确保了副作用优先。

第二个 if 检查 needs_fresh_data，如果为真返回 READ_TOOL；否则返回 MODEL。这个顺序避免了将写操作误判为读操作。

带提示练习

补全 choose_executor 中缺失的读工具分支：当 changes_external_state=False 且 needs_fresh_data=True 时返回 Executor.READ_TOOL。

在 forge/boundaries.py 中，在 if changes_external_state: 块之后添加一个新的 if 语句。
条件为 needs_fresh_data，返回 Executor.READ_TOOL。
最后，如果两个条件都不满足，返回 Executor.MODEL。
运行 python -m pytest -q tests/test_stage.py 验证。

逐级提示

注意函数参数是关键字参数，调用时需要使用 needs_fresh_data= 和 changes_external_state=。
确保返回的是枚举成员，而不是字符串。
检查缩进：每个 if 块内的 return 语句应该正确缩进。

完成标准

choose_executor(needs_fresh_data=True, changes_external_state=False) 返回 Executor.READ_TOOL。
choose_executor(needs_fresh_data=False, changes_external_state=False) 返回 Executor.MODEL。

故障注入与排查

在故障夹具 fixtures/failure.json 中，forge/boundaries.py 被注入了缺陷：choose_executor 函数只检查 needs_fresh_data，完全忽略了 changes_external_state。因此，当测试 test_external_side_effect_requires_write_tool 调用 choose_executor(needs_fresh_data=True, changes_external_state=True) 时，函数返回 Executor.READ_TOOL，而测试期望 Executor.WRITE_TOOL，导致断言失败。

本阶段的核心就是建立副作用优先的决策顺序。你已经通过工作示例和引导练习实现了正确的 choose_executor，因此能够识别出故障版本缺少对 changes_external_state 的处理，并知道修复方法是在函数开头添加该检查。

已验证的故障合同

目标测试: test_external_side_effect_requires_write_tool
故障文件: forge/boundaries.py

诊断顺序

运行故障测试命令 python -m pytest -q ../tests/test_stage.py::test_external_side_effect_requires_write_tool，观察输出。
输出显示 AssertionError: assert <Executor.READ_TOOL: 'read_tool'> is <Executor.WRITE_TOOL: 'write_tool'>，说明函数返回了 READ_TOOL。
检查 forge/boundaries.py 中的 choose_executor 实现，发现它只检查了 needs_fresh_data，没有检查 changes_external_state。
根因是决策逻辑忽略了副作用，导致有写操作的任务被分配给只读工具。

修复原则: 在 choose_executor 函数开头添加 if changes_external_state: return Executor.WRITE_TOOL，确保副作用优先于数据新鲜度。修复后，函数会先检查 changes_external_state，如果为真则返回 WRITE_TOOL，否则再检查 needs_fresh_data。

python -m pytest -q ../tests/test_stage.py::test_external_side_effect_requires_write_tool

迁移挑战

音乐场景：一个任务需要从外部数据库获取最新曲目信息，但不修改任何数据。

改变的条件: 将场景从软件交付改为音乐创作，任务变为读取最新曲目信息且不改变外部状态。

使用 Executor 和 choose_executor，确定这个任务的执行者。在 forge/boundaries.py 中调用 choose_executor(needs_fresh_data=True, changes_external_state=False)，并断言返回值为 Executor.READ_TOOL。

完成标准

调用 choose_executor(needs_fresh_data=True, changes_external_state=False) 返回 Executor.READ_TOOL。
调用 choose_executor(needs_fresh_data=False, changes_external_state=False) 返回 Executor.MODEL，确保没有副作用且不需要新鲜数据的任务仍由模型处理。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么改变外部状态的任务必须使用写工具而不是模型？请从副作用控制和可验证性两个角度解释。

一个有力回答应包含

模型本身没有直接修改外部系统的能力，它只能生成文本或建议；实际修改需要由具有写权限的工具执行。
写工具可以记录操作、支持回滚和审计，而模型直接修改会导致不可追踪的副作用，难以验证和恢复。

掌握证据

test_external_side_effect_requires_write_tool 通过：验证当 changes_external_state=True 时返回 Executor.WRITE_TOOL。
test_reasoning_without_external_state_stays_in_model 通过：验证当两个参数都为 False 时返回 Executor.MODEL。
成功创建 forge/boundaries.py 并实现 Executor 枚举和 choose_executor 函数，且测试全部通过。

STAGE 06

用同一组带权测试比较候选并拒绝缺失关键任务结果的模型

先看一个具体问题

如何公平比较候选模型并拒绝缺失关键结果的候选？

你已经在前几个阶段建立了任务分类、能力矩阵、质量成本前沿、延迟约束和模型工具边界。现在需要实现一个基准测试套件，用同一组带权测试案例比较不同候选模型，并确保关键任务结果缺失时直接拒绝该候选。

当前 forge/benchmark.py 文件不存在，测试 test_missing_critical_case_rejects_candidate 和 test_weighted_score_uses_measured_cases 会因导入失败而报错。你需要创建该文件，定义 BenchmarkCase 数据类和 score_candidate 函数，使两个测试通过。

具体来说，score_candidate 接收案例列表和结果字典，必须检查所有标记为 critical=True 的案例是否都有结果；如果缺失任何一个关键案例，就抛出包含 ‘critical’ 的 ValueError。同时，对于有结果的案例，使用案例权重计算加权平均分。

先做判断

在实现 score_candidate 时，如果某个关键案例的结果缺失，函数应该怎么做？

忽略缺失的关键案例，只对已有结果计算加权平均
抛出 ValueError，提示缺失关键基准案例
将缺失的关键案例得分视为 0 并继续计算
返回 None 表示无法评分

判断依据: 正确做法是抛出 ValueError。关键案例是必须覆盖的任务，缺失结果意味着候选模型没有完成必要评估，不能给出有效分数。忽略或视为 0 都会错误地让候选通过。

它是什么

基准评分是一个带完整性检查的加权平均计算

基准评分函数接收一组案例定义（每个案例有 id、权重和是否关键）以及候选模型在这些案例上的得分结果。它首先验证所有关键案例都有结果，然后只对已有结果的案例计算加权平均分。

这个模型的核心是：关键案例的完整性是评分的先决条件，权重用于反映不同案例的重要性。缺失关键案例意味着候选模型没有完成必要评估，因此必须拒绝。

它不是什么

它不是简单的平均，也不是忽略缺失数据的容错计算

基准评分不是对所有案例简单求平均，因为不同案例的重要性不同，必须使用权重。它也不是容错计算，不能因为某些案例缺失就静默跳过，特别是关键案例。

它不涉及模型能力或成本的评估，只基于提供的案例和结果进行数学计算。任何缺失关键案例的情况都必须显式报错，而不是给出一个看似合理的分数。

它与相邻概念的关系

与任务分类、能力矩阵和约束的关系

基准案例的 id 通常对应任务类型（如 ‘schema’、‘summary’），这些任务类型来自 Stage 01 的任务分类。案例的权重可能反映任务的重要性或频率，与 Stage 02 的能力矩阵和 Stage 03 的质量成本前沿相关。

关键案例的标记可能来自 Stage 04 的约束条件，例如某些任务必须满足最低性能。基准评分的结果可以用于后续的模型选择，因此它必须可靠地拒绝不完整的候选。

本阶段的边界决定: 当关键案例缺失时，必须抛出 ValueError 拒绝候选；当没有关键案例缺失但所有案例都缺失结果时，也应抛出 ValueError 避免除零错误。

实验 ID: model-task-judgment-06-benchmark-suite
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/model-task-judgment/06-benchmark-suite/
验收: 待验收

教师示范

目标: 演示 score_candidate 如何拒绝缺失关键案例的候选：给定一个关键案例 ‘schema’ 和结果字典缺少 ‘schema’，抛出 ValueError。

假设我们有两个基准案例：schema（权重 2，关键）和 summary（权重 1，非关键）。候选模型只提供了 summary 的结果，没有 schema 的结果。

在 score_candidate 中，我们首先检查关键案例：遍历所有案例，如果 case.critical 为 True 且 case.id 不在结果字典中，就记录缺失的关键案例 id。

如果存在缺失的关键案例，函数抛出 ValueError，消息中包含 ‘critical’ 和缺失的案例 id。这样测试 test_missing_critical_case_rejects_candidate 就能捕获异常并通过。

实施步骤

定义 BenchmarkCase 数据类，包含 id、weight 和 critical 字段，其中 critical 默认为 False。
在 score_candidate 中，使用列表推导式收集所有 critical=True 且 id 不在 results 中的案例 id。
如果 missing_critical 列表非空，抛出 ValueError("missing critical benchmark: " + ",".join(missing_critical))。
然后计算加权平均：筛选出有结果的案例，计算总权重和加权得分之和，返回加权得分除以总权重。

真实 solution 代码: forge/benchmark.py

from dataclasses import dataclass

@dataclass(frozen=True)
class BenchmarkCase:
    id: str
    weight: float
    critical: bool = False


def score_candidate(cases: list[BenchmarkCase], results: dict[str, float]) -> float:
    missing_critical = [case.id for case in cases if case.critical and case.id not in results]
    if missing_critical:
        raise ValueError("missing critical benchmark: " + ",".join(missing_critical))
    measured = [case for case in cases if case.id in results]
    if not measured:
        raise ValueError("no benchmark results")
    total = sum(case.weight for case in measured)
    return sum(results[case.id] * case.weight for case in measured) / total

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

关键案例的检查必须在计算分数之前进行，否则缺失关键案例的候选会得到一个基于部分结果的分数，这是不公平的。

抛出 ValueError 时，消息中包含 ‘critical’ 是为了让测试的 pytest.raises(ValueError, match="critical") 能够匹配。

加权平均的计算只使用有结果的案例，这样非关键案例的缺失不会影响分数，但关键案例的缺失会直接拒绝。

带提示练习

补全 score_candidate 中缺失的加权平均计算：使用案例权重和结果计算加权分数。

在 forge/benchmark.py 中，先实现关键案例检查（参考 workedExample）。
然后筛选出有结果的案例：measured = [case for case in cases if case.id in results]。
如果 measured 为空，抛出 ValueError("no benchmark results") 避免除零。
计算总权重 total = sum(case.weight for case in measured)。
计算加权得分之和 weighted_sum = sum(results[case.id] * case.weight for case in measured)。
返回 weighted_sum / total。

逐级提示

注意：加权平均是加权得分之和除以总权重，而不是简单平均。
确保只使用有结果的案例，避免 KeyError。
如果所有案例都缺失结果，应该抛出异常而不是返回 0 或 None。

完成标准

test_weighted_score_uses_measured_cases 通过：给定案例 schema(权重2,关键) 和 summary(权重1)，结果 {‘schema’:0.5,‘summary’:1.0}，返回 2/3。
test_missing_critical_case_rejects_candidate 通过：缺失关键案例时抛出 ValueError。

故障注入与排查

在故障实验 fixtures/failure.json 中，forge/benchmark.py 被注入了缺陷：移除了关键案例完整性检查。运行测试 test_missing_critical_case_rejects_candidate 时，候选模型只提供了 summary 的结果，缺失关键案例 schema，但函数没有抛出异常，而是返回了一个基于 summary 的分数。

本阶段的核心机制就是关键案例完整性检查。你已经学会了在 score_candidate 中检查缺失的关键案例并抛出 ValueError。这个故障正是缺少该检查，因此你可以通过添加检查来修复。

已验证的故障合同

目标测试: test_missing_critical_case_rejects_candidate
故障文件: forge/benchmark.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_missing_critical_case_rejects_candidate，观察测试失败，错误为 Failed: DID NOT RAISE ValueError。
查看 forge/benchmark.py 源码，发现 score_candidate 中没有检查关键案例是否缺失，直接筛选有结果的案例并计算加权平均。
对比预期行为：关键案例缺失时必须抛出 ValueError。因此需要在函数开头添加关键案例检查。
修复：添加缺失关键案例的检查，如果存在缺失则抛出 ValueError。

修复原则: 在 score_candidate 函数开头添加以下代码： python missing_critical = [case.id for case in cases if case.critical and case.id not in results] if missing_critical: raise ValueError("missing critical benchmark: " + ",".join(missing_critical)) 这样当关键案例缺失时，函数会抛出包含 ‘critical’ 的 ValueError，测试通过。

python -m pytest -q ../tests/test_stage.py::test_missing_critical_case_rejects_candidate

迁移挑战

办公研究场景：你需要评估两个候选模型在报告生成和数据提取任务上的表现。定义两个基准案例：report_generation（权重 2，关键）和 data_extraction（权重 1，非关键）。给定结果字典 {'report_generation': 0.9, 'data_extraction': 0.8}，计算加权分数。

改变的条件: 将软件交付场景中的案例 id 和权重改为办公场景的 report_generation 和 data_extraction，并调整结果数值。

在 forge/benchmark.py 中使用现有的 BenchmarkCase 和 score_candidate，定义两个案例：BenchmarkCase('report_generation', 2, True) 和 BenchmarkCase('data_extraction', 1)。然后调用 score_candidate 并传入结果字典 {'report_generation': 0.9, 'data_extraction': 0.8}，验证返回的加权分数。

完成标准

加权分数应为 (0.92 + 0.81) / (2+1) = 2.6/3 ≈ 0.8667。
如果缺失关键案例 report_generation，函数应抛出 ValueError。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么缺失关键基准案例必须导致拒绝，而不是忽略缺失案例继续计算？请从公平性和决策可靠性的角度解释。

一个有力回答应包含

关键案例代表必须满足的任务要求，缺失结果意味着候选模型没有完成必要评估，无法判断其在该任务上的表现。
如果忽略缺失案例，候选可能因为只完成了简单任务而获得高分，导致错误的选择决策。
拒绝缺失关键案例的候选可以确保所有进入比较的模型都覆盖了关键任务，保证比较的公平性。

掌握证据

test_missing_critical_case_rejects_candidate 通过：验证缺失关键案例时抛出 ValueError。
test_weighted_score_uses_measured_cases 通过：验证加权平均计算正确。
成功创建 forge/benchmark.py 并实现 BenchmarkCase 和 score_candidate，代码通过所有测试。

STAGE 07

输出包含入选理由、淘汰原因、假设和复测条件的确定性选择报告

先看一个具体问题

为什么选择报告不能只写“最佳模型”？

在上一阶段，你已经用基准测试得到每个候选模型的分数，并选出了当前任务下的最优模型。现在需要把选择结果写成一份报告，交给团队审查。

如果报告只写“我们选择了 balanced 模型”，审查者无法知道其他模型为什么被淘汰，也无法判断这个选择在什么条件下需要重新评估。

本阶段的目标是编写 build_report 函数，把选中的模型、基准分数、淘汰原因、假设和复测条件都记录下来，形成一份可审计的决策文档。

先做判断

在开始实现之前，请预测：如果 build_report 函数只返回选中的模型名称和一句“best model”，会发生什么？

测试会通过，因为报告已经说明了选择结果。
测试会失败，因为报告缺少淘汰原因和复测条件。
测试会失败，因为报告没有包含基准分数。
测试会通过，因为审查者可以自己推断淘汰原因。

判断依据: 正确答案是第二个选项。测试 test_report_preserves_rejections_and_retest_triggers 明确要求报告包含 rejected 字典中的淘汰原因和 retest_when 列表中的复测条件。只写“best model”会导致 KeyError，因为报告中没有 cheap 这个键。

它是什么

选择报告是什么

选择报告是一个不可变的数据结构，它把决策过程中的关键证据固定下来，包括选中的模型、基准分数、每个被淘汰模型的原因、做出选择时的假设，以及未来需要重新评估的触发条件。

报告中的每个字段都来自 build_report 的输入参数，函数本身不做新的计算，只负责整理和验证这些信息。

它不是什么

选择报告不是什么

选择报告不是一段自由文本，不能只写一句“我们选择了最好的模型”。它必须结构化地记录所有淘汰原因和复测条件，让审查者能够重建决策过程。

报告也不负责重新计算分数或引入外部数据，它只使用调用者提供的分数和原因。

它与相邻概念的关系

与其他组件的关系

build_report 接收来自基准测试阶段的 scores 字典，以及任务约束阶段产生的 rejected 原因和 retest_when 条件。

报告中的 reasons 字段必须包含选中模型的基准分数，格式为 benchmark_score=0.870，这样审查者可以核对分数来源。

本阶段的边界决定: 报告构建只使用提供的分数、淘汰原因、假设和复测条件，不涉及新的计算或外部数据。如果选中的模型没有基准分数，函数必须抛出 ValueError，因为无法验证选择依据。

实验 ID: model-task-judgment-07-selection-report
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/model-task-judgment/07-selection-report/
验收: 待验收

教师示范

目标: 演示 build_report 如何生成一份完整的报告：给定 selected='balanced'、scores={'balanced':0.87}、rejected={'cheap':'quality floor','premium':'cost'}、assumptions=['1000 input tokens']、retest_when=['price changes','new vision requirement']，返回包含这些字段的 SelectionReport。

假设你已经完成了基准测试，得到 balanced 模型的分数是 0.87。同时，你记录了 cheap 模型因为质量下限被淘汰，premium 模型因为成本过高被淘汰。

现在调用 build_report，它会把这些信息打包成一个 SelectionReport 对象，其中 reasons 包含基准分数和约束满足声明，rejected 保留所有淘汰原因，retest_when 保留复测条件。

实施步骤

定义 SelectionReport 数据类，包含 selected、reasons、rejected、assumptions、retest_when 字段。
在 build_report 中检查 selected 是否在 scores 中，如果不在则抛出 ValueError。
构造 reasons 元组，第一项为 f"benchmark_score={scores[selected]:.3f}"，第二项为 "meets declared constraints"。
对 rejected 字典按键排序后转换为普通字典，保证输出确定性。
将 assumptions 和 retest_when 转换为元组，返回 SelectionReport 实例。

真实 solution 代码: forge/selection_report.py

from dataclasses import dataclass

@dataclass(frozen=True)
class SelectionReport:
    selected: str
    reasons: tuple[str, ...]
    rejected: dict[str, str]
    assumptions: tuple[str, ...]
    retest_when: tuple[str, ...]


def build_report(selected: str, scores: dict[str, float], rejected: dict[str, str], assumptions: list[str], retest_when: list[str]) -> SelectionReport:
    if selected not in scores:
        raise ValueError("selected model has no benchmark score")
    if not rejected or not retest_when:
        raise ValueError("report requires rejected alternatives and retest triggers")
    reasons=(f"benchmark_score={scores[selected]:.3f}","meets declared constraints")
    return SelectionReport(selected,reasons,dict(sorted(rejected.items())),tuple(assumptions),tuple(retest_when))

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

reasons 的第一项 benchmark_score=0.870 来自 scores[selected]，格式化为三位小数，确保审查者能看到精确分数。

rejected 字典被排序后保留，这样即使输入顺序不同，输出也保持一致，便于测试和审计。

带提示练习

补全 build_report 中缺失的验证：确保 selected 在 scores 中，否则抛出 ValueError。

打开 forge/selection_report.py，找到 build_report 函数。
在函数开头添加检查：如果 selected not in scores，抛出 ValueError("selected model has no benchmark score")。
运行测试 python -m pytest -q tests/test_stage.py::test_unmeasured_selection_is_rejected，确认测试通过。

逐级提示

使用 if selected not in scores: 进行判断。
异常消息必须包含 benchmark score，因为测试用 pytest.raises(ValueError, match="benchmark score") 匹配。
不要忘记在抛出异常前不要构造报告。

完成标准

test_unmeasured_selection_is_rejected 测试通过。
build_report 在 selected 不在 scores 时抛出 ValueError。

故障注入与排查

你接手了一份已有的 forge/selection_report.py 代码，但测试 test_report_preserves_rejections_and_retest_triggers 失败了。运行测试时，报告对象中缺少 cheap 键，导致 KeyError。你需要诊断为什么报告没有保留淘汰原因和复测条件，并修复它。

本阶段你已经理解了选择报告必须包含淘汰原因和复测条件，并且知道 build_report 需要把这些输入参数原样保存到 SelectionReport 中。当前的故障代码只返回了硬编码的 reasons=("best model",)，并且把 rejected 设为空字典、retest_when 设为空元组，这违反了报告的可审计性要求。通过对比预期行为和实际代码，你可以定位到缺失的字段传递，并应用本阶段学到的修复方法。

已验证的故障合同

目标测试: test_report_preserves_rejections_and_retest_triggers
故障文件: forge/selection_report.py

诊断顺序

运行故障测试命令 python -m pytest -q ../tests/test_stage.py::test_report_preserves_rejections_and_retest_triggers，观察失败输出。
失败信息显示 KeyError: 'cheap'，说明 report.rejected 中没有 cheap 键。
检查 forge/selection_report.py 中的 build_report 函数，发现它返回 SelectionReport(selected,reasons,{},tuple(assumptions),())，其中 rejected 被硬编码为空字典，retest_when 被硬编码为空元组。
同时，reasons 被硬编码为 ("best model",)，没有包含基准分数。
根据测试要求，rejected 应该保留传入的淘汰原因，retest_when 应该保留复测条件，reasons 应该包含 benchmark_score=0.870。

修复原则: 修改 build_report 函数，使其返回完整的 SelectionReport：reasons 包含 f"benchmark_score={scores[selected]:.3f}" 和 "meets declared constraints"；rejected 使用 dict(sorted(rejected.items())) 保留排序后的淘汰原因；retest_when 使用 tuple(retest_when) 保留复测条件。同时添加对 selected 不在 scores 中的检查，抛出 ValueError。

python -m pytest -q ../tests/test_stage.py::test_report_preserves_rejections_and_retest_triggers

迁移挑战

办公研究场景：你需要为文档摘要任务选择模型。假设你已经测得 office_model 的分数为 0.92，slow_model 因为延迟过高被淘汰，假设输入为 2000 个 token，并且当出现新的文档类型时需要重新评估。

改变的条件: 将场景从软件交付改为办公研究，并更换模型名称、分数、淘汰原因、假设和复测条件。

使用 build_report 函数，传入 selected='office_model'、scores={'office_model':0.92}、rejected={'slow_model':'latency'}、assumptions=['2000 input tokens']、retest_when=['new document type']，生成报告，并检查报告中的淘汰原因和复测条件是否被正确保留。

完成标准

生成的报告对象中，rejected 字典包含键 'slow_model' 且值为 'latency'。
生成的报告对象中，retest_when 元组包含 'new document type'。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么报告必须包含淘汰原因和复测条件？如果缺少这些信息，审查者会面临什么风险？

一个有力回答应包含

淘汰原因让审查者理解为什么其他模型被排除，避免重复评估已经否决的选项。
复测条件定义了决策的有效边界，当条件变化时（如价格变动或新需求出现），审查者知道需要重新运行选择流程。
缺少这些信息会使报告变成不可审计的“黑箱”，审查者无法验证选择是否合理，也无法判断决策何时失效。

掌握证据

test_report_preserves_rejections_and_retest_triggers 测试通过，证明报告保留了淘汰原因和复测条件。
test_unmeasured_selection_is_rejected 测试通过，证明当选中模型没有基准分数时会抛出 ValueError。
build_report 函数返回的 SelectionReport 包含排序后的 rejected 字典和格式化的基准分数，确保输出确定性。

完成本章

实现任务—模型路由器和可解释选择报告。

FORGE / LOCAL CHECK

本地实验自检

未开始
2阅读中
3实验已下载
4测试结果已读取
5本地自检通过

verification.json 只在当前浏览器中解析，不会上传。这里验证的是实验合同，不是服务器认证或第三方背书。

选择 verification.json

主要层

依赖能力

为后续提供

受这些层约束

概念校准

Agent

工具

验证与评测

AI 工具、模型与任务判断

先看一个具体问题

如何仅凭三个布尔特征对任务进行分类？

先做判断

它是什么

任务分类是一个纯函数决策树

它不是什么

任务分类不依赖模型能力或用户意图

它与相邻概念的关系

TaskType 枚举与 classify_task 的关系

先看一个具体问题

为什么一个不支持工具调用的模型会被错误地选中？

先做判断

它是什么

能力匹配是集合覆盖检查

它不是什么

能力匹配不评估质量、成本或延迟

它与相邻概念的关系

能力匹配与任务分类、模型选择的关系

先看一个具体问题

为什么最便宜的模型不一定是最佳选择？

先做判断

它是什么

质量成本前沿是什么

它不是什么

质量成本前沿不是什么

它与相邻概念的关系

与其他概念的关系

先看一个具体问题

为什么一个看似可行的模型会被上下文窗口拒绝？

先做判断

它是什么

可行性检查是什么

它不是什么

可行性检查不是什么

它与相邻概念的关系

与其他概念的关系

先看一个具体问题

一个需要新鲜数据且会改变外部状态的任务，应该交给谁执行？

先做判断

它是什么

执行者选择是一个优先级决策

它不是什么

它不是具体工具实现或权限系统

它与相邻概念的关系

与已有模块的关系

先看一个具体问题

如何公平比较候选模型并拒绝缺失关键结果的候选？

先做判断

它是什么

基准评分是一个带完整性检查的加权平均计算

它不是什么

它不是简单的平均，也不是忽略缺失数据的容错计算

它与相邻概念的关系

与任务分类、能力矩阵和约束的关系

先看一个具体问题

为什么选择报告不能只写“最佳模型”？

先做判断

它是什么

选择报告是什么

它不是什么

选择报告不是什么

它与相邻概念的关系

与其他组件的关系