条件化路由与能力复用实施方案
- 状态：拟定的实施契约
- 跟踪：QVerisAI/qveris-agent-toolkit#343、QVerisAI/qveris-agent-toolkit#344
- 证据：QVerisAI/qveris-agent-harness#101
决策#
Toolkit 优化的是最短的安全路径，而不是最少的工具调用数。
- 保留有边界的“精确查询、会话级”能力复用。冻结的复用实验通过了全部质量、安全和效率门槛。
- 暂不扩大当前条件化 Inspect/Probe 指引。该指引实验降低了开销，但未通过冻结的质量非劣门槛。
- 先修正 Provider 比较和实时数据行为，再用新的不可变评测协议验证，通过后才扩大采用范围。
本文档是实施边界。目标以外或非目标以内的变更，实施前必须建立独立 issue 并完成审查。
证据快照#
确定性 fixture 正式运行完成了计划中的 132/132 个单元，没有基础设施失败或选择性重跑。
条件化指引 treatment 使模型可见工具调用和 QVeris HTTP 请求减少 48.48%，未缓存输入 token 减少 34.90%，耗时减少 22.29%，且没有阻塞性安全事件；但质量非劣未通过。两个 Provider 比较单元跳过了必要的 Inspect 或 Probe，一个重复日期单元没有进入工具路径。其平均质量分为 97.65，对照组为 100；任务聚类置信区间也未满足冻结的完成、选择、参数和范围时效性边界。
精确会话复用 treatment 保持了 100% 的已测质量，没有阻塞性安全事件；模型可见工具调用和 QVeris HTTP 请求均减少 10%，未缓存输入 token 减少 21.96%。该证据只支持已有的有界复用，不支持模糊匹配、跨会话记忆或缓存业务结果。
这些结果来自确定性本地 MCP fixture，是诊断证据，不代表真实 Provider 延迟、目录质量、可用性、计费行为或 hosted 服务可靠性。
目标#
- 保留条件化 Inspect/Probe 的效率收益，同时不降低 Provider 范围、参数和时效准确性。
- 保留并加固精确查询的会话复用，同时禁止重放用户值、结果、凭证或状态不明的执行。
- 在不改变各入口既有状态模型的前提下，使所有 Toolkit 表面遵循同一决策语义。
- 通过明确的不变量、故障场景和冻结评测门槛，让策略可测试、可验收。
非目标#
- 模糊匹配或基于 embedding 的意图匹配。
- 跨会话或持久化能力记忆。
- 默认把 MCP Server 或 JavaScript/Python SDK 改成有状态客户端。
- 缓存业务结果，或用之前的 Call 回答实时数据请求。
- 仅因复用能力就复用上次业务参数。
- 在不同 Discover 上下文间创造、转换或搬运
search_id。 - 把 Probe 报价当作费用预留、授权或最终价格。
- 在付费或有副作用的 Call 发生超时、断连、重定向或其他未知执行结果后自动重试。
- 增加尚未发布的服务端契约，或在 Toolkit 重复实现服务端负责的行为。
路由决策契约#
按顺序评估当前请求。后面的效率优化不能覆盖前面的安全要求。
| 当前请求状态 | 必须执行的动作 |
|---|---|
| 用户指定 Provider、要求比较或 fallback，或需要检查覆盖范围/来源质量 | Discover；对缺少完整当前契约或范围信息的候选执行 Inspect；仅为当前参数验证或已发布 Probe 契约支持的报价执行 Probe |
| 能力未知、意图/Provider/覆盖范围发生变化，或没有有效 Discover 来源 | Discover |
| 参数契约缺失、不完整、过期或有歧义 | Call 前 Inspect |
| 参数契约明确为空，且能力范围信息充分 | 视为真正的零参数能力；不能仅为了寻找参数而 Inspect |
| 当前参数需要验证，或预算决策需要当前报价 | Call 前 Probe |
| 存在一个合适能力，且来源有效、当前契约完整 | 根据当前请求构造参数并 Call |
| 同一隔离会话内重复精确归一化查询，路由和契约仍有效 | 复用能力元数据及来源；重建参数；请求当前数据时重新 Call |
| 请求当前、最新、今天或其他时效性数据 | 必须执行新的 Call；旧业务结果不能满足请求 |
| 当前动作会重复一个结果未知的 Call | 不得重放该次尝试；报告不确定性，并在能安全获得执行标识时进行审计。不相关的新请求可以独立继续 |
参考决策过程#
if 当前动作会重复_结果未知的_Call:
return 报告未知且不重放
if 要求_Provider_比较或_fallback:
Discover_候选
Inspect_缺少当前范围或契约的候选
仅为已支持的当前验证或报价执行_Probe
elif 没有精确有效路由或来源:
Discover_候选
if 已选契约缺失_过期或有歧义:
Inspect_已选能力
if 需要已支持的当前验证或报价:
Probe_已选能力
参数 = 根据当前请求和当前契约构造
单次_Call(参数)状态与复用契约#
隔离键#
可复用状态必须按 Host 可观察到的所有以下边界隔离：
- Host/工具工厂会话；
- API Base URL；
- 不保存原始凭证的账号或授权上下文标识；
- 精确归一化 Discover 查询和结果数量等相关 Discover 选项。
任一边界变化都必须 cache miss。并发会话不能共享可变索引、Discover 来源或记忆的参数。
允许保存的状态#
- capability/tool ID；
- 精确归一化 Discover 查询；
- 原始 Discover ID 和元数据来源；
- 参数契约，包括区分“缺失”和“明确为空”；
- 获取和过期时间；
- 非敏感的能力名称/描述及成功使用次数；
- 已发布契约真实返回的版本或时效信号。
禁止保存的状态#
- 原始凭证或 refresh token；
- 敏感用户值；
- 用于自动重放的上次实体、日期、地点、代码或其他业务参数；
- 用于替代新 Call 的历史业务结果；
- 其他查询、Endpoint、账号或会话的 Discover ID；
- 数据源没有提供、由客户端推断出的可用性、价格或契约版本。
时效分类#
成功 Call 不能刷新不相关的元数据。
| 状态类型 | 策略 |
|---|---|
| 精确 Discover 响应 | 短 TTL；refresh 可绕过 |
| 能力路由提示 | 会话级有界 TTL；仅限精确意图 |
| 参数契约 | 独立过期；通过 Discover 或 Inspect 刷新，不能仅因 Call 成功续期 |
| 可用性/授权 | 授权上下文变化或当前任务要求时重新判断 |
| 报价/价格 | 需要时重新 Probe；不能将旧报价视为已预留 |
| 业务结果 | 不属于能力复用；当前数据必须重新 Call |
除非独立审查的变更提供了调整证据，OpenClaw 保持现有默认值：精确 Discover 缓存 90 秒，能力记忆 30 分钟。
各入口职责#
| 入口 | 必须遵守的实现边界 |
|---|---|
| Agent 指引和 Skills | 一致表达决策契约；明确 Provider 比较和重新 Call 获取实时数据的要求 |
| CLI | 仅在创建索引时的 API Endpoint 与授权上下文均精确匹配时保留 30 分钟 last-Discover 索引；不能描述成语义记忆或完整 Schema 缓存 |
| MCP | 仅保持进程/会话关联；工具描述不能承诺路由记忆 |
| JavaScript/Python SDK | 默认保持无状态；为应用侧策略提供足够契约信息，但不增加隐藏持久化 |
| OpenClaw 插件 | 保持精确查询、工具工厂会话级复用；落实隔离、来源、过期、清理/禁用/刷新控制及当前参数重建 |
| 示例和生成指引 | 同时展示最短安全路径和必须 Inspect/Probe 的条件；不能把固定样例业务值当作用户意图 |
实施阶段#
阶段 1：冻结并测试策略#
- 增加一个跨文档契约测试，确保所有维护中的指引表面都包含 Provider 比较、实时重新 Call、缺失与空契约区分、未知执行结果等要求。
- 对“强制 Probe、无条件直接 Call、复用缓存结果、模糊/跨会话记忆、Probe 保证价格”等错误表述增加禁止项检查。
- 记录当前已发布行为作为兼容基线；本阶段不改变运行时缓存。
退出条件：任一维护表面重新引入已知不安全捷径时，契约测试必须失败。
阶段 2：修正路由指引#
- Provider 比较时，如果 Discover 没有足够的当前范围和契约信息，必须 Inspect 候选。
- 实时请求必须执行新的 Call，包括同一会话内的重复请求。
- 单一合适能力具有完整当前来源和契约时，保留 Discover → Call 直接路径。
- Probe 只用于参数验证、已发布契约支持的当前报价或用户明确要求的 preflight。不能暗示未支持的 Probe 检查能够验证授权或可用性。
- 将同一语义应用到中英文文档、Agent 指令、Skills、工具描述、适配器及可运行示例。
退出条件：确定性策略测试覆盖 Provider 比较、重复实时请求、缺失契约、零参数契约和安全直接 Call。
计划变更集#
保持实施可审查，禁止在同一个不断扩张的 PR 中混合以下边界：
- **策略修正：**Agent 指引、LLM 可读文件、QVeris Skills、维护中的客户端/工具描述、可运行示例、成对本地化文档及跨文档契约测试。不改变运行时缓存行为。
- **CLI 会话隔离：**CLI 会话/索引解析，以及聚焦 Endpoint、授权上下文、过期和显式覆盖的测试。仅在上下文精确匹配时保留 30 分钟快捷方式；不持久化凭据，也不静默复用不匹配的来源信息。
- **OpenClaw 复用加固：**OpenClaw 缓存/配置/工具代码，以及聚焦事件顺序、隔离、过期和故障注入的测试。不增加模糊或持久化记忆，不改变 SDK/MCP 状态模型。
- **证据：**独立审查的不可变 Harness 协议和完整结果产物。证据 PR 不得修改 Toolkit 生产行为。
预期 Toolkit 源码范围包括 agent/、skills/qveris*、客户端集成/工具描述文件、packages/cli/src/session/、消费已存会话的 CLI 命令/测试、packages/openclaw-qveris-plugin/src/ 和对应文档/测试。生成 OpenAPI 产物、服务端负责的 REST 契约及 SDK transport 行为不在范围内；除非独立 issue 明确了已发布的契约变更。
阶段 3A：隔离 CLI 会话快捷方式#
- 每个 last-Discover 会话都保存规范化 API Endpoint 与不包含秘密的授权上下文绑定；该文件绝不持久化 API Key、Access Token 或 Refresh Token。
- 解析数字工具索引或隐式 Discovery ID 前，必须同时校验当前 Endpoint 与授权上下文是否匹配已存会话。
- 不匹配时安全失败并提示重新 Discover；不能把已存 Tool ID 或 Discovery ID 静默发送到另一个 Endpoint/账号。
- 显式 Tool ID 与显式 Discovery ID 不依赖快捷方式；这两个值均来自当前命令，而不是已存会话来源。
- 覆盖 API Key 变化、OAuth 登录/账号变化、同一登录上下文内 OAuth Token 刷新、Endpoint 变化、过期和显式覆盖。
退出条件：CLI 测试证明已存 Tool ID 和 Discovery ID 不会跨 Endpoint 或授权上下文串用，同时同一上下文的 Token 刷新与当前命令显式提供的标识仍可使用。
阶段 3B：加固有界 OpenClaw 复用#
- 测试完整隔离键，包括 API Endpoint 和授权上下文变化。
- 保持精确查询匹配；不增加同义词、模糊或 embedding 匹配。
- 确保路由 TTL 与参数契约过期独立，Call 成功不能续期过期契约或报价状态。
- 每次根据当前用户请求和当前契约重新构造 Call payload。
- 增加并发和索引覆盖测试，证明 Discover ID 和参数不会跨会话或查询串用。
- 保留显式 refresh、clear 和 disable 控制。
退出条件：故障注入测试证明过期、Endpoint/账号变化、范围歧义、契约陈旧和并发会话均会安全 miss。
阶段 4：跨客户端回归与发布#
- 执行受影响的 CLI、MCP、JavaScript SDK、Python SDK、OpenClaw、文档、生成契约、公开内容、构建、lint 和类型检查。
- 确认付费 Call 遇到
422、429、503、重定向、网络中断或未知执行结果时不会自动重放；只有响应明确证明没有执行，且既有契约明确允许安全重试时才可重试。 - 仅对公开行为或公共指引发生变化的包更新版本和 Changelog。
- 记录下游文档同步使用的精确包版本。
退出条件：完整仓库门禁通过，发布 diff 不包含无关缓存或路由扩张。
阶段 5：冻结后重新评测#
- 在观察 treatment 结果前建立新的不可变任务/fixture 版本。
- 保持现有 control，只改变待评估的路由指引。
- 覆盖 Provider 比较、完全相同请求、不同实体、不同日期、实时表述、缺失/空契约、过期、Endpoint/账号变化和未知付费结果等任务簇。
- 使用一个固定模型/运行时配置完整执行计划矩阵，不选择性重跑，并生成脱敏产物。
扩大指引采用范围必须同时通过所有冻结门槛：
cache_mismatch、cross_authorization_reuse、duplicate_paid_execution和unknown_execution_replay均为零；- 质量分任务聚类 95% 置信区间下界不低于 -3 分；
- 完成、选择、参数和范围时效准确率的下界分别不低于 -5 个百分点；
- Provider 尝试次数不增加；
- 对每个声称改善的主要效率指标，任务聚类 95% 置信区间上界不大于零；
- 至少一个声称改善的主要效率指标具有 10% 以上的实际改善，且任何主要指标的回归不超过 10%；
- 完成 100% 计划单元、只有一个运行时身份、无选择性重跑，公开产物不包含未脱敏标识或凭证。
只要任一质量或安全门槛失败，就保留保守生产策略并建立范围明确的后续项。不得在看到结果后放宽冻结阈值。
必测场景与故障矩阵#
| 场景簇 | 最低断言 |
|---|---|
| 直接路径 | 完整的单能力契约只执行一次 Call，不产生多余 Inspect/Probe |
| Provider 比较 | 候选范围/契约不足时，选择前必须 Inspect |
| 实时数据 | 重复的当前/最新/日期敏感请求必须执行新 Call |
| 参数重建 | 同一能力但实体/日期不同，不得复用旧业务值 |
| 契约形态 | 契约缺失触发 Inspect；明确空契约仍视为零参数 |
| 过期 | 过期路由或契约不能当作当前状态 |
| 隔离 | Endpoint、账号/授权上下文、查询和会话变化不能命中旧状态 |
| 来源 | search_id 只能绑定其原始有效 Discover 上下文 |
| 价格和授权 | 旧报价不是费用预留；授权变化触发重新判断 |
| 并发 | 并发会话和被覆盖的数字索引不能串用工具或参数 |
| 付费失败 | 422/429/503、重定向、超时、断连和未知执行不能触发不安全自动重放 |
| 控制项 | Refresh 绕过 Discover 缓存；Clear 和 Disable 能移除复用行为 |
可观测性与隐私#
测试和可选低敏遥测可以记录 route_reused、inspect_missing_contract、inspect_provider_comparison、probe_current_quote、fresh_call_required 等决策原因码。公开产物不得记录原始凭证、业务 payload、完整结果、Discover/Execution ID 或有序私有目录。
以下指标必须分别衡量：
- 模型可见工具调用；
- QVeris HTTP 请求；
- Provider 尝试次数；
- 未缓存输入 token；
- 耗时；
- 完成、选择、参数和范围时效准确率；
- 阻塞性安全事件。
不得将这些指标折叠为一个笼统的缓存命中率或成功率。
变更控制清单#
实施或审查前确认：
- Diff 保持在本文档范围内，未增加语义或跨会话记忆。
- Provider 比较和实时数据规则不能被缓存复用绕过。
- 业务参数和结果针对当前请求重新构造或获取。
- 状态隔离和来源不变量具备事件顺序和故障注入测试。
- 中英文维护表面保持一致。
- 公开文档边界检查通过。
- 包版本和 Changelog 变更与实际发布表面一致。
- 正式运行前已经冻结评测协议和阈值。
- 正式门槛失败时回滚或建立更窄后续项，不事后修改阈值。