一键挂载与模型归一
上游各家对同一个底座模型的命名不一样：claude-3-5-sonnet-latest 与 claude-3-5-sonnet-20241022，mimo-v2.5 与 mimo-v2.5-flash。有两种处理方式，用途不同：
| 方式 | 做什么 | 适合 |
|---|---|---|
| 一键挂载（auto-match） | 把「确实提供该模型」的启用渠道挂进指定分组 | 新模型接入 |
| 模型归一（unify） | 把多个原名路由合并成一个对外名，可撤销 | 已经积累了一堆别名 |
这一页讲一键挂载；模型归一见模型归一（unify）。
一键挂载
POST /admin/routes/{id}/auto-match它把「确实提供该模式」的启用渠道挂进指定分组，用的是与创建路由同一套交集逻辑——所以过期的控制台选择不可能凭空造出一个成员。
匹配范围：exact 与 related
| 模式 | 匹配什么 |
|---|---|
exact（默认） | 普通名字精确匹配；* 由操作员自己写 |
related | 额外接受「以该 pattern 开头的其他模型」 |
related 只对不含通配符的 pattern 生效：它把 mimo-v2.5 变成 mimo-v2.5 加 mimo-v2.5* 两个匹配式。
为什么是前缀而不是
-后缀：真实目录里变体的写法是mimo-v2.5-flash、cn:glm-5.1、mimo-v2.5turbo——操作员知道的那部分是词干。而且这不改变路由匹配什么（路由名保持原样），只影响挂载动作考虑哪些渠道。
未识别的值一律按 exact 处理：related 会改写上游模型名，所以绝不能因为拼错而意外发生。
挂载后成员的转发名
related 命中的变体会为成员写 mapping_json = {"real":"<命中的模型名>"}。
只改成员的转发名，不改路由名。 否则挂上去的成员会把基础名发给根本不认它的上游——等于挂了一个只会报错的成员。
预览行会显示「命中 <模型名>」，所以宽松匹配的结果是可核对、可取消勾选的。
三层「空」的语义（最容易搞错的地方）
| 层 | 空列表的含义 |
|---|---|
| handler | channel_ids 为空 = 全部当前匹配 |
| store | 空列表 = 空操作 |
| 前端 | 因此全不选时不能发请求（会挂上全部），确认按钮在 0 选中时必须禁用 |
这三条不一致是刻意的：语义由 handler 决定，store 层不该顺手加一条「空 = 全部」。
目标分组
目标分组沿用「添加通道」的语义——是当前分组 tab，不是永远 default。
交集保护
| 情况 | 计入 |
|---|---|
| 已停用的渠道 / 未知 id / 已不再提供该模型 | skipped |
| 已在目标分组里的渠道 | 既不算 added 也不算 skipped（纯空操作） |
| 只在别的分组里的渠道 | 会被挂进来（分组可叠加） |
「已在目标分组」那一条是刻意的：连点两次不会重复挂载，也不会看起来像失败。
建路由之后的另一件自动化：能力补齐
创建一个路由，就是某个模型名开始可调用的时刻，也是网关能顺手回答「这个模型怎么调」的时刻——不需要操作员再走第二步。
两条路径，各有不能碰的底线：
| 路径 | 时机 | 底线 |
|---|---|---|
| 内置能力分类 | 同步跑 | 本地、幂等、跳过人工或目录已拥有的行 |
| 外部目录同步 | 后台只同步这一个模型 | 队列满 → 静默丢弃并推迟到下一次计划扫描；worker 里一次失败的同步只记日志 |
IMPORTANT
保存永远不能等下载。 两条路径都不许让保存变慢或变失败——所以队列满时是丢弃，不是阻塞。写这条路径时不要把任何网络调用挪进 HTTP handler。
通配符会被跳过（含
*/?）：gpt-*是匹配器，不是可调用模型名，没有目录会收录它。
外部目录的 worker 由路由装配在有目录服务时无条件启动（即使周期扫描被关掉），并注册停止回调。
模型发现（auto / manual）
渠道的适配器由 type_hint 解析，回落时取所属站点的 platform。
一次成功的渠道刷新会原子地：
- 替换
discovered_models快照； - 更新规范的
channels.models_csv； - 创建缺失的精确路由；
- 归并自动路由成员。
两条保护规则
- 缺失的模型只禁用「自动且未被人工覆盖」的成员。
- 已有路由与人工路由决策始终归操作员所有——自动流程不碰它们。
同步模式
| 模式 | 行为 |
|---|---|
auto | 发现流程自动把探测到的模型采纳为路由 + 成员 |
manual | 只刷新候选快照，逐个人工采纳 |
空值或未知值一律归一为 manual（安全默认）。新渠道的继承来源是运行设置里的 default_model_sync_mode。
失败不改状态
传输错误、状态码错误、体积超限、载荷解析失败——全都不改变任何状态。
响应在处理前被限制大小、严格解码、归一并排序，而这一切在任何数据库事务开始之前完成。
模型变更追溯
上游模型清单发生变化时会自动记录审计，可以预览影响范围，并一键做平滑的映射替换。
| 设置 | 默认 | 含义 |
|---|---|---|
model_change_retention_days | 90 | 已完成记录的保留期 |
model_change_auto_ignore_days | — | 超过这个天数未处理的变更自动忽略 |