# Agent Note: 适配器持有的推理强度能力

Status: implemented

[English](2026-07-24-adapter-owned-reasoning-effort-capabilities.md) | 中文

## 问题

推理强度过去只能在适配器中配置，因此对话无法在多次请求之间发现或更改所选模型支持的等级。若将某个适配器的等级联合类型提升到 `dsh-llm`，所有提供方和模型都必须采用一套自身可能并不支持的名称；若改用提供方特有的 options 对象，agent loop（智能体循环）又无法校验最终生效的请求，也无法通过持久化记录准确重建该请求。

## 决策

`dsh-llm` 使用不透明的品牌类型 `ReasoningEffortId` 表示推理强度。由适配器持有的单次 `resolveModel(provider, model, signal?)` 查询返回 `LlmResolvedModelInfo`，其中包含确切模型身份以及可选的上下文和推理元数据。`LlmRuntime.resolveModelInfo()` 会校验该聚合结果，并返回与适配器内部状态分离的值副本。`reasoning.efforts` 存在时，是包含展示元数据的非空有序 ID 列表，并可指定一个由配置确定的默认值。核心要求显式指定或配置指定的推理强度与列表中的某个 ID 完全一致，且绝不自动调整或为值提供别名。

`LlmCallConfig` 和 `GenerateOptions` 携带可选的推理强度。agent loop 在活跃轮次信号的控制下准备 `agent/request` 处理完成后的配置，再写入 `request/header`，因此默认值和动态变更只有成为持久化事实后才对模型可见。准备完成的调用在异步确切模型解析、请求头持久记录和分派全程保留同一项确切的适配器注册；直接调用 `LlmRuntime.stream()` 时，也会在等待解析前捕获最终的适配器注册。没有已注册适配器的路由会保留原定配置，使 `llm/stream` 中间件可以接管并短路该请求；若仍未得到处理，最终分发会拒绝该路由。恢复后的 agent loop 仅在初始提供方/模型路由未变时保留日志中记录的推理强度；如果路由发生变化，则丢弃上一模型的不透明 ID。

当部署策略允许思考时，原生 DeepSeek 适配器声明 `off`、`low`、`high` 和 `max`，默认使用配置指定的推理强度，若未配置则使用 `high`。由适配器持有的 `off` 映射为 `thinking.type: disabled`，且不带 `reasoning_effort`；`low`、`high` 和 `max` 会启用思考并携带各自的同名官方协议强度值。配置为 `thinking: disabled` 的部署仅声明 `off`，并会在提供方 I/O 前拒绝启用思考的尝试。pi-ai 适配器原样发布每个确切模型的 `getSupportedThinkingLevels()` 结果，其中包括 `off`；profile 未指定默认值时保留提供方默认行为，并将提供方协议值的映射留在 pi-ai 内部。按照 pi-ai 自身 API 的要求，其通用流选项通过省略 `reasoning` 来表示 `off`。

## 备选方案

**在核心中定义 pi-ai 的 `ThinkingLevel` 联合类型。** 不予采纳：pi-ai 当前的规范名称属于适配器实现细节；未来的提供方可以暴露不同的标识符，而无需为此发布新的核心版本。

**携带无类型约束的提供方 options 对象。** 不予采纳：agent loop 既无法校验选定值，也无法在请求头中写入稳定且与提供方无关的事实。

**自动调整不支持的等级。** 不予采纳：静默替换会导致用户选定的控制项与日志记录的请求意图不一致，还会掩盖陈旧的部署配置。

**将每个适配器规范化为核心持有的等级列表，或移除 `off`。** 不予采纳：可选值集合属于确切模型的能力。客户端可以渲染某个适配器的 `off` 选项，而无需要求所有适配器都暴露该选项。

## 影响

客户端只需查询一次确切路由，即可渲染其身份、上下文容量和由适配器持有的推理选项，而无需了解全局枚举或自行合成 `off`。适配器配置仍是部署默认值和策略的归属方，`agent/request` 则可以在该策略范围内为每个步骤替换实际生效的推理强度。确切身份、上下文或推理元数据无效时，分别抛出 `INVALID_MODEL_INFO`、`INVALID_MODEL_CONTEXT` 或 `INVALID_MODEL_REASONING`；显式指定或配置指定的值不受支持时，会在提供方 I/O 前抛出 `UNSUPPORTED_REASONING_EFFORT`。

确切模型元数据的聚合查询采用异步方式，并且对于由权威目录支持的适配器可能失败。可选信号构成调用方的取消边界；异步适配器必须在信号中止后迅速完成结算，使 agent loop 的资源释放达到完全停稳。无密钥的服务、适配器、agent loop、会话和请求头测试为校验、默认值解析、动态变更、日志记录、恢复行为、HMR（热模块替换）期间的注册所有权和取消提供回归保障；可运行快照锁定实际组装请求头中的已解析推理强度，仅在有密钥时运行的适配器测试则覆盖提供方序列化。
