Agent 路由保护基线

这是 issue #2338 的可独立运行基线。 它使用版本化的单请求和多轮 fixture，测试当前生产保护和 progress gate 行为。它不建立可测量的模型质量收益，也不完成该 issue 的委托角色覆盖。

运行

在仓库根目录，并已安装 Go：

make bench-agent-routing-protection

该目标运行 router pkg/extproc 包的学习会话测试。 它不会下载模型权重、启动 Router 部署、联系模型 provider，也不需要外部状态存储。报告写入 .agent-harness/agent-routing-protection/report.json。

这些测试也可以直接运行：

cd src/semantic-router
go test ./pkg/extproc -run '^TestRouterLearningSession' -count=1 -v

CI 在 Router Contracts 作业中，于启动外部服务或下载模型权重之前，通过 make test-core-unit 运行这些测试，并设置 ROUTER_PROTECTION_REPORT。其退出状态会卡住该作业。agent-routing-protection 产物包含 JSON 报告，契约回归时还包括每轮失败。即使失败也会尝试上传；若在报告产生前 setup 失败，上传会对缺失文件发出警告。

这些测试也会在常规核心 make test-semantic-router 门槛中运行。任何每轮模型、采样权限、硬锁定状态、preflight 原因、回放 action/reason 或 progress gate 判定/应用不匹配都会使门槛失败。每次运行执行语料两次并比较报告字节。

运行内容

语料位于 src/semantic-router/pkg/extproc/testdata/router_learning_sessions.v2.yaml。 YAML 接受注释，拒绝未知字段和重复键，且必须恰好包含一份文档。每个场景声明其范围和保护模式。每一步追加语义消息，并提供已经合格的候选、上游算法的提案和分数，以及任何 provider 状态引用或缓存热度输入。 期望结果是独立的评分字段，从不提供路由状态。 Progress gate 场景还会声明显式的版本化校准，并在分发后记录不含内容的类型化结果。这些结果驱动生产证据评估器，而不会直接指定期望路由。

Runner 使用生产消息事实提取、保护 preflight、切换保护、回放诊断转换和会话记忆写入。 下一轮读取上一轮的实际模型选择。场景和重复之间会重置记忆。配套集成测试将维护的工具循环历史，通过启用 adaptation 的生产路由学习编排发送。它检查实际采样调用和最终模型连续性，以及在同一工具循环中采样的旁路对照。这覆盖进程内编排，而不是 HTTP 或 Envoy 分发。

模型选择提案是脚本化的； 保护决策不会在 runner 中模拟或重新实现。 被接受的语料步骤会显式提交暂存的会话决策，以模拟一次成功的分发。在请求管线中，选择只暂存所有权；provider 准备、凭证解析和最终编码都成功后，所有权才会提交。取消和立即拒绝不会替换先前的所有者，也不会增加其轮次和切换计数。

selection_decision_paths_test.go 另外守护组件错误的组合：observe 保护即使在策略拒绝时也保留已应用的 adaptation 提案；preflight 读取保护范围内的热状态；救援遵循分数方向；取消覆盖选择器捷径和成功返回；Eval 保留对候选歧义的拒绝。进程内分发测试覆盖延迟拒绝、成功的所有权提交，以及在较新分发之后才到达的较旧失败。这些检查不会调用实时模型后端。

覆盖的契约包括：

• 首次请求的基线建立。
• 进行中的工具调用、工具结果和立即的用户跟进会阻止切换。
• 已完成的工具交换释放其历史锁定。
• 绑定到 provider 的响应状态，以及带可移植历史的释放。
• 小的分数优势被保持，明显优势允许切换。
• 热缓存采样抑制。
• 候选集变化阻止恢复不合格的先前模型；所有者被排除的硬绑定延续会被拒绝，而不是改路由。
• 会话范围连续性和对话范围隔离。
• 缺失身份、observe 模式和 bypass 模式保留其当前语义。
• 冷启动和证据不足时抑制模型切换。
• Provider 错误和缺失结果不会被归因于模型退化。
• 持续退化允许升级，持续恢复允许降级。
• Observe 模式记录判定但不执行，冷却和窗口内振荡会抑制切换。
• 当前模型不再合格时，抑制判定不会把它恢复回来。

该配置文件固定切换裕度为 0.05、最小轮次为零、稳定性权重为零。这将连续性锁定和基本切换权限与缓存成本和历史惩罚调优隔离开；它不是生产调优建议。

阅读报告

报告标识其 schema 以及精确语料字节的 SHA-256。 它包含每一个提案/最终模型、preflight 原因、回放 action/reason、硬锁定结果、脚本化缓存热度和断言失败。被拒绝的步骤使用 rejected: true、空的最终模型和终止性的拒绝结果。它们不会写入新的会话所有者，也不计为模型切换。

指标包括契约通过率、切换、被阻止的切换违规、不安全采样违规、不必要切换、错过的脚本化机会、回放解释覆盖率、progress gate 契约/解释覆盖率、安全抑制应用率，以及避免恢复不合格当前模型的比率。每个比率都带有计数和分母；空分母为 null，而不是成功的零违规测量。 脚本化机会表示 fixture 指定了一个被允许且足够有优势的提案。它不是对真实任务质量的反事实估计。

质量收益、计费成本、推理延迟、测得的缓存节省和统计不确定性明确不可用。确定性契约语料不是真实智能体会话的样本，测试执行时间也不是模型延迟。这些主张需要成对任务运行和测得结果。

扩展覆盖

添加带稳定 ID 和增量消息历史的短场景。将阻塞状态与其释放状态配对，这样从不切换的策略无法通过。包含最终模型、采样权限、硬锁定状态、preflight 原因和回放解释的精确期望。步骤携带语义覆盖标签；校验会拒绝缺失的必需能力和未知标签。添加或重命名场景不要求固定场景数量。保持场景隔离和确定性报告。

语料带有显式缺失覆盖列表，并复制到每份报告。 它包括 adaptation 学习和延迟结果交付、救援和失败分发/回退路径、超时、空闲过期边界、上游授权/驻留/预算资格、真实模型测量、传输和外部状态存储。 委托角色和多臂影子执行必须在其所属功能落地后才能添加。

此基线之后仍保持 issue #2338 开放：这些缺口不是通过结果。

剩余 issue 标准

本 PR 卡住当前保护基线，并保持 issue #2338 开放。 后续工作按必须产出的证据拆分：

Issue 标准	后续证据
多轮会话和委托角色	所属契约落地后，添加角色事实以及 selected/final-role 断言。
安全探索和错过的机会	用延迟结果、超时、失败切换、救援证据以及失败/回退来源扩展确定性 progress gate 覆盖。
硬保护约束	演练上游授权、安全、驻留、上下文、能力和预算冲突，以及候选资格。
质量、成本、延迟、缓存和不确定性	用实际模型结果、重复测量和约定接受阈值，运行成对的基线/探索任务。
PR 和发布校验	在 PR 测试中保留确定性保护检查；将测得证据集成到单独的发布或定时基准门槛。

现有的实时 Agent 任务脚本可以为测量 runner 提供任务示例，但其完成评分标准不是保护断言。共享场景加载和测量设计属于该后续工作。