Repository navigation
[Feature]: 升级连接诊断为 capability-aware / Improve connection diagnostics with capability-aware detection #213
Description
[Feature]: 升级连接诊断为 capability-aware / Improve connection diagnostics with capability-aware detection
Problem / pain point / 问题
当前连接测试已经比“只测 /models”更强，但仍然会遇到“技术上能连通，功能上不兼容”的情况：
/models不存在，但 inference 实际可用chat/completions可用，但responses不可用- gateway 拒绝
developerrole - 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 状态responsesvschat/completions不兼容被明确报告- renderer 收到结构化原因，而不是单一字符串
- 各主要失败路径有测试覆盖
Likely touchpoints / 可能涉及
apps/desktop/src/main/connection-ipc.tspackages/providers/src/gateway-compat.tspackages/providers/src/errors.ts- renderer settings / diagnostics UI
Activity
Sun-sunshine06 commentedon Apr 23, 2026
Parent epic / 所属总 issue: #214
github-actions commentedon Apr 23, 2026
感谢反馈，这个方向和当前代码里已经暴露出来的兼容性缺口是对齐的。
我核对了当前实现后，能确认的是：现在的连接测试已经覆盖了一部分“
/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/hintapps/desktop/src/main/connection-ipc.ts:498—/models404 时对openai-chat/openai-responses做 degrade probeapps/desktop/src/main/connection-ipc.ts:536— probe 按 wire 分流到/chat/completions或/responsesapps/desktop/src/main/connection-ipc.test.ts:889— 已覆盖/models404 但chat/completions可用的降级通过路径apps/desktop/src/main/connection-ipc.test.ts:1015— 已覆盖/models404 但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 层已有关于developerrole / reasoning 兼容性的防御性处理说明packages/core/src/index.ts:354— 生成期对 reasoning mismatch 做一次自愈重试README.md:250— 当前仍在v0.1.x，README 已将更清晰的 connection diagnostics 列为当前工作项open-codesign Bot
Sun-sunshine06 commentedon Apr 23, 2026
补一个来自 #214 讨论的提醒：这里的 diagnostics 设计最好显式依赖 #216 的“connection-test / runtime parity”约束，而不是继续单独长出一套只服务于 probe 的判断语义。
换句话说，这个 issue 更适合解决“如何把不兼容原因分类得更清楚”，但前提应当是测试链路和真实调用链路尽量共享同一份 effective provider contract。否则 diagnostics 可能会越来越详细，但仍然建立在一条和 runtime 分叉的路径上，继续制造误判。
我建议后续实现时至少把这点写进设计/验收里：
Related reminder from #214: #216
feat(shared,desktop): add provider capability profiles (#215)
github-actions commentedon May 1, 2026
感谢提交这个 feature request。之前的 bot 回复（comment id: IC_kwDOSFybr88AAAABAJmOhg）已经详细分析了当前连接诊断的实现状态，并指出了相关代码路径和不足。建议参考该回复以及关联 issue #214/#216 的讨论来推进设计。
如果后续有更具体的实现细节或需要帮助，请随时更新。
open-codesign Bot
Open-CoDesign Bot