Reasonix 模型能力元数据完全指南从 /models 能力声明到图片输入控制的逐层解析【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-ReasonixReasonix 以“按精确模型解析输入能力”为核心通过 Provider Adapter 从 OpenAI 兼容的/models响应、内置本地校验目录与动态缓存中确定每个模型是否原生支持图片输入。本文以docs/MODEL_CAPABILITIES.zh-CN.md为主线结合仓库源码讲解能力声明字段的解析规则、model-capabilities-v2.json缓存机制、内置 Adapter 的本地目录、中转站模型的图片输入配置步骤与最终优先级链帮助读者彻底理解“图片能力未识别”背后的判定逻辑并能在不依赖模型列表请求的情况下正确为自定义接入配置图片输入。一、能力元数据契约inputModalities 与三种能力状态Reasonix 的 Provider Adapter 遵循deepseek-harness的模型契约为精确模型返回inputModalities输入模态核心类型定义在 internal/provider/model_info.gotext模型接受文本输入image模型接受原生图片输入text image模型同时接受文本与图片此时无需配置VisionModels即可自动启用多模态请求。ModelInfo结构体见 internal/provider/model_info.go的InputModalities字段是能力判定的唯一事实来源同时携带ContextWindow、MaxOutputTokens、Reasoning、Pricing等目录元数据。这里有一个关键语义InputModalities为nil表示“未能确定能力”而显式的[]{text}则是“明确的否定声明”不支持图片。在 internal/config/model_capabilities.go 中三种能力状态被定义为CapabilitySupportedsupported声明包含image模态支持图片输入CapabilityUnsupportedunsupported只有有效文本声明明确不支持图片CapabilityUnknownunknown缺失、无效或冲突声明即“图片能力未识别”——内部表现为nil在 Desktop 视图返回[]。每个判定结果还带有Source能力来源共 8 种override用户显式覆盖、preset精选预设、legacy旧配置vision/vision_models、adapterAdapter 在线发现、cache动态缓存、adapter_default、unknown未知、protocol官方协议硬限制。Source是理解优先级链和排查问题的核心线索——测试 internal/config/model_capabilities_test.go 正是通过断言State与Source的组合来验证“显式配置优先于缓存”的行为。二、OpenAI 兼容 /models 响应的解析规则当接入配置了模型列表地址时Reasonix 通过FetchModelCatalog请求 OpenAI 兼容的GET /models端点实现位于 internal/provider/openai/fetch_models.go。对每个模型条目parseModalitiesinternal/provider/openai/fetch_models.go按下述顺序提取能力声明标准字段input_modalities数组如[text,image]兼容别名modalities.input嵌套对象中的 input 数组capabilities.input_modalitiescapabilities.vision布尔supports_vision布尔vision布尔。解析规则有以下要点与文档描述一一对应标准字段优先于别名只要input_modalities存在就直接采用其解析结果即使标准字段的值无效也不会回退到别名悄悄“开启”图片能力——无效即保持未知缺失 / 无效 / 冲突 → 未知decodeModalities要求数组非空且每个元素只能是小写化的text或image否则返回未知见 internal/provider/openai/fetch_models.go布尔别名解析失败或值为null同样未知重复 ID 合并与顺序无关同一响应中出现重复模型 ID 时未知观察不会覆盖有效事实而相互矛盾的有效声明最终保持未知冲突标记后清空为nil见 internal/provider/openai/fetch_models.go绝不根据模型名称猜测代码注释明确指出“callers must never infer image support from a model name”internal/provider/openai/fetch_models.go这是防止误判的硬性纪律。此外模型列表请求复用与聊天请求一致的传输策略代理、超时 10 秒、响应体上限 2 MiB并支持bearer、x-api-key与默认三种鉴权模式internal/provider/openai/fetch_models.go。三、动态缓存 model-capabilities-v2.json位置、TTL 与指纹隔离动态发现的元数据保存在 Reasonix 缓存目录下独立的model-capabilities-v2.json文件中绝不会写入config.toml。缓存实现位于 internal/config/model_capabilities.go关键约束包括缓存文件路径为CacheDir()/model-capabilities-v2.json可通过REASONIX_CACHE_HOME环境变量指定缓存根目录测试 internal/config/model_capabilities_test.go 验证了这一点TTL 与容量条目 TTL 固定 24 小时modelCapabilityCacheTTL 24 * time.Hour文件大小上限 2 MiBmodelCapabilityCacheMaxSize 2 20条目数上限 4096超限时按FetchedAt时间排序截断跨进程合并持久化时先获取.lock文件锁再与磁盘上的最新快照合并避免多次刷新互相覆盖写入使用严格原子替换fileutil.AtomicWriteFileStrictWindows 与 Unix 行为一致安全写入缓存文件权限为0600测试断言缓存中绝不包含 API Key 或Authorization头等凭据材料。路由与凭据变化隔离缓存是这套机制的核心安全设计每条缓存条目都带有ProviderFingerprint它由 HMAC-SHA256 对 Provider 的Name、Kind、BaseURL、ChatURL、RequestURL、ModelsURL、APIKeyEnv、鉴权头、代理开关以及凭据修订号credentialsRevision来自 CredentialStore计算得出internal/config/model_capabilities.go。因此修改路由、请求头或凭据都会产生新指纹旧缓存条目自然失效晚到的旧请求不会覆盖较新的成功发现PutCatalogAt按请求发起时间started排序仅在started晚于已有FetchedAt时才覆盖见 internal/config/model_capabilities.go请求失败不覆盖成功结果成功但仅返回 ID无能力字段时记录“未知”事实。V1 与 V2 的隔离V2 不读取、不迁移、不修改 V1 缓存因为旧缓存无法区分“缺字段”与“明确否定”。只依赖 V1 正面缓存的自定义模型需要刷新一次模型列表或手动开启图片输入。四、内置 Adapter 与本地校验目录不依赖模型列表请求除了在线/models发现内置 Adapter 还为所有未被修改的精选 Provider 预设生成本地校验目录presetModelInfo见 internal/config/model_capabilities.go覆盖官方 OpenCode Go 路由chat / anthropic / responsesDeepSeek vision SKU如deepseek-v4-flash-vision-expModelScope Qwen3.5 SKU其余预设模型列表kimi-cn、mimo-api、minimax-cn-api、glm-cn、stepfun-api、scnet、ollama-cloud 等见测试 internal/config/model_capabilities_test.go。内置目录的解析入口是BuiltinModelInfointernal/provider/opencode_go.go它依次尝试OpenCodeGoModelInfo官方 OpenCode Go 路由 显式图片声明表见 internal/provider/opencode_go.go、ModelScopeModelInfo与官方 DeepSeek 模型判定。这些目录采用精确匹配只有 Provider ID、API 类型openai-completions/openai-responses/anthropic-messages与 BaseURL 与目录条目完全一致时才生效自定义 Endpoint 永远不会继承目录元数据见 internal/provider/pi_catalog.go。判定顺序resolveAutomaticinternal/config/model_capabilities.go为预设目录 → 旧配置vision→ 旧配置vision_models→ Pi/内置目录事实 → 在线缓存 → 未知。自定义 Endpoint、已编辑的预设或本地目录之外的模型在没有其他有效来源时保持未知。五、中转站模型使用指南三步开启图片输入对于不支持标准能力字段的中转站网关模型需要手动声明。操作步骤如下在“设置 → 模型”新增或编辑接入获取模型列表勾选需要的模型。若显示“图片能力未识别”先向服务商确认该模型确实支持图片再将“图片输入”选为“开启”点击保存等待运行时重建成功后再发送图片。刷新模型列表和重启应用都会保留该选择。接入编辑器和刷新模型列表入口均提供三态开关自动Auto清除当前模型的vision覆盖恢复自动判定链路上下文、输出与 reasoning 设置保持不变。若沿用旧配置界面会显示“自动 · 沿用旧配置”开启On声明该接入支持图片。注意这只是用户声明不代表客户端已实测也不会触发付费能力探测关闭Off禁止原生图片输入包括本地目录已知的视觉型号。对应的 TOML 配置为同样适用于 reasonix.example.toml 中的model_overrides结构[providers.model_overrides.example-model] vision true # false 为关闭删除此字段恢复自动最终优先级链internal/config/model_capabilities.go官方协议硬限制 → 当前模型显式覆盖model_overrides.model.vision→ 原自动链路精选预设、旧配置、本地精确目录、有效在线缓存→ 未知。两个值得注意的硬性规则官方 DeepSeek 文本型号不能被手动开启当请求 URL 命中官方 DeepSeek 端点且模型属于IsOfficialDeepSeekTextModel目前为deepseek-v4-pro见 internal/provider/deepseek_models.go时能力被强制置为CapabilityUnsupported、来源标记为CapabilitySourceProtocolImageInputEnableAllowed false并给出official_deepseek_text_model的阻塞原因官方 DeepSeek 视觉型号可以显式关闭视觉型号清单由officialDeepSeekImageModels统一维护internal/provider/deepseek_models.go是官方端点图片能力的唯一权威能力解析器、运行时视觉门禁与本地目录都复用同一份清单。此外能力覆盖只影响视觉开关本身不会丢失本地目录中的上下文窗口、输出上限、协议与 reasoning 元数据——目录事实与能力判定是分离解析的见 internal/config/model_capabilities.go 的注释。界面回传的能力信息不作为发现事实保存。六、能力切换与会话重建冻结快照与生效时机图片能力配置变更后各会话的生效时机有明确的规则当前空闲会话保存后立即重建其他已打开会话在下一回合前检查并重建正在执行的请求保持冻结的能力与请求体不受切换影响若保存或重建失败、被延期必须完成重建后新配置才生效输入框读取对应 Controller 的能力快照。同时Reasonix不会自动重发失败请求或历史图片发送消息也不会临时请求/models——模型列表只由设置页的显式刷新触发。这在 internal/provider/openai/fetch_models.go 的设计中也有体现模型列表请求是一个独立的显式操作不混入聊天主链路。一个值得注意的副作用系统提示词、工具 Schema 和纯文本请求序列化保持稳定但能力切换可能改变包含历史图片的上下文投影因此这些会话在重建前后的 prefix-cache 命中不能保证一致——这与 Reasonix 围绕 prefix-cache 稳定性设计的整体理念一致变更图片能力意味着需要接受一次缓存重建成本。七、sky-valley/pi 目录来源与升级审查机制更完整的 Provider/模型目录来源于 MIT 许可的github.com/sky-valley/pi/aiGo 版 Pi。Reasonix只使用其嵌入的模型数据GetModels、Model.Input及相关字段见 internal/provider/pi_catalog.go不引入它的 Agent 或 Provider 运行时。适配层将 Pi 目录转换为 Reasonix 中性的ModelInfomodelInfoFromPi并保持“精确 Provider/模型/路由匹配”的保守策略。目录依赖版本固定在go.mod中。仓库为此建立了两条升级护栏Dependabot 每周为sky-valley/pi单独创建升级 PR不与无关的 Go 依赖混合便于聚焦审查数据与许可证变化internal/provider/opencode_go_test.go中的 catalog contract tests会在关键模型能力发生漂移如某个模型的图片能力声明变化时失败因此升级前必须审查 Provider、API 与 Endpoint 差异确认目录行为符合预期。八、文本模型与未知模型的回退路径对于文本模型和未知能力模型Reasonix 继续使用现有的Agent.VisionModel、OCR 与 MCP vision fallback 机制处理图片相关场景——原始图片不会发送给这些模型。这意味着能力已知的视觉模型走原生多模态请求文本/未知模型仅通过既有降级链路如 OCR 提取文本、MCP 工具间接消费图片内容。小结Reasonix 的模型能力元数据体系可以用一句话概括能确定的来自本地目录与协议硬限制能发现的来自/models在线声明并缓存 24 小时都不确定的保持未知并允许用户显式覆盖。理解inputModalities的三态语义、model-capabilities-v2.json的指纹隔离缓存、内置本地目录的精确匹配约束以及“官方协议硬限制 → 显式覆盖 → 自动链路 → 未知”的最终优先级链即可在中转站接入、自定义 Endpoint 与官方 DeepSeek 模型三种场景下准确预判并控制图片输入行为。相关代码入口 - internal/config/model_capabilities.go 能力解析、优先级、V2 缓存 - internal/provider/openai/fetch_models.go /models 响应解析 - internal/provider/model_info.go ModelModality / ModelInfo 契约 - internal/provider/deepseek_models.go 官方 DeepSeek 视觉型号权威清单 - internal/provider/opencode_go.go 内置 OpenCode Go / ModelScope 目录 - internal/provider/pi_catalog.go sky-valley/pi 目录适配 - internal/config/model_capabilities_test.go 能力解析与缓存测试 - reasonix.example.toml 配置示例【免费下载链接】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），仅供参考