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-ReasonixDeepSeek-Reasonix 将推理力度reasoning effort的词汇表、默认值与序列化策略完全交给各协议适配器自主声明核心层不维护任何全局统一的力度枚举。本文基于 docs/REASONING_CONTRACT.md 展开结合internal/provider与internal/config的源码实现系统讲解该契约的解析链路、校验规则、auto语义、兼容性边界以及 DeepSeek、Anthropic、GLM、Kimi K3、MiniMax、Ollama Cloud 等协议的具体档位声明帮助开发者理解配置项如何流转为请求字段、为何显式选择会先于网络 I/O 被拒绝以及如何安全地为新模型接入推理力度控制。一、契约核心能力由适配器拥有而非核心枚举契约的第一原则是每个协议适配器随工厂注册一个纯函数ReasoningForConfig它返回当前连接与模型可用的选项带顺序、显示名称与可选描述以及默认值。核心不定义统一的力度枚举不存在低/中/高这样的全局词汇表。在源码中这一设计落实为三件事适配器注册解析器internal/provider/reasoning.go 中维护了reasoningRegistry映射各适配器在包初始化阶段通过RegisterReasoning(kind, resolve)注册自己的解析函数ReasoningForConfig(kind, cfg)从注册表取出解析器执行返回Clone()后的副本。注释明确要求consumes non-secret configuration and must not perform I/O——即能力发现是纯计算绝不读取凭据、绝不发起网络请求。客户端持有不可变快照解析结果通过ReasoningProvider接口暴露为独立的能力副本。例如 OpenAI 客户端func (c *client) ReasoningCapability() provider.ReasoningCapability { return c.reasoning.Clone() }见 internal/provider/openai/reasoning_capability.go每次调用都返回克隆外部修改不会影响客户端内部行为。核心各层共用同一份声明配置校验、桌面端力度菜单、CLI 补全、本地模型目录以及请求校验全部消费同一套ReasoningCapability声明避免多处各维护一份档位表导致漂移。数据模型核心类型定义在 internal/provider/reasoning.goReasoningOption单个档位含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/disabledMiniMax 只能保留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遍历声明的 ID若存在空串、字面auto或重复项返回INVALID_MODEL_REASONING错误若声明了默认档位但默认值不在 ID 列表中返回UnsupportedReasoningEffort待校验的effort为空则直接通过空串表示继承配置见下节否则精确查找不在列表中即返回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 使用空字符串表示继承配置而不是发送字面值autoCLI 与配置层做同样的归一化NormalizeEffortinternal/config/effort.go在收到auto时返回空串EffortDisplay反向展示配置中的空力度在 UI/CLI 上显示为auto。同时保留历史兼容处理旧配置中已退役的off档位在加载时被归一化为空串normalizeStoredEffort将auto与off均映射为空大小写不敏感normalizeEffortLevel统一做ToLower TrimSpace已有合法 ID 与 TOML 字段名保持不变不重写用户配置。四、DeepSeekmedium/xhigh的历史 wire 值保留契约明确未声明自定义档位词汇表时已保存的 DeepSeekmedium、xhigh沿用历史请求值high且配置存储不被重写——只影响线上请求的序列化值。这一迁移逻辑在EffectiveEffortinternal/config/effort.go中体现显式存储的力度会经过migrateStoredDeepSeekEffort处理而normalizeProviderEffortFields只做归一化大小写、auto/off清理、去重不改写已保存的medium/xhigh字面值。换句话说配置里写什么磁盘上就保留什么只有请求序列化时映射为high。新出现的显式选择与请求覆盖则严格执行新规则——未声明的别名一律拒绝。五、兼容性边界一览契约用一张边界表明确了各层级的兼容行为完整继承如下边界兼容行为Provider TOML字段与合法 ID 不变不自动重写文件桌面EffortInfo.options新增可选元数据同时保留旧levels字段供旧客户端读取新前端连接旧后端回退读取levels字段远程模型目录继续使用原有Efforts声明保持权威模型历史不改提示词、工具定义或历史思考内容前两条在配置层与协议层的对应实现是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等分流协议/端点档位声明默认值 可选 ID说明Kimi K3max可选low/high/max固定采样值协议不传温度等字段GLMZhipu/LongCatenabled可选enabled/disabled二元思考开关经RestrictReasoning裁剪reasoning_effort不发送MiniMaxadaptive可选adaptive/disabled经RestrictReasoning裁剪thinking.type驱动DeepSeekhigh可选disabled/high/maxdeepseek-v4-flash/deepseek-v4-pro及官方视觉模型为high可选disabled/low/high/maxthinkingreasoning_effort双字段Ollama Cloud空默认可选none/low/medium/high/max接受reasoning_effortmax本地 Ollama 不匹配OpenAI / MiMo空默认可选low/medium/highmax_completion_tokens契约OpenAI 官方端点未知端点空能力无力度控制DeepSeek 分支还受显式thinking配置影响若thinking: disabled能力被收窄为disabled单档且请求中reasoning_effort清空deepSeekRequestThinking见 internal/provider/openai/effort.gothinking是供应商无关的逃生舱字段未知值被忽略以保证请求不因笔误而失败。Anthropic 适配器internal/provider/anthropic/reasoning_capability.go场景档位声明reasoning_protocoldeepseek或 DeepSeek 端点high可选disabled/low/high/max显式thinkingenabled/disabled以该值为默认可选enabled/disabled随后经RestrictReasoning裁剪默认Anthropic 原生空默认可选low/medium/high/xhigh/maxResponses API 适配器internal/provider/responses/reasoning_capability.go场景档位声明protocoldeepseek或端点探测为 deepseekhigh可选none/low/high/maxMiMo 端点空默认可选none/low/medium/highprotocolopenai空默认可选low/medium/high其他空能力三个适配器均以ApplyOpenCodeGoContract打底并统一应用DeclaredReasoning保证部署声明的supported_efforts/default_effort优先于内置回退表。七、请求级覆盖与缓存语义请求级 overrideRequest.EffortOverride在客户端已解析好的能力上校验通过后才允许进入流式 I/O。以 OpenAI 客户端为例internal/provider/openai/effort.gorequestEffort(req)EffortOverride非空即获胜否则继承客户端构造时解析出的c.effortconfiguredEffort(cfg)构造期校验auto/off/none/thinkingdisabled直接透传其余走cap.ValidateDeepSeek 的deepSeekRequestThinking(req)override 为disabled时关闭思考并清空reasoning_effortoverride 为其他值时强制开启思考。契约同时提示默认请求保留原有序列化方式不新增提示词字节因此不调整力度不会改变既有请求形态但主动修改力度可能改变服务端缓存行为——力度值参与请求内容前缀缓存命中率可能因此变化这正是项目围绕 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.gonormalizeProviderEffortFields归一化effort中auto/off清空default_effort/supported_efforts统一小写去重ReasoningCapabilityForEntry决定走哪条路径Kind为空远程/解析器条目时直接用SupportedEffortsDefaultEffort构造能力否则按ReasoningProtocolForEntry解析出的协议显式配置 → OpenCode Go 契约 → 模型能力注册表 → GLM/DeepSeek 端点启发式构造provider.Config并调用provider.ReasoningForConfig适配器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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考