JohnXu22786/model-catalog

English

Model Catalog — 模型目录自动发现（dsh 插件）

本插件为 dsh（插件化 DeepSeek harness，一切皆是插件）生态设计：当你在 dsh 中配置了一个 OpenAI 兼容的 API 主机（官方 API、中转网关、本地推理服务等）后，插件自动从该主机的接口拉取模型信息——模型列表、定价（每百万 token 的输入/输出/缓存价）、推理参数（上下文长度、最大输出、能力标志：工具调用/结构化输出/视觉/并行工具等），归一化后生成可直接使用的模型配置，省去手工填写。

核心价值：

• 主机类型自动识别，无需配置协议细节；
• 全链路单位归一化（每 token 美元 / 每百万美元 / 倍率 / 按次）；
• 定价可溯源（captured_at + 来源端点），动态定价结构化表达；
• 能力缺失时可选轻量实测探测；
• 输出三种产物：完整目录、dsh 配置片段、人类可读报告。

---

功能特性

• 主机类型自动识别：标准兼容（最小字段）/ 富元数据（/models 带定价与参数清单）/ 倍率计价网关（quota 体系）/ 能力标志代理（/model/info 能力布尔族）/ Ollama / vLLM，全部端点探测失败时报错并支持 --kind 手工指定。
• 归一化模型记录：id / 上下文窗口 / 最大输出 / 定价族（input、output、cache_read、cache_write、internal_reasoning，单位 USD/1M）/ 能力标志 / 来源溯源。
• 定价来源链：主机接口 → 用户覆盖配置 → 外部价格镜像 → 内置默认表 → 标注未知（产生告警）。
• 内置默认表：官方 API（DeepSeek）的模型事实与定价兜底；动态定价（2026-08-16 起 peak/off-peak 分时计费）以结构化 tiers 表达。
• 能力探测验证（可开关）：对元数据缺失的能力项（工具调用/结构化输出/流式）发送最小化请求实测，结果按 (baseUrl, model) 缓存。
• 缓存与并发安全：分类/探测/镜像结果按 TTL 缓存；文件锁 + 原子写防止并发进程互相破坏；损坏缓存自动恢复。
• 交互式配置生成：pick 命令列出模型与价格，选择后生成 dsh 配置片段。
• 自包含：manifest + 入口工厂 + 工具/事件接口，harness 可直接加载（见 接入说明）。

工作原理

baseUrl + apiKey
   │
   ▼
① 主机识别（探测端点，结果缓存 1h）
   ├─ /models 富元数据        → augmented
   ├─ /v1/models              → ├─ /api/pricing → quota
   │                            ├─ /version     → vllm
   │                            ├─ /model/info  → flag
   │                            └─ 否则         → bare
   ├─ /api/tags               → ollama
   └─ 全部失败                → unknown（报错，可 --kind 指定）
   │
   ▼
② 采集（按类型解析模型列表/定价/能力）
   │
   ▼
③ 归一化（单位换算 + 来源链补全 + 别名解析）
   │
   ▼
④ 能力探测（可开关，仅补元数据缺失项）
   │
   ▼
⑤ 输出
   ├─ out/catalog.json     完整目录（schema: model-catalog/v1）
   ├─ out/dsh-models.json  dsh 配置片段（schema: dsh/models/v1）
   └─ out/report.md        人类可读报告

快速开始

要求：Node.js ≥ 21（无运行时依赖；构建仅需 typescript）。

npm install          # 安装开发依赖
npm run build        # 编译到 dist/

# 发现 DeepSeek 官方 API 的模型目录
export DEEPSEEK_API_KEY=sk-xxx
node dist/src/main.js discover --base-url https://api.deepseek.com

# 发现本地 Ollama
node dist/src/main.js discover --base-url http://127.0.0.1:11434 --probe always

# 中转网关（倍率计价）
node dist/src/main.js discover --base-url https://gateway.example.com --api-key-env GATEWAY_KEY

# 交互式选择模型并生成 dsh 配置片段（也可用管道一次性喂入回答：
#   第 1 行 baseUrl，第 2 行密钥环境变量名（空行=自动检测），第 3 行模型编号）
node dist/src/main.js pick --base-url https://api.deepseek.com

运行后在 out/ 目录得到三份产物。把 dsh-models.json 交给 dsh harness 即完成模型配置（字段说明见 接入说明）。

主机类型

类型	识别依据	定价来源	说明
bare 标准兼容	/v1/models 仅最小字段	无 → 走兜底链	OpenAI 兼容最基础形态；DeepSeek 官方 API 即此类，由内置默认表补齐
augmented 富元数据	/models 含 context_length/pricing/supported_parameters	主机直接提供（每 token 美元字符串）	少数网关实现
quota 倍率计价网关	/api/pricing（兼容旧式 map 形态）	倍率 × $2.0 × 分组倍率	中转网关常用 quota 计价体系
flag 能力标志代理	/model/info（404 时回退 /v1/model/info）	每 token 美元数字	返回能力布尔族与价格
ollama	/api/tags	无 → 走兜底链	本地服务，/api/show 提供能力与上下文
vllm	/v1/models + /version	无 → 走兜底链	本地推理服务，无需密钥

归一化与单位换算

目录内所有按量价格统一为 每百万 token 美元（USD/1M），按次价格单独标注：

输入形态	换算
每 token 美元字符串（如 "0.00000056"、"$0.00003"）	×1e6，四舍五入到 6 位小数
每 token 美元数字（如 1.5e-7）	×1e6
倍率（quota 体系，model_ratio）	输入 = model_ratio × 2.0 × group_ratio；输出 = model_ratio × completion_ratio × 2.0 × group_ratio（completion_ratio/group_ratio 缺省 1；group_ratio 为映射时取 default 组）
按次（quota_type=1）	单次美元 = model_price × group_ratio，billing: "per-call"

augmented 类型的定价字段映射：prompt → input、completion → output、input_cache_read → cacheRead、input_cache_write → cacheWrite、internal_reasoning → internalReasoning。

定价来源优先级

1. 主机接口（整体信任：主机给了部分价格就不再拼接其他来源）
2. 用户覆盖配置 data/overrides.json（替换语义：配置了哪个字段就覆盖哪个字段）
3. 外部价格镜像 --external-url（仅填充完全缺失的定价；结果缓存 1h）
4. 内置默认表 data/builtin-table.json（仅填充缺失；含 DeepSeek 官方模型事实）
5. 以上皆无 → pricing: null，报告与告警标注「未知」

能力字段与上下文/最大输出同样遵循「主机 > 覆盖 > 镜像 > 内置表」的优先级（覆盖为替换语义，其余仅填空）。

动态定价

DeepSeek 官方 API 自 2026-08-16 起按 峰值/非峰值 分时计费（峰值：01:00–04:00 与 06:00–10:00 UTC，其余时段半价）。目录中：

• pricing.dynamic: true；
• pricing.amounts 为基准档（首档 off-peak）价格；
• pricing.tiers 携带全部分档（label、UTC 时段、各档价格）；
• 报告（report.md）单独列出动态定价模型并提示按档位计费；
• 内置默认表收录当日官方价格，如与官方文档不一致请以官方文档为准并更新 data/builtin-table.json。

能力探测

对元数据缺失的能力项（工具调用 / 结构化输出 / 流式）发送最小化探测请求（max_tokens 极小、消息极短），实测主机是否支持：

• 工具调用：携带 tools + 强制 tool_choice；
• 结构化输出：response_format: {type: "json_object"}（消息含 "json" 字样，规避 JSON 模式的经典拒绝陷阱）；
• 流式：stream: true，实测响应必须为 SSE（含 data: 事件并收到 [DONE]），只回普通 JSON 判为不支持。

判读：2xx = 支持；400/404/405/422 = 不支持（错误体摘要留证）；401/403 = 中止全部探测并告警（避免无效消耗）；5xx/网络/超时 = 保持未知并短时缓存错误。

• 模式：auto（默认，有密钥或本地主机才探测）/ never / always；
• 结果按 (baseUrl, model, 能力) 缓存 24 小时（错误类 30 分钟）；
• 视觉/并行工具等无法低成本实测的能力仅依赖元数据，不探测。

缓存与并发安全

• 缓存目录 var/（vault.json）：主机分类（1h）、探测结果（24h/30m）、外部镜像（1h）；
• 写入全部走「临时文件 + 原子 rename」；损坏的缓存文件自动重置，不影响运行；
• 跨进程文件锁（var/.lock）：陈旧锁（>5 分钟）自动接管，等待超时（10s）抛错；
• cache --clear 一键清空。

配置

配置文件 catalog.config.json（位于插件根目录，可 --config FILE 覆盖；所有字段可选）：

{
  "baseUrl": "https://api.deepseek.com",
  "apiKeyEnv": "DEEPSEEK_API_KEY",
  "probe": "auto",
  "externalUrl": "https://example.com/mirror.json",
  "outputDir": "out",
  "cacheDir": "var",
  "httpTimeoutMs": 10000
}

字段	默认	说明
baseUrl	无	主机地址；也可命令行 --base-url
apiKeyEnv	自动	密钥环境变量名；自动检测 MODELCAT_API_KEY / DEEPSEEK_API_KEY / OPENAI_API_KEY
kindHint	无	强制主机类型（bare/augmented/quota/flag/ollama/vllm）
probe	auto	能力探测模式
catalogTtlSec	900	目录新鲜度（插件工具 list 复用）
probeTtlSec	86400	探测结果缓存 TTL
detectTtlSec	3600	主机分类缓存 TTL
externalUrl	无	外部价格镜像 URL（结构见 data/mirror.example.json）
outputDir / cacheDir	out / var	输出与缓存目录
concurrency	4	采集并发数（Ollama /api/show 等）
httpTimeoutMs	10000	HTTP 超时

密钥只经环境变量传递（--api-key 仅限命令行临时使用），任何产物文件都不包含密钥明文。

数据文件

文件	作用
data/builtin-table.json	内置默认表（兜底）：DeepSeek 官方模型事实与分时定价
data/overrides.example.json → 复制为 data/overrides.json	用户手动覆盖：逐字段替换
data/aliases.example.json → 复制为 data/aliases.json	别名映射：旧名/别名 → 规范 id
data/mirror.example.json	外部镜像格式示例（可自托管同构 JSON）

输出物

文件	内容
out/catalog.json	完整目录（schema model-catalog/v1）：元信息、告警、全部归一化条目
out/dsh-models.json	dsh 配置片段（schema dsh/models/v1）：harness 可直接消费
out/report.md	人类可读：目录表、未知定价清单、动态定价、告警

CLI 一览

model-catalog discover [参数]          发现并输出模型目录（默认命令）
model-catalog pick [参数]              交互式选择模型并生成 dsh 配置片段
model-catalog probe --model ID [参数]  对单个模型执行能力探测
model-catalog cache --clear            清空缓存
model-catalog config                   查看生效配置

--base-url URL      --api-key-env NAME   --api-key KEY
--kind KIND         --probe MODE         --out DIR
--cache DIR         --external-url URL   --config FILE
--model ID          --help

dsh 接入

插件自包含：manifest.json 声明入口与接口，dist/src/plugin.js 导出 createPlugin() 工厂，注册 5 个工具（catalog.discover/list/refresh/select/probe）与 2 个事件（catalog.updated/catalog.failed）。同时支持 dsh bundle 安装（package.json → dsh.bundle → cordis.patch.yml）：Cordis 入口 dist/src/dsh.js 导出 name/inject/apply，把同样的 5 个工具注册到 harness。harness 加载方式、工具参数与返回、事件载荷、配置片段消费方式详见 docs/integration.md。

限制与说明

• 视觉、并行工具等能力无法低成本实测，仅取元数据（缺失则未知）；
• 倍率网关的 group_ratio 若为映射且无 default 组，按 1 计——实际分组倍率可在覆盖配置中修正；
• 探测请求消耗少量 token（每模型最多 3 次、每次 1–16 token）；无密钥的标准主机在 auto 模式下不探测；
• 内置默认表的价格为兜底值，动态定价以官方文档与 tiers 为准。

开发

npm run build    # 编译 TypeScript
npm test         # 编译 + 运行全部测试（node:test，无外部测试依赖）

测试覆盖：单位换算、主机识别、各类型采集、归一化优先级链、能力探测判读与缓存、缓存仓（TTL/锁/损坏恢复）、输出产物、端到端流水线（本地 mock 主机）。