@steerable/agent-shell-web 0.6.15

package/src/components/settings/UsagePanel.tsx

@@ -0,0 +1,196 @@
+import { useCallback, useEffect, useState } from 'react';
+import { LuLoaderCircle, LuChartBar, LuRefreshCw } from 'react-icons/lu';
+import { getElectronBridge, isElectron } from '@/lib/electron-bridge';
+
+/**
+ * UsagePanel — W6-9 用量与成本归因的桌面面板。
+ *
+ * 每轮 CoreLoop 结束后,local-backend 把该轮的累计 token 用量(以及按
+ * framework pricing 单价表估算的 USD 成本)落进 `usage_events` 表;本面板
+ * 按 model 分桶聚合展示近 N 天的用量与成本。
+ *
+ * 成本口径:只统计有单价的模型(framework `MODEL_PRICES`);本地/未知模型
+ * 无单价,token 照常计入但成本列渲染为 "—",不计入总成本。
+ *
+ * 数据自管理:挂载拉一次,可手动刷新 / 切换时间窗。走 local-backend REST
+ * (`/api/v2/usage/summary?days=N`),无专用 IPC channel。
+ */
+
+interface UsageModelBucketWire {
+  model: string;
+  provider: string;
+  turns: number;
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  cachedPromptTokens: number;
+  costUsd: number | null;
+}
+
+interface UsageSummaryWire {
+  sinceDays: number;
+  byModel: UsageModelBucketWire[];
+  totals: {
+    turns: number;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cachedPromptTokens: number;
+    costUsd: number;
+  };
+}
+
+const WINDOW_OPTIONS = [
+  { days: 7, label: '近 7 天' },
+  { days: 30, label: '近 30 天' },
+  { days: 90, label: '近 90 天' },
+] as const;
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(2)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}
+
+function formatCost(usd: number | null): string {
+  if (usd === null) return '—';
+  if (usd < 0.01) return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(2)}`;
+}
+
+export function UsagePanel() {
+  const [days, setDays] = useState<number>(30);
+  const [summary, setSummary] = useState<UsageSummaryWire | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchSummary = useCallback(async (windowDays: number) => {
+    if (!isElectron()) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await getElectronBridge()!.localBackend.request<UsageSummaryWire>({
+        method: 'GET',
+        path: `/api/v2/usage/summary?days=${windowDays}`,
+      });
+      setSummary(res);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void fetchSummary(days);
+  }, [fetchSummary, days]);
+
+  return (
+    <div className="space-y-4">
+      <div className="bg-agent-muted/30 border border-agent-border/60 rounded-agent-md p-3.5 space-y-3">
+        <div className="flex items-center justify-between">
+          <h4 className="text-xs font-semibold text-agent-foreground flex items-center gap-1.5">
+            <LuChartBar className="h-3.5 w-3.5 text-agent-muted-foreground" />
+            用量与成本
+          </h4>
+          <div className="flex items-center gap-1.5">
+            {WINDOW_OPTIONS.map((opt) => (
+              <button
+                key={opt.days}
+                type="button"
+                onClick={() => setDays(opt.days)}
+                className={`h-6 px-2 rounded-full text-[10px] font-medium transition-colors ${
+                  days === opt.days
+                    ? 'bg-agent-foreground text-agent-canvas'
+                    : 'bg-agent-canvas text-agent-muted-foreground border border-agent-border hover:bg-agent-muted/40'
+                }`}
+              >
+                {opt.label}
+              </button>
+            ))}
+            <button
+              type="button"
+              onClick={() => void fetchSummary(days)}
+              disabled={loading}
+              className="h-6 w-6 rounded-full border border-agent-border bg-agent-canvas text-agent-muted-foreground hover:bg-agent-muted/40 flex items-center justify-center"
+              title="刷新"
+            >
+              <LuRefreshCw className={`h-3 w-3 ${loading ? 'animate-spin' : ''}`} />
+            </button>
+          </div>
+        </div>
+
+        {loading && !summary ? (
+          <div className="flex items-center gap-2 py-4 text-xs text-agent-muted-foreground">
+            <LuLoaderCircle className="h-3.5 w-3.5 animate-spin" />
+            读取用量...
+          </div>
+        ) : !summary || summary.byModel.length === 0 ? (
+          <p className="text-[11px] text-agent-muted-foreground py-2">
+            该时间窗内暂无用量记录。完成一轮对话后,这里会按模型聚合 token 与成本。
+          </p>
+        ) : (
+          <>
+            {/* 总计卡片 */}
+            <div className="grid grid-cols-4 gap-2">
+              <div className="rounded-agent-md border border-agent-border bg-agent-canvas px-2.5 py-2">
+                <div className="text-[10px] text-agent-muted-foreground">总轮次</div>
+                <div className="text-sm font-semibold text-agent-foreground">{summary.totals.turns}</div>
+              </div>
+              <div className="rounded-agent-md border border-agent-border bg-agent-canvas px-2.5 py-2">
+                <div className="text-[10px] text-agent-muted-foreground">总 Token</div>
+                <div className="text-sm font-semibold text-agent-foreground">{formatTokens(summary.totals.totalTokens)}</div>
+              </div>
+              <div className="rounded-agent-md border border-agent-border bg-agent-canvas px-2.5 py-2">
+                <div className="text-[10px] text-agent-muted-foreground">缓存命中</div>
+                <div className="text-sm font-semibold text-agent-foreground">{formatTokens(summary.totals.cachedPromptTokens)}</div>
+              </div>
+              <div className="rounded-agent-md border border-agent-border bg-agent-canvas px-2.5 py-2">
+                <div className="text-[10px] text-agent-muted-foreground">估算成本</div>
+                <div className="text-sm font-semibold text-agent-foreground">{formatCost(summary.totals.costUsd)}</div>
+              </div>
+            </div>
+
+            {/* 按模型分桶 */}
+            <div className="rounded-agent-md border border-agent-border overflow-hidden">
+              <table className="w-full text-[11px]">
+                <thead>
+                  <tr className="bg-agent-muted/40 text-agent-muted-foreground">
+                    <th className="text-left font-medium px-2.5 py-1.5">模型</th>
+                    <th className="text-right font-medium px-2.5 py-1.5">轮次</th>
+                    <th className="text-right font-medium px-2.5 py-1.5">输入</th>
+                    <th className="text-right font-medium px-2.5 py-1.5">输出</th>
+                    <th className="text-right font-medium px-2.5 py-1.5">成本</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {summary.byModel.map((b) => (
+                    <tr key={`${b.provider}/${b.model}`} className="border-t border-agent-border/50">
+                      <td className="px-2.5 py-1.5 font-mono text-agent-foreground truncate max-w-[140px]" title={b.model}>
+                        {b.model}
+                      </td>
+                      <td className="px-2.5 py-1.5 text-right text-agent-muted-foreground">{b.turns}</td>
+                      <td className="px-2.5 py-1.5 text-right text-agent-muted-foreground">{formatTokens(b.promptTokens)}</td>
+                      <td className="px-2.5 py-1.5 text-right text-agent-muted-foreground">{formatTokens(b.completionTokens)}</td>
+                      <td className="px-2.5 py-1.5 text-right text-agent-foreground">{formatCost(b.costUsd)}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+
+            <p className="text-[10px] text-agent-muted-foreground">
+              成本按 framework 单价表估算,只统计有单价的模型;"—" 表示该模型无单价(本地/未知)。缓存命中为命中 prompt 缓存的 token 数。
+            </p>
+          </>
+        )}
+      </div>
+
+      {error && (
+        <div className="rounded-agent-md border border-agent-destructive/20 bg-agent-destructive/10 p-2.5 text-xs text-agent-destructive">
+          {error}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/settings/WebSearchSettingsPanel.test.tsx

@@ -0,0 +1,90 @@
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const request = vi.fn();
+
+vi.mock('@/lib/electron-bridge', () => ({
+  isElectron: () => true,
+  getElectronBridge: () => ({
+    localBackend: { request },
+  }),
+}));
+
+const { WebSearchSettingsPanel } = await import('./WebSearchSettingsPanel');
+
+beforeEach(() => {
+  request.mockReset();
+  request.mockResolvedValue({ provider: 'tavily', apiKey: '' });
+});
+
+afterEach(cleanup);
+
+describe('WebSearchSettingsPanel', () => {
+  it('loads Tavily by default and hides the key field on the free backend', async () => {
+    render(<WebSearchSettingsPanel />);
+    await screen.findByTestId('web-search-provider-ddg');
+    expect(screen.getByText('Tavily API Key')).toBeTruthy();
+
+    fireEvent.click(screen.getByTestId('web-search-provider-ddg'));
+    expect(screen.queryByText('Tavily API Key')).toBeNull();
+    expect(screen.getByText(/DuckDuckGo 公开搜索页/)).toBeTruthy();
+  });
+
+  it('POSTs provider=ddg and shows the restart copy', async () => {
+    request
+      .mockResolvedValueOnce({ provider: 'tavily' })
+      .mockResolvedValueOnce({ provider: 'ddg' });
+
+    render(<WebSearchSettingsPanel />);
+    await screen.findByTestId('web-search-provider-ddg');
+    fireEvent.click(screen.getByTestId('web-search-provider-ddg'));
+    fireEvent.click(screen.getByRole('button', { name: '保存' }));
+
+    await waitFor(() => {
+      expect(request).toHaveBeenCalledWith(
+        expect.objectContaining({
+          method: 'POST',
+          path: '/api/v2/local-settings/web-search',
+          body: { provider: 'ddg', apiKey: '' },
+        }),
+      );
+    });
+    expect(await screen.findByText(/重启应用后 sidecar 会注册免费搜索/)).toBeTruthy();
+  });
+
+  it('keeps 免费 selected when the save echo omits provider', async () => {
+    request.mockResolvedValueOnce({ provider: 'tavily' }).mockResolvedValueOnce({});
+
+    render(<WebSearchSettingsPanel />);
+    await screen.findByTestId('web-search-provider-ddg');
+    fireEvent.click(screen.getByTestId('web-search-provider-ddg'));
+    fireEvent.click(screen.getByRole('button', { name: '保存' }));
+
+    expect(await screen.findByText(/重启应用后 sidecar 会注册免费搜索/)).toBeTruthy();
+    expect(screen.queryByText('Tavily API Key')).toBeNull();
+    expect(screen.getByTestId('web-search-provider-ddg').className).toContain('border-agent-foreground/40');
+  });
+
+  it('POSTs a Tavily key and keeps the key field', async () => {
+    request
+      .mockResolvedValueOnce({ provider: 'tavily' })
+      .mockResolvedValueOnce({ provider: 'tavily', apiKey: 'tvly-k' });
+
+    render(<WebSearchSettingsPanel />);
+    const keyInput = await screen.findByPlaceholderText('tvly-...（留空 = 不注册 Tavily）');
+    fireEvent.change(keyInput, { target: { value: ' tvly-k ' } });
+    fireEvent.click(screen.getByRole('button', { name: '保存' }));
+
+    await waitFor(() => {
+      expect(request).toHaveBeenCalledWith(
+        expect.objectContaining({
+          method: 'POST',
+          path: '/api/v2/local-settings/web-search',
+          body: { provider: 'tavily', apiKey: 'tvly-k' },
+        }),
+      );
+    });
+    expect(await screen.findByText(/重启应用后 sidecar 会注册 web_search/)).toBeTruthy();
+    expect(screen.getByText('Tavily API Key')).toBeTruthy();
+  });
+});

package/src/components/settings/WebSearchSettingsPanel.tsx

@@ -0,0 +1,183 @@
+import { useCallback, useEffect, useState } from 'react';
+import { LuLoaderCircle, LuSearch } from 'react-icons/lu';
+import { getElectronBridge, isElectron } from '@/lib/electron-bridge';
+
+/**
+ * Search backend settings. `ddg` registers `web_search` with no key.
+ * Tavily still needs a key. Empty Tavily + OpenAI hosted search is handled
+ * on spawn, not here. DuckDuckGo is never a silent fallback.
+ *
+ * Saved to settings_kv; injected as STEERABLE_WEB_SEARCH_PROVIDER / API_KEY
+ * on the next sidecar spawn (restart the app after saving).
+ */
+
+type SearchProvider = 'ddg' | 'tavily';
+
+interface WebSearchSettingsWire {
+  provider?: SearchProvider;
+  apiKey?: string;
+}
+
+function readProvider(raw: unknown, fallback: SearchProvider): SearchProvider {
+  if (raw === 'ddg' || raw === 'tavily') return raw;
+  return fallback;
+}
+
+export function WebSearchSettingsPanel() {
+  const [provider, setProvider] = useState<SearchProvider>('tavily');
+  const [apiKey, setApiKey] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [status, setStatus] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchSettings = useCallback(async () => {
+    if (!isElectron()) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await getElectronBridge()!.localBackend.request<WebSearchSettingsWire | null>({
+        method: 'GET',
+        path: '/api/v2/local-settings/web-search',
+      });
+      setProvider(readProvider(res?.provider, 'tavily'));
+      setApiKey(res?.apiKey ?? '');
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void fetchSettings();
+  }, [fetchSettings]);
+
+  const handleSave = async () => {
+    if (!isElectron()) return;
+    setSaving(true);
+    setError(null);
+    setStatus(null);
+    try {
+      const posted = provider;
+      const saved = await getElectronBridge()!.localBackend.request<WebSearchSettingsWire>({
+        method: 'POST',
+        path: '/api/v2/local-settings/web-search',
+        body: { provider: posted, apiKey: apiKey.trim() },
+      });
+      // Old main processes echo `{ apiKey }` only. Missing provider must not
+      // snap the radio back to Tavily — keep what the user just saved.
+      const nextProvider = readProvider(saved?.provider, posted);
+      setProvider(nextProvider);
+      setApiKey(saved?.apiKey ?? '');
+      if (nextProvider === 'ddg') {
+        setStatus('已保存 — 重启应用后 sidecar 会注册免费搜索（DuckDuckGo）');
+      } else if (saved?.apiKey) {
+        setStatus('已保存 — 重启应用后 sidecar 会注册 web_search');
+      } else {
+        setStatus('已保存 — 未配置则模型没有搜索工具（OpenAI 可用聊天凭证走托管搜索）');
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <div className="bg-agent-muted/30 border border-agent-border/60 rounded-agent-md p-3.5 space-y-3">
+        <h4 className="text-xs font-semibold text-agent-foreground flex items-center gap-1.5">
+          <LuSearch className="h-3.5 w-3.5 text-agent-muted-foreground" />
+          网络搜索
+        </h4>
+
+        {loading ? (
+          <div className="flex items-center gap-2 py-2 text-xs text-agent-muted-foreground">
+            <LuLoaderCircle className="h-3.5 w-3.5 animate-spin" />
+            读取搜索设置...
+          </div>
+        ) : (
+          <>
+            <div className="space-y-1.5">
+              <label className="text-[11px] font-medium text-agent-muted-foreground">
+                搜索后端
+              </label>
+              <div className="flex gap-2">
+                {(
+                  [
+                    { value: 'ddg', label: '免费', hint: 'DuckDuckGo，无需 Key' },
+                    { value: 'tavily', label: 'Tavily', hint: '需 API Key，结果更稳' },
+                  ] as const
+                ).map((opt) => (
+                  <button
+                    key={opt.value}
+                    type="button"
+                    data-testid={`web-search-provider-${opt.value}`}
+                    onClick={() => setProvider(opt.value)}
+                    className={`flex-1 rounded-agent-md border px-3 py-2 text-left transition-colors ${
+                      provider === opt.value
+                        ? 'border-agent-foreground/40 bg-agent-foreground/5'
+                        : 'border-agent-border bg-agent-canvas hover:bg-agent-muted/40'
+                    }`}
+                  >
+                    <div className="text-xs font-medium text-agent-foreground">{opt.label}</div>
+                    <div className="text-[10px] text-agent-muted-foreground">{opt.hint}</div>
+                  </button>
+                ))}
+              </div>
+            </div>
+
+            {provider === 'tavily' && (
+              <div className="space-y-1.5">
+                <label className="text-[11px] font-medium text-agent-muted-foreground">
+                  Tavily API Key
+                </label>
+                <input
+                  type="password"
+                  value={apiKey}
+                  onChange={(e) => setApiKey(e.target.value)}
+                  placeholder="tvly-...（留空 = 不注册 Tavily）"
+                  className="h-8 w-full rounded-agent-md border border-agent-border bg-agent-canvas px-3 font-mono text-[11px] text-agent-foreground focus:outline-none focus:ring-2 focus:ring-agent-foreground/30"
+                  autoComplete="off"
+                />
+              </div>
+            )}
+
+            <div className="flex items-center justify-between gap-2">
+              <p className="text-[10px] text-agent-muted-foreground">
+                {provider === 'ddg'
+                  ? '免费后端走 DuckDuckGo 公开搜索页，无需 Key。质量与稳定性不如 Tavily；国内网络可能需要系统代理。Harbor 评测仍关闭网络工具。'
+                  : 'GLM / OpenRouter / DeepSeek 需要这把钥；OpenAI（api.openai.com）可用聊天凭证走托管搜索，不必另配。Harbor 评测仍关闭网络工具。'}
+              </p>
+              <button
+                type="button"
+                onClick={handleSave}
+                disabled={saving}
+                className={`h-8 shrink-0 px-4 rounded-full text-xs font-medium transition-all ${
+                  saving
+                    ? 'bg-agent-muted text-agent-muted-foreground cursor-not-allowed'
+                    : 'bg-agent-foreground text-agent-canvas hover:opacity-90'
+                }`}
+              >
+                {saving ? <LuLoaderCircle className="h-3 w-3 animate-spin" /> : '保存'}
+              </button>
+            </div>
+
+            {status && (
+              <p className="text-[10px] text-agent-muted-foreground bg-agent-muted/10 px-2 py-1 rounded border border-agent-border/20">
+                {status}
+              </p>
+            )}
+          </>
+        )}
+      </div>
+
+      {error && (
+        <div className="rounded-agent-md border border-agent-destructive/20 bg-agent-destructive/10 p-2.5 text-xs text-agent-destructive">
+          {error}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/settings/compat-flags-model.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import {
+  COMPAT_AUTO,
+  formStateFromOverrides,
+  overridesFromFormState,
+} from './compat-flags-model';
+import type { CompatFlagDescriptor } from '@/lib/local-api';
+
+// 与框架 compat.py `_FLAG_WIRE_SPEC` 同形的描述符夹具。
+const FLAGS: CompatFlagDescriptor[] = [
+  { key: 'supportsUsageInStreaming', field: 'supports_usage_in_streaming', kind: 'bool', default: true, description: '' },
+  { key: 'maxTokensField', field: 'max_tokens_field', kind: 'enum:max_tokens,max_completion_tokens', default: 'max_tokens', description: '' },
+  { key: 'supportsTemperature', field: 'supports_temperature', kind: 'bool', default: true, description: '' },
+  { key: 'reasoningDeltaFields', field: 'reasoning_delta_fields', kind: 'string-list', default: ['reasoning_content', 'reasoning'], description: '' },
+];
+
+describe('compat-flags-model (W1.3.2)', () => {
+  it('unset overrides render as auto for every flag', () => {
+    expect(formStateFromOverrides(undefined, FLAGS)).toEqual({
+      supportsUsageInStreaming: COMPAT_AUTO,
+      maxTokensField: COMPAT_AUTO,
+      supportsTemperature: COMPAT_AUTO,
+      reasoningDeltaFields: COMPAT_AUTO,
+    });
+  });
+
+  it('persisted overrides map to their form values', () => {
+    const state = formStateFromOverrides(
+      { supportsTemperature: false, reasoningDeltaFields: ['reasoning_content'] },
+      FLAGS,
+    );
+    expect(state.supportsTemperature).toBe('false');
+    expect(state.reasoningDeltaFields).toBe('reasoning_content');
+    expect(state.maxTokensField).toBe(COMPAT_AUTO);
+  });
+
+  it('all-auto form state produces no overrides (auto-detect fallback)', () => {
+    const state = formStateFromOverrides(undefined, FLAGS);
+    expect(overridesFromFormState(state, FLAGS)).toBeUndefined();
+  });
+
+  it('form state builds a typed overrides payload', () => {
+    const overrides = overridesFromFormState(
+      {
+        supportsTemperature: 'false',
+        maxTokensField: 'max_completion_tokens',
+        reasoningDeltaFields: 'reasoning_content, reasoning',
+        supportsUsageInStreaming: COMPAT_AUTO,
+      },
+      FLAGS,
+    );
+    expect(overrides).toEqual({
+      supportsTemperature: false,
+      maxTokensField: 'max_completion_tokens',
+      reasoningDeltaFields: ['reasoning_content', 'reasoning'],
+    });
+  });
+
+  it('invalid enum values and empty lists are dropped', () => {
+    const overrides = overridesFromFormState(
+      { maxTokensField: 'bogus_field', reasoningDeltaFields: '  ' },
+      FLAGS,
+    );
+    expect(overrides).toBeUndefined();
+  });
+
+  it('round-trips: overrides → form → overrides', () => {
+    const original = { supportsTemperature: false as const, reasoningDeltaFields: ['reasoning'] };
+    expect(overridesFromFormState(formStateFromOverrides(original, FLAGS), FLAGS)).toEqual(original);
+  });
+});

package/src/components/settings/compat-flags-model.ts

@@ -0,0 +1,57 @@
+import type { CompatFlagDescriptor, OpenAICompatOverrides } from '@/lib/local-api';
+
+/**
+ * compat 旗标设置区的纯状态模型——无 React、无运行时框架依赖，node 侧
+ * vitest 直接可测（与 orchestration-children-model 同一拆分理由）。
+ *
+ * 表单值统一为字符串三态：'auto'（不覆盖，走框架 URL 自动探测）|
+ * 'true'/'false'（bool 旗标）| 枚举选项 | 逗号分隔列表（string-list）。
+ */
+
+export const COMPAT_AUTO = 'auto';
+
+export type CompatFormState = Record<string, string>;
+
+/** 已持久化的覆盖 → 表单初值；未覆盖的旗标落在 'auto'。 */
+export function formStateFromOverrides(
+  overrides: OpenAICompatOverrides | undefined,
+  flags: CompatFlagDescriptor[],
+): CompatFormState {
+  const state: CompatFormState = {};
+  const source = (overrides ?? {}) as Record<string, unknown>;
+  for (const flag of flags) {
+    const value = source[flag.key];
+    if (value === undefined || value === null) {
+      state[flag.key] = COMPAT_AUTO;
+    } else if (flag.kind === 'bool') {
+      state[flag.key] = value === true ? 'true' : 'false';
+    } else if (flag.kind === 'string-list') {
+      state[flag.key] = Array.isArray(value) ? value.join(', ') : COMPAT_AUTO;
+    } else {
+      state[flag.key] = String(value);
+    }
+  }
+  return state;
+}
+
+/** 表单状态 → 覆盖载荷；全部 'auto'/空时返回 undefined（= 不下发覆盖）。 */
+export function overridesFromFormState(
+  state: CompatFormState,
+  flags: CompatFlagDescriptor[],
+): OpenAICompatOverrides | undefined {
+  const out: Record<string, unknown> = {};
+  for (const flag of flags) {
+    const raw = (state[flag.key] ?? COMPAT_AUTO).trim();
+    if (raw === COMPAT_AUTO || raw === '') continue;
+    if (flag.kind === 'bool') {
+      if (raw === 'true' || raw === 'false') out[flag.key] = raw === 'true';
+    } else if (flag.kind === 'string-list') {
+      const list = raw.split(',').map((v) => v.trim()).filter(Boolean);
+      if (list.length > 0) out[flag.key] = list;
+    } else if (flag.kind.startsWith('enum:')) {
+      const options = flag.kind.slice('enum:'.length).split(',');
+      if (options.includes(raw)) out[flag.key] = raw;
+    }
+  }
+  return Object.keys(out).length > 0 ? (out as OpenAICompatOverrides) : undefined;
+}