[Feature]: 加固 Provider / Gateway 兼容性与外部 API 接入 / Harden provider-gateway compatibility and external API integration

[Sun-sunshine06]

[Feature]: 加固 Provider / Gateway 兼容性与外部 API 接入 / Harden provider-gateway compatibility and external API integration

Problem / pain point / 问题

Open CoDesign 已经支持多 provider、自定义 OpenAI-compatible endpoint、keyless provider、以及外部配置导入，但 API 兼容性仍然偏“隐式”：

• 不同 gateway 只实现了部分 OpenAI-compatible 接口
• 有些 endpoint 有 /models，有些没有
• 有些支持 responses，有些只支持 chat/completions
• system / developer role 行为不一致
• reasoning 支持依赖 provider 和 model
• 外部配置导入正在增多，但每个来源仍然有独立逻辑

Open CoDesign already supports multiple providers, custom OpenAI-compatible endpoints, keyless providers, and external config import. The remaining pain is compatibility hardening:

• different gateways partially implement OpenAI-compatible APIs
• some endpoints expose /models, some do not
• some providers support responses, others only chat/completions
• role handling differs across gateways
• reasoning support depends on provider/model
• external imports are growing, but each source still has bespoke logic

Proposed solution / 方案

把 provider compatibility 当成一等产品能力，而不只是零散补丁。

Treat provider compatibility as a first-class product surface rather than a collection of one-off fixes.

本 epic 追踪以下工作：

• provider capability profile
• capability-aware diagnostics
• connection-test and runtime parity
• LiteLLM first-class preset
• formal model discovery modes
• explicit wire / role / reasoning policy
• unified external-provider adapter framework
• OpenCode / Codex / CCS-style import follow-up
• actionable provider error normalization

Alternatives considered / 备选方案

• 继续按案例追加兼容补丁

  • 缺点：可扩展性差，后续维护成本高

• 为每个 provider 单独做一套 bespoke integration

  • 缺点：会绕开现有 wire + baseUrl + headers + model 抽象

• Keep shipping incremental compatibility patches

  • Rejected because it scales poorly

• Build bespoke integration paths for every provider

  • Rejected because it fights the existing abstraction

Scope / 范围

Provider / model

Hard-constraints check / 约束检查

• I have read the hard constraints in CLAUDE.md and this proposal does not conflict with them.

Child issues / 子 issue

• [Feature]: 引入显式 Provider Capability Profile / Add explicit provider capability profiles #206 Capability profile / 能力画像
• [Feature]: 升级连接诊断为 capability-aware / Improve connection diagnostics with capability-aware detection #213 Diagnostics and capability detection / 诊断与能力探测
• [Feature]: 对齐“测试连接”和“实际调用”链路 / Ensure connection-test and actual-invocation parity #216 Connection-test and runtime parity / 测试连接与实际调用链路对齐
• [Feature]: 增加 LiteLLM Gateway 一等预设 / Add a first-class LiteLLM gateway preset #208 LiteLLM gateway preset / LiteLLM 网关预设
• [Feature]: 正式建模模型发现模式 / Formalize provider model discovery modes #210 Model discovery modes / 模型发现模式
• [Feature]: 显式化 wire / role / reasoning 兼容策略 / Make wire-role-reasoning compatibility policy explicit #207 Wire-role-reasoning policy / wire、role、reasoning 兼容策略
• [Feature]: 统一外部 Provider 导入为共享 Adapter 框架 / Unify external provider imports under a shared adapter framework #211 External provider adapter framework / 外部 provider adapter 框架
• [Feature]: 跟进 OpenCode / Codex / CCS 风格配置导入路线 / Follow up OpenCode-Codex-CCS style import roadmap #209 OpenCode-Codex-CCS import follow-up / OpenCode、Codex、CCS 导入后续
• [Feature]: 增强 Provider 错误归一化与恢复提示 / Improve provider error normalization and recovery actions #212 Error normalization and recovery hints / 错误归一化与恢复提示

Suggested order / 建议顺序

1. Capability profile
2. Diagnostics and capability detection
3. Connection-test and runtime parity
4. Model discovery modes
5. LiteLLM gateway preset
6. Wire-role-reasoning policy
7. External provider adapter framework
8. OpenCode-Codex-CCS follow-up
9. Error normalization and recovery hints

Current code references / 现有代码参考

• packages/providers/src/index.ts
• packages/providers/src/errors.ts
• packages/providers/src/gateway-compat.ts
• apps/desktop/src/main/provider-settings.ts
• apps/desktop/src/main/resolve-api-key.ts
• apps/desktop/src/main/connection-ipc.ts
• apps/desktop/src/main/imports/opencode-config.ts
• apps/desktop/src/main/onboarding-ipc.ts

[github-actions]

感谢提这个 epic。基于当前仓库实现，我确认这个方向和现状是对齐的：现在已经有一批 provider / gateway compatibility 的基础设施，但还没有独立的 capability profile / unified adapter framework 落地，所以把这类工作集中追踪在一个 umbrella issue 里是合理的。

目前能从代码里直接验证到的，是“兼容性增强”已经分散存在于 provider 层、连接诊断、错误归一化和导入链路里；但还没有找到单独的 capability profile schema、formal model discovery modes、LiteLLM first-class preset 或统一 external-provider adapter framework 实现。项目当前也还在 v0.1.x pre-alpha 阶段，README 里把 “Provider & API config polish” 明确列为正在进行中的工作。

Relevant code:

• packages/providers/src/gateway-compat.ts:1 — 已有 gateway 兼容检测，专门识别 /models 可用但 /messages 未实现的 Anthropic-compatible relay。
• apps/desktop/src/main/connection-ipc.ts:40 — 连接测试已区分 models、chat_completion_degraded、responses_degraded 三种探测结果。
• apps/desktop/src/main/connection-ipc.ts:471 — 当 /models 返回 404 时，会 fallback probe 到真实 inference endpoint，而不是直接判定 endpoint 不可用。
• packages/providers/src/index.ts:175 — 已有 wire / role / reasoning 兼容逻辑，避免把 developer role 发给不兼容的 OpenAI-compatible gateway。
• packages/providers/src/index.ts:341 — 对 strict openai-responses gateway，已显式把 system prompt 转成 top-level instructions，并移除 system / developer entries。
• packages/providers/src/errors.ts:1 — 已有 provider error normalization，保留 upstream status/code/request-id，并对 body 做脱敏。
• apps/desktop/src/main/provider-settings.ts:72 — 已支持 keyless provider / IP-whitelisted gateway 配置。
• apps/desktop/src/main/provider-settings.ts:215 — 当前 provider entry 解析已经覆盖 wire、httpHeaders、queryParams、reasoningLevel 等字段。
• apps/desktop/src/main/imports/opencode-config.ts:273 — 已有 OpenCode import 基础，但未知 auth type / 不支持 provider 仍然是按来源分别处理和 warning。
• README.md:250 — 当前仍是 v0.1.x，README 也把 Provider / API config polish 列为当前阶段重点。

---

open-codesign Bot

[hqhq1025]

补充一点, "测试链接"链路 和 "实际调用" 链路应该确保是统一的 之前遇到包括现在也存在很多误判

[JeremyP42]

Hello.
I propose an implementation option for adding providers and models. The main settings window (01) contains a list of added providers and an "Add Provider" button.
The "Add and Edit Providers" window (02) contains provider connection settings and a list of available models.
The basic provider URL is filled in from a pop-up window (03) or manually. The list of providers with links is available here: https://models.dev/api.json .
Models can be selected from the menu (04) or entered manually (05).

[hqhq1025]

looks good! thank you.
@Sun-sunshine06