feat(diagnostics): bridge generate failures to diagnose() hypotheses (#130) (#165)

## Summary

Test-connection 失败已经走 \`diagnose()\` 给出可操作 hypothesis（如 404 →
\`missingV1\` + 自动加 \`/v1\`），但**真实生成失败完全没接这套系统**，用户只看到原始 IPC 错误文案，毫无方向。

本 PR 把 generate 失败接到 diagnostic hypothesis 系统，覆盖 404/4xx/5xx 多种场景，并为 404
missing-\`/v1\` 加自动 fix 按钮。

## What changed

### main 进程
- \`apps/desktop/src/main/index.ts\`：generate catch 块给 thrown error 附加
\`upstream_status\` / \`upstream_provider\` / \`upstream_baseurl\` /
\`upstream_wire\` metadata
- 新增 helper \`extractUpstreamHttpStatus()\`

### shared
- 新增 \`diagnoseGenerateFailure()\` in
\`packages/shared/src/diagnostics.ts\`：
- 400 + \"instructions\" 关键词 → \`openaiResponsesMisconfigured\` +
\`switchWire\` 提示
- 5xx + \"not implemented\" / \"page not found\" →
\`gatewayIncompatible\` + \`switchWire\` 提示
  - 通用 5xx → \`serverError\` + \`waitAndRetry\`
- 404（含裸 \"404 page not found\" 文案，#130 原始形态）→ \`missingV1\` + \`/v1\`
自动 fix
  - 401/403/429/402 → 委托现有 \`diagnose()\`
  - 其它 → \`unknown\`（toast 跳过避免噪音）

### renderer
- \`apps/desktop/src/renderer/src/store.ts\` \`applyGenerateError\`：调用
\`diagnoseGenerateFailure\` 把 cause sentence 拼到 toast description；404
missing-\`/v1\` case 加 **\"Apply fix\" action button** 通过
\`config:v1:update-provider\` 自动加 \`/v1\`

### i18n（en + zh-CN）
-
\`diagnostics.cause.{gatewayIncompatible,openaiResponsesMisconfigured,serverError}\`
- \`diagnostics.fix.switchWire\`
-
\`notifications.{generationFailedApplyFix,generationFailedBaseUrlUpdated}\`

## Design trade-offs

- 新增 \`diagnoseGenerateFailure\` 而非扩展 \`diagnose()\` —— connection-test
传 \`ErrorCode\`，generate 传 \`{status, message, wire, ...}\`，重载会很别扭
- status 提取：先读 \`err.upstream_status\`，fallback 到 message regex ——
Electron IPC 在某些版本会剥掉 custom Error props
- 404 auto-fix 按钮只对 missing-\`/v1\` 实现，其它 hypothesis
只有提示文本（updateKey/switchWire/addCredits 需要用户判断）

## Test plan

- [x] 10 new tests in \`diagnostics.test.ts\`（25/25 pass）
- [x] 870/870 desktop tests green
- [x] \`pnpm typecheck\` + \`pnpm lint\` clean

## Follow-up

- 403 \"Your request was blocked\" / Cloudflare ray id 的
\`gatewayWafBlocked\` 分支（issue #124 专用）将在后续 commit 追加
- 其它 hypothesis 的 auto-fix 按钮（如 switchWire one-click）

Closes #130
Refs #124, #134, #158

---------

Signed-off-by: hqhq1025 <1506751656@qq.com>

Author: hqhq1025

.changeset/generate-failure-diagnose-bridge.md

@@ -0,0 +1,12 @@
+---
+'@open-codesign/desktop': patch
+'@open-codesign/shared': minor
+'@open-codesign/i18n': patch
+---
+
+feat(diagnostics): bridge generate failures to diagnose() hypotheses (#130)
+
+- Main process `codesign:v1:generate` catch block now tags the thrown error with `upstream_status` / `upstream_provider` / `upstream_baseurl` / `upstream_wire` so the renderer can reason about the failure without re-parsing `err.message`.
+- New `diagnoseGenerateFailure()` in `@open-codesign/shared` maps generate-time failures to the same `DiagnosticHypothesis` shape the connection-test path already uses: 404 / "404 page not found" → missing `/v1`; 5xx with "not implemented" or "page not found" body → gateway does not implement the provider API; 400 with "instructions" body → openai-responses wire misconfigured; 401/403/429 reuse existing hypotheses.
+- Renderer `applyGenerateError` now appends the most-likely-cause sentence to the failure toast description and, for the missing-`/v1` case, surfaces an "Apply fix" action that updates the provider's baseUrl via `config:v1:update-provider` — addressing the Win11 relay-gateway failure in #130 with a one-click fix rather than a dead-end error message.
+- Adds new i18n cause keys (`gatewayIncompatible`, `openaiResponsesMisconfigured`, `serverError`) and fix keys (`switchWire`) in en + zh-CN.

apps/desktop/src/main/index.ts

@@ -160,6 +160,35 @@ function createWindow(): void {
 
 type Database = BetterSqlite3.Database;
 
+/**
+ * Pull an HTTP status code out of a caught provider error. Mirrors
+ * `packages/providers/src/retry.ts::extractStatus` intentionally — we don't
+ * import from retry.ts to avoid coupling main to a retry-internal helper
+ * that might get reshaped. Used by the generate catch block to tag the
+ * thrown err with `upstream_status` so the renderer's diagnose pipeline
+ * can pick up a hypothesis.
+ */
+function extractUpstreamHttpStatus(err: unknown): number | undefined {
+  if (typeof err !== 'object' || err === null) return undefined;
+  const candidates: unknown[] = [
+    (err as { status?: unknown }).status,
+    (err as { statusCode?: unknown }).statusCode,
+    (err as { upstream_status?: unknown }).upstream_status,
+    (err as { response?: { status?: unknown } }).response?.status,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'number' && Number.isFinite(c) && c >= 100 && c < 600) return c;
+  }
+  if (err instanceof Error) {
+    const m = /\b(\d{3})\b/.exec(err.message);
+    if (m?.[1]) {
+      const n = Number(m[1]);
+      if (n >= 400 && n < 600) return n;
+    }
+  }
+  return undefined;
+}
+
 function resolveActiveApiKeyFromState(providerId: string): Promise<string> {
   return resolveActiveApiKey(providerId, {
     getCodexAccessToken: () => getCodexTokenStore().getValidAccessToken(),
@@ -686,12 +715,35 @@ function registerIpcHandlers(db: Database | null): void {
         });
         return result;
       } catch (err) {
+        // Attach upstream metadata to the thrown err so the renderer's
+        // diagnostic pipeline (store.ts::applyGenerateError →
+        // diagnoseGenerateFailure) can map this failure to a "most likely
+        // cause + suggested fix" hypothesis. Without this, renderer only
+        // sees err.message + err.code and cannot offer actionable hints
+        // (e.g. the #130 404-page-not-found case that needs /v1 appended).
+        const upstreamStatus = extractUpstreamHttpStatus(err);
+        if (err !== null && typeof err === 'object') {
+          const errAsRec = err as Record<string, unknown>;
+          if (upstreamStatus !== undefined && errAsRec['upstream_status'] === undefined) {
+            errAsRec['upstream_status'] = upstreamStatus;
+          }
+          if (errAsRec['upstream_provider'] === undefined) {
+            errAsRec['upstream_provider'] = active.model.provider;
+          }
+          if (errAsRec['upstream_baseurl'] === undefined && baseUrl !== undefined) {
+            errAsRec['upstream_baseurl'] = baseUrl;
+          }
+          if (errAsRec['upstream_wire'] === undefined && active.wire !== undefined) {
+            errAsRec['upstream_wire'] = active.wire;
+          }
+        }
         logIpc.error('generate.fail', {
           generationId: id,
           ms: Date.now() - t0,
           provider: active.model.provider,
           modelId: active.model.modelId,
           baseUrl: baseUrl ?? '<default>',
+          status: upstreamStatus,
           message: err instanceof Error ? err.message : String(err),
           code: err instanceof CodesignError ? err.code : undefined,
         });

apps/desktop/src/renderer/src/store.generateFixApply.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { applyGenerateBaseUrlFix, useCodesignStore } from './store';
+
+const initialState = useCodesignStore.getState();
+
+function resetStore(): void {
+  useCodesignStore.setState({ ...initialState, toasts: [], reportableErrors: [] });
+}
+
+function installWindow(updateProvider: unknown): void {
+  (globalThis as unknown as { window: { codesign: unknown } }).window = {
+    codesign: updateProvider === undefined ? {} : { config: { updateProvider } },
+  };
+}
+
+beforeEach(() => {
+  resetStore();
+});
+
+afterEach(() => {
+  (globalThis as unknown as { window?: unknown }).window = undefined;
+  vi.restoreAllMocks();
+});
+
+describe('applyGenerateBaseUrlFix — silent-fallback regressions for #130', () => {
+  it('emits a success toast when IPC updates the provider', async () => {
+    const next = { ...(initialState.config ?? { schemaVersion: 3 }) } as unknown;
+    const updateProvider = vi.fn().mockResolvedValue(next);
+    installWindow(updateProvider);
+
+    const { getState, setState } = useCodesignStore;
+    await applyGenerateBaseUrlFix(getState, setState, 'openai-compat', 'https://host/v1');
+
+    expect(updateProvider).toHaveBeenCalledWith({
+      id: 'openai-compat',
+      baseUrl: 'https://host/v1',
+    });
+    const toasts = useCodesignStore.getState().toasts;
+    expect(toasts).toHaveLength(1);
+    expect(toasts[0]?.variant).toBe('success');
+  });
+
+  it('surfaces an error toast when IPC throws — never silent', async () => {
+    const updateProvider = vi.fn().mockRejectedValue(new Error('ENOENT config.toml'));
+    installWindow(updateProvider);
+
+    const { getState, setState } = useCodesignStore;
+    await applyGenerateBaseUrlFix(getState, setState, 'openai-compat', 'https://host/v1');
+
+    const toasts = useCodesignStore.getState().toasts;
+    expect(toasts).toHaveLength(1);
+    expect(toasts[0]?.variant).toBe('error');
+    expect(toasts[0]?.description).toContain('ENOENT config.toml');
+    // Must also be reportable so users can file it.
+    expect(useCodesignStore.getState().reportableErrors).toHaveLength(1);
+    expect(useCodesignStore.getState().reportableErrors[0]?.code).toBe('GENERATE_FIX_APPLY_FAILED');
+  });
+
+  it('surfaces an "unavailable" toast when updateProvider IPC is missing — not silent', async () => {
+    installWindow(undefined);
+
+    const { getState, setState } = useCodesignStore;
+    await applyGenerateBaseUrlFix(getState, setState, 'openai-compat', 'https://host/v1');
+
+    const toasts = useCodesignStore.getState().toasts;
+    expect(toasts).toHaveLength(1);
+    expect(toasts[0]?.variant).toBe('error');
+    expect(useCodesignStore.getState().reportableErrors).toHaveLength(1);
+    expect(useCodesignStore.getState().reportableErrors[0]?.code).toBe(
+      'GENERATE_FIX_APPLY_UNAVAILABLE',
+    );
+  });
+});

apps/desktop/src/renderer/src/store.ts

@@ -10,6 +10,7 @@ import type {
   CommentScope,
   Design,
   DiagnosticEventRow,
+  DiagnosticHypothesis,
   LocalInputFile,
   ModelRef,
   OnboardingState,
@@ -18,6 +19,7 @@ import type {
   ReportableError,
   SelectedElement,
 } from '@open-codesign/shared';
+import { diagnoseGenerateFailure } from '@open-codesign/shared';
 import { computeFingerprint } from '@open-codesign/shared/fingerprint';
 import { create } from 'zustand';
 import type { StoreApi } from 'zustand';
@@ -974,6 +976,41 @@ export function extractUpstreamContext(err: unknown): Record<string, unknown> |
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
+/**
+ * Pull an HTTP status code off a caught generate error. Looks at the
+ * `upstream_status` field main/index.ts attaches first, then falls back to
+ * common SDK locations, and finally regex-scans `err.message` for the
+ * #130-style "404 page not found" text that arrives with no structured status.
+ */
+export function extractGenerateStatus(err: unknown): number | undefined {
+  if (err === null || typeof err !== 'object') return undefined;
+  const rec = err as Record<string, unknown>;
+  const candidates: unknown[] = [
+    rec['upstream_status'],
+    rec['status'],
+    rec['statusCode'],
+    (rec['response'] as { status?: unknown } | undefined)?.status,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'number' && Number.isFinite(c) && c >= 100 && c < 600) return c;
+  }
+  if (err instanceof Error) {
+    const m = /\b([45]\d{2})\b/.exec(err.message);
+    if (m?.[1]) return Number(m[1]);
+  }
+  return undefined;
+}
+
+/**
+ * Pick an upstream-* string field off an err, guarding the "wrong type"
+ * and "empty string" cases so callers can use `?? fallback`.
+ */
+function pickUpstreamString(err: unknown, key: string): string | undefined {
+  if (err === null || typeof err !== 'object') return undefined;
+  const v = (err as Record<string, unknown>)[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
 function applyGenerateError(
   get: GetState,
   set: SetState,
@@ -1009,10 +1046,21 @@ function applyGenerateError(
   }
   const code = extractCodesignErrorCode(err) ?? 'GENERATION_FAILED';
   const upstream = extractUpstreamContext(err);
+
+  // Bridge the failure into the connection-test diagnostics system so the
+  // toast tells the user WHY and WHAT TO TRY instead of just dumping the
+  // upstream message. Fixes #130 (404 → "add /v1") and gives #158 / #134 a
+  // home for gateway / instructions-required hints.
+  const cfg = get().config;
+  const hypothesis = deriveGenerateHypothesis(err, cfg);
+  const description = buildGenerateErrorDescription(msg, hypothesis);
+  const action = buildGenerateFixAction(get, set, hypothesis, err, cfg);
+
   get().pushToast({
     variant: 'error',
     title: tr('notifications.generationFailed'),
-    description: msg,
+    description,
+    ...(action !== undefined ? { action } : {}),
     localId: get().createReportableError({
       code,
       scope: 'generate',
@@ -1024,6 +1072,113 @@ function applyGenerateError(
   });
 }
 
+function deriveGenerateHypothesis(
+  err: unknown,
+  cfg: OnboardingState | null,
+): DiagnosticHypothesis | undefined {
+  const provider = pickUpstreamString(err, 'upstream_provider') ?? cfg?.provider ?? 'unknown';
+  const baseUrl = pickUpstreamString(err, 'upstream_baseurl') ?? cfg?.baseUrl ?? undefined;
+  const wire = pickUpstreamString(err, 'upstream_wire');
+  const status = extractGenerateStatus(err);
+  const message = err instanceof Error ? err.message : undefined;
+  const ctx = {
+    provider,
+    ...(baseUrl !== undefined && baseUrl !== null ? { baseUrl } : {}),
+    ...(wire !== undefined ? { wire } : {}),
+    ...(status !== undefined ? { status } : {}),
+    ...(message !== undefined ? { message } : {}),
+  };
+  const hypotheses = diagnoseGenerateFailure(ctx);
+  const primary = hypotheses[0];
+  // Skip the bare "unknown" hypothesis — appending "Unknown error" to a
+  // toast that already shows the upstream message is just noise.
+  if (primary === undefined || primary.cause === 'diagnostics.cause.unknown') {
+    return undefined;
+  }
+  return primary;
+}
+
+function buildGenerateErrorDescription(
+  originalMessage: string,
+  hypothesis: DiagnosticHypothesis | undefined,
+): string {
+  if (hypothesis === undefined) return originalMessage;
+  const hint = tr(hypothesis.cause);
+  // When the i18n key was missing, tr() falls back to returning the key
+  // itself; don't double up "diagnostics.cause.x" in the toast.
+  if (hint === hypothesis.cause) return originalMessage;
+  return `${originalMessage}\n\n${tr('diagnostics.mostLikelyCause')} ${hint}`;
+}
+
+function buildGenerateFixAction(
+  get: GetState,
+  set: SetState,
+  hypothesis: DiagnosticHypothesis | undefined,
+  err: unknown,
+  cfg: OnboardingState | null,
+): Toast['action'] | undefined {
+  const fix = hypothesis?.suggestedFix;
+  if (fix === undefined) return undefined;
+  if (fix.baseUrlTransform === undefined) return undefined;
+  const providerId = pickUpstreamString(err, 'upstream_provider') ?? cfg?.provider;
+  const baseUrl = pickUpstreamString(err, 'upstream_baseurl') ?? cfg?.baseUrl ?? null;
+  if (
+    providerId === undefined ||
+    providerId === null ||
+    baseUrl === null ||
+    !/^https?:\/\/\S+/i.test(baseUrl.trim())
+  ) {
+    return undefined;
+  }
+  const nextBaseUrl = fix.baseUrlTransform(baseUrl);
+  if (nextBaseUrl === baseUrl) return undefined;
+  return {
+    label: tr('notifications.generationFailedApplyFix'),
+    onClick: () => {
+      void applyGenerateBaseUrlFix(get, set, providerId, nextBaseUrl);
+    },
+  };
+}
+
+export async function applyGenerateBaseUrlFix(
+  get: GetState,
+  set: SetState,
+  providerId: string,
+  nextBaseUrl: string,
+): Promise<void> {
+  const api = window.codesign?.config?.updateProvider;
+  // Don't silently swallow "this app version lacks the IPC" — surface it as a
+  // reportable error so users know why the Apply-fix button did nothing and
+  // can fall back to editing baseUrl manually in Settings.
+  if (api === undefined) {
+    get().reportableErrorToast({
+      code: 'GENERATE_FIX_APPLY_UNAVAILABLE',
+      scope: 'generate',
+      title: tr('notifications.generationFailedFixUnavailable'),
+      description: tr('notifications.generationFailedFixUnavailableDescription'),
+    });
+    return;
+  }
+  try {
+    const next = await api({ id: providerId, baseUrl: nextBaseUrl });
+    set({ config: next });
+    get().pushToast({
+      variant: 'success',
+      title: tr('notifications.generationFailedBaseUrlUpdated'),
+    });
+  } catch (updateErr) {
+    get().reportableErrorToast({
+      code: 'GENERATE_FIX_APPLY_FAILED',
+      scope: 'generate',
+      title: tr('notifications.generationFailedFixApplyFailed'),
+      description: updateErr instanceof Error ? updateErr.message : String(updateErr),
+      ...(updateErr instanceof Error && updateErr.stack !== undefined
+        ? { stack: updateErr.stack }
+        : {}),
+    });
+  }
+}
+
 function advanceStageIfCurrent(
   get: GetState,
   set: SetState,

packages/i18n/src/locales/en.json

@@ -558,6 +558,11 @@
     "designSystemCleared": "Design system cleared",
     "clearDesignSystemFailed": "Unable to clear design system",
     "generationFailed": "Generation failed",
+    "generationFailedApplyFix": "Apply fix",
+    "generationFailedBaseUrlUpdated": "Base URL updated. Try the request again.",
+    "generationFailedFixUnavailable": "Auto-fix unavailable",
+    "generationFailedFixUnavailableDescription": "This app version can't apply the fix automatically. Please edit the Base URL manually in Settings.",
+    "generationFailedFixApplyFailed": "Could not apply fix",
     "cancellationFailed": "Cancellation failed",
     "inlineCommentFailed": "Inline comment failed",
     "commentNeedsSnapshot": "Generate a design first before leaving a comment",
@@ -778,6 +783,9 @@
       "timedOut": "Request timed out — check firewall or VPN.",
       "corsError": "CORS error (should not happen in main process). This is a bug.",
       "sslError": "SSL / certificate error (self-signed cert on relay?).",
+      "gatewayIncompatible": "The gateway accepted the connection but does not implement this provider's API. Try switching wire (e.g. openai-chat).",
+      "openaiResponsesMisconfigured": "The endpoint rejected the request shape. The wire may be wrong — try switching to openai-chat.",
+      "serverError": "Upstream server error. May be transient — try again.",
       "unknown": "Unknown error — check the full log for details."
     },
     "fix": {
@@ -789,7 +797,8 @@
       "checkNetwork": "Check network / VPN",
       "checkVpn": "Check VPN / firewall",
       "reportBug": "Report this bug",
-      "disableTls": "Disable TLS verify"
+      "disableTls": "Disable TLS verify",
+      "switchWire": "Switch wire in Settings"
     },
     "applyFix": "Apply this fix",
     "setBaseUrlFirst": "Set a Base URL first",