[Feature]: 增强 Provider 错误归一化与恢复提示 / Improve provider error normalization and recovery actions

[Sun-sunshine06]

[Feature]: 增强 Provider 错误归一化与恢复提示 / Improve provider error normalization and recovery actions

Problem / pain point / 问题

现在已经有 provider error normalization，但恢复指引还不够稳定。不同 gateway 的失败方式很多：

• auth failure
• endpoint shape 不兼容
• partial compatibility
• upstream “not implemented”
• request shape rejection

用户很多时候不只是需要一个 normalized error string，而是需要“下一步怎么修”。

We already normalize provider errors, but users often need the next action, not only the normalized error details.

Proposed solution / 方案

基于现有 normalization 增加 recovery categories 和 actionable hints，例如：

• base URL 需要补 /v1
• 从 responses 切到 chat/completions
• 对当前 model 关闭 reasoning
• 改成 manual model entry
• 重新导入 provider credentials
• 补充 gateway-specific headers

Build on the current normalization layer rather than replacing it.

Alternatives considered / 备选方案

• 只输出技术细节，不做恢复动作提示
  • 对用户和排障都不够友好

Scope / 范围

Provider / model

Acceptance criteria / 验收标准

• normalized error 可映射到 recovery category
• 多类已知兼容问题能给出 targeted hints
• 这些 hints 可在 diagnostics 或 settings 中显示
• logging 依旧是 structured 且已 scrubbed

Likely touchpoints / 可能涉及

• packages/providers/src/errors.ts
• packages/providers/src/gateway-compat.ts
• renderer toasts / diagnostics UI
• generate-fix flows where relevant

[Sun-sunshine06]

Parent epic / 所属总 issue: #214

[github-actions]

感谢反馈，这个方向和当前实现之间确实还有一个 gap。仓库里已经有 provider error normalization，但它目前主要用于结构化日志；还没有把 normalized error 直接映射成统一的 recovery category。There is already a diagnostics/fix layer, but today it covers a limited set of known cases rather than a general recovery taxonomy.

Relevant code:

• packages/providers/src/errors.ts:27 — NormalizedProviderError 目前包含 upstream provider/status/code/message/request id/redacted body/retry count 等字段，还没有 recovery category。
• packages/providers/src/errors.ts:166 — normalizeProviderError() 负责扁平化并 scrub 上游错误，供结构化日志使用。
• packages/shared/src/diagnostics.ts:57 — connection 失败会映射到 cause + suggestedFix，当前已覆盖的例子包括 404 -> /v1、401/403、429、网络/SSL/CORS。
• packages/shared/src/diagnostics.ts:212 — generate 失败目前只覆盖一部分 recovery hints：缺少 /v1、invalid key、gateway incompatible、openai-responses misconfigured、relay streaming bug、generic 5xx / rate limit。
• apps/desktop/src/renderer/src/components/ConnectionDiagnosticPanel.tsx:93 — Settings 里的 connection diagnostics 已经可以展示 most likely cause 和 actionable fix。
• apps/desktop/src/renderer/src/store.ts:1050 — generate error 会桥接到同一套 diagnostics，并且在存在 baseUrlTransform 时能给出 “Apply fix”。
• apps/desktop/src/renderer/src/components/settings/DiagnosticsPanel.tsx:108 — Diagnostics 面板当前主要还是事件列表 / 导出 / report UI；我在这里没有找到 targeted recovery-hint UI。
• packages/shared/src/config.ts:130 — provider schema 已支持 httpHeaders / queryParams；但 apps/desktop/src/renderer/src/components/AddCustomProviderModal.tsx:73 明确写了 advanced headers/queryParams 还 deferred，所以 gateway-specific header 的恢复路径目前还没有完整落到 UI。
• apps/desktop/src/renderer/src/components/Settings.tsx:1362 and apps/desktop/src/main/onboarding-ipc.ts:1257 — provider re-import flows 已存在（Codex / Claude Code / Gemini / OpenCode）。
• packages/providers/src/retry.ts:293 and apps/desktop/src/main/diagnostics-ipc.ts:453 — structured logging 和 scrubbed diagnostics bundle 已经在做。
• README.md:250 — 当前仓库还处于 v0.1.3、快速迭代的 pre-alpha 阶段，README 也把 “Provider & API config polish” 和更清晰的 connection diagnostics 列为当前优先项。

从当前代码结构看，这个需求更像是在现有 diagnostics.ts 映射层上继续扩展，并把它和 provider normalization 连接起来，而不是替换掉现有 normalization。

---

open-codesign Bot

[github-actions]

Thank you for your feature request! It looks like this issue has already received a detailed response from the bot above. The analysis covers the current state of provider error normalization and recovery hints, and maps out the existing code paths and gaps. This is a great proposal and aligns with the project's direction. Maintainers will review it alongside the linked epic #214. If you have additional specifics or example scenarios, feel free to share them here.

Open-CoDesign Bot