feat(settings): auto-detect running CLIProxyAPI and show import banner

When the Models tab mounts, probes http://127.0.0.1:8317/v1/models via
the existing testEndpoint IPC bridge (anthropic wire, no key). If CPA is
running and no provider already points at localhost:8317, a
LocalCpaImportCard banner is shown above the provider list.

- Detection runs once per mount (guarded by 'idle' sentinel state).
- Skipped entirely if any existing provider row has a baseUrl matching
  /^https?://(localhost|127.0.0.1):8317/ — avoids spam after import.
- "Import" opens AddCustomProviderModal pre-filled with the CPA preset
  (same handler as the Add Provider menu item) and immediately hides the
  banner.
- "Dismiss" writes cpa-detection-dismissed-v1=1 to localStorage so the
  banner never reappears for this install.
- Detection failures are silently swallowed — best-effort enhancement.
- New i18n keys under settings.providers.cpaDetection.* (en + zh-CN).
- Changeset: patch bump for desktop + i18n.

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

Author: hqhq1025

.changeset/cpa-autodetect.md

@@ -0,0 +1,8 @@
+---
+'@open-codesign/desktop': patch
+'@open-codesign/i18n': patch
+---
+
+feat(settings): auto-detect running CLIProxyAPI and show import banner
+
+When the Models tab mounts, probes `http://127.0.0.1:8317/v1/models` via the existing `testEndpoint` IPC bridge. If CLIProxyAPI is running and no provider is already configured at that address, displays a `LocalCpaImportCard` banner above the provider list offering one-click import into `AddCustomProviderModal`. The banner is dismissible and the preference persists to `localStorage` via key `cpa-detection-dismissed-v1`.

apps/desktop/src/renderer/src/components/AddCustomProviderModal.tsx

@@ -110,27 +110,27 @@ export function AddCustomProviderModal({
   const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const discoverySeq = useRef(0);
 
-  function scheduleDiscovery(currentBaseUrl: string, currentWire: WireApi) {
+  function scheduleDiscovery(currentBaseUrl: string, currentApiKey: string, currentWire: WireApi) {
     if (debounceTimer.current !== null) clearTimeout(debounceTimer.current);
     if (!currentBaseUrl.trim().match(/^https?:\/\//)) {
       discoverySeq.current += 1;
       setDiscovery({ kind: 'idle' });
       return;
     }
     debounceTimer.current = setTimeout(() => {
-      void runDiscovery(currentBaseUrl, currentWire);
+      void runDiscovery(currentBaseUrl, currentApiKey, currentWire);
     }, 500);
   }
 
-  async function runDiscovery(currentBaseUrl: string, currentWire: WireApi) {
+  async function runDiscovery(currentBaseUrl: string, currentApiKey: string, currentWire: WireApi) {
     if (!window.codesign?.config) return;
     const seq = ++discoverySeq.current;
     setDiscovery({ kind: 'discovering' });
     try {
       const res = await window.codesign.config.testEndpoint({
         wire: currentWire,
         baseUrl: currentBaseUrl.trim(),
-        apiKey: '',
+        apiKey: currentApiKey.trim(),
       });
       if (seq !== discoverySeq.current) return;
       if (res.ok && res.models.length > 0) {
@@ -151,17 +151,18 @@ export function AddCustomProviderModal({
     setBaseUrl(v);
     if (wireAuto) setWire(detectWireFromBaseUrl(v));
     setTest({ kind: 'idle' });
-    scheduleDiscovery(v, wireAuto ? detectWireFromBaseUrl(v) : wire);
+    scheduleDiscovery(v, apiKey, wireAuto ? detectWireFromBaseUrl(v) : wire);
   }
 
   function handleApiKeyChange(v: string) {
     setApiKey(v);
+    scheduleDiscovery(baseUrl, v, wire);
   }
 
   function handleWireChange(v: WireApi) {
     setWire(v);
     setWireAuto(false);
-    scheduleDiscovery(baseUrl, v);
+    scheduleDiscovery(baseUrl, apiKey, v);
   }
 
   function handleModelSelect(v: string) {

apps/desktop/src/renderer/src/components/Settings.test.ts

@@ -34,3 +34,42 @@ describe('applyLocaleChange', () => {
     expect(result).toBe('zh-CN');
   });
 });
+
+describe('CPA detection regex', () => {
+  const CPA_REGEX = /^https?:\/\/(localhost|127\.0\.0\.1):8317/;
+
+  it('matches http://localhost:8317', () => {
+    expect('http://localhost:8317').toMatch(CPA_REGEX);
+  });
+
+  it('matches https://127.0.0.1:8317', () => {
+    expect('https://127.0.0.1:8317').toMatch(CPA_REGEX);
+  });
+
+  it('does not match other ports', () => {
+    expect('http://localhost:8080').not.toMatch(CPA_REGEX);
+    expect('https://example.com:8317').not.toMatch(CPA_REGEX);
+  });
+});
+
+describe('CPA detection localStorage dismissal', () => {
+  const KEY = 'cpa-detection-dismissed-v1';
+
+  it('reads and writes dismissal flag', () => {
+    const getItemSpy = vi.spyOn(Storage.prototype, 'getItem');
+    const setItemSpy = vi.spyOn(Storage.prototype, 'setItem');
+
+    // Check initial read
+    expect(window.localStorage.getItem(KEY)).toBeNull();
+
+    // Simulate user dismissal
+    window.localStorage.setItem(KEY, '1');
+    expect(setItemSpy).toHaveBeenCalledWith(KEY, '1');
+
+    // Verify we can read it back
+    expect(window.localStorage.getItem(KEY)).toBe('1');
+
+    getItemSpy.mockRestore();
+    setItemSpy.mockRestore();
+  });
+});

apps/desktop/src/renderer/src/components/Settings.tsx

@@ -22,6 +22,7 @@ import {
   RotateCcw,
   Sliders,
   Trash2,
+  Zap,
 } from 'lucide-react';
 import { useEffect, useRef, useState } from 'react';
 import type { AppPaths, Preferences, ProviderRow, StorageKind } from '../../../preload/index';
@@ -848,6 +849,47 @@ function WarningsList({ warnings }: { warnings: string[] }) {
   );
 }
 
+const CPA_DETECTION_DISMISSED_KEY = 'cpa-detection-dismissed-v1';
+
+function LocalCpaImportCard({
+  onImport,
+  onDismiss,
+}: {
+  onImport: () => void;
+  onDismiss: () => void;
+}) {
+  const t = useT();
+  return (
+    <div className="rounded-[var(--radius-md)] border border-[var(--color-accent)] bg-[var(--color-accent-tint)] px-[var(--space-3)] py-[var(--space-2_5)] flex items-start gap-[var(--space-3)]">
+      <Zap className="w-4 h-4 mt-0.5 shrink-0 text-[var(--color-accent)]" aria-hidden="true" />
+      <div className="flex-1 min-w-0">
+        <p className="text-[var(--text-sm)] font-medium text-[var(--color-text-primary)] leading-snug">
+          {t('settings.providers.cpaDetection.title')}
+        </p>
+        <p className="text-[var(--text-xs)] text-[var(--color-text-secondary)] mt-0.5 leading-[var(--leading-body)]">
+          {t('settings.providers.cpaDetection.body')}
+        </p>
+      </div>
+      <div className="flex items-center gap-[var(--space-1_5)] shrink-0">
+        <button
+          type="button"
+          onClick={onImport}
+          className="h-7 px-[var(--space-2_5)] rounded-[var(--radius-sm)] text-[var(--text-xs)] text-[var(--color-on-accent)] bg-[var(--color-accent)] hover:opacity-90 transition-opacity whitespace-nowrap"
+        >
+          {t('settings.providers.cpaDetection.importAction')}
+        </button>
+        <button
+          type="button"
+          onClick={onDismiss}
+          className="h-7 px-[var(--space-2)] rounded-[var(--radius-sm)] text-[var(--text-xs)] text-[var(--color-text-secondary)] hover:bg-[var(--color-surface-hover)] transition-colors whitespace-nowrap"
+        >
+          {t('settings.providers.cpaDetection.dismissAction')}
+        </button>
+      </div>
+    </div>
+  );
+}
+
 function ModelsTab() {
   const t = useT();
   const config = useCodesignStore((s) => s.config);
@@ -858,6 +900,9 @@ function ModelsTab() {
   const [loading, setLoading] = useState(true);
   const [showAddCustom, setShowAddCustom] = useState(false);
   const [showAddMenu, setShowAddMenu] = useState(false);
+  const [cpaDetection, setCpaDetection] = useState<
+    'idle' | 'detecting' | 'available' | 'unavailable'
+  >('idle');
   const [externalConfigs, setExternalConfigs] = useState<{
     codex?: { count: number } | undefined;
     claudeCode?:
@@ -986,6 +1031,44 @@ function ModelsTab() {
       });
   }, [pushToast, t]);
 
+  useEffect(() => {
+    if (!window.codesign?.config?.testEndpoint) return;
+    // Only probe once — once we've reached a terminal state, skip.
+    if (cpaDetection !== 'idle') return;
+    // Skip if user already dismissed this banner for this install.
+    try {
+      if (window.localStorage.getItem(CPA_DETECTION_DISMISSED_KEY) === '1') return;
+    } catch {
+      // localStorage unavailable — proceed with detection
+    }
+    // Skip detection if a provider is already pointing at the CPA port.
+    // We wait for the rows load to settle before probing so we don't flash
+    // the banner and immediately hide it on the next render tick.
+    if (loading) return;
+    const alreadyConfigured = rows.some((r) =>
+      /^https?:\/\/(localhost|127\.0\.0\.1):8317/.test(r.baseUrl ?? ''),
+    );
+    if (alreadyConfigured) return;
+
+    setCpaDetection('detecting');
+    void window.codesign.config
+      .testEndpoint({ wire: 'anthropic', baseUrl: 'http://127.0.0.1:8317', apiKey: '' })
+      .then((res) => {
+        setCpaDetection(res.ok ? 'available' : 'unavailable');
+      })
+      .catch((err) => {
+        reportableErrorToast({
+          code: 'CPA_DETECTION_FAILED',
+          scope: 'settings',
+          title: t('settings.imageGen.toast.loadFailed', {
+            defaultValue: 'Image generation settings failed to load',
+          }),
+          description: cleanIpcError(err) || t('settings.common.unknownError'),
+        });
+        setCpaDetection('unavailable');
+      });
+  }, [cpaDetection, loading, rows, pushToast, reportableErrorToast, t]);
+
   async function reloadRows() {
     if (!window.codesign) return;
     const [nextRows, state] = await Promise.all([
@@ -1305,6 +1388,28 @@ function ModelsTab() {
 
       <div className="space-y-[var(--space-3)]">
         <ChatgptLoginCard onStatusChange={reloadRows} />
+        {cpaDetection === 'available' && (
+          <LocalCpaImportCard
+            onImport={() => {
+              setCustomProviderPreset({
+                name: 'CLIProxyAPI',
+                baseUrl: 'http://127.0.0.1:8317',
+                wire: 'anthropic',
+                defaultModel: '',
+              });
+              setShowAddCustom(true);
+              setCpaDetection('unavailable');
+            }}
+            onDismiss={() => {
+              try {
+                window.localStorage.setItem(CPA_DETECTION_DISMISSED_KEY, '1');
+              } catch {
+                // non-fatal
+              }
+              setCpaDetection('unavailable');
+            }}
+          />
+        )}
         {externalConfigs !== null &&
           (externalConfigs.codex !== undefined ||
             externalConfigs.claudeCode !== undefined ||

packages/i18n/src/locales/en.json

@@ -312,6 +312,12 @@
         "apiKeyOptional": "API key only required if you configured `api-keys` in CPA config.yaml",
         "thinkingHint": "Tip: append `(high)` / `(xhigh)` / `(8192)` to model name to control thinking budget"
       },
+      "cpaDetection": {
+        "title": "CLIProxyAPI detected on your machine",
+        "body": "Import it as a provider to use your OAuth-authenticated Claude / Codex / Gemini accounts.",
+        "importAction": "Import",
+        "dismissAction": "Dismiss"
+      },
       "reasoning": {
         "label": "Reasoning depth",
         "default": "Default (auto)",

packages/i18n/src/locales/zh-CN.json

@@ -312,6 +312,12 @@
         "apiKeyOptional": "仅当你在 CPA config.yaml 里配置了 api-keys 才需要填",
         "thinkingHint": "提示：在 model 名后加 `(high)` / `(xhigh)` / `(8192)` 可控制思考力度"
       },
+      "cpaDetection": {
+        "title": "检测到本机运行的 CLIProxyAPI",
+        "body": "一键导入即可使用你已登录的 Claude / Codex / Gemini 订阅账号。",
+        "importAction": "导入",
+        "dismissAction": "忽略"
+      },
       "reasoning": {
         "label": "推理深度",
         "default": "默认（自动）",