# 模型匹配与推荐规则

文件名沿用早期参考记录，本文描述当前推荐实现；pi-web 对比用于说明来源，不代表两者行为完全相同。

核查 pi-web 固定提交：`6fcd7d44981ab51a21d6cd6eb06d361d0e3d3068`。

## pi-web 实际流程

- [ModelsConfig.tsx](https://github.com/agegr/pi-web/blob/6fcd7d44981ab51a21d6cd6eb06d361d0e3d3068/components/ModelsConfig.tsx) 的 `handleCatalogFill` 将模型 ID、供应商名称和 Base URL 发给目录接口；请求序号防止旧结果覆盖新选择。`fillEmptyModelFields` 只补全空白字段和缺失单价，返回应用数量。结果留在草稿，用户最后保存。
- [catalog/route.ts](https://github.com/agegr/pi-web/blob/6fcd7d44981ab51a21d6cd6eb06d361d0e3d3068/app/api/models-config/catalog/route.ts) 下载 Models.dev，使用一小时缓存和进行中的请求复用；刷新失败时有旧缓存则回退。搜索结果和自动推荐独立计算。
- [model-catalog.ts](https://github.com/agegr/pi-web/blob/6fcd7d44981ab51a21d6cd6eb06d361d0e3d3068/lib/model-catalog.ts) 先归一化 ID（大小写、`models/`、`provider/id`），再优先匹配供应商 ID／名称、API 主机名；没有直接匹配时按字段推荐一致值。参数字段需要至少 60% 的候选支持。价格按输入／输出组合分组，需要至少两个有效报价，最大组达到 60% 或至少 5 个来源支持，并且不能并列。支持不足或存在分歧时不填价格。

## 本插件的实现与差异

主流程为：**选择已添加供应商 → 选择其模型 → 填入模型信息 → 保存**。两级选框同排显示；搜索只在弹出框内出现；最多展示前 200 个搜索结果。高级来源选择、字段差异、价格编辑、推理映射继续折叠。

`recommend` 在宿主读取所选路由的名称和 Base URL，仅用主机名作本地匹配，不向目录服务发送路由地址或凭据。一次调用返回参数建议、匹配说明、候选和可用价格 ticket。来源选择不再是默认流程的前置步骤。

当前参数推荐：识别到模型官方来源时，显示名、上下文、最大输出和输入模态按官方来源权重 5、其他来源权重 1 投票，仍需达到总权重的 60%，并列不采用。一个供应商只计一票；官方地区条目各计 5。字段缺失仍计入总权重，不伪造数据。未识别到官方来源时沿用供应商名称、API 地址直接匹配，再回退等权投票。

具体推理档位不参与投票：仅取官方目录的 reasoning_options/effort。优先匹配已配置的官方供应商或地址，否则按官方来源表顺序选择（例如 moonshotai，再 moonshotai-cn）。官方缺失或仅提供 toggle/budget_tokens 时不从其他来源推断档位。reasoning 能力标记独立传递供界面解释，不写入宿主不支持的字段；已有用户配置继续保留，高级比较仍允许显式选择来源。

价格继续沿用独立的供应商匹配及共识规则，不受参数权重影响。DSH 的保存方式、字段类型和以下行为保持本插件语义：

- 名称与 API 主机名匹配到不同供应商，或名称仍对应多个候选时，不自动选择价格。界面显示分歧，用户可在“参考价格来源”中明确选择；两类证据一致时优先使用其交集。
- 缺失缓存价与并列缓存价保持未知，不像 pi-web 默认填零；明确的零价仍保留。
- 订阅、阶梯、分时及附加计费不作为固定单价参加推荐。CNY 必须有原生币种数据，不换算 USD。
- 参数来自 Models.dev，价格按选定来源使用 Models.dev 或 basellm。任一来源失败不会阻止另一来源的结果；分别解释失败原因，参数刷新失败也不采用过期建议。
- 参考报价保存在宿主，保存使用已预览快照；共识价格记录支持数、总数和参与来源，不能标作某一家官方报价。
- 已有名称、容量、具体推理档和人工单价通常保留；图片缺失、false/空推理档可按已知建议补全到草稿。其他冲突由高级比较主动应用，详见 [草稿规则](editor.md#草稿与撤销)。推理布尔值不凭空生成 DSH 推理档。
- 沿用可配置缓存 TTL 和明确失败行为，没有照搬 pi-web 的陈旧缓存回退；显式重新获取参考单价绕过 TTL。
- 原有批量导入入口仍单独确认所选模型及字段，自动推荐主要作用于模型编辑器和内置模型覆盖面板。

## 即时刷新

客户端订阅与 DSH 原生模型页相同的 `settings/document-updated`、`llm/adapters-updated` 和 `connection/reset` 事件。界面挂载时监听，卸载时清理；收到事件重新读取模型列表和供应商目录，旧响应失效。主列表、导入供应商列表及内置供应商列表同步刷新，不重新读取或丢弃当前模型草稿。目标模型被删除时清空选择。

自动化覆盖直接匹配、共识与分歧、复杂计费、未知价、原币种、报价来源写盘和重启、异步切换、动态供应商增删、草稿保留及 350 模型搜索。用户已在 DSH Desktop 0.2.0-rc.2 实际安装后确认主要界面、配置写盘和 Gateway 使用流程；其他宿主版本及边界场景仍按兼容性范围单独评估。