config-center/docs/model-sources/MAINTENANCE.md

# 模型来源维护与核验规则

此目录记录 `compute/providers`、`compute/coding-plans`、`compute/model-specs` 的模型数据来源。每家供应商一个目录；官网证据、单模型和单接入面分别记录。

## 本轮核验范围

- 核验日期：2026-10-03。
- 配置范围：29 个 Provider、11 个套餐、23 个共享规格文件。
- 当前模型记录：626 条（同一模型在不同接入面会分别计数）。
- 353 条 `partial`：只核实表中列出的字段，可能仅确认官网出现该 ID；不是整条规格全通过。
- 272 条 `pending`：登记官网入口，但尚未取得该条模型的字段级证明。
- 353 条 partial 中，216 条仅确认 ID，137 条还核实过其他字段；仍不代表整条通过。
- 1 条 `historical`：匿名模型的历史兼容记录，不证明当前平台可用。

没有把所有存量数据写成已核实。当前确认的是本轮明确核对的字段、官网公共目录以及本地配置契约；没有执行逐供应商账号的收费模型调用。

## 统一记录规则

官网不可读、未取得型号专属证据、无字段证明和仅确认 ID 的记录单列在 [来源缺口清单](../source-gaps/README.md)。修改字段证明后运行 `npm run sources:gaps` 更新派生清单；这一步不更新来源日期或提高核验状态。

1. **来源必须是发布者的官网、官方文档、官方 API 或可验证的官方代码仓库。** 搜索摘要、聚合榜单、社区文章、第三方转载和本仓旧配置只能帮助定位，不是字段的主证据。官方域名上的用户文章也不等于官方公告。
2. **原厂与接入面分开。** 原厂存在某模型，不证明套餐可用；国际端点不证明国内端点可用；OpenRouter USD 价格不覆盖国内 CNY。
3. **数字写清含义。** 上下文窗口、最大输入、最大输出、默认输出参数分别记录。官网只写 K/M 时注明换算，优先使用明文整数；输入/输出独立限制不使用 output<=input 的通用断言。
4. **价格写清单位和条件。** 区分每百万 token、每张、每秒、每字符、search unit、按实例；原价、限时优惠、缓存命中/写入、峰谷、长上下文阶梯分别注明。未知价格省略；-1 等 API 占位值不转换成零价。
5. **日期写清用途。** `checkedAt` 是本轮实际访问日期；模型发布时间另行确认。读取了官网不代表所有模型字段都已核实，页面壳或登录墙不可标为证明。
6. **本仓策略不冒充官网参数。** `routing.tier`、`routingPriority`、`defaultReference`、产品能力标签、预设启用状态等是产品配置/工程判断；不要引用营销榜单来证明它们。
7. **官方来源也有边界。** 官方 API 的动态目录是某一时点的接入面快照；缺失表示本次未列出，不能自动推断原厂退役。官网参数核对不等于实际账号调用验收。来源元数据保存实际跳转地址与成功读取正文的 SHA-256，不保存完整网页原文；访问失败的 URL 明确记录。

## 导航

供应商、模型和接入面导航见 [README.md](README.md)。

## 文件格式

- `providers/<supplier>/README.md`：只作该供应商的模型/接入面导航。
- `providers/<supplier>/SOURCES.md`：官网入口、读取结果、内容摘要和适用边界。
- `providers/<supplier>/models/<model-id>.md`：一个精确模型 ID；参数详情、各接入面差异、已核字段、状态和指纹。
- `providers/<supplier>/access/<category>--<config-id>.md`：一个配置文件的端点、协议、币种、访问模式、平台指纹和关联模型。
- [TEMPLATE.md](TEMPLATE.md)：按来源目录、模型和接入面分别复制格式；来源 ID 使用稳定的英文短名。
- 每个单模型文件的 `source-config` 段落定位一个 canonical JSON 文件；每一行对应一条 `models[].modelName` 或 `specs[].id`。
- “已核字段→来源”使用完整字段路径，必须指向成功读取的官网来源。未列出的字段仍未核实。ID 的核对要求完整标识符匹配，不能以 gpt-5.5 出现来证明 gpt-5；ID 出现也不证明该端点可调用。
- `source-config-fingerprint` 记录端点、协议、币种和平台非凭据字段，防止只改平台而遗漏来源复核。API Key 等凭据不写进来源记录。
- 行尾 SHA-256 是当前完整模型对象的指纹，用于发现配置已变而文档未复核。指纹不是官方签名，也不证明字段正确。

## 更新流程

1. 从供应商页面的官方入口打开对应模型、地域与接入面，读取正文/公共 API。把失败、页面壳或权限要求原样登记。
2. 将官网内容与现有 JSON 逐字段比较；发现差异时先记录含义、单位、限时/地域条件，再改配置。
3. 同步 Provider、共享规格、套餐名单及相关回归。删除某接入面不再列出的预置型号时添加该接入面的 tombstones；历史兼容规格是否保留单独判断。
4. 基于现有 Markdown 增量编辑受影响行和核验说明；不要整页重建或删除既有来源历史。更新实际核实的字段、日期和状态。
5. 运行 `node scripts/validate-sources.mjs --fingerprints`，将对应模型的新指纹写入单模型文件；平台字段改变时同步单接入面文件的 `#@config` 指纹，确认参数表与 JSON 一致。
6. 数据变化时递增 `manifest.json#presetDataVersion` 并更新日期；纯文档修订不需要假装发布数据更新。
7. 执行 `npm run validate`、`npm test` 和 `git diff --check`。必要时在已授权账号进行聚焦实测，并记录结果与限制。

```bash
npm run validate:sources
node scripts/validate-sources.mjs --fingerprints
npm run validate
npm test
```

来源校验不访问网络，也不消费模型额度：检查官方域名、引用、日期、全部模型覆盖、重复 ID、完整对象指纹和参数表是否与配置一致。更新数据后若来源记录陈旧，CI 会失败。

## 本轮修正记录

- Qwen3.7 Max：合并两个冲突的 canonical ID；官网明确纯文本、1000000 上下文、131072 最大输出，API/Token Plan 同步；北京隐式缓存命中价补为 2.4 元/百万 token。
- MiniMax Hailuo 2.3 Fast：合并只在大小写上不同的两个规格，保留 exact 别名及原有非 Agent 路由。
- Cohere Embed：兼容 API 官网明确不支持 dimensions 参数，移除该接入面可选维度列表；原生共享规格和默认响应维度保留。
- OpenRouter auto：移除原来的零价字段，明确官网 -1 是动态计价占位值。
- OpenRouter 当前目录未列出的三个旧预置：从该 Provider 移除并 tombstone，不将原厂模型或其他网关的历史兼容规格同步判为退役。

2026-10-02 的 [JSON 审计快照](../../reports/provider-model-audit-2026-10-02.json) 保留为历史结果；此目录是后续字段级来源记录入口。历史快照日期和计数不会因为本轮修正而重写。

## 目录拆分与文件名约定

- 一个精确 ID 一个模型文件，同 ID 在本供应商多个配置中的记录放在同一模型文件内分段列出；跨平台的名称不自动当同一模型。
- 文件名将 ID 转小写；`/`、`:` 等非字母数字/点/下划线/连字符替换成 `--`。有冲突时追加原始 ID 的 SHA-256 前 8 位。文件名只负责存储；正文和配置仍保存精确大小写。
- 接入面文件名为 `providers--openai.md`、`coding-plans--zhipu-coding.md`、`model-specs--qwen.md` 等，与 JSON 的目录/名称对应。
- 模型和接入面通过 `sourceCatalog: "../SOURCES.md"` 复用同一官网证据目录；不得引用另一个供应商的来源目录或越级路径。
- 参数详情块逐字段与 JSON 校验；引用、核验状态及原有日期在结构迁移中必须原样保留。
- 更新共享官网来源时，确认影响哪些引用模型；不要只刷新所有日期或指纹来掩盖未复核字段。
- 每次更新前的强制核查清单以仓库 [AGENTS.md](../../AGENTS.md) 为准。