Skip to content

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

Open
Open
[Feature]: 加固 Provider / Gateway 兼容性与外部 API 接入 / Harden provider-gateway compatibility and external API integration#214
Labels
enhancementNew feature or requesttriageAwaiting maintainer review

Description

@Sun-sunshine06
Sun-sunshine06
opened on Apr 23, 2026

[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

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

Activity

  1. Sun-sunshine06
    added
    enhancementNew feature or request
    triageAwaiting maintainer review
    on Apr 23, 2026

  2. github-actions commented on Apr 23, 2026

    @github-actions
    github-actionsBot
    on Apr 23, 2026 – with GitHub Actions
    Contributor

    感谢提这个 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

  3. hqhq1025 commented on Apr 23, 2026

    @hqhq1025
    hqhq1025
    on Apr 23, 2026
    Collaborator

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

  4. JeremyP42 commented on Apr 23, 2026

    @JeremyP42
    JeremyP42
    on Apr 23, 2026

    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).

    Image Image Image Image Image

  5. hqhq1025 commented on Apr 23, 2026

    @hqhq1025
    hqhq1025
    on Apr 23, 2026
    Collaborator

    looks good! thank you.
    @Sun-sunshine06

  6. Sun-sunshine06 commented on Apr 23, 2026

    @Sun-sunshine06
    Sun-sunshine06
    on Apr 23, 2026
    CollaboratorAuthor

    根据 @hqhq1025 提到的反馈，我补了一个单独子 issue：#216。

    之所以单独拆，是因为这里的核心问题不是单纯 diagnostics 做得不够，而是“测试连接”和“实际调用”目前仍可能走不同的有效 provider contract，导致 test-pass/runtime-fail 或 test-fail/runtime-pass 的误判。

    和 #213 的边界：#213 更偏 capability-aware diagnostics；#216 更偏 connection-test / runtime parity，本质上是在要求两条链路共享同一套 provider 解析、auth、wire、baseUrl、keyless 语义。

  7. Sun-sunshine06 commented on Apr 23, 2026

    @Sun-sunshine06
    Sun-sunshine06
    on Apr 23, 2026
    CollaboratorAuthor

    @hqhq1025 这个点我同意，而且我觉得是需要单独跟踪的结构性问题，不只是提示文案问题。

    我已经补了子 issue #216，专门跟踪“测试连接”和“实际调用”链路对齐这件事。后续会重点看这几件事：

    • active provider 解析是否和真实 generate 完全一致
    • auth / headers / baseUrl / wire / keyless 规则是否复用同一套语义
    • /models probe 和真实 inference fallback 的关系是否被明确建模
    • 覆盖 test-pass/runtime-fail 与 test-fail/runtime-pass 这两类回归场景

    目前 #215 先落了 capability profile 这层基础，后面做 #216 时就可以少一些硬编码判断。

  8. Sun-sunshine06 commented on Apr 23, 2026

    @Sun-sunshine06
    Sun-sunshine06
    on Apr 23, 2026
    CollaboratorAuthor

    @JeremyP42 Thank you, this is very helpful.

    Your proposal lines up well with two tracks we are already splitting out under this epic:

    A few parts of your suggestion feel especially useful:

    • keeping provider connection settings and model selection close together
    • allowing both discovered models and manual model entry
    • making provider presets easier to bootstrap instead of requiring everything to be typed from scratch

    I do think we should treat external provider lists like models.dev/api.json as a helpful seed rather than the sole source of truth, because auth shape, supported wire, and runtime compatibility can still differ by gateway.

    We will keep this UI direction in mind as we work through the provider/API issues. Thanks again for taking the time to mock it up.

  9. Sun-sunshine06
    added 2 commits that reference this issue on Apr 23, 2026

    feat(shared,desktop): add provider capability profiles (#215)

    8f596f6

    feat(desktop): align connection test credential resolution with runti…

    3bf2add
  10. hqhq1025
    added
    bot-rerunTemporary label to rerun automation
    and removed
    bot-rerunTemporary label to rerun automation
    on May 1, 2026

  11. github-actions commented on May 1, 2026

    @github-actions
    github-actionsBot
    on May 1, 2026 – with GitHub Actions
    Contributor

    This is a well-structured epic that accurately reflects the current state of provider compatibility in the codebase. The code references you listed align with what's present:

    • packages/providers/src/gateway-compat.ts — already detects gateway-specific behavior (e.g., Anthropic relay with /models but no /messages)
    • apps/desktop/src/main/connection-ipc.ts — connection test already distinguishes models, chat_completion_degraded, responses_degraded, and fallback probes
    • packages/providers/src/index.ts — handles wire/role/reasoning adaptation for OpenAI-compatible gateways
    • apps/desktop/src/main/provider-settings.ts — supports keyless providers, wire, httpHeaders, queryParams, reasoningLevel fields

    All nine child issues are now tracked, and #216 (connection-test/runtime parity) has been added based on @hqhq1025's feedback, which is a good call. The existing infrastructure provides a solid base for this work.

    If you'd like deeper code-level analysis for any specific child issue (e.g., how model discovery could reuse the existing probe flow, or how the provider adapter framework might build on synthesizeWireModel), feel free to tag this bot or open a follow-up.

    Open-CoDesign Bot

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requesttriageAwaiting maintainer review

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions