---
name: model-connector
version: 1.5.0
description: 自定义大模型自动接入工程师（宿主无关版）。当用户说"接入自定义大模型""配置自己的大模型""把模型接入本Agent""接入工程师""接一个自己的模型"或希望把第三方/自建 OpenAI 兼容模型（DeepSeek、智谱 GLM、Kimi、硅基流动等）自动接入当前 Agent 时使用。触发后 AI 全自动完成：查注册表/读文档→定位配置位→写配置→验证，用户不手动改任何配置。核心机制：① 双层注册表（公共表 models_registry.json + 私有覆盖表 models_registry.local.json，后者打包分发时排除）——常用模型只需说名称+API Key 即可零读文档接入；② 能力矩阵按确切模型名核验、禁止从兄弟模型推断（实测：mimo-v2.5-pro 纯文本 vs mimo-v2.5 多模态）；③ 全部能力/上限值均经实时 API 探针校验——预填 supportsImages:true 时图片探针必做（防注册表漂移致能力错配），输出上限必测（防文档虚标如 MiniMax M3 标称 1M 实测 512K），输入上限无实时探针但必须在交付说明声明来源。未知模型自动退回读文档全流程。本 skill 宿主无关：默认以 WorkBuddy 为参考宿主，其他智能体按第 0.5 步适配。
agent_created: true
---

# 自定义大模型接入工程师

你是当前 Agent 的接入工程师。请「完全自动地」把一款自定义大模型接入本 Agent，由你完成全部操作，用户不手动改任何配置。本 skill **宿主无关**：流程以 WorkBuddy 为参考宿主编写，用于其他智能体时按第 0.5 步适配即可。

## 用户提供
- 模型名称（或接入文档链接/全文）
- API Key（可选）
- 需要保留的参数（可选）

## 你的执行步骤

### 0. 双层注册表快路径（优先执行）
本 skill 同目录下有两份注册表：
- `models_registry.json` — **公共表**（随 skill 分发）：仅收录厂商官方公开端点，任何人持该厂商 key 即可用
- `models_registry.local.json` — **私有覆盖表**（仅本机自用，**打包分发时必须排除**）：中转/订阅专属端点等私有配置

执行顺序：
1. **加载与容错**：读公共表 → 读私有表（若存在）→ 按 id 覆盖合并（local 优先）。任一文件缺失或 JSON 解析失败 → 跳过该层继续，**不得中断**；两层全部不可读 → 视同 0 命中，退回读文档全流程。
2. **规范化**用户口语模型名：转小写，空格与连字符统一。
3. **匹配**（方向明确）：规范化后的用户词是某条目 **id 或其 aliases 任一项的子串**（含相等）→ 命中该条目。
   - **命中 1 条** → 预填配置（url / vendor / auth / modelId / 能力字段 / token 上限全部采用注册表值），仅当用户未给 API Key 时才追问 key。跳过 Step 1–3，直接进入 **Step 4 验证**。
   - **命中 >1 条**（如只说「mimo」同时匹配 `mimo-v2.5` 与 `mimo-v2.5-pro`）→ **单条提问**让用户二选一，避免套错兄弟模型能力。选定后走预填 + Step 4。
   - **0 命中** → 退回 **Step 1–3** 读文档全流程。注册表是加速器不是替代品。
4. **注册表值 ≠ 最终权威**：token 上限与多模态可能漂移或虚标，Step 4 探针对注册表值同样强制生效——探针结果优于注册表，冲突时以探针为准并在交付说明点出差异。
5. **自增长**：每次成功接入并实测后，把该模型条目（含实测值与 `verifiedBy`/`confidence`）追加进注册表——**官方公开端点入公共表；中转/订阅专属端点入私有覆盖表**，并同步维护两层文件的各自 `version` 字段。

> 设计意图：注册表消除「读文档+追问参数」的摩擦，探针消除「静态表过时/虚标」的错误。已知模型零摩擦且写入值真实；未知模型有完整兜底；私有端点与公共分发隔离。

### 0.5 宿主适配（非 WorkBuddy 宿主必做）
本 skill 以 WorkBuddy 为参考宿主（`~/.workbuddy/models.json`，字段见 Step 2）。用于其他智能体时：
1. **定位该宿主的模型配置位**：查官方文档或现有配置文件（常见：`config.json` / `settings.json` / 环境变量 / Web 后台表单）。
2. **字段映射**：把注册表/文档参数映射到该宿主的字段名（如宿主用 `contextWindow` 而非 `maxInputTokens`，用 `vision` 而非 `supportsImages`）。
3. **确认该宿主的重载方式**：改完配置后需重启/重载/热切换，向用户说明。
4. 映射不确定时单条提问，不臆测字段名。

### 1. 读文档：提取接入必需项
- 接口地址（含是否带 `/v1`）
- 鉴权方式（Header 名与格式，如 `Authorization: Bearer `）
- 模型标识（`model` 字段的真实取值，大小写敏感）
- 请求/响应格式、是否 OpenAI 兼容
- **上下文窗口 / Token 上限**：`maxInputTokens` 与 `maxOutputTokens` 的真实取值（注意单位换算：文档常写 `1M`→`1000000`、`1024K`→`1024000`、`384k`→`384000`）
- **能力矩阵（关键，逐项确认，以文档原文为准，不得假设）**：
  - 图片输入（vision / image input）
  - 图片/多模态**输出**（image generation / multimodal output）
  - 工具调用（function calling / tool_call）
  - 推理（reasoning / thinking）
  - ⚠️ **能力矩阵必须按「你要接入的【确切模型名】」核验，禁止从同系列兄弟模型推断**：文档的多模态/能力示例常使用另一个模型名（实测案例：用户要接 `mimo-v2.5-pro`，但多模态文档示例写的是 `mimo-v2.5`；前者实测 + 图片返回 404 `No endpoints found that support image input`，后者返回 200）。`mimo-v2.5-pro` 是纯文本 Agent 旗舰，多模态只在 `mimo-v2.5` 上。两模型 API Key/地址相同，仅模型名不同——套用兄弟模型能力会直接错配。

### 2. 找配置位
定位**当前宿主**存放模型配置的地方（WorkBuddy 为 `~/.workbuddy/models.json`；其他智能体先走第 0.5 步适配），确认它支持的字段，典型字段：
`id` `name` `vendor` `url` `apiKey` `supportsToolCall` `supportsImages` `supportsReasoning` `maxInputTokens` `maxOutputTokens` `useCustomProtocol`

### 3. 填配置
严格按文档示例把字段写进去，特别注意：
- URL 末尾 `/v1`、Bearer 前缀、模型名大小写与文档**完全一致**
- **能力字段如实填写**（本 skill 对原始版本的修复点）：
  - 文档**未声明**支持图片输出 → `supportsImages: false`，绝不为了"显得支持"而误填 `true`
  - 同理适用于工具调用、推理等能力字段
  - 原始版本未探测多模态能力，曾导致接入"不支持多模态输出"的模型时被错误启用图片能力
- **Token 上限（本 skill 第二次修复点，2026-08-17 确立）**：
  - 文档**已给出** → 严格按文档换算为纯数字填写。**但文档给出的上限可能是虚标**（实测案例：MiniMax M3 文档写"最大输出 1M"，实际 API 只接受到 524288/512K，超出即 400 `Invalid request parameters`）。所以填完后必须走下方"Step 4 上限实测"校验，被拒就下调到实测可用值并标注。
  - 文档**未给出** → **绝不允许静默臆测一个偏小的数字当事实写死**（实测曾默认填 `128000 / 8000`，而模型实际支持 `1024000 / 384000`，差 8 倍，直接把上下文窗口压短）。必须二选一：
    ① 用**单条提问**向用户索取正确上限；
    ② 若用户也未知，填入一个基于模型家族公开范围的**估值**，并在交付说明里**高亮标注"Token 上限为待核实估值，很可能需上调"**，不得伪装成已确认值。

### 4. 做验证
- **基础验证**：用该模型发一条最简文本请求（如「你好」），确认能正常返回。
- **上限实测（必做，防止文档虚标导致发起会话 400）**：发一条请求，把 `max_tokens` 设为刚填入的 `maxOutputTokens` 值，确认 API 返回 200。若返回 400 `Invalid request parameters`，说明文档上限虚标——二分探测真实可用的 `max_tokens` 上限（如 524288/512K 这类 2 的幂常为硬上限），把 `maxOutputTokens` 改为实测值，并在交付里说明"文档标称 X 但 API 实际仅接受 Y"。**此步不做，用户选该模型发起会话时会直接失败。**
- **多模态验证（预填 true 或用户声称支持时必做；预填 false 时按需复验）**：用该【确切模型名】发一条带图片的请求验证（图片 URL 或 base64 均可）。判定规则：
  - 返回 **200** 且正常理解图片 → `supportsImages: true`。
  - 返回 **404** `No endpoints found that support image input`（或类似）→ 该确切模型**不支持**图片输入，`supportsImages: false`，**即使同系列兄弟模型（如 `mimo-v2.5`）支持也不能套用**。
  - ⚠️ 注册表快路径预填 `supportsImages: true` 的，图片探针**从"按需"升级为"必做"**——注册表值可能随厂商漂移，不实测即写入 = 把能力错配风险原样传给宿主（mimo 踩坑的镜像场景）。文档未声明支持图片输出时，跳过图片输出验证。
  - ⚠️ 不要因为「用户说支持多模态」或「兄弟模型文档说支持」就跳过实测或反填 `true`；这两类来源都可能与你接入的确切模型名不符（见 Step 1 的 mimo 案例）。
- **交付说明**：明确告知用户——
  - 实际接入的模型名、vendor、接口地址
  - 能力矩阵（图片输入 / 图片输出 / 工具调用 / 推理 的支持情况）
  - **Token 上限（`maxInputTokens` / `maxOutputTokens`）的取值来源**：是文档确认值、用户给定值、注册表历史实证值，还是待核实估值？**`maxInputTokens` 无实时探针，必须在交付说明里单独声明其来源与局限**（如"输入上限来自注册表历史实证，未经本次实时校验，厂商若缩窗会在长会话时报 400"）。若为估值必须高亮提示"很可能需上调"。
  - 任何与用户预期不符的点，例如：*"你提供的模型不支持多模态输出，已按文档如实将 `supportsImages` 置为 false，不会误启用图片能力。"*

## 关键约束
- **注册表是假设，探针是真相**：从注册表预填的值仅作起点；输出上限与多模态（预填 true 时）的最终取值一律以 Step 4 实时探针为准，冲突时修正并在交付说明告知用户。输入上限无实时探针，以注册表/文档值为准但必须声明来源。
- **双层注册表隔离**：公共表只收官方公开端点；私有端点（中转/订阅专属）只进 local 覆盖表；**分发打包时必须排除 models_registry.local.json**。
- **不臆测能力**：任何能力字段必须以文档原文或实测为唯一依据。
- **不臆测 Token 上限**：`maxInputTokens` / `maxOutputTokens` 必须来自文档或用户明确给定；缺失时按上文"Token 上限"规则处理，**绝不把猜测的小值当事实静默写入**（这会悄悄把模型的真实上下文窗口压短）。
- **不静默降级也不静默升级**：能力与实际不符、或 Token 上限为估值时，在交付说明里明确点出，让用户知情。
- **用户零手动操作**：配置文件、字段、验证全部由你完成；只在文档缺失关键信息时，才用单条提问向用户索取，绝不要求用户自己改配置。