minimal-agent 0.10.0 → 0.12.0

package/src/config/configService.ts

@@ -0,0 +1,554 @@
+import { randomUUID } from 'node:crypto';
+
+import type { Provider } from '../types.js';
+import {
+  readMinimalAgentConfig,
+  updateMinimalAgentConfig,
+  defaultMaxTokens,
+  type MinimalAgentConfig,
+  type AdvisorConfig,
+  type ModelConfig,
+  type ApiFormat,
+  type ToolConfigs,
+  type SubagentsConfig,
+  type BrowserConfig,
+  type ComputerUseConfig,
+  DEFAULT_SUBAGENTS_CONFIG,
+  DEFAULT_BROWSER_CONFIG,
+  DEFAULT_COMPUTER_USE_CONFIG,
+} from './configFile.js';
+import { CONFIG_LIMITS, normalizeLimited } from './numericLimits.js';
+
+export type ConfigSource = 'json' | 'environment' | 'none';
+export type ToolConfigKey = keyof ToolConfigs;
+export type ToolStatusState = 'unconfigured' | 'configured' | 'incomplete';
+
+export interface ToolStatus {
+  state: ToolStatusState;
+  configured: boolean;
+}
+
+export interface ConfigSnapshot {
+  source: ConfigSource;
+  readOnly: boolean;
+  config: MinimalAgentConfig | null;
+  revision: number;
+}
+
+/**
+ * 模型列表的三种变更操作——加/改/删，走同一个 ConfigPatch 提交（不新开一族方法）。
+ * `add` 的字段全 Partial（不是 Omit 后的必填）：必填校验在 applyModelsPatch 里运行时做
+ * （防御性 `m.baseURL?.trim()` 风格 + 清晰的中文报错），类型层不重复这份校验，两者保持一致
+ * 而不是「类型说必填、实现却防着 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: 'remove'; id: string };
+
+export interface ConfigPatch {
+  models?: ModelOp[];
+  baseModelId?: string | null;
+  compactRatio?: number;
+  advisor?: (Partial<Omit<AdvisorConfig, 'contextPolicy'>> & { clear?: boolean });
+  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 };
+  };
+}
+
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+
+function positiveInt(value: string | undefined, fallback: number): number {
+  const parsed = Number.parseInt(value ?? '', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+/**
+ * 纯 env 自举路径（无 JSON 配置文件时的兜底）。只产出 OpenAI 格式的模型——Anthropic 格式
+ * 只能通过 JSON 配置（Desktop/CLI）新增，这是刻意的范围限制，不是遗漏。
+ *
+ * 顾问不再有独立的 env 自举路径（ADVISOR_AGENT_* 家族整体移除）——顾问配置以后只能通过
+ * JSON 配置的 `advisor.modelId` 引用模型列表条目，没有 JSON 时顾问就是未配置。
+ *
+ * ⚠️ 这里派生的模型 id/createdAt/updatedAt 必须是固定字面量，不能用 randomUUID()/Date.now()——
+ * configFromEnv() 在每次 reload() 都会重新构造，reload() 靠 JSON.stringify 差异判断 revision
+ * 是否变化；任何一次性值都会让 env 模式下每次 reload 的 revision 都在跳，进而每轮对话都触发
+ * 桌面端 resetProvider()。
+ */
+function configFromEnv(): MinimalAgentConfig | null {
+  const baseURL = process.env.MINIMAL_AGENT_BASE_URL;
+  const apiKey = process.env.MINIMAL_AGENT_API_KEY;
+  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) {
+    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',
+    };
+  }
+  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 };
+  }
+  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 envModel: ModelConfig = {
+    id: 'env-base',
+    apiFormat: 'openai',
+    ...(name !== 'env' ? { displayName: name } : {}),
+    baseURL,
+    apiKey,
+    model,
+    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',
+    },
+    enabled: true,
+    createdAt: 0,
+    updatedAt: 0,
+  };
+  return {
+    version: 4,
+    models: [envModel],
+    baseModelId: envModel.id,
+    ...(compactRatio > 0 && compactRatio <= 1 ? { compactRatio } : {}),
+    subagents: {
+      ...DEFAULT_SUBAGENTS_CONFIG,
+      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),
+    },
+    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,
+      ))),
+      observationFrames: 1,
+    },
+    tools,
+    savedAt: 0,
+  };
+}
+
+function resolveProvider(entry: ModelConfig, compactRatio?: number): Provider {
+  return {
+    name: entry.displayName ?? entry.model,
+    baseURL: entry.baseURL,
+    apiKey: entry.apiKey,
+    model: entry.model,
+    contextWindow: entry.contextWindow,
+    maxTokens: entry.maxTokens ?? defaultMaxTokens(entry.contextWindow),
+    apiFormat: entry.apiFormat,
+    supportsVision: entry.supportsVision !== false,
+    promptCache: entry.promptCache ?? { mode: 'auto' },
+    ...(compactRatio !== undefined ? { compactRatio } : {}),
+  };
+}
+
+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,
+        value as Record<string, unknown>,
+      );
+    } else if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+function hasEntries(value: object | undefined): boolean {
+  return !!value && Object.keys(value).length > 0;
+}
+
+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 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');
+      out.push({
+        id: randomUUID(),
+        apiFormat,
+        ...(m.displayName?.trim() ? { displayName: m.displayName.trim() } : {}),
+        baseURL,
+        apiKey,
+        model: modelId,
+        contextWindow: m.contextWindow && m.contextWindow > 0 ? m.contextWindow : DEFAULT_CONTEXT_WINDOW,
+        ...(m.maxTokens ? { maxTokens: m.maxTokens } : {}),
+        supportsVision: m.supportsVision !== false,
+        promptCache: m.promptCache ?? { mode: 'auto' },
+        enabled: m.enabled ?? true,
+        createdAt: now,
+        updatedAt: now,
+      });
+    } else if (item.op === 'update') {
+      const index = out.findIndex((entry) => entry.id === item.id);
+      if (index === -1) throw new Error('要修改的模型不存在（可能已被删除）');
+      const existing = out[index]!;
+      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.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.promptCache ? { promptCache: patch.promptCache } : {}),
+        ...(patch.enabled !== undefined ? { enabled: patch.enabled } : {}),
+        updatedAt: now,
+      };
+      if (patch.apiKey?.trim()) next.apiKey = patch.apiKey.trim();
+      if (patch.clearApiKey) next.apiKey = '';
+      out[index] = next;
+    } else {
+      out = out.filter((entry) => entry.id !== item.id);
+    }
+  }
+  return out;
+}
+
+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 (patch.baseModelId !== undefined) {
+    if (patch.baseModelId !== null && !models.some((entry) => entry.id === patch.baseModelId)) {
+      throw new Error('要设为基座的模型不存在');
+    }
+    baseModelId = patch.baseModelId;
+  }
+
+  // 不变量：禁止删除/禁用当前基座模型指向的条目（先设别的为基座）。
+  if (baseModelId !== null) {
+    const baseEntry = models.find((entry) => entry.id === baseModelId);
+    if (!baseEntry) throw new Error('当前基座模型已被删除，请先设置其他模型为基座');
+    if (baseEntry.enabled === false) throw new Error('不能禁用当前基座模型，请先设置其他模型为基座');
+  }
+
+  let advisor = base?.advisor;
+  if (patch.advisor) {
+    if (patch.advisor.clear) {
+      advisor = undefined;
+    } else {
+      advisor = {
+        enabled: patch.advisor.enabled ?? advisor?.enabled ?? true,
+        mode: patch.advisor.mode ?? advisor?.mode ?? 'auto',
+        modelId: patch.advisor.modelId !== undefined ? patch.advisor.modelId : (advisor?.modelId ?? null),
+        contextPolicy: 'full-relevant',
+        shareSensitive: patch.advisor.shareSensitive ?? advisor?.shareSensitive ?? false,
+        inputTokenBudget: normalizeLimited(
+          patch.advisor.inputTokenBudget ?? advisor?.inputTokenBudget,
+          CONFIG_LIMITS.advisorInputTokenBudget, 128_000),
+        timeoutMs: normalizeLimited(
+          patch.advisor.timeoutMs ?? advisor?.timeoutMs,
+          CONFIG_LIMITS.advisorTimeoutMs, 180_000),
+      };
+    }
+  }
+  // 顾问引用的模型若已被删除或禁用，级联置空（软失联——解析层已把 null/悬空 id 当
+  // 「未配置」优雅处理，不留死链接；这与基座模型的硬阻止是刻意的不对称：顾问本来就是
+  // 可降级的第二意见，不像基座那样「没有就整个应用跑不起来」）。
+  if (advisor?.modelId) {
+    const referenced = models.find((entry) => entry.id === advisor!.modelId);
+    if (!referenced || referenced.enabled === false) advisor = { ...advisor, modelId: null };
+  }
+
+  // 比例类：保留 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 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?.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.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;
+    }
+  }
+  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?.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.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;
+    }
+  }
+  // 数字字段必须在**写入时**就按同一份边界规整——此前这里是裸 spread，读回时才被
+  // parseSubagents 的边界收窄，于是「存进去 300、读出来 100」，UI 表现成静默变回原值。
+  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),
+  };
+  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 } : {}) };
+}
+
+/** 仅不完整工具凭据使用草稿桶；其余设置都通过 patch 立即生效。 */
+export type AutosaveSection = 'tools';
+export type AutosaveState = 'applied' | 'draft';
+
+export class ConfigService {
+  private snapshot: ConfigSnapshot = { source: 'none', readOnly: false, config: null, revision: 0 };
+
+  get revision(): number { return this.snapshot.revision; }
+
+  async reload(): Promise<ConfigSnapshot> {
+    const envOnly = process.env.MINIMAL_AGENT_CONFIG_MODE === 'env';
+    const json = envOnly ? null : await readMinimalAgentConfig();
+    const env = configFromEnv();
+    const next: Omit<ConfigSnapshot, 'revision'> = {
+      source: json ? 'json' : env ? 'environment' : 'none',
+      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 };
+    return this.getSnapshot();
+  }
+
+  async getSnapshot(): Promise<ConfigSnapshot> {
+    if (this.snapshot.revision === 0) await this.reload();
+    return structuredClone(this.snapshot);
+  }
+
+  async provider(): Promise<Provider | null> {
+    const { config } = await this.getSnapshot();
+    const entry = config?.models.find((m) => m.id === config.baseModelId);
+    if (!entry?.apiKey) return null;
+    return resolveProvider(entry, config?.compactRatio);
+  }
+
+  async providerForModel(modelId?: string | null): Promise<Provider | null> {
+    if (!modelId) return this.provider();
+    const { config } = await this.getSnapshot();
+    const entry = config?.models.find((m) => m.id === modelId);
+    if (!entry?.apiKey) return null;
+    return resolveProvider(entry, config?.compactRatio);
+  }
+
+  /** 带 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;
+  }
+
+  /**
+   * 保留「未启用但已配置」和「完全未配置」两种返回值的区分——advisor.ts 的两条不同报错
+   * 文案依赖这个区分，所以只按 modelId+对应条目 apiKey 是否非空判定可解析性，不掺 .enabled。
+   *
+   * `supportsVision` 现在是模型条目的属性（不再是顾问自己的行为字段），这里从所引用的
+   * ModelConfig 镜像到返回对象顶层，让 advisor.ts 的 `advisor.supportsVision` 读取方式
+   * 保持不变——它是解析后的便利视图，不是存储形状本身。
+   */
+  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 entry = config!.models.find((m) => m.id === advisor.modelId);
+    if (!entry?.apiKey) return null;
+    return { ...advisor, provider: resolveProvider(entry), supportsVision: entry.supportsVision !== false };
+  }
+
+  async subagents(): Promise<SubagentsConfig> {
+    return (await this.reload()).config?.subagents ?? DEFAULT_SUBAGENTS_CONFIG;
+  }
+
+  async browser(): Promise<BrowserConfig> {
+    return (await this.reload()).config?.browser ?? DEFAULT_BROWSER_CONFIG;
+  }
+
+  async computerUse(): Promise<ComputerUseConfig> {
+    return (await this.reload()).config?.computerUse ?? DEFAULT_COMPUTER_USE_CONFIG;
+  }
+
+  async tool<K extends ToolConfigKey>(key: K): Promise<ToolConfigs[K]> {
+    return (await this.reload()).config?.tools[key];
+  }
+
+  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 },
+    };
+  }
+
+  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));
+    return this.reload();
+  }
+
+  /** 现在只服务 tools 分区的实时录入表单（imageGeneration/textToSpeech 多字段、可能中途非法）。 */
+  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.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 };
+      const drafts = structuredClone(active.drafts ?? {});
+      for (const key of Object.keys(patch.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>);
+        try {
+          active = { version: 4, ...applyConfigPatch(active, { tools: { [key]: merged } as ConfigPatch['tools'] }), savedAt: active.savedAt };
+          delete drafts.tools?.[key];
+        } catch {
+          state = 'draft';
+          draftFields.push(key);
+          (drafts.tools ??= {})[key] = merged;
+        }
+      }
+      if (!hasEntries(drafts.tools)) delete drafts.tools;
+      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,
+        ...(hasEntries(drafts) ? { drafts } : {}),
+      };
+    });
+    return { snapshot: await this.reload(), state, draftFields };
+  }
+}
+
+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',
+]);
+
+/** 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];
+  return env;
+}
+
+export async function trustedToolEnv(
+  kind: 'imageGeneration' | 'openRouter' | 'textToSpeech',
+  service: ConfigService = configService,
+): Promise<NodeJS.ProcessEnv> {
+  const env = sanitizeCredentialEnv();
+  if (kind === 'imageGeneration') {
+    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 (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;
+    }
+  } 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; }
+  }
+  return env;
+}

package/src/config/numericLimits.js

@@ -0,0 +1,61 @@
+/**
+ * 配置里每一个「数字输入」的边界与取值语义——**唯一真值**。
+ *
+ * 为什么要有这个文件（真实事故）：同一个数字此前在**三层各写一份**互不相同的边界——
+ * 前端 input 的 `min/max/step`、写入时 `applyConfigPatch` 的 clamp、读回时
+ * `parseAdvisor/parseSubagents` 的 `boundedNumber`。三份一旦不一致，用户在设置页输入
+ * 一个「前端允许、后端不允许」的值，回车/失焦后会**静默变回原值**：前端没报错（它认为
+ * 合法），后端也没报错（它认为自己只是在纠偏），中间没有任何提示。顾问「输入预算」被
+ * 死钉在 128000 就是这么来的——用户的顾问模型是 90 万上下文窗口，却怎么改都跳回 12.8 万。
+ *
+ * 因此：**边界只准在这里声明**，minimal-agent 的读/写两层与 minimal-desktop 的设置页
+ * 全部 import 这里。前端 clamp 后再提交，后端再 clamp 一次兜底——两次 clamp 结果必然
+ * 相同，用户看到的值就是存下来的值。
+ *
+ * 单位约定：这里的边界一律用**存储单位**（毫秒 / 比例 / 绝对个数）。UI 若按秒/分钟/
+ * 百分比展示，自己换算（见 minimal-desktop `NumberInput`），不在这里再开一份显示单位的
+ * 边界，否则又回到多份真值。
+ */
+export const CONFIG_LIMITS = {
+    /** 顾问单次咨询喂进去的输入 token 上限。上界给到 200 万是为了容纳百万级上下文模型；
+     *  真正生效值还会再被「所选顾问模型的 contextWindow」二次收窄（见 advisor.ts）。 */
+    advisorInputTokenBudget: { min: 1_000, max: 2_000_000, step: 1_000, kind: 'integer' },
+    /** 顾问单次咨询的最长等待（毫秒）。重思考模型 + 大上下文可以跑很久，上界给到 10 分钟。 */
+    advisorTimeoutMs: { min: 5_000, max: 600_000, step: 5_000, kind: 'integer' },
+    /** 单个回合内最多派生几个子任务。 */
+    subagentMaxCallsPerTurn: { min: 1, max: 50, step: 1, kind: 'integer' },
+    /** 子任务并发上限。 */
+    subagentMaxConcurrent: { min: 1, max: 20, step: 1, kind: 'integer' },
+    /** 单个子任务的总时长兜底（毫秒），上界 2 小时。 */
+    subagentTimeoutMs: { min: 60_000, max: 7_200_000, step: 60_000, kind: 'integer' },
+    /** explore（只读调研）子任务的轮数上限。 */
+    subagentExploreMaxTurns: { min: 5, max: 500, step: 5, kind: 'integer' },
+    /** general（读写执行）子任务的轮数上限。 */
+    subagentGeneralMaxTurns: { min: 10, max: 1_000, step: 10, kind: 'integer' },
+    /** 电脑操作每帧画面的像素预算。 */
+    computerUseMaxImagePixels: { min: 100_000, max: 10_000_000, step: 100_000, kind: 'integer' },
+    /** 自动压缩触发阈值，占 contextWindow 的比例（0,1]。UI 按百分比展示，保留 2 位小数。 */
+    compactRatio: { min: 0.01, max: 1, step: 0.01, kind: 'ratio' },
+    /** 模型条目的上下文窗口。 */
+    modelContextWindow: { min: 1_000, max: 20_000_000, step: 1_000, kind: 'integer' },
+    /** 模型条目的单次输出上限（可留空 = 用公式推荐值，故 UI 允许空串，这里只约束填了值的情况）。 */
+    modelMaxTokens: { min: 256, max: 1_000_000, step: 256, kind: 'integer' },
+};
+/** 比例类字段保留的小数位（4 位比例 = 2 位百分比）。 */
+const RATIO_DECIMALS = 4;
+/**
+ * 把任意输入规整成该字段合法的存储值：非法/空 → fallback；整数类四舍五入；
+ * 比例类保留 4 位小数（否则 `0.85` 会被步进累加成 `0.8500000000000001` 存进 config.json）。
+ * 最后按 min/max 收口。
+ */
+export function normalizeLimited(value, limit, fallback) {
+    const raw = typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+    const rounded = limit.kind === 'integer'
+        ? Math.round(raw)
+        : Number(raw.toFixed(RATIO_DECIMALS));
+    return Math.min(limit.max, Math.max(limit.min, rounded));
+}
+/** 判断一个值是否已经落在合法范围内（UI 用来决定要不要提示「已自动调整」）。 */
+export function withinLimit(value, limit) {
+    return Number.isFinite(value) && value >= limit.min && value <= limit.max;
+}