Model Connector

自定义大模型接入工程师

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

脚本加速器：本 skill 附带 scripts/（probe.py 探针 / match_registry.py 注册表匹配 / validate_registry.py 注册表校验，纯标准库零依赖）。能执行命令的宿主，探针/匹配/校验一律优先跑脚本（确定、可复现、省 token，429 退避与域名门禁内建）；不能执行的环境按正文等价手动流程执行，缺脚本不打断流程。

⚡ 先跑 Step -1：宿主能力自检（三问路由，任何流程之前）

执行任何其他步骤前，先静默自检当前环境的三项能力（按能力路由，不按宿主身份猜）：

路由结果：

• L1 全配置宿主（三问全过，如 WorkBuddy / Claude Code）→ 正常走完整流程（Step 0 起）；scriptCapable 的宿主探针/匹配优先跑 scripts/，脚本缺失或执行失败回退手动流程并声明
• L2 表单宿主（①只有 UI 表单可填，②③至少一项可用）→ 走完整流程产出配置，但交付形态改为「可粘贴的表单字段清单」（第 0.5 步字段映射）
• L3 固定模型宿主（①不满足，模型平台不可换，如豆包/元器类对话产品）→ 不硬接，自动转「接入咨询台」降级模式：
  • 第一轮就向用户声明：「当前宿主的底层模型由平台固定，无法把模型接入到我自己身上；但我可以完成接入的前置工作」
  • 可交付：① 免费清单/模型画像（照常执行发现层与读文档层）② 通用参数卡（见下方产出物定义）③ 用户指定目标宿主后，输出该宿主格式的配置片段 + 逐步验证清单
  • 探针在 L3 下非默认执行：仅在用户明确同意后做（须声明目标端点，见「安全与隐私」）
  • 注册表自增长在 L3 下跳过（无库可写）；用户粘贴的验证请求照常处理

L3 通用参数卡（标准产出物，禁止即兴发挥）：

用户后续说出目标宿主（如「给我 WorkBuddy 格式」），再把参数卡转写为该宿主配置片段。

自检纪律：

• 自检复用流程既有动作的失败信号（读注册表、找配置位），不新增侵入性探测；一次探测失败即转问用户，禁止换路径递归试探
• L3 判定不靠自我认知（铁律）：不因「我知道自己是豆包/固定模型产品」这类自我判断就定 L3——实测证明模型对自身「模型固定」常无自我认知（豆包前两轮都没意识到，直到用户点破）。判定 L3 的唯一依据是探测证据（确实探测到无配置位）或用户裁决。当 ① 问因无探测能力（②问同时失败：无文件工具 / skill 内容仅为注入的纯文本）而「探测不到配置位」时，禁止猜测判级，直接单条提问让用户裁决：「你的宿主能改模型配置吗：能改配置文件 / 只有设置界面可填 / 模型固定不可换？」
• 我的运行环境 ≠ 用户的机器（实证：豆包沙箱检测不到用户 Mac 上的 WorkBuddy，曾误报「本机未检测到」）——环境探测结论只用于路由，不得当作用户机器现状向用户断言；涉及用户机器的事实，以用户口述为准或显式提问
• 自检有歧义（如分不清 L2/L3）→ 单条提问用户：「你的宿主模型可以换吗：能改配置文件 / 只有设置界面可填 / 模型固定不可换？」

安全与隐私（硬约束，优先级高于「完全自动」目标）

隐私红线：

1. 凭证不进云对话：宿主能力未确认为「本地可配置」之前，不主动索取 API key；用户在云宿主（对话可能被平台存储）主动粘贴 key 时，提示一句存储风险，建议先用占位符完成参数格式验证、真实 key 留到本地宿主再填
2. 失败即问只要能力不要凭证：自检失败转提问时，只问宿主能力分级，绝不在首轮提问里要 key
3. 最小写入：注册表自增长只写 skill 本地注册表文件，不碰其他位置
4. 禁越界探测：自检失败不触发「换别的路径再试试」的递归试探——一次不成即转入提问，防止在未知宿主上表现出爬取行为
5. 域名白名单（带 key 请求的前置门禁）：探针/验证把真实 key 发往某 url 前，先核对该 url 域名是否属于公共表 trustedDomains[vendor]（local 中转条目须为用户已确认的自配端点）。白名单外 = 升级为用户显式确认（等同写配置级双重确认），讲明「该域名不在该厂商已知域名列表」再继续——注册表条目若被污染，这道门禁是 key 不被引到仿冒端点的最后防线。公共表新增条目必须同步补录域名及来源。

用户提供

• 模型名称（或接入文档链接/全文）
• API Key（可选；宿主确认为可配置后再给，见安全红线 1）
• 需要保留的参数（可选）

你的执行步骤

⚡ 免费优先发现层（Step 0 之前条件触发）

何时触发（任一满足才执行，否则跳过）：

• 用户明确要「免费」的模型 / API / 额度
• 用户没指定具体模型（如「帮我接个能用的就行」「有没有不要钱的」）
• 注册表匹配命中 retiredModels 墓碑条目（含其 aliases）
• 已配置渠道突然报 404「model not found」（疑似下架）→ 先核实是否应入墓碑，再转本层推荐替代

动作（本层拉取 OpenRouter 清单属 HTTP 探针，须遵守上方「安全与隐私」的声明纪律；L3 宿主下先声明目标端点并征得用户同意再发）：

1. 实时拉取免费清单，禁止凭记忆或注册表历史值输出：
   • OpenRouter：GET https://openrouter.ai/api/v1/models，筛选 pricing.prompt === "0" 且 pricing.completion === "0" 的条目，按 context_length 降序给出 Top 10；模型 id 带 :free 后缀 = 公共免费路由。该接口 400+ 条目，禁止把原始响应全量读入上下文，先过滤再展示：curl -s https://openrouter.ai/api/v1/models | jq '[.data[] | select(.pricing.prompt=="0" and .pricing.completion=="0") | {id, context_length}] | sort_by(-.context_length) | .[:10]'（无 jq 时用 python3 等价实现）。context_length 是厂商自报的上下文元数据，接入 OpenRouter 系模型时直接作为 maxInputTokens 的 documented 来源（仍按探针分级复核）。
   • 免费 API 唯一推荐聚合中转站 OpenRouter：它是最大的模型聚合中转站，一个 key 即可通用全部上架模型，天然适合作为免费/试用模型的统一入口。不为任何单厂商免费档背书——本 skill 只客观列出 OpenRouter 上的免费路由，不推荐「智谱 / 硅基流动 / 商汤」等某一家厂商的免费档；用户若要某厂商专属免费档，走 Step 1 读该厂商文档，参数以文档为准、能力上限以 Step 4 探针为准。适用边界（2026-09-07 复盘确立）：「OpenRouter 唯一推荐」仅限免费/试用发现场景，不得外溢到付费模型选型——付费需求的选型菜单以厂商官方目录为准（见 Step 0 品牌级请求选型层），OpenRouter 只作价格对照；库存里有现成 OpenRouter key 不构成绕过官方文档的理由（库存决定「用哪个通道接入」，不决定「参数与生命周期的权威源是谁」）。
2. 向用户展示选择，每项注明：模型 id / 上下文长度 / 免费性质（:free 公共免费路由 vs 新户赠送额度 vs 公测期限定）/ 是否需要新注册 OpenRouter key。
3. 用户选定后进入正常接入流程（注册表快路径或 Step 1–4），免费模型同样必须过探针——免费档常伴更严的参数校验与限流。

纪律：

• 「免费」是营销状态不是技术属性：清单仅本次会话有效；写进任何持久文件必须带日期戳。
• 不承诺「长期免费」；交付说明必须提配额与限流风险（如 OpenRouter :free 路由有每日请求次数限制）。
• 实测成功的免费模型自增长入表时标 freeTier 与 freeTierCheckedOn（字段定义见公共表 note）。

0. 双层注册表快路径（优先执行）

本 skill 同目录下有两份注册表：

• models_registry.json — 公共表（随 skill 分发）：收录「任何持该渠道公开注册 key 的用户均可用」的端点，含两类 channel：direct（厂商直连，key=模型原厂发放，如 DeepSeek 官方）/ cloud-hosted（云厂商托管渠道，key=云厂商发放、模型是别家的，如腾讯云 Token Plan 的 DeepSeek、阿里千问平台接入的第三方模型）。每条目必带 keyIssuer 标注发卡方
• models_registry.local.json — 私有覆盖表（仅本机自用，打包分发时必须排除）：private-relay 私有中转端点（无公开注册渠道的 token 站/自建网关）
• 渠道铁律（2026-09-07 渠道三元重构）：渠道 = 三元（direct / cloud-hosted / private-relay），公共/私有划分按「有无公开注册渠道」划线，不按「厂商直连与否」——云厂商托管的第三方模型属公共表（持云厂商 key 即可用），进 local 表会导致分发时丢失已实测条目。快路径命中后必须核对用户 key 发卡方与条目 keyIssuer 一致：云厂商 key 发往厂商直连端点（或反向）必 401，这不是 key 本身的问题，是渠道错配——先问渠道，再怀疑 key

执行顺序：

1. 加载与容错：读公共表 → 读私有表（若存在）→ 按 id 覆盖合并（local 优先）。任一文件缺失或 JSON 解析失败 → 跳过该层继续，不得中断；两层全部不可读 → 视同 0 命中，退回读文档全流程。
2. 规范化用户口语模型名：转小写，空格与连字符统一。
3. 匹配（方向明确）：规范化后的用户词是某条目 id 或其 aliases 任一项的子串（含相等）→ 命中该条目。scriptCapable 宿主直接跑 python3 scripts/match_registry.py "用户词"，其 JSON 输出（unique/ambiguous/miss/tombstone/disabled）即本步结果；手动流程等价执行——注意条目级 tombstone: true 的停用条目不参与命中/预填，所有命中均为停用条目时按「渠道已停用」处理（见第 6 条墓碑短路）。
   • 命中 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 读文档全流程。注册表是加速器不是替代品。
   • 品牌级请求选型层（0 命中且用户词是品牌/家族词时）：用户说「接 gpt4 / 接 deepseek / 接 kimi」这类品牌词 ≠ 指定模型 id，真实待决问题是三件事：哪一代、哪个档位、免费还是付费。数据源纪律（2026-09-07 复盘确立）：官方目录优先，聚合清单只作补充——先拉厂商官方模型目录 + 官方 deprecations 页（如 OpenAI developers.openai.com/api/docs/models/all 与 /api/docs/deprecations），再可拉 OpenRouter GET /api/v1/models（无 key 公开接口）作价格对照。禁止只用聚合清单出菜单：它是转售商二手视图，价格是转售价、生命周期状态滞后（实证：官方已定 gpt-4 于 2026-10-23 停服、替代 gpt-5.6-sol，OpenRouter 清单同日仍在正常售卖，无任何停服标注——只看聚合清单会漏掉停服倒计时）。菜单每项标 model id / 上下文 / 单价 / 免费性 / 生命周期状态，并主动点出代际差（实证：当前代 gpt-5.6-luna $0.20/$1.20 每百万、1M 上下文，比 2023 老款 gpt-4（8k 上下文、$30/$60）便宜一个数量级且更强——不亮菜单，用户不知道「gpt4」已是过时代词）。用户选定具体 id 后再回注册表/读文档流程。禁止把品牌词默认映射到该品牌最老的同名模型。
4. 注册表值 ≠ 最终权威，但探针分级执行：token 上限与多模态可能漂移或虚标，探针结果永远优于注册表，冲突时以探针为准并在交付说明点出差异。探针不是一律全量——按下方「探针分级」判级，把探针预算花在不确定的数据上。
5. 自增长：每次成功接入并实测后，把该模型条目（含实测值与 verifiedBy/confidence）追加进注册表——公共表收录「有公开注册渠道」的端点（direct 或 cloud-hosted 均可，带 channel/keyIssuer 字段）；private-relay 私有中转只进 local 覆盖表，并同步维护两层文件的各自 version 字段。L3 宿主下跳过自增长（无库可写）。
6. 墓碑短路：公共表的 retiredModels 数组同样参与第 3 步别名匹配；命中墓碑 → 不预填、不追问 key，直接转「免费优先发现层」，告知该模型已失效并推荐替代。墓碑条目的 recheckAfter 之前免复核直接判死；过了该日期用户质疑时，可实时复核一次（复活则移出墓碑并更新注册表）。local 表条目级墓碑（tombstone: true）同理：该条目因用户停用某厂商/渠道（如 2026-09-07 移除商汤 SenseNova）而不再维护——命中即不预填、不追问 key，告知「该渠道已停用（removedOn/removedBy）」并转「免费优先发现层」或读文档全流程；removedOn 之前的历史探针数据仅供复活复核参考，不作为当前可用性依据。

⚡ 探针分级（进入 Step 4 前先判级，决定跑哪些探针）

判级依据 = 条目 confidence + lastVerified（距今天数）：

• 判级歧义从严：分不清轻验证还是全量 → 全量。
• 探针预算声明：开跑前声明预计请求次数（轻验证≈1 次，全量≈3-6 次，二分另计）——免费/公测档每日配额个位数时，探针本身可能耗光当日额度，此时主动建议轻验证或跳过，别让接入动作把接入结果变不可用。
• 同会话重复接入同一模型：直接复用本会话已得探针结果，不发重复请求。
• 自增长写表时同步更新 lastVerified（日期）与 probe（结构化实测值），verifiedBy 保留人类可读注记。

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

0.5 宿主适配（非 WorkBuddy 宿主必做）

本 skill 以 WorkBuddy 为参考宿主（~/.workbuddy/models.json，字段见 Step 2）。用于其他智能体时：

1. 定位该宿主的模型配置位：查官方文档或现有配置文件（常见：config.json / settings.json / 环境变量 / Web 后台表单）。
2. 字段映射：把注册表/文档参数映射到该宿主的字段名（如宿主用 contextWindow 而非 maxInputTokens，用 vision 而非 supportsImages）。
3. 确认该宿主的重载方式：改完配置后需重启/重载/热切换，向用户说明。
4. 映射不确定时单条提问，不臆测字段名。
5. L2 表单宿主（只有 UI 表单可填）：交付形态 = 按该宿主表单字段逐项列出的「可粘贴填写清单」，每项注明取值来源（文档/注册表/探针实测）。

0.6 协议失配检查（宿主协议 ≠ 端点协议时，写入配置前必做）

宿主说 Anthropic Messages 协议（如 Claude Code）而端点是 OpenAI 兼容（或反之）时，直接写入 = 宿主根本发不出能被理解的请求。这一步在 Step 3 写配置之前执行，失配未解决禁止写配置：

1. 判定宿主协议：查宿主文档/现有配置——出现 ANTHROPIC_BASE_URL、anthropic-version、Messages API 字样 → Anthropic 协议；OPENAI_BASE_URL/base_url + chat/completions 字样 → OpenAI 兼容。判定不了 → 单条提问用户或查文档，禁止默认。
2. 失配时三选一（按序尝试）：
   • ① 厂商原生双协议端点：查注册表条目 altProtocol 字段（如 DeepSeek 的 anthropic-compatible 端点；status: documented-未实测 的必须先探针），或读厂商文档确认有无。有 → 按 0.5 字段映射走，⚠️ 该端点的 model id 可能与按量端点不同，必须按其文档另核。
   • ② 环境变量 shim：宿主支持 ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN 类覆盖时，把 base_url 指向兼容端点。写环境变量属写配置，走双重确认。
   • ③ 明示不支持：两者皆无 → 告知用户「此宿主 × 此端点组合需协议转换网关（如 CCR 类本地网关工具），本 skill 不覆盖网关搭建」，交付通用参数卡 + 网关选型建议，不硬写配置。

1. 读文档：提取接入必需项

• ⚠️ 本步是硬闸门不是可选项：0 命中后必须真实读取厂商官方接入文档（模型目录 / API reference / deprecations 页），拿到一手参数后才准进 Step 2；聚合平台清单只能补充价格对照，不能替代官方文档成为参数来源（2026-09-07 复盘：该步曾被跳过——品牌选型用了 OpenRouter 清单后直接出了推荐，官方文档一次没读，导致漏掉官方弃用信息。反例教训：用户自己都能找到 developers.openai.com/api/docs/models/all，接入工程师没有理由找不到）。
• 生命周期检查（读文档必查项）：确认目标模型在厂商官方 deprecations 页的状态——是否已弃用 / 停服日期 / 官方替代模型。命中已弃用或已定停服日期的模型 → 必须先向用户亮牌（停服日期 + 官方替代），用户仍坚持才继续接入；禁止只看聚合平台还在售卖就当模型健康（实证 2026-09-07：gpt-4 详情页无 deprecated 字样，但官方 deprecations 页列明 2026-10-23 停服、替代 gpt-5.6-sol；弃用信息可能只在 deprecations 页而不在模型详情页，两页都要查）。
• 接口地址（含是否带 /v1）
• 鉴权方式（Header 名与格式，如 Authorization: Bearer ）
• 模型标识（model 字段的真实取值，大小写敏感）
• 请求/响应格式、是否 OpenAI 兼容
• 上下文窗口 / Token 上限：maxInputTokens 与 maxOutputTokens 的真实取值（注意单位换算：文档常写 1M→1000000、1024K→1024000、384k→384000）
• 订阅套餐 ≠ 按量付费（关键，接入前必查）：厂商的「套餐制」（Coding Plan / Token Plan / 订阅）与「按量付费」是两套接入参数——专属端点 + 专属 key + model id 三者都可能不同：
  • 端点不同：智谱 Coding Plan 用 /api/coding/paas/v4（不是通用 /api/paas/v4，用错报错/功能受限/不抵扣额度）；腾讯 Token Plan 用 api.lkeap.cloud.tencent.com/plan/v3；Kimi Code 订阅用 api.kimi.com/coding/v1（不是 api.moonshot.cn）
  • key 不通用：套餐 key 通常只对套餐端点生效（实测案例：Kimi Code 订阅 key 发到按量端点直接 401），且智谱 Coding Plan 要求用套餐概览页创建的专属 key，不能混平台普通 key
  • model id 可能不同：Kimi 订阅端点是 kimi-for-coding，而按量端点是 kimi-k3/kimi-k2.7-code——同一家族两个 id，套错按错计费方式扣费或 404
  • 计费形态不同：订阅多为请求配额制（Kimi Code 300-1200 次/5h 滚动窗口、30 并发上限），非 token 计费；配额接近耗尽会 429
  • 接入前先问清用户持的是哪种 key：套餐 key → 查套餐专属端点（注册表 local 表优先）；按量 key → 通用端点。分不清就问，禁止默认按量端点
• 协议族与双协议端点：确认文档提供的协议（openai-compatible / anthropic-compatible / 其他），与宿主协议（0.6）对照；厂商同时提供双协议端点时记入注册表条目 altProtocol（标 documented-未实测），供协议失配时选用
• 能力矩阵（关键，逐项确认，以文档原文为准，不得假设）：
  • 图片输入（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 前缀、模型名大小写与文档完全一致
• id 字段 = API 请求的 model 字段，宿主原样透传（中转站失败的头号根因）：WorkBuddy 源码坐实——stripCustomLocalModelPrefix 只剥 custom-local: 前缀（slice(13)），不剥 vendor/ 前缀，id 其余部分原样成为发给 API 的 model。所以 id 必须精确等于中转站要求的 model 字符串（大小写、含/不含厂商前缀一字不差）。⚠️ 中转站 model 命名规范不统一：腾讯 Token Plan 要 deepseek/deepseek-v4-pro-0813（带 deepseek/ 前缀），商汤 SenseNova 要 deepseek-v4-flash（平铺不带前缀）。禁止自行给 id 加 vendor/ 前缀——写 sensenova/deepseek-v4-flash 会让宿主把整串当 model 发出，中转站返 400/404。id 取值以 Step 1 文档原文或 Step 4 探针为准；注册表的 modelId 字段才是要写进宿主 id 的值，别误用注册表的「id 键」（可能带 vendor 前缀）。
• vendor 是元数据标签，不参与请求路由（2026-08-20 源码实证，推翻此前"vendor 填错导致调用失败"的误诊）：WorkBuddy 对自定义模型用 url + apiKey + id（→model）三个字段路由，normalizeCustomModel 只做「加 custom 标签 + 解析环境变量」，请求构造中无任何 vendor 路由逻辑；此前在 app.asar 里用 strings 搜到的 getVendorPrefix 实为 css-tree 的 CSS 前缀代码，与模型无关（误读）。vendor 仅用于 UI 分组展示。故 vendor 填「提供 url 的一方」（中转站如 sensenova）只为分组合理，填成原厂名不会导致调用失败——把失败归因于 vendor 是误诊，真因是上方 id 前缀透传 + 下方「配置持久性」。建议 vendor 仍填「提供 url 的一方」保持分组正确，但别指望它决定成败。
• 能力字段如实填写（本 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 上限为待核实估值，很可能需上调"，不得伪装成已确认值。
• 配置持久性（写后必验，区分两种场景）：WorkBuddy 对 models.json 有 file watcher（watchFile→debounceSync→sync），运行中改文件会被立即重新加载（2026-08-20 实测：改文件后 CLI --model 列表即刻出现 custom-local:<id> 新条目，且实际调用成功）。但在 UI 模型选择器保存、或 WorkBuddy 重启时，宿主会用内存配置重写文件，未被正确加载的条目会丢失（2026-08-20 case 观察：带 sensenova/ 前缀的 id 条目被回滚消失——注意那次 id 本就写错，可能是被 SmartMerge 过滤而非单纯回滚）。写完配置必须：① 立即读回校验写入成功；② 用下方「宿主层验证」确认宿主真的加载（而非只落盘）；③ 若条目消失 → 改走宿主 UI 注入（设置→模型→添加自定义模型），观察 UI 生成的 id/vendor 格式照抄。只写文件不验宿主加载 = 虚假的"接入完成"。 注意 models.json 有两级：用户级 ~/.workbuddy/models.json 与项目级 <workspace>/.workbuddy/models.json，先确认目标宿主读的是哪一级。

4. 做验证

先按 Step 0「探针分级」判级决定探针范围；scriptCapable 宿主用 scripts/probe.py（smoke/output-limit/image/tool/input-limit/context-metadata 子命令，结果单行 JSON，429 退避与域名门禁内建），手动流程按下述等价步骤。

错误码决策表（探针失败先查表再行动，禁止自由发挥）：

• 宿主层验证（API 能通 ≠ 宿主能通，必做）：「基础验证」是你自己用 curl/脚本直打 API，只证明 url/model/key 本身对。但中转站失败常发生在宿主实际发出请求这一层——id 前缀透传（sensenova/deepseek-v4-flash 被整串当 model 发出）、配置被回滚、vendor 误配。因此必须在宿主里实际选该模型发一次请求，从宿主日志/实际请求反推「实际发出的 model 字符串」与 HTTP 状态码，确认它等于 API 要求的精确值。WorkBuddy 有两条快速验证手段：① codebuddy --help 看 --model 选项列表——已加载的自定义模型会以 custom-local:<id> 形态列出（新条目出现 = 宿主已加载）；② 直接跑 codebuddy -p -y --model custom-local:<id> "测试提示词" 做真实请求，返回正常即链路打通。日志位置（WorkBuddy/macOS）：~/Library/Logs/WorkBuddy/main.log、renderer.log，或 ~/.workbuddy/traces/*/trace_*.json（搜模型名/端点/返回的 error body）；其他宿主/其他 OS 的日志路径以该宿主文档为准，禁止臆测路径。拿真错，别从字段名猜。
• 基础验证：用该模型发一条最简文本请求（如「你好」），确认能正常返回。
• 上限实测（全量判级必做；轻验证判级默认采信注册表值，防文档虚标导致发起会话 400）：先验注册表/文档值——发一条 max_tokens = 所填 maxOutputTokens 的请求，200 即收工（1 次调用）。若返回 400 Invalid request parameters，说明上限虚标——二分探测真实可用边界（524288/512K 这类 2 的幂常为硬上限）。二分纪律：轮次上限 8 轮，未收敛则取已验证值并在交付说明标注区间；429 退避硬规则：2s→8s→30s 三次仍 429 即熔断，该模型上限标注「限流阻断未定界（日期）」，禁止继续打、禁止记假边界。⚠️ 区分 429 与 400：中转站（如 SenseNova Free 公测）配额极紧，探测会间歇性返 429 Workspace allocated quota exceeded（限流非拒绝），只有 400 才计为真上限拒绝——曾因把 429 误判为 max_tokens 拒绝得到假边界（304625 而非真实 384000）。实测出更小边界就把 maxOutputTokens 改为实测值，并在交付里说明"文档标称 X 但 API 实际仅接受 Y"。此步不做（全量判级时），用户选该模型发起会话时会直接失败。
• 输入上限探针（两档廉价探针，按序做；全量判级时执行）：
  1. 元数据白拿：OpenRouter 系模型直接读 /api/v1/models 的 context_length（免费无 key，可跑 probe.py context-metadata）；Moonshot 系模型同走此路——GET https://api.moonshot.cn/v1/models 返回每模型的 context_length/supports_image_in/supports_video_in/supports_reasoning 能力位（2026-09-07 官方文档核实），一次请求同时核上限与多模态，能力字段预填值可直接对表纠偏；其他厂商的文档明示值按 documented 采信。
  2. 错误体披露：发一条超长 filler prompt（约目标上限 ×1.05，先声明 token 成本再执行；probe.py input-limit 对 >50k pad 要求 --confirm），多数端点 400 错误体会自报真实上限（如 maximum context length is 131072 tokens），从错误体提取数字。 ⚠️ 合计口径陷阱：部分端点报的是「输入+输出合并」总额（实测案例：OpenRouter minimax/minimax-m3:free 报错披露 1048576 为输入+输出合计）——此时 maxInputTokens 与 maxOutputTokens 必须按合计口径保守拆分，不可两字段都填满总额。两档都做不了（成本/限流）→ 维持估值并在交付说明高亮。
• 多模态验证（预填 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 案例）。
• 请求形态对齐验证（全量判级必做；轻验证可跳过）：探针的裸「你好」≠宿主真实请求。全量探针最后一轮用与宿主相同的形态发一条：stream: true + 一个哑工具定义（如 get_weather，可跑 probe.py smoke --stream 与 probe.py tool）。它暴露纯文本探针测不出的问题：① 端点要求流式才有正常响应；② tool_calls 响应格式方言；③ reasoning 参数方言（reasoning_content / reasoning / thinking 各家不一）。方言例外记入注册表条目 quirks 数组，写入宿主配置时检查宿主能否表达该参数，不能则在交付说明声明行为差异（如「思考模式强制开启，宿主的关闭开关会无效」）。
• 交付说明：明确告知用户——
  • 实际接入的模型名、vendor、接口地址
  • 能力矩阵（图片输入 / 图片输出 / 工具调用 / 推理 的支持情况）
  • Token 上限（maxInputTokens / maxOutputTokens）的取值来源：是文档确认值、用户给定值、注册表历史实证值、探针实测值，还是待核实估值？同时注明本次探针判级（轻验证/全量/用户跳过）与输入上限探针来源（元数据/错误体披露/未探）。输入上限若未过两档探针，必须在交付说明里单独声明其来源与局限（如"输入上限来自注册表历史实证，未经本次实时校验，厂商若缩窗会在长会话时报 400"）。若为估值必须高亮提示"很可能需上调"。
  • 任何与用户预期不符的点，例如："你提供的模型不支持多模态输出，已按文档如实将 supportsImages 置为 false，不会误启用图片能力。" 若为 L3 降级交付，还须注明：探针是否已执行（未执行的项，参数卡对应字段标注「待探针」），以及该参数卡适用于哪个目标宿主。

关键约束

• 注册表是假设，探针是真相，分级是纪律：从注册表预填的值仅作起点；输出上限与多模态（预填 true 时）的最终取值以 Step 4 实时探针为准，冲突时修正并在交付说明告知用户。探针按「探针分级」执行——不确定的数据必须全量探，保鲜期内的 tested 数据轻验证即可，探针预算不为已确定性买单。输入上限走两档廉价探针（元数据/错误体披露），做不到才声明来源。
• 带 key 只发白名单域名：发真实 key 前核对 url 域名 ∈ trustedDomains[vendor]（local 中转条目须用户已确认）；白名单外升级双重确认。公共表加条目必须同步补域名+来源。
• 429 退避熔断：2s→8s→30s 三次仍 429 即熔断，标注「限流阻断未定界」；429 永不计入上限边界，也不因限流得出能力否定结论。
• 协议失配不硬写：宿主协议 ≠ 端点协议时按 0.6 三选一（双协议端点 / env shim / 明示不支持转参数卡），禁止把 OpenAI 兼容端点硬写进 Anthropic 协议宿主。
• 双层注册表隔离：公共表只收官方公开端点；私有端点（中转/订阅专属）只进 local 覆盖表；分发打包时必须排除 models_registry.local.json。
• 免费信息有时效：任何「免费」结论必须来自本次会话的实时查询（OpenRouter pricing 字段 / 厂商官网现状），禁止把注册表历史值当「当前仍免费」引用；条目的 freeTier 只是最近一次核验记录，距 freeTierCheckedOn 较久即视为存疑。模型下架后移入公共表 retiredModels 墓碑而非直接删除，保留曾经验证的参数供同类渠道复用与溯源。
• id 原样透传：宿主只剥 custom-local: 前缀，vendor/ 前缀与其余字符原样成为 API 的 model 字段。id 必须精确等于 API 要求的 model 字符串（含大小写、含/不含厂商前缀），禁止自行加 vendor 前缀——这是中转站接入失败的头号根因。
• 写配置必验宿主加载：只写文件 ≠ 接入成功——宿主在 UI 保存/重启时可能重写 models.json，未正确加载的条目会丢。必须读回校验 + 宿主层验证（CLI --model 列表 / 实际请求）；条目失效则走宿主 UI 注入，绝不把「写文件」当成交付终点。
• 不臆测能力：任何能力字段必须以文档原文或实测为唯一依据。
• 不臆测 Token 上限：maxInputTokens / maxOutputTokens 必须来自文档或用户明确给定；缺失时按上文"Token 上限"规则处理，绝不把猜测的小值当事实静默写入（这会悄悄把模型的真实上下文窗口压短）。
• 不静默降级也不静默升级：能力与实际不符、或 Token 上限为估值时，在交付说明里明确点出，让用户知情。
• 用户零手动操作：配置文件、字段、验证全部由你完成；只在文档缺失关键信息时，才用单条提问向用户索取，绝不要求用户自己改配置。