DeepSeek-Reasonix 适配器拥有的推理选项契约（Adapter-Owned Reasoning Contract）深入解析

DeepSeek-Reasonix 适配器拥有的推理选项契约（Adapter-Owned Reasoning Contract）深入解析

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix

DeepSeek-Reasonix 将"推理力度（reasoning effort）"的词汇表、默认值与序列化策略完全交给各协议适配器自主声明，核心层不维护任何全局统一的力度枚举。本文基于 docs/REASONING_CONTRACT.md 展开，结合internal/provider与internal/config的源码实现，系统讲解该契约的解析链路、校验规则、auto语义、兼容性边界，以及 DeepSeek、Anthropic、GLM、Kimi K3、MiniMax、Ollama Cloud 等协议的具体档位声明，帮助开发者理解配置项如何流转为请求字段、为何显式选择会先于网络 I/O 被拒绝，以及如何安全地为新模型接入推理力度控制。

一、契约核心：能力由适配器拥有，而非核心枚举

契约的第一原则是：每个协议适配器随工厂注册一个纯函数ReasoningForConfig，它返回当前连接与模型可用的选项（带顺序）、显示名称与可选描述，以及默认值。核心不定义统一的力度枚举，不存在"低/中/高"这样的全局词汇表。

在源码中，这一设计落实为三件事：

1. 适配器注册解析器：internal/provider/reasoning.go 中维护了reasoningRegistry映射，各适配器在包初始化阶段通过RegisterReasoning(kind, resolve)注册自己的解析函数；ReasoningForConfig(kind, cfg)从注册表取出解析器执行，返回Clone()后的副本。注释明确要求："consumes non-secret configuration and must not perform I/O"——即能力发现是纯计算，绝不读取凭据、绝不发起网络请求。
2. 客户端持有不可变快照：解析结果通过ReasoningProvider接口暴露为独立的能力副本。例如 OpenAI 客户端func (c *client) ReasoningCapability() provider.ReasoningCapability { return c.reasoning.Clone() }（见 internal/provider/openai/reasoning_capability.go），每次调用都返回克隆，外部修改不会影响客户端内部行为。
3. 核心各层共用同一份声明：配置校验、桌面端力度菜单、CLI 补全、本地模型目录以及请求校验，全部消费同一套ReasoningCapability声明，避免多处各维护一份档位表导致漂移。

数据模型

核心类型定义在 internal/provider/reasoning.go：

• ReasoningOption：单个档位，含ID（唯一标识）、Name（显示名）、Description（可选描述）。注释强调它是"adapter-owned identifier, not a global effort enum"。
• ReasoningCapability：一次解析出的端点/模型能力，含Options []ReasoningOption与Default string。Default为空表示保留供应商默认行为；选项列表为空表示该连接不具备力度控制能力。
• ReasoningProvider：接口，客户端只要实现ReasoningCapability() ReasoningCapability即可暴露能力。

ReasoningOptions(def string, ids ...string)是构造能力的便捷函数：第一个参数为默认档位，后续参数按顺序生成ID == Name的选项列表，例如provider.ReasoningOptions("high", "disabled", "low", "high", "max")表示默认high，可选档位依次为disabled/low/high/max。

部署声明优先于回退词汇表

DeclaredReasoning(cfg, fallback)（internal/provider/reasoning.go）允许部署显式声明档位以覆盖内置回退表：

• 读取配置中的supported_efforts（字符串数组），过滤空串与auto后去重；若非空，则以第一个元素作为默认值重建能力；
• 若配置了default_effort，则覆盖默认档位。

同时提供RestrictReasoning(cap, ids...)将能力裁剪到固定的线上协议子集，例如 GLM 协议最终只能保留enabled/disabled，MiniMax 只能保留adaptive/disabled（见下文协议表）。PreferredReasoning则仅供主机侧自动策略使用，注释明确警告：显式用户选择必须走Validate并报告拒绝，绝不可悄悄回退。

二、严格校验：显式选择必须精确匹配声明 ID

契约的第二条硬性规则：显式选择必须与声明的 ID 完全一致，不做任何就近档位映射（nearest-level mapping）。这是全文反复强调的设计取向：

• 不支持的值在网络请求前返回UNSUPPORTED_REASONING_EFFORT，绝不静默降级到相邻档位；
• 非法能力声明（如空 ID、重复 ID、auto混入声明）直接以INVALID_MODEL_REASONING拒绝；
• 只具备开关能力的协议（如 GLM 的enabled/disabled），不能通过在supported_efforts里填一堆深度值来虚构低/中/高能力——因为DeclaredReasoning的声明会经过协议层裁剪，且校验是精确匹配。

Validate的实现（internal/provider/reasoning.go）：

1. 遍历声明的 ID，若存在空串、字面auto或重复项，返回INVALID_MODEL_REASONING错误；
2. 若声明了默认档位但默认值不在 ID 列表中，返回UnsupportedReasoningEffort；
3. 待校验的effort为空则直接通过（空串表示继承配置，见下节）；
4. 否则精确查找，不在列表中即返回UnsupportedReasoningEffort。

错误类型UnsupportedReasoningEffort的错误信息形如：UNSUPPORTED_REASONING_EFFORT: model "xxx" does not support "yyy" (supported: [...])，携带模型名、非法值和支持列表，便于用户在 CLI 中直接看到可选项。测试覆盖见 internal/config/effort_test.go、internal/provider/openai/effort_test.go 与 internal/provider/reasoning_test.go。

非法默认值保留可见，不静默回退

契约要求：配置中非法的默认值保留下来供校验报错，而不是回退到第一个档位。这对应Validate中Default不在 ID 列表即报错的分支。其动机是让配置错误"显性化"：用户在保存配置时即可看到校验失败，而不是悄悄被替换成一个看似合理实则违背意图的档位。

三、auto的语义与空字符串继承

auto是历史遗留的 UI/CLI 拼写，语义为"清除覆盖、使用默认"，它不是适配器选项，也不代表自适应思考。这一点在契约中专门澄清，避免与模型侧"自动思考"产生歧义。

• 请求级 override 使用空字符串表示继承配置，而不是发送字面值auto；
• CLI 与配置层做同样的归一化：NormalizeEffort（internal/config/effort.go）在收到auto时返回空串；
• EffortDisplay反向展示：配置中的空力度在 UI/CLI 上显示为auto。

同时保留历史兼容处理：

• 旧配置中已退役的off档位在加载时被归一化为空串（normalizeStoredEffort将"auto"与"off"均映射为空）；
• 大小写不敏感：normalizeEffortLevel统一做ToLower + TrimSpace；
• 已有合法 ID 与 TOML 字段名保持不变，不重写用户配置。

四、DeepSeekmedium/xhigh的历史 wire 值保留

契约明确：未声明自定义档位词汇表时，已保存的 DeepSeekmedium、xhigh沿用历史请求值high，且配置存储不被重写——只影响线上请求的序列化值。

这一迁移逻辑在EffectiveEffort（internal/config/effort.go）中体现：显式存储的力度会经过migrateStoredDeepSeekEffort处理；而normalizeProviderEffortFields只做归一化（大小写、auto/off清理、去重），不改写已保存的medium/xhigh字面值。换句话说：配置里写什么，磁盘上就保留什么；只有请求序列化时映射为high。新出现的显式选择与请求覆盖则严格执行新规则——未声明的别名一律拒绝。

五、兼容性边界一览

契约用一张边界表明确了各层级的兼容行为，完整继承如下：

前两条在配置层与协议层的对应实现是：normalizeProviderEffortFields只做归一化不改写合法值；EffortCapabilityForEntry构造EffortCapability{Supported, Levels, Default}，其中Levels以auto开头拼接cap.IDs()，即旧的levels语义仍完整可用。auto被始终放在候选列表首位，保证 UI 上"继承默认"永远可达。

六、各协议适配器的档位声明（源码证据）

契约只规定机制，具体词汇表由各适配器自行裁决。以下是当前仓库中各协议的ReasoningForConfig实际声明：

OpenAI 兼容适配器（internal/provider/openai/reasoning_capability.go），按reasoning_protocol或端点自动探测（IsDeepSeek/IsZhipu/IsMiniMax/IsOllamaCloud/IsMiMo等）分流：

DeepSeek 分支还受显式thinking配置影响：若thinking: disabled，能力被收窄为disabled单档，且请求中reasoning_effort清空（deepSeekRequestThinking，见 internal/provider/openai/effort.go）；thinking是供应商无关的逃生舱字段，未知值被忽略以保证请求不因笔误而失败。

Anthropic 适配器（internal/provider/anthropic/reasoning_capability.go）：

Responses API 适配器（internal/provider/responses/reasoning_capability.go）：

三个适配器均以ApplyOpenCodeGoContract打底并统一应用DeclaredReasoning，保证部署声明的supported_efforts/default_effort优先于内置回退表。

七、请求级覆盖与缓存语义

请求级 override（Request.EffortOverride）在客户端已解析好的能力上校验通过后才允许进入流式 I/O。以 OpenAI 客户端为例（internal/provider/openai/effort.go）：

• requestEffort(req)：EffortOverride非空即获胜，否则继承客户端构造时解析出的c.effort；
• configuredEffort(cfg)：构造期校验，auto/off/none/thinking=disabled直接透传，其余走cap.Validate；
• DeepSeek 的deepSeekRequestThinking(req)：override 为disabled时关闭思考并清空reasoning_effort；override 为其他值时强制开启思考。

契约同时提示：默认请求保留原有序列化方式（不新增提示词字节），因此"不调整力度"不会改变既有请求形态；但主动修改力度可能改变服务端缓存行为——力度值参与请求内容，前缀缓存命中率可能因此变化，这正是项目围绕 prefix-cache 稳定性设计的关注点（见仓库根目录 README.md 对 DeepSeek-native 与 prefix-cache 的描述）。契约本身不注入任何提示词内容，也不做自动跨模型力度迁移。

八、实验性 governor 与设计边界

实验性 governor 在自动应用 low 档位前，会先检查适配器的声明能力（PreferredReasoning即为此类主机侧自动策略设计），确保自动策略不越出声明范围。

契约还明确声明了两条设计边界，避免架构扩散：

• 不引入自动跨模型力度迁移：不会因为模型 A 支持high就自动把模型 B 的档位迁移过去；
• 不移植 Harness 的请求日志架构：Reasonix 的该设计受 DeepSeek Harness 的 adapter-owned reasoning contract 启发，但为独立实现，未复制任何上游代码——理由写在文档末尾，也是本仓库"契约本地化、实现自主化"的一贯做法。

九、配置实操：TOML 中的字段与解析链路

结合契约与源码，开发者可在一份 Provider TOML 中这样配置推理力度（字段名与合法 ID 均以仓库为准，此处为示意组合）：

[providers.deepseek] kind = "openai" base_url = "https://api.deepseek.com" # 触发 IsDeepSeek 端点探测 model = "deepseek-v4-pro" # 命中模型能力注册表（见 modelReasoningCapabilities） effort = "high" # 显式存储的默认力度 default_effort = "high" # supported_efforts 存在时的运行时默认 supported_efforts = ["disabled", "low", "high", "max"] # 部署显式声明，覆盖内置回退表 [providers.deepseek.model_overrides.deepseek-v4-flash] supported_efforts = ["low", "high"] default_effort = "low"

配置加载后的完整解析链路（全部位于 internal/config/effort.go）：

1. normalizeProviderEffortFields归一化：effort中auto/off清空，default_effort/supported_efforts统一小写去重；
2. ReasoningCapabilityForEntry决定走哪条路径：Kind为空（远程/解析器条目）时直接用SupportedEfforts+DefaultEffort构造能力；否则按ReasoningProtocolForEntry解析出的协议（显式配置 → OpenCode Go 契约 → 模型能力注册表 → GLM/DeepSeek 端点启发式）构造provider.Config并调用provider.ReasoningForConfig；
3. 适配器ReasoningForConfig返回能力副本 →Validate校验默认值与显式值 →EffectiveEffort决定请求实际携带的力度（含 DeepSeekmedium/xhigh→high的历史 wire 值迁移）。

日常 CLI 使用中，/effort auto|<level>是唯一入口：auto清除覆盖继承默认，<level>必须与声明 ID 精确一致，非法值在发送任何网络请求之前就会收到UNSUPPORTED_REASONING_EFFORT报错并附带支持列表。

十、总结

DeepSeek-Reasonix 的适配器拥有推理选项契约，用一套"声明 + 精确校验 + 克隆快照"的机制，把推理力度的词汇表、默认值与序列化策略彻底下放到协议适配器：

• 核心不设全局枚举，所有 UI/CLI/配置/校验共享同一声明来源；
• 显式选择严格精确匹配，网络 I/O 之前即拒绝非法值，不做就近映射、不静默回退、不虚构档位；
• auto只表达"清除覆盖"，空字符串才是请求级继承的拼写；
• 历史配置（off、大小写、DeepSeekmedium/xhigh）在存储层保持原样，仅在请求序列化时兼容映射；
• 五类边界（Provider TOML、桌面菜单、前后端版本、远程模型目录、历史内容）均有明确兼容行为。

想深入验证契约行为，推荐阅读 internal/provider/reasoning_test.go、internal/config/effort_test.go 与 internal/provider/openai/effort_override_test.go 中的测试用例，它们以断言形式固化了"精确匹配、拒绝别名、保留非法默认值"等全部关键语义。

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix