fix(desktop): degrade-probe test connection when /models is unavailable on OpenAI-compat endpoints (#179)

Some OpenAI-compatible gateways (Zhipu GLM at /api/paas/v4 is the
reported case, but any proxy that omits a public /models endpoint fits)
return HTTP 404 for GET /models even though /chat/completions works
fine. The "Test connection" button was reporting a hard 404 failure for
those providers and the diagnostics panel was suggesting "add /v1",
which would corrupt a correct baseUrl.

Two changes:

1. runProviderTest now falls back to POST /chat/completions with a
   minimal probe request when GET /models returns 404 on openai-chat or
   openai-responses wires. Any 2xx or API-originated 4xx (400/402/422/
   429) counts as "endpoint reachable". 401/403 is surfaced as an auth
   error instead of the misleading 404 hint. Anthropic wires do not
   degrade — /v1/models is standard there. Success now carries a
   probeMethod field so the renderer can distinguish a full pass from
   a degraded pass.

2. diagnose() in @open-codesign/shared skips the missingV1 hypothesis
   when the baseUrl already carries a /v\d+ segment (GLM /v4, AI Studio
   /v1beta, Cloudflare Workers AI /v1, ...) and returns the generic
   unknown cause instead, so users are never pushed into duplicating
   version segments.

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

Author: hqhq1025

apps/desktop/src/main/connection-ipc.test.ts

@@ -18,6 +18,7 @@ import {
   getCacheKey,
   normalizeBaseUrl,
   normalizeOllamaBaseUrl,
+  runProviderTest,
 } from './connection-ipc';
 
 // ---------------------------------------------------------------------------
@@ -840,3 +841,193 @@ describe('normalizeOllamaBaseUrl', () => {
     expect(() => normalizeOllamaBaseUrl('http://')).toThrow(/not a valid URL/);
   });
 });
+
+// ---------------------------------------------------------------------------
+// runProviderTest — degrade-probe when /models 404s on OpenAI-compat endpoints
+// (regression for Zhipu GLM and similar gateways that don't expose /models).
+// ---------------------------------------------------------------------------
+
+interface FakeFetchCall {
+  url: string;
+  method: string;
+  body: string | undefined;
+}
+
+function installFakeFetch(
+  handler: (url: string, init: RequestInit) => { status: number; body?: unknown },
+): { calls: FakeFetchCall[]; restore: () => void } {
+  const calls: FakeFetchCall[] = [];
+  const originalFetch = globalThis.fetch;
+  const fake = (async (url: string, init: RequestInit = {}) => {
+    calls.push({
+      url,
+      method: typeof init.method === 'string' ? init.method : 'GET',
+      body: typeof init.body === 'string' ? init.body : undefined,
+    });
+    const { status, body } = handler(url, init);
+    return new Response(body === undefined ? null : JSON.stringify(body), {
+      status,
+      headers: { 'content-type': 'application/json' },
+    });
+  }) as unknown as typeof fetch;
+  (globalThis as { fetch: typeof fetch }).fetch = fake;
+  return {
+    calls,
+    restore: () => {
+      (globalThis as { fetch: typeof fetch }).fetch = originalFetch;
+    },
+  };
+}
+
+describe('runProviderTest degrade-probe (issue #179)', () => {
+  beforeEach(() => {
+    // Use real timers so fetchWithTimeout's AbortController doesn't get stuck
+    // behind vi.useFakeTimers() from the outer beforeEach.
+    vi.useRealTimers();
+  });
+
+  it('openai-chat: /models 404 but /chat/completions 200 → ok, probeMethod=chat_completion_degraded (GLM case)', async () => {
+    const { calls, restore } = installFakeFetch((url) => {
+      if (url.endsWith('/models')) return { status: 404, body: { error: 'not found' } };
+      if (url.endsWith('/chat/completions')) return { status: 200, body: { id: 'probe-response' } };
+      return { status: 500 };
+    });
+    try {
+      const res = await runProviderTest({
+        provider: 'glm',
+        wire: 'openai-chat',
+        apiKey: 'sk-glm-test',
+        baseUrl: 'https://open.bigmodel.cn/api/paas/v4',
+      });
+      expect(res.ok).toBe(true);
+      if (res.ok) expect(res.probeMethod).toBe('chat_completion_degraded');
+      expect(calls).toHaveLength(2);
+      expect(calls[0]?.url).toMatch(/\/models$/);
+      expect(calls[1]?.url).toMatch(/\/chat\/completions$/);
+      expect(calls[1]?.method).toBe('POST');
+      expect(calls[1]?.body).toBeTruthy();
+      const body = JSON.parse(calls[1]?.body ?? '{}');
+      expect(body.max_tokens).toBe(1);
+      expect(body.stream).toBe(false);
+      expect(Array.isArray(body.messages)).toBe(true);
+    } finally {
+      restore();
+    }
+  });
+
+  it('openai-chat: /models 404 and /chat/completions also 404 → preserves original 404', async () => {
+    const { restore } = installFakeFetch(() => ({ status: 404 }));
+    try {
+      const res = await runProviderTest({
+        provider: 'broken-gateway',
+        wire: 'openai-chat',
+        apiKey: 'sk-test',
+        baseUrl: 'https://broken.example.com/v1',
+      });
+      expect(res.ok).toBe(false);
+      if (!res.ok) {
+        expect(res.code).toBe('404');
+        expect(res.message).toBe('HTTP 404');
+      }
+    } finally {
+      restore();
+    }
+  });
+
+  it('openai-chat: /models 404 + /chat/completions 400 (model_unknown) → still pass (endpoint alive)', async () => {
+    const { restore } = installFakeFetch((url) => {
+      if (url.endsWith('/models')) return { status: 404 };
+      return { status: 400, body: { error: { message: 'model_not_found' } } };
+    });
+    try {
+      const res = await runProviderTest({
+        provider: 'glm',
+        wire: 'openai-chat',
+        apiKey: 'sk-glm-test',
+        baseUrl: 'https://open.bigmodel.cn/api/paas/v4',
+      });
+      expect(res.ok).toBe(true);
+      if (res.ok) expect(res.probeMethod).toBe('chat_completion_degraded');
+    } finally {
+      restore();
+    }
+  });
+
+  it('openai-chat: /models 404 + /chat/completions 401 → surface auth error, not 404', async () => {
+    const { restore } = installFakeFetch((url) => {
+      if (url.endsWith('/models')) return { status: 404 };
+      return { status: 401 };
+    });
+    try {
+      const res = await runProviderTest({
+        provider: 'glm',
+        wire: 'openai-chat',
+        apiKey: 'wrong-key',
+        baseUrl: 'https://open.bigmodel.cn/api/paas/v4',
+      });
+      expect(res.ok).toBe(false);
+      if (!res.ok) {
+        expect(res.code).toBe('401');
+        expect(res.message).toBe('HTTP 401');
+      }
+    } finally {
+      restore();
+    }
+  });
+
+  it('openai-chat: /models 200 → no degrade probe, probeMethod=models', async () => {
+    const { calls, restore } = installFakeFetch(() => ({ status: 200, body: { data: [] } }));
+    try {
+      const res = await runProviderTest({
+        provider: 'openai',
+        wire: 'openai-chat',
+        apiKey: 'sk-test',
+        baseUrl: 'https://api.openai.com/v1',
+      });
+      expect(res.ok).toBe(true);
+      if (res.ok) expect(res.probeMethod).toBe('models');
+      expect(calls).toHaveLength(1);
+      expect(calls[0]?.method).toBe('GET');
+    } finally {
+      restore();
+    }
+  });
+
+  it('anthropic: /models 404 does NOT degrade (standard endpoint must stay authoritative)', async () => {
+    const { calls, restore } = installFakeFetch(() => ({ status: 404 }));
+    try {
+      const res = await runProviderTest({
+        provider: 'anthropic-like',
+        wire: 'anthropic',
+        apiKey: 'sk-ant-test',
+        baseUrl: 'https://api.anthropic.com',
+      });
+      expect(res.ok).toBe(false);
+      if (!res.ok) expect(res.code).toBe('404');
+      // Only /v1/models should have been probed — no /v1/messages degrade.
+      expect(calls).toHaveLength(1);
+      expect(calls[0]?.url).toMatch(/\/v1\/models$/);
+    } finally {
+      restore();
+    }
+  });
+
+  it('openai-responses: /models 404 + /chat/completions 2xx → degrade pass', async () => {
+    const { restore } = installFakeFetch((url) => {
+      if (url.endsWith('/models')) return { status: 404 };
+      return { status: 200, body: { ok: true } };
+    });
+    try {
+      const res = await runProviderTest({
+        provider: 'responses-gateway',
+        wire: 'openai-responses',
+        apiKey: 'sk-test',
+        baseUrl: 'https://gateway.example.com/v1',
+      });
+      expect(res.ok).toBe(true);
+      if (res.ok) expect(res.probeMethod).toBe('chat_completion_degraded');
+    } finally {
+      restore();
+    }
+  });
+});

apps/desktop/src/main/connection-ipc.ts

@@ -39,6 +39,14 @@ interface ModelsListPayloadV1 {
 
 export interface ConnectionTestResult {
   ok: true;
+  /**
+   * `models` when the standard GET /models probe succeeded.
+   * `chat_completion_degraded` when /models 404'd but POST /chat/completions
+   * proved the endpoint is alive (e.g. Zhipu GLM's gateway — no public /models
+   * but /chat/completions works fine). The renderer surfaces this so users
+   * know /models is unavailable even though generation will work.
+   */
+  probeMethod?: 'models' | 'chat_completion_degraded';
 }
 
 export interface ConnectionTestError {
@@ -345,7 +353,7 @@ export function _getModelsCache(): Map<string, CacheEntry> {
 // IPC registration
 // ---------------------------------------------------------------------------
 
-interface ActiveProviderCredentials {
+export interface ActiveProviderCredentials {
   provider: string;
   wire: WireApi;
   apiKey: string;
@@ -446,7 +454,9 @@ async function testChatGPTCodexOAuth(): Promise<ConnectionTestResponse> {
   return { ok: true };
 }
 
-async function runProviderTest(creds: ActiveProviderCredentials): Promise<ConnectionTestResponse> {
+export async function runProviderTest(
+  creds: ActiveProviderCredentials,
+): Promise<ConnectionTestResponse> {
   // ChatGPT subscription uses OAuth + ChatGPT-Account-Id headers; its host
   // has no `/models` endpoint that a generic Bearer probe can reach. A plain
   // HTTP probe would return 401 here and render as the misleading "API key
@@ -456,7 +466,7 @@ async function runProviderTest(creds: ActiveProviderCredentials): Promise<Connec
     return testChatGPTCodexOAuth();
   }
 
-  const { url } = buildEndpointForWire(creds.wire, creds.baseUrl);
+  const { url, normalizedBaseUrl } = buildEndpointForWire(creds.wire, creds.baseUrl);
   const headers = buildAuthHeadersForWire(
     creds.wire,
     creds.apiKey,
@@ -477,10 +487,69 @@ async function runProviderTest(creds: ActiveProviderCredentials): Promise<Connec
     };
   }
   if (!res.ok) {
+    // Some OpenAI-compatible gateways (Zhipu GLM, a handful of self-hosted
+    // proxies) don't expose /models but their /chat/completions works fine.
+    // If the primary probe 404s on those wires, degrade-probe with a tiny
+    // chat request before declaring the endpoint dead. We intentionally do
+    // not degrade anthropic — its /v1/models is standard, and skipping it
+    // would mask real path-shape mistakes.
+    if (res.status === 404 && (creds.wire === 'openai-chat' || creds.wire === 'openai-responses')) {
+      const probe = await probeChatCompletion(normalizedBaseUrl, headers);
+      if (probe.kind === 'pass') {
+        return { ok: true, probeMethod: 'chat_completion_degraded' };
+      }
+      if (probe.kind === 'http' && probe.status !== 404) {
+        const { code, hint } = classifyHttpError(probe.status);
+        return { ok: false, code, message: `HTTP ${probe.status}`, hint };
+      }
+      // /chat/completions also 404'd (or the network dropped) — fall through
+      // and report the original /models 404.
+    }
     const { code, hint } = classifyHttpError(res.status);
     return { ok: false, code, message: `HTTP ${res.status}`, hint };
   }
-  return { ok: true };
+  return { ok: true, probeMethod: 'models' };
+}
+
+type ProbeResult =
+  | { kind: 'pass' }
+  | { kind: 'http'; status: number }
+  | { kind: 'network'; message: string };
+
+/**
+ * POST a minimal chat-completion request to verify the endpoint is alive
+ * when GET /models returned 404. A 2xx response or any API-originated 4xx
+ * (400 model_unknown, 402 insufficient credits, 422, 429 — and 401/403 too,
+ * which we surface as an auth error instead of the misleading 404 hint)
+ * counts as "endpoint reachable". Only 404 and 5xx count as a real failure.
+ */
+async function probeChatCompletion(
+  normalizedBaseUrl: string,
+  headers: Record<string, string>,
+): Promise<ProbeResult> {
+  const url = `${normalizedBaseUrl}/chat/completions`;
+  let res: Response;
+  try {
+    res = await fetchWithTimeout(url, {
+      method: 'POST',
+      headers: { ...headers, 'content-type': 'application/json' },
+      body: JSON.stringify({
+        model: 'probe',
+        messages: [{ role: 'user', content: 'ping' }],
+        max_tokens: 1,
+        stream: false,
+      }),
+    });
+  } catch (err) {
+    return { kind: 'network', message: err instanceof Error ? err.message : String(err) };
+  }
+  if (res.ok) return { kind: 'pass' };
+  if (res.status === 404 || res.status >= 500) return { kind: 'http', status: res.status };
+  // 401/403 — endpoint alive but auth rejected; surface as auth error so the
+  // diagnostics panel shows the key-invalid hint instead of the 404 one.
+  if (res.status === 401 || res.status === 403) return { kind: 'http', status: res.status };
+  // 400/402/422/429 etc. — endpoint alive, request-level rejection.
+  return { kind: 'pass' };
 }
 
 export function registerConnectionIpc(): void {

packages/shared/src/diagnostics.test.ts

@@ -54,10 +54,40 @@ describe('diagnose', () => {
     expect(fix?.baseUrlTransform?.('https://api.example.com')).toBe('https://api.example.com/v1');
   });
 
-  it('404 transform is idempotent when /v1 already present', () => {
-    const result = diagnose('404', { ...baseCtx, baseUrl: 'https://api.example.com/v1' });
-    const transform = result[0]?.suggestedFix?.baseUrlTransform;
-    expect(transform?.('https://api.example.com/v1')).toBe('https://api.example.com/v1');
+  // Regression: Zhipu GLM (issue #179) — baseUrl is /api/paas/v4, /models 404
+  // is because GLM does not expose /models, NOT because /v1 is missing.
+  // Auto-suggesting "add /v1" would corrupt a correct baseUrl.
+  it('404 skips missingV1 when baseUrl already has /v4 (GLM)', () => {
+    const result = diagnose('404', {
+      ...baseCtx,
+      baseUrl: 'https://open.bigmodel.cn/api/paas/v4',
+    });
+    expect(result[0]?.cause).toBe('diagnostics.cause.unknown');
+    expect(result[0]?.suggestedFix).toBeUndefined();
+  });
+
+  it('404 skips missingV1 when baseUrl already has /v1 (e.g. Cloudflare Workers AI)', () => {
+    const result = diagnose('404', {
+      ...baseCtx,
+      baseUrl: 'https://gateway.ai.cloudflare.com/v1/account/foo/openai',
+    });
+    expect(result[0]?.cause).toBe('diagnostics.cause.unknown');
+    expect(result[0]?.suggestedFix).toBeUndefined();
+  });
+
+  it('404 skips missingV1 when baseUrl already has /v1beta (AI Studio)', () => {
+    const result = diagnose('404', {
+      ...baseCtx,
+      baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai',
+    });
+    expect(result[0]?.cause).toBe('diagnostics.cause.unknown');
+    expect(result[0]?.suggestedFix).toBeUndefined();
+  });
+
+  it('404 still suggests missingV1 when baseUrl has NO version segment', () => {
+    const result = diagnose('404', { ...baseCtx, baseUrl: 'https://api.example.com' });
+    expect(result[0]?.cause).toBe('diagnostics.cause.missingV1');
+    expect(result[0]?.suggestedFix?.label).toBe('diagnostics.fix.addV1');
   });
 
   it('maps 429 to rateLimit with waitAndRetry fix', () => {

packages/shared/src/diagnostics.ts

@@ -81,6 +81,16 @@ export function diagnose(code: ErrorCode, ctx: DiagnoseContext): DiagnosticHypot
   }
 
   if (normalised === '404') {
+    // If the baseUrl already encodes a version segment (/v1, /v4, /v1beta,
+    // etc.), suggesting "add /v1" is wrong — Zhipu GLM uses /v4, AI Studio
+    // uses /v1beta, and some Cloudflare Workers AI gateways already carry
+    // /v1. A 404 on such endpoints usually means /models simply isn't
+    // exposed, not that the path is malformed. Fall back to the generic
+    // hypothesis so the user isn't pushed into corrupting a correct baseUrl.
+    const hasVersionSegment = /\/v\d+[a-z]*(?:\/|$)/i.test(ctx.baseUrl);
+    if (hasVersionSegment) {
+      return [{ cause: 'diagnostics.cause.unknown' }];
+    }
     return [
       {
         cause: 'diagnostics.cause.missingV1',