aidog-add-platform

# aidog 加平台 / 改平台 给 aidog 新增一个平台预设，或修改一个平台的默认配置（base_url、端点协议、coding plan、默认模型、余额/配额查询）。本 skill 给出**改哪几处、什么顺序、怎么验证**，并把调研证实的反直觉陷阱前置，避免照源码直觉走错。 > file:line 锚点对应当前代码（2026-06-15 校对）。行号会随代码漂移，定位以**函数名/符号名**为准，行号仅作快速跳转参考。 --- ## 0. 四条认知纠偏（动手前必读，最大价值） 1. **平台预设住前端，不在后端。** `db.rs` 没有任何平台 seed 函数。`create_platform`（`src-tauri/src/gateway/db.rs:508`）是纯落库——传什么 base_url / endpoints / models 就存什么，**对默认配置零知识**。所有「选了平台 → 自动填 base_url」的预设逻辑都在前端 `src/pages/Platforms.tsx` 的 `getDefaultEndpoints`（`:150`）。**别去 db.rs 找 seed，没有。** 2. **Protocol 枚举 Rust↔TS 必须逐字双写，无容错，失配整体解析失败。** Rust `Protocol`（`src-tauri/src/gateway/models.rs:5`）每个变体的 `#[serde(rename="xxx")]` 字符串，必须与 TS 联合类型（`src/services/api.ts:6-27`）的字面量 `"xxx"` **逐字一致**。`Protocol` 没有容错 deserialize（不像 `ClientType` 有 `deserialize_client_type_lenient`，`models.rs:320`）——TS 传一个 Rust 不认识的字符串 → 整个 Platform 反序列化失败而非回退。漏改一侧 = 静默炸。 3. **`adapter/{glm,kimi,minimax,bailian,codex}.rs` 是死代码，禁去改。** 这 5 个文件全标 `#[allow(dead_code)]`，且 `converter.rs` 的 dispatch **从不调它们**（内部本就 `super::openai::to_openai` 直转）。真实协议转换只在 `convert_request`（`src-tauri/src/gateway/adapter/converter.rs:10`）的 **5 个 wire 分支**。加平台时**不要**去这些 adapter 文件加逻辑。 4. **coding plan / 余额查询按 base_url 子串分派，不按 Protocol 枚举。** `query_quota`（`src-tauri/src/gateway/quota.rs:373`）用 `base_url.to_lowercase()` 做 `if url.contains("...")` 顺序匹配，与 `Protocol` 枚举无关。接余额/配额查询时认 base_url 子串，别去枚举上挂。 --- ## 1. 先判路径：加平台是哪种？ ``` 新平台的上游报文格式是什么？ ├─ OpenAI Chat Completions 兼容（绝大多数国内/聚合/中转平台） │ → endpoint.protocol = "openai"，base_url 含 /v1 等前缀 │ → 【路径 1】零 wire 改动，走 converter.rs:34 默认分支 to_openai ├─ Anthropic Messages 兼容（很多平台提供 /anthropic 端点） │ → endpoint.protocol = "anthropic"，base_url 到 host 根（proxy 拼 /v1/messages） │ → 【路径 1】零 wire 改动，走 converter.rs:12 ├─ Gemini / OpenAI Responses / OpenAI Completions │ → 对应 wire protocol，已有 adapter，零新增 → 【路径 1】 └─ 全新私有 wire 格式（现实中几乎不出现） → 【路径 2】新建 adapter + converter match + parse_sse + 入站解析（重活） ``` 90%+ 的「加平台」是**路径 1**——只是又一个 OpenAI/Anthropic 兼容中转/聚合站，复用现成 wire 协议，给它一个独立枚举名 + 预设 base_url。 > 关键区分：**Protocol 变体有两类语义**（`models.rs:6-17` 注释划分）： > - **wire protocol（可作 endpoint 协议）**：仅 `anthropic / openai / openai_responses / openai_completions / gemini` 这 5 个决定请求体格式与 SSE 解析。 > - **平台类型（仅作平台主协议）**：其余全部（glm/kimi/deepseek/newapi…），只是身份标签 + 决定 OpenAI 兼容平台的 chat path，**不参与 wire 转换**。 > 新平台加的枚举变体几乎总是「平台类型」，wire 复用前 5 个之一。 --- ## 2. 路径 1：纯 OpenAI/Anthropic 兼容平台（6 处，缺一即失败） 按顺序改。前 3 处是跨层契约，后 3 处是前端预设。 ### ① Rust Protocol 枚举加变体 — `src-tauri/src/gateway/models.rs:5` 在「平台类型」段加一行： ```rust #[serde(rename = "foo")] // ★ rename 字符串 = DB/JSON 持久值，确定后不可改 Foo, ``` > 加完后所有对 `Protocol` 的 **exhaustive match** 会编译报错指路（见 §4），按提示补。 ### ② TS Protocol 联合类型加字面量 — `src/services/api.ts:6-27` ```ts | "foo" // ★ 与 ① 的 rename 逐字一致 ``` ### ③ `platform_fetch_models` 的 `|` 链 — `src-tauri/src/lib.rs:687` 新 OpenAI 兼容平台多半归到「走 `{base}/models` GET」那条 `Protocol::A | Protocol::B | ... =>` 链。**编译强制**（exhaustive match），不补 `cargo build` 报错。 ### ④ `PROTOCOLS` 下拉条目 — `src/pages/Platforms.tsx:17` ```ts { value: "foo", label: "Foo", keywords: ["foo", "foo.com"], codingPlan: false }, ``` **不补 = 用户在「添加平台」下拉里选不到**（软失败，无编译报错）。`codingPlan: true` 标记编程订阅平台。`keywords` 供智能粘贴解析器匹配（`src/utils/platformPaste.ts` `matchPlatform`）。 ### ⑤ `getDefaultEndpoints` 预设端点 — `src/pages/Platforms.tsx:150` 在 `base` map（`Partial<Record<Protocol, PlatformEndpoint[]>>`）里加该平台 → `PlatformEndpoint[]`： ```ts foo: [ { protocol: "openai", base_url: "https://api.foo.com/v1", client_type: "default", coding_plan: false }, ], ``` **铁律：base_url 含版本前缀**（如 `/v1`、`/api/paas/v4`）。proxy 拼 `api_path`（OpenAI 系 = `/chat/completions`，`converter.rs:44`），**禁额外拼接**。**不补 = 选了平台后 endpoints 为空，用户得手填 base_url**（`Partial`，非 exhaustive，不报错）。 > 多端点示例（glm，`Platforms.tsx:168-171`）：同平台可配 openai + anthropic 双端点，运行期按入站协议匹配（`proxy.rs:945-957`）。coding plan 平台用 `cp` 三元切 base_url（kimi，`:176-178`）。 ### ⑥ 显示名 — `src/pages/Platforms.tsx:397` `PROTOCOL_LABELS` ```ts foo: "Foo", ``` 这是 `Record<Protocol, string>`，**tsc exhaustive 强制**，不补 `yarn build` 报错。（研究里把它叫「显示名 map」——它就是 `PROTOCOL_LABELS`；`DEFAULT_NAMES` 在 `:470` 从它派生。） ### 可选项 - **颜色** `PROTOCOL_COLORS`（`Platforms.tsx:472`）：key 是 `string` 非 `Protocol`，非 exhaustive，不补走 fallback `var(--accent)`。 - **默认模型** `getDefaultModels`（`Platforms.tsx:371`）：在 presets map 加一行预填模型槽位，见 §5。强烈建议补（否则选平台后模型槽位空）。 - **余额 / coding plan 查询**：见 `references/quota-coding-plan.md`。 > 路径 1 **不需要**改任何 wire header / converter / 鉴权 / adapter——这些按 wire 协议分支，复用现成。后端 `db.rs / router.rs / converter.rs / adapter/` 均无需动。 完整 file:line 触点表见 `references/touchpoints-map.md`。 --- ## 3. 路径 2：加新 wire 协议（重活，几乎用不上） 仅当上游报文格式 anthropic/openai/openai_responses/openai_completions/gemini **全不匹配**时。除 §2 全部外，还需： 1. **新建 adapter** `src-tauri/src/gateway/adapter/xxx.rs`（参考 `adapter/openai.rs` / `anthropic.rs` **活** adapter，**别参考死代码 glm/kimi**）+ `adapter/mod.rs` 注册 mod。 2. **`convert_request` 加 match 分支** — `converter.rs:10`（返回 `(Value, api_path)`）。 3. **`parse_sse` 加 match 分支** — `converter.rs:66` 附近（流式 SSE 解析）。 4. **`parse_incoming_request`**（若作入站协议）— `converter.rs` 入站解析。 5. **wire 鉴权头** — `proxy.rs` `build_upstream_headers`（`:2482` 附近）/ `apply_default_headers`（`:2307` 附近）按 wire 协议加分支（anthropic `x-api-key` / gemini `x-goog-api-key` / 默认 Bearer）。 6. **endpoint 协议选项** `ENDPOINT_PROTOCOLS` — `Platforms.tsx:91`（只有 wire 协议进这个列表）。 7. **默认身份** `ClientType::default_for_protocol`（`models.rs:307`，非 exhaustive 有 `_`）+ 前端 `defaultClientForProtocol`（`Platforms.tsx:120`）。 8. 把新 wire 协议在 Protocol 枚举里**列为 wire 协议段**（`models.rs:6-16` 区）。 --- ## 4. 加 Protocol 变体后必补的 Rust match（编译强制） 加一个 `Protocol` 变体后，所有**无 `_` 兜底**的 exhaustive match 编译失败。已知热点： - `platform_fetch_models`（`lib.rs:687`）— `|` 链，**必补**（见 §2③）。 有 `_` 兜底、**多数情况不用动**的： - `convert_request` / `parse_sse`（`converter.rs`）— `_ => to_openai`，OpenAI 兼容平台自动兜底。 - `inject_coding_plan_fields`（`proxy.rs:2553`）— `_` 兜底，仅当要注特殊字段才加分支。 - `ClientType::default_for_protocol`（`models.rs:307`）— 有 `_`。 > 实操：加完变体直接 `cargo build`，编译器把所有必补 match 指出来，按提示补 `|` 链即可。不会漏。 --- ## 5. 默认模型预设（`getDefaultModels`） 详见 `references/default-model.md`。要点： 预设住前端 `getDefaultModels(protocol, codingPlan?)`（`src/pages/Platforms.tsx:371`），与 `getDefaultEndpoints` 并列。加平台时在其 `presets` map 加一行该平台 → 槽位对象，填**单个 model 名/槽位**（非列表）： ```ts foo: { default: "foo-model-v1" }, // OpenAI 兼容平台多归 default 槽 glm: { default: "glm-4.6" }, // 现有示例 kimi: { default: cp ? "kimi-k2.7-code" : "kimi-k2.6" }, // coding plan 切型号（型号名以源码为准） ``` - 返回 `Partial<Record<ModelSlot, string>>`（Partial，未覆盖平台返回 `{}` 不报错）。 - 槽位 key 必须 ∈ `ModelSlot`（`default/sonnet/opus/haiku/gpt`，`api.ts:47` / `models.rs:235`）。 - 准则：取该平台当前主力型号，**确定才填，不确定留空**（注释 `Platforms.tsx:370`）。 - 两个消费点已按 Protocol 泛化、**无需改**：表单 auto-fill（`:1620`，切协议时 `setModels` 展开预设）、列表卡片回退展示（`:1164`，已配置 → 上游 available → 预设回退）。 路由消费走 `resolve_model`（`router.rs:317`）：请求模型名含 opus/sonnet/haiku/gpt → 用对应槽位，否则 `default`，无 default → 透传（去 `[budget]` 后缀）。 --- ## 6. 余额 / coding plan / 价格接入（仅平台支持上游查询时） 完整模板见 `references/quota-coding-plan.md`。要点： - **余额查询**（按量平台）：照搬 `query_deepseek_balance`（`quota.rs:138`）骨架 → 新增 `query_foo_balance` + 在 `query_quota` 余额段（`quota.rs:392` 附近）加 `if url.contains("api.foo.com") { return query_foo_balance(...).await; }`。返回 `balance: Some(BalanceInfo{...}), coding_plan: None`。 - **coding plan 配额**（订阅平台）：照搬 `query_kimi_coding_plan`（`quota.rs:243`）→ 在 coding plan 段（`quota.rs:380` 附近，**优先于余额段**）加分派。返回 `coding_plan: Some(CodingPlanInfo{tiers, level}), balance: None`。 - 🔴 **tier `name` 硬约束**：必须 ∈ `cycle_ms_for_tier` 已知集合 `{"five_hour","weekly_limit","seven_day","mcp_monthly"}`（`usage_color.rs:30`）。未知 name → 无周期 → statusline 配色退 Neutral。 - **价格估算**（按量平台）：**无需改代码**。`resolve_price`（`db.rs:2840`）回退链：`pricing[platform_type]` → 顶层 → `default_platform` → fallback。只要 `model_price` 表该模型 `price_data.pricing` 含新 `platform_type` 键（= Protocol rename 字符串）即命中，否则自动回退。靠价格同步/手填，不动代码。 - **无上游 quota API 的平台**：用 `manual_budgets`（platform 列，JSON）本地限额兜底，与请求驱动预估并行（`manual_budget.rs`），无需改 quota.rs。 > 典型新平台只改 `quota.rs`（1 函数 + 1 分派行），可选改 `usage_color.rs`（新 tier 周期）。command（`platform_query_quota`，`lib.rs`）/ api.ts / Platforms.tsx 都已泛化，**无需改**。 --- ## 7. client_type 陷阱（协议 ≠ 身份） - **Protocol** = 报文格式（决定 URL path / 鉴权 header 名 / 请求体结构）。 - **ClientType** = 模拟哪个客户端通过上游校验（注入 UA + `X-Stainless-*` 等指纹头，`proxy.rs:2250` `apply_client_headers`）。 - 二者**正交**：同一 `openai` 协议可配 `codex_tui` 或 `claude_code` 或 `default` 身份。 🔴 **coding plan 上游对 client_type 有身份白名单（协议 ≠ 身份）**：例如 Kimi coding plan 上游**只接 Claude Code 身份、拒 Codex**。所以 `Platforms.tsx` 给 Kimi 的 openai-wire coding endpoint 配的是 `client_type: "claude_code"` 而非 `codex_tui`——即便协议是 openai，身份也必须填上游接受的那个。配 coding endpoint 的 `client_type` 要匹配**上游实际白名单**，别按 wire 协议想当然。 --- ## 8. coding plan 字段注入（仅需特殊 body 字段时） - `inject_coding_plan_fields(body, protocol)`（`proxy.rs:2553`）按**平台主协议** `platform_type` match 注入请求体字段。当前唯一实分支是 `Protocol::Kimi`（注 `prompt_cache_key`），其余走 `_` 兜底（不注）。 - 新平台 coding plan 需特殊字段 → 在 `Protocol::Kimi` 分支旁、`_` 前加 `Protocol::Foo =>` 分支。 - 🔴 **parity 要求**：proxy（`proxy.rs:1074-1077`）与 model-test（`lib.rs:837-838`）**并行**调 `inject_coding_plan_fields` + `override_coding_plan_path`。改注入逻辑**两处必须同步**，否则 model_test 与实际代理行为不一致（见 memory `model-test-proxy-parity`）。 - `override_coding_plan_path`（`proxy.rs:2582`）当前是空壳（参数全 `_` 前缀，无 match）。各平台靠 base_url 区分 coding/normal，多数**不需要**动它；需要时先建 match 骨架。 --- ## 9. URL 构造铁律 - `base_url` **含版本前缀**（`/v1`、`/api/paas/v4`、`/api/anthropic` 等）。 - `provider_api_path()`（`converter.rs:44`）OpenAI 系**只返 `/chat/completions`**；anthropic 拼 `/v1/messages`，gemini 拼 `/v1beta/...`。 - 最终 URL = `base_url + api_path`。**禁止额外拼接**（CLAUDE.md 硬约束 + memory `url-construction-rule`）。 - 即 anthropic 端点 base_url 填到 **host 根**（如 `https://open.bigmodel.cn/api/anthropic`，proxy 拼 `/v1/messages`）；openai 端点 base_url 含 `/v1`（proxy 拼 `/chat/completions`）。 --- ## 10. 验证门禁 ```bash # 动前端（Platforms.tsx / api.ts） yarn build # tsc + vite，exhaustive Record 错位会在这里炸 yarn check:i18n # 仅当新增了 i18n 文案 key # 动后端（models.rs / quota.rs / proxy.rs / lib.rs） cd src-tauri && cargo build # exhaustive match 漏补在这里炸 cd src-tauri && cargo clippy # warning 必须清零（memory warnings-are-issues） cd src-tauri && cargo test # 若动 quota/estimate/usage_color ``` 收尾自检： - [ ] Protocol 变体 Rust rename ↔ TS 字面量**逐字一致**（§0-2）。 - [ ] `PROTOCOL_LABELS` / `PROTOCOLS` / `getDefaultEndpoints` 三处都补（否则选不到 / 无预填 / tsc 报错）。 - [ ] base_url 含版本前缀，无额外拼接（§9）。 - [ ] coding endpoint `client_type` 匹配上游身份白名单（§7）。 - [ ] coding plan tier `name` ∈ `cycle_ms_for_tier` 集合（§6）。 - [ ] 改 inject 逻辑则 proxy + model-test 两处同步（§8）。 - [ ] 没去改 glm/kimi/minimax/bailian/codex 死代码 adapter（§0-3）。 --- ## 反例黑名单（不要做） 1. ❌ 去 `db.rs` 找/加平台 seed —— 预设住前端 `getDefaultEndpoints`。 2. ❌ 只改 Rust Protocol 不改 TS（或反之）—— 无容错，整体解析失败。 3. ❌ 去 `adapter/{glm,kimi,minimax,bailian,codex}.rs` 加转换逻辑 —— 死代码，从不被调。 4. ❌ base_url 不含版本前缀，或在 base_url 后再拼 `/chat/completions` —— 双拼接。 5. ❌ coding endpoint 按 wire 协议想当然填 client_type —— 上游有身份白名单。 6. ❌ coding plan tier 用 `cycle_ms_for_tier` 集合外的 name —— 配色退中性。 7. ❌ 改 inject 只改 proxy 不改 model-test —— parity 破坏。 8. ❌ 加平台去改定价 UI（`PricingTab.tsx`）—— 定价按模型名键，与平台无关，0 触点。 ## 相关 - 触点全表：`references/touchpoints-map.md`