minimal-agent 0.13.0 → 0.14.0

package/src/config/configService.ts

@@ -1,21 +1,35 @@
 import { randomUUID } from 'node:crypto';
 
-import type { Provider } from '../types.js';
 import {
-  readMinimalAgentConfig,
-  updateMinimalAgentConfig,
-  defaultMaxTokens,
-  type MinimalAgentConfig,
+  type ModelFallbackReason,
+  type ModelRef,
+  modelRefFromLegacy,
+} from '../modelRef.js';
+import {
+  type OnlineModelCatalogItem,
+  type TeamCredentials,
+  fetchOnlineModels,
+  loadTeamCredentials,
+  resolveOnlineModel,
+} from '../team/auth.js';
+import type { GatewayProvider, LocalProvider, Provider } from '../types.js';
+import {
   type AdvisorConfig,
-  type ModelConfig,
   type ApiFormat,
-  type ToolConfigs,
-  type SubagentsConfig,
   type BrowserConfig,
   type ComputerUseConfig,
-  DEFAULT_SUBAGENTS_CONFIG,
+  DEFAULT_ADVISOR_CONFIG,
   DEFAULT_BROWSER_CONFIG,
   DEFAULT_COMPUTER_USE_CONFIG,
+  DEFAULT_SUBAGENTS_CONFIG,
+  type MinimalAgentConfig,
+  type ModelConfig,
+  type SubagentsConfig,
+  type ToolConfigs,
+  type WorkflowModelRoles,
+  defaultMaxTokens,
+  readMinimalAgentConfig,
+  updateMinimalAgentConfig,
 } from './configFile.js';
 import { CONFIG_LIMITS, normalizeLimited } from './numericLimits.js';
 
@@ -42,28 +56,103 @@ export interface ConfigSnapshot {
  * 而不是「类型说必填、实现却防着 undefined」的分裂状态。
  */
 export type ModelOp =
-  | { op: 'add'; model: Partial<Omit<ModelConfig, 'id' | 'createdAt' | 'updatedAt'>> }
-  | { op: 'update'; id: string; patch: Partial<Omit<ModelConfig, 'id' | 'createdAt' | 'updatedAt'>> & { clearApiKey?: boolean } }
+  | {
+      op: 'add';
+      model: Partial<Omit<ModelConfig, 'id' | 'createdAt' | 'updatedAt'>>;
+    }
+  | {
+      op: 'update';
+      id: string;
+      patch: Partial<Omit<ModelConfig, 'id' | 'createdAt' | 'updatedAt'>> & {
+        clearApiKey?: boolean;
+      };
+    }
   | { op: 'remove'; id: string };
 
 export interface ConfigPatch {
   models?: ModelOp[];
   baseModelId?: string | null;
+  /** 私有部署/开发覆盖用的团队服务器地址；普通用户使用内置 KakadeAI 服务。 */
+  teamServerUrl?: string | null;
   compactRatio?: number;
-  advisor?: (Partial<Omit<AdvisorConfig, 'contextPolicy'>> & { clear?: boolean });
+  advisor?: Partial<Omit<AdvisorConfig, 'contextPolicy'>> & { clear?: boolean };
+  /** Set a role to null/empty to remove its mapping. */
+  workflowModels?: Partial<Record<string, string | null>>;
   subagents?: Partial<SubagentsConfig>;
   browser?: Partial<BrowserConfig>;
   computerUse?: Partial<ComputerUseConfig>;
   tools?: {
-    webSearch?: Partial<NonNullable<ToolConfigs['webSearch']>> & { clear?: boolean };
-    imageGeneration?: Partial<NonNullable<ToolConfigs['imageGeneration']>> & { clear?: boolean; clearApiKey?: boolean };
-    openRouter?: Partial<NonNullable<ToolConfigs['openRouter']>> & { clear?: boolean };
-    textToSpeech?: Partial<NonNullable<ToolConfigs['textToSpeech']>> & { clear?: boolean; clearApiKey?: boolean };
+    webSearch?: Partial<NonNullable<ToolConfigs['webSearch']>> & {
+      clear?: boolean;
+    };
+    imageGeneration?: Partial<NonNullable<ToolConfigs['imageGeneration']>> & {
+      clear?: boolean;
+      clearApiKey?: boolean;
+    };
+    openRouter?: Partial<NonNullable<ToolConfigs['openRouter']>> & {
+      clear?: boolean;
+    };
+    textToSpeech?: Partial<NonNullable<ToolConfigs['textToSpeech']>> & {
+      clear?: boolean;
+      clearApiKey?: boolean;
+    };
   };
 }
 
 const DEFAULT_CONTEXT_WINDOW = 128_000;
 
+export interface ModelResolution {
+  provider: Provider | null;
+  fallbackReason: ModelFallbackReason;
+}
+
+function gatewayFallbackReason(
+  model?: OnlineModelCatalogItem,
+  error?: unknown,
+): ModelFallbackReason {
+  const state = model?.availability?.state;
+  if (state === 'quota_exhausted' || state === 'concurrency_exceeded')
+    return 'quota_exhausted';
+  if (state === 'model_disabled' || state === 'disabled')
+    return 'model_disabled';
+  if (state === 'device_expired') return 'credential_expired';
+  if (state === 'not_authorized') return 'grant_revoked';
+  if (state === 'server_offline' || state === 'offline') return 'offline';
+  const message = error instanceof Error ? error.message : '';
+  if (message.includes('DEVICE_REVOKED') || message.includes('401'))
+    return 'credential_expired';
+  if (message.includes('MODEL_UNAVAILABLE') || message.includes('403'))
+    return 'grant_revoked';
+  return 'offline';
+}
+
+function gatewayProviderFromModel(
+  credentials: TeamCredentials,
+  model: OnlineModelCatalogItem,
+): GatewayProvider {
+  return {
+    name: model.displayName || model.model,
+    source: 'gateway',
+    remoteModelId: model.id,
+    gatewayUrl: credentials.serverUrl,
+    gatewayToken: credentials.deviceToken,
+    gatewayMaxToolCategories: model.maxToolCategories,
+    gatewayDefaultToolCategories: model.defaultToolCategories,
+    // Deprecated compatibility field: before the explicit max/default/session
+    // split this field was used as the provider boundary. Keep its safe
+    // default as the server maximum; the current Session selection is applied
+    // per turn by runAgentTurn/useChat.
+    gatewayToolCategories: model.maxToolCategories,
+    model: model.model,
+    contextWindow: model.contextWindow,
+    maxTokens: model.maxTokens,
+    apiFormat: model.apiFormat,
+    supportsVision: model.supportsVision,
+    gatewayCapabilities: model.capabilities,
+    promptCache: { mode: 'disabled' },
+  };
+}
+
 function positiveInt(value: string | undefined, fallback: number): number {
   const parsed = Number.parseInt(value ?? '', 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
@@ -87,25 +176,43 @@ function configFromEnv(): MinimalAgentConfig | null {
   const model = process.env.MINIMAL_AGENT_MODEL;
   if (!baseURL || !apiKey || !model) return null;
   const tools: ToolConfigs = {};
-  if (process.env.TAVILY_API_KEY) tools.webSearch = { provider: 'tavily', apiKey: process.env.TAVILY_API_KEY };
-  if (process.env.OPENAI_IMAGE_BASE_URL && process.env.OPENAI_IMAGE_API_KEY && process.env.OPENAI_IMAGE_MODEL) {
+  if (process.env.TAVILY_API_KEY)
+    tools.webSearch = {
+      provider: 'tavily',
+      apiKey: process.env.TAVILY_API_KEY,
+    };
+  if (
+    process.env.OPENAI_IMAGE_BASE_URL &&
+    process.env.OPENAI_IMAGE_API_KEY &&
+    process.env.OPENAI_IMAGE_MODEL
+  ) {
     tools.imageGeneration = {
       provider: process.env.OPENAI_IMAGE_PROVIDER ?? 'openai',
       baseURL: process.env.OPENAI_IMAGE_BASE_URL,
       apiKey: process.env.OPENAI_IMAGE_API_KEY,
       model: process.env.OPENAI_IMAGE_MODEL,
-      protocol: process.env.OPENAI_IMAGE_PROTOCOL === 'chat' || process.env.OPENAI_IMAGE_PROTOCOL === 'images'
-        ? process.env.OPENAI_IMAGE_PROTOCOL
-        : 'auto',
+      protocol:
+        process.env.OPENAI_IMAGE_PROTOCOL === 'chat' ||
+        process.env.OPENAI_IMAGE_PROTOCOL === 'images'
+          ? process.env.OPENAI_IMAGE_PROTOCOL
+          : 'auto',
     };
   }
-  if (process.env.OPENROUTER_API_KEY) tools.openRouter = { apiKey: process.env.OPENROUTER_API_KEY };
+  if (process.env.OPENROUTER_API_KEY)
+    tools.openRouter = { apiKey: process.env.OPENROUTER_API_KEY };
   if (process.env.MINIMAX_API_KEY && process.env.MINIMAX_GROUP_ID) {
-    tools.textToSpeech = { provider: 'minimax', apiKey: process.env.MINIMAX_API_KEY, groupId: process.env.MINIMAX_GROUP_ID };
+    tools.textToSpeech = {
+      provider: 'minimax',
+      apiKey: process.env.MINIMAX_API_KEY,
+      groupId: process.env.MINIMAX_GROUP_ID,
+    };
   }
   const compactRatio = Number(process.env.MINIMAL_AGENT_COMPACT_RATIO);
   const name = process.env.MINIMAL_AGENT_PROVIDER ?? 'env';
-  const contextWindow = positiveInt(process.env.MINIMAL_AGENT_CONTEXT_WINDOW, DEFAULT_CONTEXT_WINDOW);
+  const contextWindow = positiveInt(
+    process.env.MINIMAL_AGENT_CONTEXT_WINDOW,
+    DEFAULT_CONTEXT_WINDOW,
+  );
   const envModel: ModelConfig = {
     id: 'env-base',
     apiFormat: 'openai',
@@ -114,13 +221,17 @@ function configFromEnv(): MinimalAgentConfig | null {
     apiKey,
     model,
     contextWindow,
-    maxTokens: positiveInt(process.env.MINIMAL_AGENT_MAX_TOKENS, defaultMaxTokens(contextWindow)),
+    maxTokens: positiveInt(
+      process.env.MINIMAL_AGENT_MAX_TOKENS,
+      defaultMaxTokens(contextWindow),
+    ),
     promptCache: {
-      mode: process.env.MINIMAL_AGENT_PROMPT_CACHE_MODE === 'session-key'
-        ? 'session-key'
-        : process.env.MINIMAL_AGENT_PROMPT_CACHE_MODE === 'disabled'
-          ? 'disabled'
-          : 'auto',
+      mode:
+        process.env.MINIMAL_AGENT_PROMPT_CACHE_MODE === 'session-key'
+          ? 'session-key'
+          : process.env.MINIMAL_AGENT_PROMPT_CACHE_MODE === 'disabled'
+            ? 'disabled'
+            : 'auto',
     },
     enabled: true,
     createdAt: 0,
@@ -130,23 +241,39 @@ function configFromEnv(): MinimalAgentConfig | null {
     version: 4,
     models: [envModel],
     baseModelId: envModel.id,
+    teamServerUrl: process.env.KAKADEAI_SOCIAL_SERVER_URL?.trim() || null,
     ...(compactRatio > 0 && compactRatio <= 1 ? { compactRatio } : {}),
     subagents: {
       ...DEFAULT_SUBAGENTS_CONFIG,
-      maxCallsPerTurn: positiveInt(process.env.AGENT_TOOL_MAX_CALLS_PER_TURN, 6),
+      maxCallsPerTurn: positiveInt(
+        process.env.AGENT_TOOL_MAX_CALLS_PER_TURN,
+        6,
+      ),
       maxConcurrent: positiveInt(process.env.AGENT_TOOL_MAX_CONCURRENT, 3),
       timeoutMs: positiveInt(process.env.AGENT_TOOL_TIMEOUT_MS, 1_800_000),
-      exploreMaxTurns: positiveInt(process.env.AGENT_TOOL_EXPLORE_MAX_TURNS, 50),
-      generalMaxTurns: positiveInt(process.env.AGENT_TOOL_GENERAL_MAX_TURNS, 100),
+      exploreMaxTurns: positiveInt(
+        process.env.AGENT_TOOL_EXPLORE_MAX_TURNS,
+        200,
+      ),
+      generalMaxTurns: positiveInt(
+        process.env.AGENT_TOOL_GENERAL_MAX_TURNS,
+        100,
+      ),
     },
     browser: DEFAULT_BROWSER_CONFIG,
     computerUse: {
       enabled: process.env.MINIMAL_AGENT_COMPUTER_USE_ENABLED !== 'false',
       imagePolicy: 'single-adaptive',
-      maxImagePixels: Math.min(4_000_000, Math.max(250_000, positiveInt(
-        process.env.MINIMAL_AGENT_COMPUTER_USE_MAX_IMAGE_PIXELS,
-        DEFAULT_COMPUTER_USE_CONFIG.maxImagePixels,
-      ))),
+      maxImagePixels: Math.min(
+        4_000_000,
+        Math.max(
+          250_000,
+          positiveInt(
+            process.env.MINIMAL_AGENT_COMPUTER_USE_MAX_IMAGE_PIXELS,
+            DEFAULT_COMPUTER_USE_CONFIG.maxImagePixels,
+          ),
+        ),
+      ),
       observationFrames: 1,
     },
     tools,
@@ -154,8 +281,12 @@ function configFromEnv(): MinimalAgentConfig | null {
   };
 }
 
-function resolveProvider(entry: ModelConfig, compactRatio?: number): Provider {
+function resolveProvider(
+  entry: ModelConfig,
+  compactRatio?: number,
+): LocalProvider {
   return {
+    source: 'local',
     name: entry.displayName ?? entry.model,
     baseURL: entry.baseURL,
     apiKey: entry.apiKey,
@@ -164,17 +295,31 @@ function resolveProvider(entry: ModelConfig, compactRatio?: number): Provider {
     maxTokens: entry.maxTokens ?? defaultMaxTokens(entry.contextWindow),
     apiFormat: entry.apiFormat,
     supportsVision: entry.supportsVision !== false,
+    ...(entry.supportsJsonSchema !== undefined
+      ? { supportsJsonSchema: entry.supportsJsonSchema }
+      : {}),
     promptCache: entry.promptCache ?? { mode: 'auto' },
     ...(compactRatio !== undefined ? { compactRatio } : {}),
+    // cache_edits 式回收：仅 Anthropic 格式 + 显式 env 开启时生效（非公开协议，
+    // 依赖支持该扩展的网关端点；语义与默认值说明见 types.ts Provider.cacheEdits）
+    ...(entry.apiFormat === 'anthropic' &&
+    process.env.MINIMAL_AGENT_CACHE_EDITS === '1'
+      ? { cacheEdits: true }
+      : {}),
   };
 }
 
-function mergeRecord(base: Record<string, unknown> | undefined, patch: Record<string, unknown>): Record<string, unknown> {
+function mergeRecord(
+  base: Record<string, unknown> | undefined,
+  patch: Record<string, unknown>,
+): Record<string, unknown> {
   const out: Record<string, unknown> = { ...(base ?? {}) };
   for (const [key, value] of Object.entries(patch)) {
     if (value && typeof value === 'object' && !Array.isArray(value)) {
       out[key] = mergeRecord(
-        out[key] && typeof out[key] === 'object' && !Array.isArray(out[key]) ? out[key] as Record<string, unknown> : undefined,
+        out[key] && typeof out[key] === 'object' && !Array.isArray(out[key])
+          ? (out[key] as Record<string, unknown>)
+          : undefined,
         value as Record<string, unknown>,
       );
     } else if (value !== undefined) out[key] = value;
@@ -186,17 +331,33 @@ function hasEntries(value: object | undefined): boolean {
   return !!value && Object.keys(value).length > 0;
 }
 
-function applyModelsPatch(models: ModelConfig[], ops: ModelOp[]): ModelConfig[] {
+/** Remove an optional config key while keeping the persisted object sparse. */
+function omitKey<T extends object>(
+  value: T | undefined,
+  key: PropertyKey,
+): T | undefined {
+  if (!value) return value;
+  const { [key]: _removed, ...rest } = value as T &
+    Record<PropertyKey, unknown>;
+  return rest as T;
+}
+
+function applyModelsPatch(
+  models: ModelConfig[],
+  ops: ModelOp[],
+): ModelConfig[] {
   let out = [...models];
   const now = Date.now();
   for (const item of ops) {
     if (item.op === 'add') {
       const m = item.model;
-      const apiFormat: ApiFormat = m.apiFormat === 'anthropic' ? 'anthropic' : 'openai';
+      const apiFormat: ApiFormat =
+        m.apiFormat === 'anthropic' ? 'anthropic' : 'openai';
       const baseURL = m.baseURL?.trim();
       const modelId = m.model?.trim();
       const apiKey = m.apiKey?.trim();
-      if (!baseURL || !modelId || !apiKey) throw new Error('模型缺少 Base URL、模型 ID 或 API Key');
+      if (!baseURL || !modelId || !apiKey)
+        throw new Error('模型缺少 Base URL、模型 ID 或 API Key');
       out.push({
         id: randomUUID(),
         apiFormat,
@@ -204,9 +365,15 @@ function applyModelsPatch(models: ModelConfig[], ops: ModelOp[]): ModelConfig[]
         baseURL,
         apiKey,
         model: modelId,
-        contextWindow: m.contextWindow && m.contextWindow > 0 ? m.contextWindow : DEFAULT_CONTEXT_WINDOW,
+        contextWindow:
+          m.contextWindow && m.contextWindow > 0
+            ? m.contextWindow
+            : DEFAULT_CONTEXT_WINDOW,
         ...(m.maxTokens ? { maxTokens: m.maxTokens } : {}),
         supportsVision: m.supportsVision !== false,
+        ...(m.supportsJsonSchema !== undefined
+          ? { supportsJsonSchema: m.supportsJsonSchema }
+          : {}),
         promptCache: m.promptCache ?? { mode: 'auto' },
         enabled: m.enabled ?? true,
         createdAt: now,
@@ -219,13 +386,27 @@ function applyModelsPatch(models: ModelConfig[], ops: ModelOp[]): ModelConfig[]
       const patch = item.patch;
       const next: ModelConfig = {
         ...existing,
-        ...(patch.apiFormat ? { apiFormat: patch.apiFormat === 'anthropic' ? 'anthropic' : 'openai' } : {}),
-        ...(patch.displayName !== undefined ? { displayName: patch.displayName.trim() || undefined } : {}),
+        ...(patch.apiFormat
+          ? {
+              apiFormat:
+                patch.apiFormat === 'anthropic' ? 'anthropic' : 'openai',
+            }
+          : {}),
+        ...(patch.displayName !== undefined
+          ? { displayName: patch.displayName.trim() || undefined }
+          : {}),
         ...(patch.baseURL?.trim() ? { baseURL: patch.baseURL.trim() } : {}),
         ...(patch.model?.trim() ? { model: patch.model.trim() } : {}),
         ...(patch.contextWindow ? { contextWindow: patch.contextWindow } : {}),
-        ...(patch.maxTokens !== undefined ? { maxTokens: patch.maxTokens || undefined } : {}),
-        ...(patch.supportsVision !== undefined ? { supportsVision: patch.supportsVision !== false } : {}),
+        ...(patch.maxTokens !== undefined
+          ? { maxTokens: patch.maxTokens || undefined }
+          : {}),
+        ...(patch.supportsVision !== undefined
+          ? { supportsVision: patch.supportsVision !== false }
+          : {}),
+        ...(patch.supportsJsonSchema !== undefined
+          ? { supportsJsonSchema: patch.supportsJsonSchema }
+          : {}),
         ...(patch.promptCache ? { promptCache: patch.promptCache } : {}),
         ...(patch.enabled !== undefined ? { enabled: patch.enabled } : {}),
         updatedAt: now,
@@ -240,18 +421,26 @@ function applyModelsPatch(models: ModelConfig[], ops: ModelOp[]): ModelConfig[]
   return out;
 }
 
-function applyConfigPatch(base: MinimalAgentConfig | null, patch: ConfigPatch): Omit<MinimalAgentConfig, 'version' | 'savedAt'> {
-  const wasEmpty = (base?.models.length ?? 0) === 0 && (base?.baseModelId ?? null) === null;
+function applyConfigPatch(
+  base: MinimalAgentConfig | null,
+  patch: ConfigPatch,
+): Omit<MinimalAgentConfig, 'version' | 'savedAt'> {
+  const wasEmpty =
+    (base?.models.length ?? 0) === 0 && (base?.baseModelId ?? null) === null;
   let models = base?.models ?? [];
   let baseModelId = base?.baseModelId ?? null;
 
   if (patch.models?.length) models = applyModelsPatch(models, patch.models);
 
   // 全新安装加第一个模型时自动设为基座——否则用户加完模型还是没法聊天。
-  if (wasEmpty && baseModelId === null && models.length > 0) baseModelId = models[0]!.id;
+  if (wasEmpty && baseModelId === null && models.length > 0)
+    baseModelId = models[0]!.id;
 
   if (patch.baseModelId !== undefined) {
-    if (patch.baseModelId !== null && !models.some((entry) => entry.id === patch.baseModelId)) {
+    if (
+      patch.baseModelId !== null &&
+      !models.some((entry) => entry.id === patch.baseModelId)
+    ) {
       throw new Error('要设为基座的模型不存在');
     }
     baseModelId = patch.baseModelId;
@@ -260,8 +449,16 @@ function applyConfigPatch(base: MinimalAgentConfig | null, patch: ConfigPatch):
   // 不变量：禁止删除/禁用当前基座模型指向的条目（先设别的为基座）。
   if (baseModelId !== null) {
     const baseEntry = models.find((entry) => entry.id === baseModelId);
-    if (!baseEntry) throw new Error('当前基座模型已被删除，请先设置其他模型为基座');
-    if (baseEntry.enabled === false) throw new Error('不能禁用当前基座模型，请先设置其他模型为基座');
+    if (!baseEntry)
+      throw new Error('当前基座模型已被删除，请先设置其他模型为基座');
+    if (baseEntry.enabled === false)
+      throw new Error('不能禁用当前基座模型，请先设置其他模型为基座');
+  }
+
+  // 团队服务器地址：不像 baseModelId 那样要交叉校验（不引用 models[]），一个裸字符串。
+  let teamServerUrl = base?.teamServerUrl ?? null;
+  if (patch.teamServerUrl !== undefined) {
+    teamServerUrl = patch.teamServerUrl?.trim() || null;
   }
 
   let advisor = base?.advisor;
@@ -270,90 +467,197 @@ function applyConfigPatch(base: MinimalAgentConfig | null, patch: ConfigPatch):
       advisor = undefined;
     } else {
       advisor = {
-        enabled: patch.advisor.enabled ?? advisor?.enabled ?? true,
+        enabled: patch.advisor.enabled ?? advisor?.enabled ?? DEFAULT_ADVISOR_CONFIG.enabled,
         mode: patch.advisor.mode ?? advisor?.mode ?? 'auto',
-        modelId: patch.advisor.modelId !== undefined ? patch.advisor.modelId : (advisor?.modelId ?? null),
+        modelId:
+          patch.advisor.modelId !== undefined
+            ? patch.advisor.modelId
+            : (advisor?.modelId ?? null),
         contextPolicy: 'full-relevant',
-        shareSensitive: patch.advisor.shareSensitive ?? advisor?.shareSensitive ?? false,
+        shareSensitive:
+          patch.advisor.shareSensitive ?? advisor?.shareSensitive ?? false,
         inputTokenBudget: normalizeLimited(
           patch.advisor.inputTokenBudget ?? advisor?.inputTokenBudget,
-          CONFIG_LIMITS.advisorInputTokenBudget, 128_000),
+          CONFIG_LIMITS.advisorInputTokenBudget,
+          DEFAULT_ADVISOR_CONFIG.inputTokenBudget,
+        ),
         timeoutMs: normalizeLimited(
           patch.advisor.timeoutMs ?? advisor?.timeoutMs,
-          CONFIG_LIMITS.advisorTimeoutMs, 180_000),
+          CONFIG_LIMITS.advisorTimeoutMs,
+          DEFAULT_ADVISOR_CONFIG.timeoutMs,
+        ),
       };
     }
   }
   // 顾问引用的模型若已被删除或禁用，级联置空（软失联——解析层已把 null/悬空 id 当
   // 「未配置」优雅处理，不留死链接；这与基座模型的硬阻止是刻意的不对称：顾问本来就是
   // 可降级的第二意见，不像基座那样「没有就整个应用跑不起来」）。
-  if (advisor?.modelId) {
+  if (advisor?.modelId && !advisor.modelId.startsWith('online:')) {
     const referenced = models.find((entry) => entry.id === advisor!.modelId);
-    if (!referenced || referenced.enabled === false) advisor = { ...advisor, modelId: null };
+    if (!referenced || referenced.enabled === false)
+      advisor = { ...advisor, modelId: null };
+  }
+
+  const workflowModels: WorkflowModelRoles = {
+    ...(base?.workflowModels ?? {}),
+  };
+  for (const [role, modelId] of Object.entries(patch.workflowModels ?? {})) {
+    if (modelId) workflowModels[role] = modelId;
+    else delete workflowModels[role];
+  }
+  for (const role of Object.keys(workflowModels)) {
+    const modelId = workflowModels[role];
+    const configured = models.find((entry) => entry.id === modelId);
+    if (!configured || configured.enabled === false)
+      delete workflowModels[role];
   }
 
   // 比例类：保留 4 位小数（= 百分比 2 位），否则 UI 上下箭头按 0.01 步进会累加出
   // `0.8500000000000001` 这种浮点脏值直接写进 config.json。
-  const compactRatio = patch.compactRatio !== undefined
-    ? (patch.compactRatio > 0 && patch.compactRatio <= 1
-      ? normalizeLimited(patch.compactRatio, CONFIG_LIMITS.compactRatio, CONFIG_LIMITS.compactRatio.max)
-      : undefined)
-    : base?.compactRatio;
+  const compactRatio =
+    patch.compactRatio !== undefined
+      ? patch.compactRatio > 0 && patch.compactRatio <= 1
+        ? normalizeLimited(
+            patch.compactRatio,
+            CONFIG_LIMITS.compactRatio,
+            CONFIG_LIMITS.compactRatio.max,
+          )
+        : undefined
+      : base?.compactRatio;
 
-  const tools: ToolConfigs = { ...(base?.tools ?? {}) };
+  let tools: ToolConfigs = { ...(base?.tools ?? {}) };
   const drafts = structuredClone(base?.drafts ?? {});
   const toolPatch = patch.tools;
   if (toolPatch?.webSearch) {
-    if (toolPatch.webSearch.clear) { delete tools.webSearch; delete drafts.tools?.webSearch; }
-    else tools.webSearch = mergeRecord(tools.webSearch, { provider: 'tavily', ...toolPatch.webSearch }) as ToolConfigs['webSearch'];
+    if (toolPatch.webSearch.clear) {
+      tools = omitKey(tools, 'webSearch') ?? {};
+      if (drafts.tools) drafts.tools = omitKey(drafts.tools, 'webSearch');
+    } else
+      tools.webSearch = mergeRecord(tools.webSearch, {
+        provider: 'tavily',
+        ...toolPatch.webSearch,
+      }) as ToolConfigs['webSearch'];
   }
   if (toolPatch?.imageGeneration) {
-    if (toolPatch.imageGeneration.clear) { delete tools.imageGeneration; delete drafts.tools?.imageGeneration; }
-    else {
-      const next = mergeRecord(tools.imageGeneration, toolPatch.imageGeneration) as NonNullable<ToolConfigs['imageGeneration']>;
+    if (toolPatch.imageGeneration.clear) {
+      tools = omitKey(tools, 'imageGeneration') ?? {};
+      if (drafts.tools) drafts.tools = omitKey(drafts.tools, 'imageGeneration');
+    } else {
+      const next = mergeRecord(
+        tools.imageGeneration,
+        toolPatch.imageGeneration,
+      ) as NonNullable<ToolConfigs['imageGeneration']>;
       if (toolPatch.imageGeneration.clearApiKey) next.apiKey = '';
-      delete (next as typeof next & { clear?: boolean; clearApiKey?: boolean }).clear;
-      delete (next as typeof next & { clear?: boolean; clearApiKey?: boolean }).clearApiKey;
-      if (!next.baseURL || !next.apiKey || !next.model) throw new Error('图片生成缺少 Base URL、API Key 或模型名称');
-      tools.imageGeneration = next;
+      const cleanNext = omitKey(
+        omitKey(
+          next as typeof next & { clear?: boolean; clearApiKey?: boolean },
+          'clear',
+        ),
+        'clearApiKey',
+      ) as NonNullable<ToolConfigs['imageGeneration']>;
+      if (!cleanNext.baseURL || !cleanNext.apiKey || !cleanNext.model)
+        throw new Error('图片生成缺少 Base URL、API Key 或模型名称');
+      tools.imageGeneration = cleanNext;
     }
   }
   if (toolPatch?.openRouter) {
-    if (toolPatch.openRouter.clear) { delete tools.openRouter; delete drafts.tools?.openRouter; }
-    else tools.openRouter = mergeRecord(tools.openRouter, toolPatch.openRouter) as ToolConfigs['openRouter'];
+    if (toolPatch.openRouter.clear) {
+      tools = omitKey(tools, 'openRouter') ?? {};
+      if (drafts.tools) drafts.tools = omitKey(drafts.tools, 'openRouter');
+    } else
+      tools.openRouter = mergeRecord(
+        tools.openRouter,
+        toolPatch.openRouter,
+      ) as ToolConfigs['openRouter'];
   }
   if (toolPatch?.textToSpeech) {
-    if (toolPatch.textToSpeech.clear) { delete tools.textToSpeech; delete drafts.tools?.textToSpeech; }
-    else {
-      const next = mergeRecord(tools.textToSpeech, { provider: 'minimax', ...toolPatch.textToSpeech }) as NonNullable<ToolConfigs['textToSpeech']>;
+    if (toolPatch.textToSpeech.clear) {
+      tools = omitKey(tools, 'textToSpeech') ?? {};
+      if (drafts.tools) drafts.tools = omitKey(drafts.tools, 'textToSpeech');
+    } else {
+      const next = mergeRecord(tools.textToSpeech, {
+        provider: 'minimax',
+        ...toolPatch.textToSpeech,
+      }) as NonNullable<ToolConfigs['textToSpeech']>;
       if (toolPatch.textToSpeech.clearApiKey) next.apiKey = '';
-      delete (next as typeof next & { clear?: boolean; clearApiKey?: boolean }).clear;
-      delete (next as typeof next & { clear?: boolean; clearApiKey?: boolean }).clearApiKey;
-      if (!next.apiKey || !next.groupId) throw new Error('MiniMax 语音缺少 API Key 或 Group ID');
-      tools.textToSpeech = next;
+      const cleanNext = omitKey(
+        omitKey(
+          next as typeof next & { clear?: boolean; clearApiKey?: boolean },
+          'clear',
+        ),
+        'clearApiKey',
+      ) as NonNullable<ToolConfigs['textToSpeech']>;
+      if (!cleanNext.apiKey || !cleanNext.groupId)
+        throw new Error('MiniMax 语音缺少 API Key 或 Group ID');
+      tools.textToSpeech = cleanNext;
     }
   }
   // 数字字段必须在**写入时**就按同一份边界规整——此前这里是裸 spread，读回时才被
   // parseSubagents 的边界收窄，于是「存进去 300、读出来 100」，UI 表现成静默变回原值。
-  const mergedSubagents = { ...(base?.subagents ?? DEFAULT_SUBAGENTS_CONFIG), ...(patch.subagents ?? {}) };
+  const mergedSubagents = {
+    ...(base?.subagents ?? DEFAULT_SUBAGENTS_CONFIG),
+    ...(patch.subagents ?? {}),
+  };
   const subagents: SubagentsConfig = {
     ...mergedSubagents,
-    maxCallsPerTurn: normalizeLimited(mergedSubagents.maxCallsPerTurn, CONFIG_LIMITS.subagentMaxCallsPerTurn, DEFAULT_SUBAGENTS_CONFIG.maxCallsPerTurn),
-    maxConcurrent: normalizeLimited(mergedSubagents.maxConcurrent, CONFIG_LIMITS.subagentMaxConcurrent, DEFAULT_SUBAGENTS_CONFIG.maxConcurrent),
-    timeoutMs: normalizeLimited(mergedSubagents.timeoutMs, CONFIG_LIMITS.subagentTimeoutMs, DEFAULT_SUBAGENTS_CONFIG.timeoutMs),
-    exploreMaxTurns: normalizeLimited(mergedSubagents.exploreMaxTurns, CONFIG_LIMITS.subagentExploreMaxTurns, DEFAULT_SUBAGENTS_CONFIG.exploreMaxTurns),
-    generalMaxTurns: normalizeLimited(mergedSubagents.generalMaxTurns, CONFIG_LIMITS.subagentGeneralMaxTurns, DEFAULT_SUBAGENTS_CONFIG.generalMaxTurns),
+    maxCallsPerTurn: normalizeLimited(
+      mergedSubagents.maxCallsPerTurn,
+      CONFIG_LIMITS.subagentMaxCallsPerTurn,
+      DEFAULT_SUBAGENTS_CONFIG.maxCallsPerTurn,
+    ),
+    maxConcurrent: normalizeLimited(
+      mergedSubagents.maxConcurrent,
+      CONFIG_LIMITS.subagentMaxConcurrent,
+      DEFAULT_SUBAGENTS_CONFIG.maxConcurrent,
+    ),
+    timeoutMs: normalizeLimited(
+      mergedSubagents.timeoutMs,
+      CONFIG_LIMITS.subagentTimeoutMs,
+      DEFAULT_SUBAGENTS_CONFIG.timeoutMs,
+    ),
+    exploreMaxTurns: normalizeLimited(
+      mergedSubagents.exploreMaxTurns,
+      CONFIG_LIMITS.subagentExploreMaxTurns,
+      DEFAULT_SUBAGENTS_CONFIG.exploreMaxTurns,
+    ),
+    generalMaxTurns: normalizeLimited(
+      mergedSubagents.generalMaxTurns,
+      CONFIG_LIMITS.subagentGeneralMaxTurns,
+      DEFAULT_SUBAGENTS_CONFIG.generalMaxTurns,
+    ),
+  };
+  const browser: BrowserConfig = {
+    ...(base?.browser ?? DEFAULT_BROWSER_CONFIG),
+    ...(patch.browser ?? {}),
+    profileId: 'default',
   };
-  const browser: BrowserConfig = { ...(base?.browser ?? DEFAULT_BROWSER_CONFIG), ...(patch.browser ?? {}), profileId: 'default' };
   const computerUse: ComputerUseConfig = {
     ...(base?.computerUse ?? DEFAULT_COMPUTER_USE_CONFIG),
     ...(patch.computerUse ?? {}),
   };
   computerUse.observationFrames = 1;
   computerUse.maxImagePixels = normalizeLimited(
-    computerUse.maxImagePixels, CONFIG_LIMITS.computerUseMaxImagePixels, DEFAULT_COMPUTER_USE_CONFIG.maxImagePixels);
-  if (!hasEntries(drafts.tools)) delete drafts.tools;
-  return { models, baseModelId, ...(compactRatio !== undefined ? { compactRatio } : {}), advisor, subagents, browser, computerUse, tools, ...(hasEntries(drafts) ? { drafts } : {}) };
+    computerUse.maxImagePixels,
+    CONFIG_LIMITS.computerUseMaxImagePixels,
+    DEFAULT_COMPUTER_USE_CONFIG.maxImagePixels,
+  );
+  if (!hasEntries(drafts.tools)) drafts.tools = undefined;
+  return {
+    models,
+    baseModelId,
+    teamServerUrl,
+    ...(compactRatio !== undefined ? { compactRatio } : {}),
+    advisor,
+    // Preserve an explicit empty object through updateMinimalAgentConfig so
+    // removing the final role is distinguishable from an unrelated mutator
+    // that omitted this optional field.
+    workflowModels,
+    subagents,
+    browser,
+    computerUse,
+    tools,
+    ...(hasEntries(drafts) ? { drafts } : {}),
+  };
 }
 
 /** 仅不完整工具凭据使用草稿桶；其余设置都通过 patch 立即生效。 */
@@ -361,9 +665,16 @@ export type AutosaveSection = 'tools';
 export type AutosaveState = 'applied' | 'draft';
 
 export class ConfigService {
-  private snapshot: ConfigSnapshot = { source: 'none', readOnly: false, config: null, revision: 0 };
+  private snapshot: ConfigSnapshot = {
+    source: 'none',
+    readOnly: false,
+    config: null,
+    revision: 0,
+  };
 
-  get revision(): number { return this.snapshot.revision; }
+  get revision(): number {
+    return this.snapshot.revision;
+  }
 
   async reload(): Promise<ConfigSnapshot> {
     const envOnly = process.env.MINIMAL_AGENT_CONFIG_MODE === 'env';
@@ -374,11 +685,15 @@ export class ConfigService {
       readOnly: envOnly,
       config: json ?? env,
     };
-    const changed = this.snapshot.revision === 0
-      || this.snapshot.source !== next.source
-      || this.snapshot.readOnly !== next.readOnly
-      || JSON.stringify(this.snapshot.config) !== JSON.stringify(next.config);
-    this.snapshot = { ...next, revision: changed ? this.snapshot.revision + 1 : this.snapshot.revision };
+    const changed =
+      this.snapshot.revision === 0 ||
+      this.snapshot.source !== next.source ||
+      this.snapshot.readOnly !== next.readOnly ||
+      JSON.stringify(this.snapshot.config) !== JSON.stringify(next.config);
+    this.snapshot = {
+      ...next,
+      revision: changed ? this.snapshot.revision + 1 : this.snapshot.revision,
+    };
     return this.getSnapshot();
   }
 
@@ -394,21 +709,166 @@ export class ConfigService {
     return resolveProvider(entry, config?.compactRatio);
   }
 
+  /**
+   * 团队登录服务器的默认地址：env 优先于 config.json，跟随 minimal-desktop 的
+   * `resolve_social_server()`（`src-tauri/src/lib.rs`）已验证的同一优先级——这两个
+   * 项目共享 `KAKADEAI_SOCIAL_SERVER_URL` 这一个环境变量名，语义必须一致，不能
+   * minimal-agent 这边搞成 config 优先。
+   *
+   * ⚠️ 不能简单读 `getSnapshot().config?.teamServerUrl`：那个 snapshot 在存在
+   * config.json 时完全不看 env（`reload()` 里 `config: json ?? env`，env 只在
+   * **没有** config.json 时才整体生效），会让"config.json 存在但没配地址、同时设了
+   * env"这种常见场景里 env 被错误地忽略。这里必须独立读 `process.env`。
+   *
+   * 返回值带 `source`，供诊断和私有部署使用；正式用户不需要接触服务器地址。
+   */
+  async resolveTeamServerUrl(): Promise<{
+    value: string | null;
+    source: 'env' | 'config' | 'default' | 'none';
+  }> {
+    const rawEnvValue = process.env.KAKADEAI_SOCIAL_SERVER_URL;
+    if (rawEnvValue !== undefined)
+      return {
+        value: rawEnvValue.trim() || null,
+        source: 'env',
+      };
+    const { config } = await this.getSnapshot();
+    const configValue = config?.teamServerUrl ?? null;
+    return configValue
+      ? { value: configValue, source: 'config' }
+      : { value: 'https://kakadeai.com', source: 'default' };
+  }
+
   async providerForModel(modelId?: string | null): Promise<Provider | null> {
     if (!modelId) return this.provider();
+    const ref = modelRefFromLegacy(modelId);
+    if (ref.source === 'gateway') {
+      const resolved = await this.providerForRef(ref);
+      return resolved;
+    }
     const { config } = await this.getSnapshot();
     const entry = config?.models.find((m) => m.id === modelId);
     if (!entry?.apiKey) return null;
     return resolveProvider(entry, config?.compactRatio);
   }
 
+  /** Resolve a portable workflow role from fresh cross-process config. */
+  async providerForWorkflowRole(role: string): Promise<Provider | null> {
+    const { config } = await this.reload();
+    const modelId = config?.workflowModels?.[role];
+    return modelId ? this.providerForModel(modelId) : null;
+  }
+
+  private async providerForGatewayModel(
+    modelId: string,
+  ): Promise<Provider | null> {
+    // A remembered gateway model must not make standalone mode inspect the
+    // team credential file or attempt a network request.  The configured
+    // server is the explicit opt-in boundary; credentials are read only after
+    // it is present.
+    const configured = await this.resolveTeamServerUrl();
+    if (!configured.value) return null;
+    const resolved = await resolveOnlineModel(
+      modelId,
+      configured.value ?? undefined,
+    ).catch(() => null);
+    if (!resolved) return null;
+    const { credentials, model } = resolved;
+    if (model.availability && model.availability.state !== 'available')
+      return null;
+    return gatewayProviderFromModel(credentials, model);
+  }
+
+  /** Resolve the persisted source-aware identity without making callers encode
+   * gateway selections as the legacy `online:<id>` string. */
+  async providerForRef(ref?: ModelRef | null): Promise<Provider | null> {
+    if (!ref) return this.provider();
+    return ref.source === 'gateway'
+      ? this.providerForGatewayModel(ref.modelId)
+      : this.providerForModel(ref.modelId);
+  }
+
+  /**
+   * Resolve a persisted model reference and retain the reason when a gateway
+   * model cannot be used.  The reason is intentionally kept at the local
+   * session boundary: it is UI/selection state, not a server-side session or
+   * prompt record.
+   */
+  async resolveModelRef(ref?: ModelRef | null): Promise<ModelResolution> {
+    if (!ref)
+      return {
+        provider: await this.providerForModel(null),
+        fallbackReason: null,
+      };
+    if (ref.source === 'local')
+      return {
+        provider: await this.providerForRef(ref),
+        fallbackReason: null,
+      };
+
+    const configured = await this.resolveTeamServerUrl();
+    if (!configured.value)
+      return { provider: null, fallbackReason: 'logged_out' };
+    const credentials = await loadTeamCredentials(configured.value);
+    if (!credentials) return { provider: null, fallbackReason: 'logged_out' };
+    try {
+      const models = await fetchOnlineModels(credentials);
+      const model = models.find((item) => item.id === ref.modelId);
+      if (!model) return { provider: null, fallbackReason: 'grant_revoked' };
+      if (
+        model.availability?.state !== undefined &&
+        model.availability.state !== 'available'
+      )
+        return {
+          provider: null,
+          fallbackReason: gatewayFallbackReason(model),
+        };
+      return {
+        provider: gatewayProviderFromModel(credentials, model),
+        fallbackReason: null,
+      };
+    } catch (error) {
+      return {
+        provider: null,
+        fallbackReason: gatewayFallbackReason(undefined, error),
+      };
+    }
+  }
+
+  /** Online defaults are server-owned and fetched only when team credentials
+   * exist.  No standalone launch calls this path. */
+  async onlineDefaultProvider(): Promise<Provider | null> {
+    const configured = await this.resolveTeamServerUrl();
+    if (!configured.value) return null;
+    const credentials = await import('../team/auth.js')
+      .then((module) =>
+        module.loadTeamCredentials(configured.value ?? undefined),
+      )
+      .catch(() => null);
+    if (!credentials) return null;
+    const models = await import('../team/auth.js')
+      .then((module) => module.fetchOnlineModels(credentials))
+      .catch(() => []);
+    const model = models.find(
+      (item) =>
+        item.isDefault &&
+        (!item.availability || item.availability.state === 'available'),
+    );
+    if (!model) return null;
+    return gatewayProviderFromModel(credentials, model);
+  }
+
   /** 带 apiKey 的原始列表——仅服务端内部消费（桌面端 store.ts 的 readConfig() 会脱敏成 ModelView）。 */
   async models(): Promise<ModelConfig[]> {
     return (await this.getSnapshot()).config?.models ?? [];
   }
 
   async model(id: string): Promise<ModelConfig | null> {
-    return (await this.getSnapshot()).config?.models.find((entry) => entry.id === id) ?? null;
+    return (
+      (await this.getSnapshot()).config?.models.find(
+        (entry) => entry.id === id,
+      ) ?? null
+    );
   }
 
   /**
@@ -419,16 +879,33 @@ export class ConfigService {
    * ModelConfig 镜像到返回对象顶层，让 advisor.ts 的 `advisor.supportsVision` 读取方式
    * 保持不变——它是解析后的便利视图，不是存储形状本身。
    */
-  async advisor(): Promise<(AdvisorConfig & { provider: Provider; supportsVision: boolean }) | null> {
+  async advisor(): Promise<
+    (AdvisorConfig & { provider: Provider; supportsVision: boolean }) | null
+  > {
     // fresh reload（不用 getSnapshot 的缓存）——CLI/TUI/Desktop/Cron 共享同一份 config.json，
     // 跨进程时缓存会读到过期状态（如 A 进程 /advisor off 后 B 进程仍判定已启用）。这条不变量
     // 由 test/configService.test.ts 的 "advisor() always does a fresh reload" 用例锁定。
     const { config } = await this.reload();
     const advisor = config?.advisor;
     if (!advisor?.modelId) return null;
+    const advisorRef = modelRefFromLegacy(advisor.modelId);
+    if (advisorRef.source === 'gateway') {
+      const provider = await this.providerForRef(advisorRef);
+      return provider
+        ? {
+            ...advisor,
+            provider,
+            supportsVision: provider.supportsVision !== false,
+          }
+        : null;
+    }
     const entry = config!.models.find((m) => m.id === advisor.modelId);
     if (!entry?.apiKey) return null;
-    return { ...advisor, provider: resolveProvider(entry), supportsVision: entry.supportsVision !== false };
+    return {
+      ...advisor,
+      provider: resolveProvider(entry),
+      supportsVision: entry.supportsVision !== false,
+    };
   }
 
   /**
@@ -440,12 +917,27 @@ export class ConfigService {
    * resolveAvailability 是在主循环构造工具集时同步调用的，不能 await；
    * 而且每次工具集构造都读盘的话开销太大（主循环每轮都可能构造一次）。
    */
-  advisorAvailabilitySync(): { enabled: boolean; mode: 'auto' | 'manual'; modelId: string | null; configured: boolean } {
+  advisorAvailabilitySync(): {
+    enabled: boolean;
+    mode: 'auto' | 'manual';
+    modelId: string | null;
+    configured: boolean;
+  } {
     const config = this.snapshot.config;
     const advisor = config?.advisor;
-    if (!advisor?.modelId) return { enabled: false, mode: 'auto', modelId: null, configured: false };
+    if (!advisor?.modelId)
+      return { enabled: false, mode: 'auto', modelId: null, configured: false };
+    if (modelRefFromLegacy(advisor.modelId).source === 'gateway') {
+      return {
+        enabled: advisor.enabled !== false,
+        mode: advisor.mode === 'manual' ? 'manual' : 'auto',
+        modelId: advisor.modelId,
+        configured: true,
+      };
+    }
     const entry = config?.models?.find((m) => m.id === advisor.modelId);
-    if (!entry?.apiKey) return { enabled: false, mode: 'auto', modelId: null, configured: false };
+    if (!entry?.apiKey)
+      return { enabled: false, mode: 'auto', modelId: null, configured: false };
     return {
       enabled: advisor.enabled !== false,
       mode: advisor.mode === 'manual' ? 'manual' : 'auto',
@@ -463,7 +955,9 @@ export class ConfigService {
   }
 
   async computerUse(): Promise<ComputerUseConfig> {
-    return (await this.reload()).config?.computerUse ?? DEFAULT_COMPUTER_USE_CONFIG;
+    return (
+      (await this.reload()).config?.computerUse ?? DEFAULT_COMPUTER_USE_CONFIG
+    );
   }
 
   async tool<K extends ToolConfigKey>(key: K): Promise<ToolConfigs[K]> {
@@ -473,53 +967,104 @@ export class ConfigService {
   async toolStatus(): Promise<Record<ToolConfigKey, ToolStatus>> {
     const tools = (await this.reload()).config?.tools ?? {};
     return {
-      webSearch: { state: tools.webSearch ? 'configured' : 'unconfigured', configured: !!tools.webSearch },
-      imageGeneration: { state: tools.imageGeneration ? 'configured' : 'unconfigured', configured: !!tools.imageGeneration },
-      openRouter: { state: tools.openRouter ? 'configured' : 'unconfigured', configured: !!tools.openRouter },
-      textToSpeech: { state: tools.textToSpeech ? 'configured' : 'unconfigured', configured: !!tools.textToSpeech },
+      webSearch: {
+        state: tools.webSearch ? 'configured' : 'unconfigured',
+        configured: !!tools.webSearch,
+      },
+      imageGeneration: {
+        state: tools.imageGeneration ? 'configured' : 'unconfigured',
+        configured: !!tools.imageGeneration,
+      },
+      openRouter: {
+        state: tools.openRouter ? 'configured' : 'unconfigured',
+        configured: !!tools.openRouter,
+      },
+      textToSpeech: {
+        state: tools.textToSpeech ? 'configured' : 'unconfigured',
+        configured: !!tools.textToSpeech,
+      },
     };
   }
 
   async savePatch(patch: ConfigPatch): Promise<ConfigSnapshot> {
     const current = await this.getSnapshot();
-    if (current.readOnly) throw new Error('当前使用环境变量只读配置，不能从设置页修改');
-    await updateMinimalAgentConfig((latest) => applyConfigPatch(latest ?? current.config, patch));
+    if (current.readOnly)
+      throw new Error('当前使用环境变量只读配置，不能从设置页修改');
+    await updateMinimalAgentConfig((latest) =>
+      applyConfigPatch(latest ?? current.config, patch),
+    );
     return this.reload();
   }
 
   /** 现在只服务 tools 分区的实时录入表单（imageGeneration/textToSpeech 多字段、可能中途非法）。 */
-  async autosave(section: AutosaveSection, patch: ConfigPatch): Promise<{ snapshot: ConfigSnapshot; state: AutosaveState; draftFields: string[] }> {
+  async autosave(
+    section: AutosaveSection,
+    patch: ConfigPatch,
+  ): Promise<{
+    snapshot: ConfigSnapshot;
+    state: AutosaveState;
+    draftFields: string[];
+  }> {
     void section;
     const current = await this.getSnapshot();
-    if (current.readOnly) throw new Error('当前使用环境变量只读配置，不能从设置页修改');
+    if (current.readOnly)
+      throw new Error('当前使用环境变量只读配置，不能从设置页修改');
     if (!current.config) throw new Error('请先添加至少一个模型');
     let state: AutosaveState = 'applied';
     const draftFields: string[] = [];
     await updateMinimalAgentConfig((latest) => {
       let active = latest ?? current.config!;
-      if (patch.subagents) active = { version: 4, ...applyConfigPatch(active, { subagents: patch.subagents }), savedAt: active.savedAt };
-      if (patch.computerUse) active = { version: 4, ...applyConfigPatch(active, { computerUse: patch.computerUse }), savedAt: active.savedAt };
+      if (patch.subagents)
+        active = {
+          version: 4,
+          ...applyConfigPatch(active, { subagents: patch.subagents }),
+          savedAt: active.savedAt,
+        };
+      if (patch.computerUse)
+        active = {
+          version: 4,
+          ...applyConfigPatch(active, { computerUse: patch.computerUse }),
+          savedAt: active.savedAt,
+        };
       const drafts = structuredClone(active.drafts ?? {});
       for (const key of Object.keys(patch.tools ?? {})) {
-        const rawPiece = patch.tools![key as keyof NonNullable<ConfigPatch['tools']>];
+        const rawPiece =
+          patch.tools![key as keyof NonNullable<ConfigPatch['tools']>];
         if (!rawPiece) continue;
-        const previous = (drafts.tools ?? {})[key];
-        const merged = mergeRecord(previous, rawPiece as Record<string, unknown>);
+        const previous = drafts.tools?.[key];
+        const merged = mergeRecord(
+          previous,
+          rawPiece as Record<string, unknown>,
+        );
         try {
-          active = { version: 4, ...applyConfigPatch(active, { tools: { [key]: merged } as ConfigPatch['tools'] }), savedAt: active.savedAt };
-          delete drafts.tools?.[key];
+          active = {
+            version: 4,
+            ...applyConfigPatch(active, {
+              tools: { [key]: merged } as ConfigPatch['tools'],
+            }),
+            savedAt: active.savedAt,
+          };
+          drafts.tools = omitKey(drafts.tools, key);
         } catch {
           state = 'draft';
           draftFields.push(key);
-          (drafts.tools ??= {})[key] = merged;
+          const toolDrafts = drafts.tools ?? {};
+          toolDrafts[key] = merged;
+          drafts.tools = toolDrafts;
         }
       }
-      if (!hasEntries(drafts.tools)) delete drafts.tools;
+      if (!hasEntries(drafts.tools)) drafts.tools = undefined;
       return {
-        models: active.models, baseModelId: active.baseModelId,
-        ...(active.compactRatio !== undefined ? { compactRatio: active.compactRatio } : {}),
-        advisor: active.advisor, subagents: active.subagents, browser: active.browser,
-        computerUse: active.computerUse, tools: active.tools,
+        models: active.models,
+        baseModelId: active.baseModelId,
+        ...(active.compactRatio !== undefined
+          ? { compactRatio: active.compactRatio }
+          : {}),
+        advisor: active.advisor,
+        subagents: active.subagents,
+        browser: active.browser,
+        computerUse: active.computerUse,
+        tools: active.tools,
         ...(hasEntries(drafts) ? { drafts } : {}),
       };
     });
@@ -530,14 +1075,22 @@ export class ConfigService {
 export const configService = new ConfigService();
 
 export const SENSITIVE_ENV_KEYS = new Set([
-  'MINIMAL_AGENT_API_KEY', 'TAVILY_API_KEY', 'OPENAI_IMAGE_API_KEY',
-  'OPENROUTER_API_KEY', 'MINIMAX_API_KEY', 'MINIMAX_GROUP_ID',
+  'MINIMAL_AGENT_API_KEY',
+  'TAVILY_API_KEY',
+  'OPENAI_IMAGE_API_KEY',
+  'OPENROUTER_API_KEY',
+  'MINIMAX_API_KEY',
+  'MINIMAX_GROUP_ID',
 ]);
 
 /** Child processes inherit normal runtime variables, never model or tool credentials. */
-export function sanitizeCredentialEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = { ...source };
-  for (const key of SENSITIVE_ENV_KEYS) delete env[key];
+export function sanitizeCredentialEnv(
+  source: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  let env: NodeJS.ProcessEnv = { ...source };
+  for (const key of SENSITIVE_ENV_KEYS) {
+    env = omitKey(env, key) ?? {};
+  }
   return env;
 }
 
@@ -550,28 +1103,33 @@ export async function trustedToolEnv(
     let cfg = await service.tool('imageGeneration');
     if (!cfg) {
       const openRouter = await service.tool('openRouter');
-      if (openRouter) cfg = {
-        provider: 'openrouter',
-        baseURL: 'https://openrouter.ai/api/v1',
-        apiKey: openRouter.apiKey,
-        model: 'google/gemini-3-pro-image-preview',
-        protocol: 'chat',
-      };
+      if (openRouter)
+        cfg = {
+          provider: 'openrouter',
+          baseURL: 'https://openrouter.ai/api/v1',
+          apiKey: openRouter.apiKey,
+          model: 'google/gemini-3-pro-image-preview',
+          protocol: 'chat',
+        };
     }
     if (cfg) {
       env.OPENAI_IMAGE_PROVIDER = cfg.provider;
       env.OPENAI_IMAGE_BASE_URL = cfg.baseURL;
       env.OPENAI_IMAGE_API_KEY = cfg.apiKey;
       env.OPENAI_IMAGE_MODEL = cfg.model;
-      if (cfg.protocol && cfg.protocol !== 'auto') env.OPENAI_IMAGE_PROTOCOL = cfg.protocol;
-      else delete env.OPENAI_IMAGE_PROTOCOL;
+      if (cfg.protocol && cfg.protocol !== 'auto')
+        env.OPENAI_IMAGE_PROTOCOL = cfg.protocol;
+      else env.OPENAI_IMAGE_PROTOCOL = undefined;
     }
   } else if (kind === 'openRouter') {
     const cfg = await service.tool('openRouter');
     if (cfg) env.OPENROUTER_API_KEY = cfg.apiKey;
   } else {
     const cfg = await service.tool('textToSpeech');
-    if (cfg) { env.MINIMAX_API_KEY = cfg.apiKey; env.MINIMAX_GROUP_ID = cfg.groupId; }
+    if (cfg) {
+      env.MINIMAX_API_KEY = cfg.apiKey;
+      env.MINIMAX_GROUP_ID = cfg.groupId;
+    }
   }
   return env;
 }