[Feature]: 升级连接诊断为 capability-aware / Improve connection diagnostics with capability-aware detection

[Sun-sunshine06]

[Feature]: 升级连接诊断为 capability-aware / Improve connection diagnostics with capability-aware detection

Problem / pain point / 问题

当前连接测试已经比“只测 /models”更强，但仍然会遇到“技术上能连通，功能上不兼容”的情况：

• /models 不存在，但 inference 实际可用
• chat/completions 可用，但 responses 不可用
• gateway 拒绝 developer role
• auth 正常，但 selected wire 不兼容

Current tests are already better than a naive /models probe, but users can still hit endpoints that are reachable while functionally incompatible.

Proposed solution / 方案

把 diagnostics 从“能不能连上”升级成“哪一层不兼容”。

Classify failures across:

• authentication / 鉴权
• endpoint shape / endpoint 形状
• wire support / wire 兼容性
• model discovery / 模型发现
• role compatibility / role 兼容
• reasoning compatibility / reasoning 兼容

Where possible, return structured results that can also feed capability updates or UI hints.

Alternatives considered / 备选方案

• 维持简单 pass/fail
  • 对 multi-gateway 场景信息不足

Scope / 范围

Provider / model

Acceptance criteria / 验收标准

• diagnostics 区分 auth、endpoint、wire、model-discovery 失败
• /models 缺失但 inference 可用时，显示 degraded-compatible 状态
• responses vs chat/completions 不兼容被明确报告
• renderer 收到结构化原因，而不是单一字符串
• 各主要失败路径有测试覆盖

Likely touchpoints / 可能涉及

• apps/desktop/src/main/connection-ipc.ts
• packages/providers/src/gateway-compat.ts
• packages/providers/src/errors.ts
• renderer settings / diagnostics UI

[Sun-sunshine06]

Parent epic / 所属总 issue: #214

[github-actions]

感谢反馈，这个方向和当前代码里已经暴露出来的兼容性缺口是对齐的。

我核对了当前实现后，能确认的是：现在的连接测试已经覆盖了一部分“/models 不可用，但实际推理仍可用”的降级兼容场景，但还不是端到端的 capability-aware 诊断。openai-chat 和 openai-responses 都会在 /models 返回 404 时继续探测各自真实的推理端点，并通过 probeMethod 返回 chat_completion_degraded / responses_degraded；不过当前主进程返回给 renderer 的结果仍然主要是 probeMethod 或 code/message/hint，我没有在现有 connection test 返回结构里找到更细的 auth / endpoint-shape / wire / role / reasoning 分类结果。

另外，生成期已经有一部分启发式兼容性判断：例如 400 且包含 instructions 会被识别为 openai-responses 配置不兼容，5xx 且包含 not implemented / page not found 会被识别为 gateway incompatible；但这些更多还是 generate-time 的诊断，而不是连接测试阶段直接返回的结构化 capability 结果。renderer 侧目前也是根据 errorCode 在前端本地推断“most likely cause”，不是主进程直接下发结构化 incompatibility reason。

项目目前还在 v0.1.x 的早期阶段，README 里也把 “clearer connection diagnostics” 列在当前 polish 项里，所以这类增强和现有方向是一致的。

Relevant code:

• apps/desktop/src/main/connection-ipc.ts:40 — 当前连接测试成功结果只暴露 probeMethod，失败结果是 code/message/hint
• apps/desktop/src/main/connection-ipc.ts:498 — /models 404 时对 openai-chat / openai-responses 做 degrade probe
• apps/desktop/src/main/connection-ipc.ts:536 — probe 按 wire 分流到 /chat/completions 或 /responses
• apps/desktop/src/main/connection-ipc.test.ts:889 — 已覆盖 /models 404 但 chat/completions 可用的降级通过路径
• apps/desktop/src/main/connection-ipc.test.ts:1015 — 已覆盖 /models 404 但 responses 可用的降级通过路径
• apps/desktop/src/main/connection-ipc.test.ts:1044 — 防止 openai-responses 被只支持 chat/completions 的网关误判为可用
• packages/shared/src/diagnostics.ts:212 — generate-time 的兼容性启发式诊断（如 instructions、gateway incompatible、relay streaming bug）
• apps/desktop/src/renderer/src/components/ConnectionDiagnosticPanel.tsx:93 — renderer 目前基于 errorCode 本地推断诊断结论
• packages/providers/src/index.ts:175 — provider 层已有关于 developer role / reasoning 兼容性的防御性处理说明
• packages/core/src/index.ts:354 — 生成期对 reasoning mismatch 做一次自愈重试
• README.md:250 — 当前仍在 v0.1.x，README 已将更清晰的 connection diagnostics 列为当前工作项

---

open-codesign Bot

[Sun-sunshine06]

补一个来自 #214 讨论的提醒：这里的 diagnostics 设计最好显式依赖 #216 的“connection-test / runtime parity”约束，而不是继续单独长出一套只服务于 probe 的判断语义。

换句话说，这个 issue 更适合解决“如何把不兼容原因分类得更清楚”，但前提应当是测试链路和真实调用链路尽量共享同一份 effective provider contract。否则 diagnostics 可能会越来越详细，但仍然建立在一条和 runtime 分叉的路径上，继续制造误判。

我建议后续实现时至少把这点写进设计/验收里：

• capability-aware diagnostics 产出的分类，尽量来自与 runtime 共享的 provider 解析、auth、wire、baseUrl、keyless 语义
• 如果某些结论只能由 probe 推断，也要明确标注“这是 probe-only inference”，避免被 UI 当成 runtime 事实

Related reminder from #214: #216

[github-actions]

感谢提交这个 feature request。之前的 bot 回复（comment id: IC_kwDOSFybr88AAAABAJmOhg）已经详细分析了当前连接诊断的实现状态，并指出了相关代码路径和不足。建议参考该回复以及关联 issue #214/#216 的讨论来推进设计。

如果后续有更具体的实现细节或需要帮助，请随时更新。

---

open-codesign Bot

Open-CoDesign Bot