前言¶

DeepSeek Harness (DSH) 生态奉行“一切皆插件”的理念。在使用 DSH 时，配置 OpenAI 兼容的主机（包括官方 API、中转网关或本地推理服务）通常需要手动维护模型列表、定价策略和推理参数。

Model Catalog 插件解决了这个重复劳动。它通过探测目标主机的端点，自动拉取模型信息、定价和能力，并进行归一化处理，最终生成可直接加载的配置文件。

插件定位¶

• 名称: model-catalog
• 作者: JohnXu22786
• 分类: 模型推理
• 许可证: MIT
• 核心价值: 自动发现、归一化配置、交互式生成

安装与启用¶

在 DSH 中安装该插件，使用以下命令：

dsh plugin --profile demo add github:JohnXu22786/model-catalog

如果需要移除，可以使用：

dsh plugin --profile demo remove model-catalog

核心功能¶

该插件包含以下核心能力：

• 主机类型自动检测: 自动识别标准兼容、丰富元数据、额度计费、能力标志代理、Ollama 或 vLLM 等不同类型的主机。
• 归一化的模型记录: 输出的模型记录包含 ID、上下文窗口、最大输出、定价族（含缓存读写/内部推理价格，单位为 USD/1M）、能力标志和来源溯源。
• 定价来源链: 按照主机端点 > 用户覆盖 > 外部价格镜像 > 内置默认表的优先级填充定价信息。
• 内置默认表: 针对官方 API（如 DeepSeek）内置了默认的事实和定价回退表。
• 能力探测验证: 可选地发送最小请求，探测主机元数据中缺失的能力（如工具调用、结构化输出、流式传输）。
• 缓存和并发安全: 分类、探测和镜像结果会被缓存；文件锁和原子写入防止并发进程损坏缓存。
• 交互式配置生成: 通过 pick 命令列出模型和价格，供用户选择后生成 dsh 配置片段。
• 自包含: 包含清单、入口工厂和工具接口，可被 Harness 直接加载。

工作流程¶

插件的工作流程分为以下步骤：

1. 主机检测: 探测端点，根据 /models、/v1/models、/api/pricing、/model/info 等不同响应判断主机类型。
2. 拉取: 根据类型解析模型列表、定价和参数。
3. 归一化: 进行单位转换（如 USD/Token 转 USD/1M）、源链补全和别名解析。
4. 能力探测: （可选）探测缺失的能力并缓存。
5. 输出: 生成完整目录、dsh 配置片段和人类可读报告。

使用示例¶

使用前需满足 Node.js >= 21（无运行时依赖，仅构建需要 TypeScript）。

1. 安装依赖并构建：

    npm install
    npm run build

2. 发现官方 API：

    export DEEPSEEK_API_KEY=sk-xxx
    node dist/src/main.js discover --base-url https://api.deepseek.com

3. 发现本地 Ollama：

    node dist/src/main.js discover --base-url http://127.0.0.1:11434 --probe always

4. 发现网关（需指定环境变量）：

    node dist/src/main.js discover --base-url https://gateway.example.com --api-key-env GATEWAY_KEY

5. 交互式选择模型：

    node dist/src/main.js pick --base-url https://api.deepseek.com

技术细节¶

• 输出文件: 运行后会在 out/ 目录下生成三个文件：
  • catalog.json: 完整目录（schema: model-catalog/v1）。
  • dsh-models.json: dsh 配置片段（schema: dsh/models/v1）。
  • report.md: 人类可读报告。
• 主机类型: 插件支持 bare（标准兼容）、augmented（丰富元数据）、quota（额度计费）、flag（能力标志）、ollama 和 vllm 等类型。
• 定价单位: 所有定价均归一化为 USD per million tokens (USD/1M)。
• 容错: 如果所有端点探测均失败，插件会报错。可通过 --kind 手动指定主机类型。

结尾¶

Model Catalog 插件通过自动化和标准化，简化了 DSH 环境下的模型配置流程。

• GitHub 仓库: https://github.com/JohnXu22786/model-catalog
• 目录页面: https://www.skillhub.cn/plugins/JohnXu22786/model-catalog