minimal-agent 0.10.0 → 0.12.0

package/src/config/configFile.ts

@@ -0,0 +1,633 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, copyFile, mkdir, readFile, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { execSiblingDir } from '../utils/greenRoot.js';
+import type { PromptCacheConfig } from '../types.js';
+import { normalizePromptCacheMode } from '../llm/promptCache.js';
+import { CONFIG_LIMITS, normalizeLimited } from './numericLimits.js';
+import {
+  DEFAULT_BROWSER_CONFIG,
+  DEFAULT_COMPUTER_USE_CONFIG,
+  DEFAULT_SUBAGENTS_CONFIG,
+} from './configDefaults.js';
+
+export {
+  DEFAULT_BROWSER_CONFIG,
+  DEFAULT_COMPUTER_USE_CONFIG,
+  DEFAULT_SUBAGENTS_CONFIG,
+} from './configDefaults.js';
+
+export type ImageProtocol = 'auto' | 'chat' | 'images';
+export type ApiFormat = 'openai' | 'anthropic';
+
+/** 一个模型条目——「模型列表」的元素，基座模型和顾问模型都从这里引用。 */
+export interface ModelConfig {
+  id: string;
+  apiFormat: ApiFormat;
+  /** 可选展示名；缺省时 UI/解析都回退用 model 字符串本身——「名称」不再是必填概念。 */
+  displayName?: string;
+  baseURL: string;
+  apiKey: string;
+  model: string;
+  contextWindow: number;
+  maxTokens?: number;
+  supportsVision?: boolean;
+  promptCache?: PromptCacheConfig;
+  enabled: boolean;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface AdvisorConfig {
+  enabled: boolean;
+  mode: 'auto' | 'manual';
+  /** 引用 models[].id；null = 未选。顾问不再自带一整套独立 provider 字段。 */
+  modelId: string | null;
+  contextPolicy: 'full-relevant';
+  shareSensitive: boolean;
+  /** 顾问单次输入预算。独立于模型声明的上下文窗口，避免百万窗口吞入整段历史。 */
+  inputTokenBudget: number;
+  timeoutMs: number;
+}
+
+export interface SubagentsConfig {
+  enabled: boolean;
+  maxCallsPerTurn: number;
+  maxConcurrent: number;
+  defaultWriteIsolation: 'none' | 'worktree';
+  timeoutMs: number;
+  exploreMaxTurns: number;
+  generalMaxTurns: number;
+}
+
+export interface BrowserConfig {
+  enabled: boolean;
+  profileId: 'default';
+  developerMode: boolean;
+  allowedCdpOrigins: string[];
+}
+
+export interface ComputerUseConfig {
+  enabled: boolean;
+  imagePolicy: 'single-adaptive';
+  maxImagePixels: number;
+  /** Compatibility field. Product mode always clamps this to one frame. */
+  observationFrames: number;
+}
+
+export interface ToolConfigs {
+  webSearch?: { provider: 'tavily'; apiKey: string };
+  imageGeneration?: {
+    provider: string;
+    baseURL: string;
+    apiKey: string;
+    model: string;
+    protocol?: ImageProtocol;
+  };
+  openRouter?: { apiKey: string };
+  textToSpeech?: { provider: 'minimax'; apiKey: string; groupId: string };
+}
+
+export interface MinimalAgentConfig {
+  version: 4;
+  models: ModelConfig[];
+  /** 当前被标记为基座（主循环）的模型 id；null = 尚未选定。 */
+  baseModelId: string | null;
+  compactRatio?: number;
+  advisor?: AdvisorConfig;
+  subagents: SubagentsConfig;
+  browser?: BrowserConfig;
+  computerUse?: ComputerUseConfig;
+  tools: ToolConfigs;
+  /** Secure, incomplete settings that must not replace the last runnable config. */
+  drafts?: ConfigDrafts;
+  savedAt: number;
+}
+
+/**
+ * 加模型是提交式弹窗、顾问改字段都是有界枚举/数字——不会出现「输入中途非法值」，
+ * 所以 v3 时代的 provider/advisor 草稿桶随 schema 一起删除，只剩 tools（imageGeneration/
+ * textToSpeech 仍是多字段实时录入表单，可能中途非法）。
+ */
+export interface ConfigDrafts {
+  tools?: Record<string, Record<string, unknown>>;
+}
+
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+const LOCK_STALE_MS = 120_000;
+const LOCK_WAIT_MS = 15_000;
+
+/**
+ * 建议的单次输出 token 上限：min(32768, max(4096, contextWindow×0.25))。
+ * 上限 32768（非更保守的 16384）呼应 .env.example 的实测教训——16384 偏紧，写大 JSON
+ * 输出时会被截断；maxTokens 是上限不是预订额度，设大不额外花钱。
+ */
+export function defaultMaxTokens(contextWindow: number): number {
+  return Math.min(32_768, Math.max(4_096, Math.round(contextWindow * 0.25)));
+}
+
+function homeConfigPath(): string {
+  return join(process.env.MINIMAL_AGENT_HOME ?? homedir(), '.minimal-agent', 'config.json');
+}
+
+export function getConfigFilePath(): string {
+  return process.env.MINIMAL_AGENT_CONFIG_FILE ?? homeConfigPath();
+}
+
+function positiveNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+/** compactRatio 是可选字段：缺省/非法一律返回 undefined（让消费方用自己的默认比例），
+ *  存在时按比例语义规整到 4 位小数——`0.8500000000000001` 这种步进累加出来的浮点脏值
+ *  会在下次读盘时被抹平，不会一路带进 provider。 */
+function parseCompactRatio(value: unknown): number | undefined {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) return undefined;
+  return normalizeLimited(value, CONFIG_LIMITS.compactRatio, CONFIG_LIMITS.compactRatio.max);
+}
+
+function nonEmpty(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function defaultPromptCacheMode(baseURL: string): PromptCacheConfig['mode'] {
+  try {
+    const hostname = new URL(baseURL).hostname.toLowerCase();
+    return hostname === 'api.moonshot.cn' || hostname.endsWith('.moonshot.cn')
+      ? 'session-key'
+      : 'auto';
+  } catch {
+    return 'auto';
+  }
+}
+
+// ---------------- v4（当前）解析 ----------------
+
+function parseModel(value: unknown): ModelConfig | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const raw = value as Record<string, unknown>;
+  const id = nonEmpty(raw.id);
+  const baseURL = nonEmpty(raw.baseURL);
+  const model = nonEmpty(raw.model);
+  if (!id || !baseURL || !model) return null;
+  const apiKey = typeof raw.apiKey === 'string' ? raw.apiKey.trim() : '';
+  const displayName = nonEmpty(raw.displayName);
+  const now = Date.now();
+  return {
+    id,
+    apiFormat: raw.apiFormat === 'anthropic' ? 'anthropic' : 'openai',
+    ...(displayName ? { displayName } : {}),
+    baseURL,
+    apiKey,
+    model,
+    contextWindow: positiveNumber(raw.contextWindow) ?? DEFAULT_CONTEXT_WINDOW,
+    ...(positiveNumber(raw.maxTokens) !== undefined ? { maxTokens: positiveNumber(raw.maxTokens) } : {}),
+    supportsVision: raw.supportsVision !== false,
+    promptCache: {
+      mode: normalizePromptCacheMode(
+        (raw.promptCache as Record<string, unknown> | undefined)?.mode
+          ?? defaultPromptCacheMode(baseURL),
+      ),
+    },
+    enabled: raw.enabled !== false,
+    createdAt: positiveNumber(raw.createdAt) ?? now,
+    updatedAt: positiveNumber(raw.updatedAt) ?? now,
+  };
+}
+
+function parseModels(value: unknown): ModelConfig[] {
+  if (!Array.isArray(value)) return [];
+  const out: ModelConfig[] = [];
+  for (const item of value) {
+    const model = parseModel(item);
+    if (model) out.push(model);
+  }
+  return out;
+}
+
+function parseTools(value: unknown): ToolConfigs {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const raw = value as Record<string, unknown>;
+  const out: ToolConfigs = {};
+  const search = raw.webSearch as Record<string, unknown> | undefined;
+  const searchKey = nonEmpty(search?.apiKey);
+  if (searchKey) out.webSearch = { provider: 'tavily', apiKey: searchKey };
+  const image = raw.imageGeneration as Record<string, unknown> | undefined;
+  const imageBaseURL = nonEmpty(image?.baseURL);
+  const imageApiKey = nonEmpty(image?.apiKey);
+  const imageModel = nonEmpty(image?.model);
+  if (imageBaseURL && imageApiKey && imageModel) {
+    const protocol = image?.protocol === 'chat' || image?.protocol === 'images' ? image.protocol : 'auto';
+    out.imageGeneration = {
+      provider: nonEmpty(image?.provider) ?? 'openai',
+      baseURL: imageBaseURL,
+      apiKey: imageApiKey,
+      model: imageModel,
+      protocol,
+    };
+  }
+  const openRouterKey = nonEmpty((raw.openRouter as Record<string, unknown> | undefined)?.apiKey);
+  if (openRouterKey) out.openRouter = { apiKey: openRouterKey };
+  const speech = raw.textToSpeech as Record<string, unknown> | undefined;
+  const speechKey = nonEmpty(speech?.apiKey);
+  const groupId = nonEmpty(speech?.groupId);
+  if (speechKey && groupId) out.textToSpeech = { provider: 'minimax', apiKey: speechKey, groupId };
+  return out;
+}
+
+function parseAdvisor(value: unknown): AdvisorConfig | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const raw = value as Record<string, unknown>;
+  return {
+    enabled: raw.enabled !== false,
+    mode: raw.mode === 'manual' ? 'manual' : 'auto',
+    modelId: nonEmpty(raw.modelId) ?? null,
+    contextPolicy: 'full-relevant',
+    shareSensitive: raw.shareSensitive === true,
+    inputTokenBudget: normalizeLimited(raw.inputTokenBudget, CONFIG_LIMITS.advisorInputTokenBudget, 128_000),
+    timeoutMs: normalizeLimited(raw.timeoutMs, CONFIG_LIMITS.advisorTimeoutMs, 180_000),
+  };
+}
+
+function parseSubagents(value: unknown): SubagentsConfig {
+  const raw = value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+  return {
+    enabled: raw.enabled !== false,
+    maxCallsPerTurn: normalizeLimited(raw.maxCallsPerTurn, CONFIG_LIMITS.subagentMaxCallsPerTurn, 6),
+    maxConcurrent: normalizeLimited(raw.maxConcurrent, CONFIG_LIMITS.subagentMaxConcurrent, 3),
+    defaultWriteIsolation: raw.defaultWriteIsolation === 'worktree' ? 'worktree' : 'none',
+    timeoutMs: normalizeLimited(raw.timeoutMs, CONFIG_LIMITS.subagentTimeoutMs, 1_800_000),
+    exploreMaxTurns: normalizeLimited(raw.exploreMaxTurns, CONFIG_LIMITS.subagentExploreMaxTurns, 50),
+    generalMaxTurns: normalizeLimited(raw.generalMaxTurns, CONFIG_LIMITS.subagentGeneralMaxTurns, 100),
+  };
+}
+
+function parseBrowser(value: unknown): BrowserConfig {
+  const raw = value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+  return {
+    enabled: raw.enabled !== false,
+    profileId: 'default',
+    developerMode: raw.developerMode === true,
+    allowedCdpOrigins: Array.isArray(raw.allowedCdpOrigins)
+      ? raw.allowedCdpOrigins.filter((item): item is string => typeof item === 'string' && /^https?:\/\//i.test(item)).slice(0, 100)
+      : [],
+  };
+}
+
+function parseComputerUse(value: unknown): ComputerUseConfig {
+  const raw = value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+  return {
+    enabled: raw.enabled !== false,
+    imagePolicy: 'single-adaptive',
+    maxImagePixels: normalizeLimited(raw.maxImagePixels, CONFIG_LIMITS.computerUseMaxImagePixels, 1_600_000),
+    observationFrames: 1,
+  };
+}
+
+function parseCurrent(data: Record<string, unknown>): MinimalAgentConfig | null {
+  if (data.version !== 4) return null;
+  const advisor = parseAdvisor(data.advisor);
+  const compactRatio = parseCompactRatio(data.compactRatio);
+  return {
+    version: 4,
+    models: parseModels(data.models),
+    baseModelId: nonEmpty(data.baseModelId) ?? null,
+    ...(compactRatio !== undefined ? { compactRatio } : {}),
+    ...(advisor ? { advisor } : {}),
+    subagents: parseSubagents(data.subagents),
+    browser: parseBrowser(data.browser),
+    computerUse: parseComputerUse(data.computerUse),
+    tools: parseTools(data.tools),
+    ...(data.drafts && typeof data.drafts === 'object' && !Array.isArray(data.drafts)
+      ? { drafts: structuredClone(data.drafts as ConfigDrafts) }
+      : {}),
+    savedAt: typeof data.savedAt === 'number' ? data.savedAt : 0,
+  };
+}
+
+// ---------------- v1/v2/v3（旧版）迁移专用解析 ----------------
+// 这些类型/函数只服务迁移路径，不对外导出——v4 是唯一的当前 schema。
+
+interface LegacyProviderConfig {
+  name: string;
+  baseURL: string;
+  apiKey: string;
+  model: string;
+  contextWindow: number;
+  compactRatio?: number;
+  maxTokens?: number;
+}
+
+interface LegacyAdvisorConfig {
+  enabled: boolean;
+  mode: 'auto' | 'manual';
+  provider: LegacyProviderConfig;
+  supportsVision: boolean;
+  shareSensitive: boolean;
+  inputTokenBudget: number;
+  timeoutMs: number;
+}
+
+function parseLegacyProviderConfig(value: unknown): LegacyProviderConfig | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const raw = value as Record<string, unknown>;
+  const baseURL = nonEmpty(raw.baseURL);
+  const apiKey = typeof raw.apiKey === 'string' ? raw.apiKey.trim() : undefined;
+  const model = nonEmpty(raw.model);
+  if (!baseURL || apiKey === undefined || !model) return null;
+  const compactRatio = parseCompactRatio(raw.compactRatio);
+  return {
+    name: nonEmpty(raw.name) ?? 'env',
+    baseURL,
+    apiKey,
+    model,
+    contextWindow: positiveNumber(raw.contextWindow) ?? DEFAULT_CONTEXT_WINDOW,
+    ...(compactRatio !== undefined ? { compactRatio } : {}),
+    ...(positiveNumber(raw.maxTokens) !== undefined ? { maxTokens: positiveNumber(raw.maxTokens) } : {}),
+  };
+}
+
+function parseLegacyAdvisorConfig(value: unknown): LegacyAdvisorConfig | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const raw = value as Record<string, unknown>;
+  const provider = parseLegacyProviderConfig(raw.provider);
+  if (!provider) return undefined;
+  return {
+    enabled: raw.enabled !== false,
+    mode: raw.mode === 'manual' ? 'manual' : 'auto',
+    provider,
+    supportsVision: raw.supportsVision === true,
+    shareSensitive: raw.shareSensitive === true,
+    inputTokenBudget: normalizeLimited(raw.inputTokenBudget, CONFIG_LIMITS.advisorInputTokenBudget, 128_000),
+    timeoutMs: normalizeLimited(raw.timeoutMs, CONFIG_LIMITS.advisorTimeoutMs, 180_000),
+  };
+}
+
+/**
+ * 把「单一基座 provider + 可选单一顾问 provider」的旧形状构造成 v4 的模型列表形状。
+ * v1（无 version 字段的扁平文件）与 v2/v3（provider/advisor 单对象）迁移路径共用这一个函数。
+ */
+function buildV4FromLegacy(
+  legacyProvider: LegacyProviderConfig,
+  legacyAdvisor: LegacyAdvisorConfig | undefined,
+  subagents: SubagentsConfig,
+  tools: ToolConfigs,
+  savedAt: number,
+): MinimalAgentConfig {
+  const now = Date.now();
+  const baseModel: ModelConfig = {
+    id: 'migrated-base',
+    apiFormat: 'openai',
+    ...(legacyProvider.name !== 'env' ? { displayName: legacyProvider.name } : {}),
+    baseURL: legacyProvider.baseURL,
+    apiKey: legacyProvider.apiKey,
+    model: legacyProvider.model,
+    contextWindow: legacyProvider.contextWindow,
+    ...(legacyProvider.maxTokens !== undefined ? { maxTokens: legacyProvider.maxTokens } : {}),
+    enabled: true,
+    createdAt: now,
+    updatedAt: now,
+  };
+  const models: ModelConfig[] = [baseModel];
+  let advisor: AdvisorConfig | undefined;
+  if (legacyAdvisor) {
+    const sameAsBase = legacyAdvisor.provider.baseURL === baseModel.baseURL
+      && legacyAdvisor.provider.apiKey === baseModel.apiKey
+      && legacyAdvisor.provider.model === baseModel.model;
+    let advisorModelId: string;
+    if (sameAsBase) {
+      if (legacyAdvisor.supportsVision) baseModel.supportsVision = true;
+      advisorModelId = baseModel.id;
+    } else {
+      const advisorModel: ModelConfig = {
+        id: 'migrated-advisor',
+        apiFormat: 'openai',
+        ...(legacyAdvisor.provider.name !== 'advisor' ? { displayName: legacyAdvisor.provider.name } : {}),
+        baseURL: legacyAdvisor.provider.baseURL,
+        apiKey: legacyAdvisor.provider.apiKey,
+        model: legacyAdvisor.provider.model,
+        contextWindow: legacyAdvisor.provider.contextWindow,
+        ...(legacyAdvisor.provider.maxTokens !== undefined ? { maxTokens: legacyAdvisor.provider.maxTokens } : {}),
+        ...(legacyAdvisor.supportsVision ? { supportsVision: true } : {}),
+        enabled: true,
+        createdAt: now,
+        updatedAt: now,
+      };
+      models.push(advisorModel);
+      advisorModelId = advisorModel.id;
+    }
+    advisor = {
+      enabled: legacyAdvisor.enabled,
+      mode: legacyAdvisor.mode,
+      modelId: advisorModelId,
+      contextPolicy: 'full-relevant',
+      shareSensitive: legacyAdvisor.shareSensitive,
+      inputTokenBudget: legacyAdvisor.inputTokenBudget,
+      timeoutMs: legacyAdvisor.timeoutMs,
+    };
+  }
+  return {
+    version: 4,
+    models,
+    baseModelId: baseModel.id,
+    ...(legacyProvider.compactRatio !== undefined ? { compactRatio: legacyProvider.compactRatio } : {}),
+    ...(advisor ? { advisor } : {}),
+    subagents,
+    browser: DEFAULT_BROWSER_CONFIG,
+    computerUse: DEFAULT_COMPUTER_USE_CONFIG,
+    tools,
+    savedAt,
+  };
+}
+
+function migrateV1(data: Record<string, unknown>): MinimalAgentConfig | null {
+  const provider = parseLegacyProviderConfig({
+    name: data.provider,
+    baseURL: data.baseURL,
+    apiKey: data.apiKey,
+    model: data.model,
+    contextWindow: data.contextWindow,
+    compactRatio: data.compactRatio,
+    maxTokens: data.maxTokens,
+  });
+  if (!provider) return null;
+  const tools: ToolConfigs = {};
+  const tavilyApiKey = nonEmpty(data.tavilyApiKey);
+  if (tavilyApiKey) tools.webSearch = { provider: 'tavily', apiKey: tavilyApiKey };
+  return buildV4FromLegacy(provider, undefined, DEFAULT_SUBAGENTS_CONFIG, tools, typeof data.savedAt === 'number' ? data.savedAt : 0);
+}
+
+function migrateV3(data: Record<string, unknown>): MinimalAgentConfig | null {
+  const provider = parseLegacyProviderConfig(data.provider);
+  if (!provider) return null;
+  const advisor = parseLegacyAdvisorConfig(data.advisor);
+  return buildV4FromLegacy(
+    provider,
+    advisor,
+    parseSubagents(data.subagents),
+    parseTools(data.tools),
+    typeof data.savedAt === 'number' ? data.savedAt : 0,
+  );
+}
+
+async function parseConfigFile(
+  file: string,
+): Promise<{ config: MinimalAgentConfig; migrated: boolean; fromVersion: number } | null> {
+  try {
+    const data = JSON.parse(await readFile(file, 'utf8')) as unknown;
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return null;
+    const object = data as Record<string, unknown>;
+    const current = parseCurrent(object);
+    if (current) return { config: current, migrated: object.version !== 4, fromVersion: 4 };
+    if (object.version === 2 || object.version === 3) {
+      const migrated = migrateV3(object);
+      if (migrated) return { config: migrated, migrated: true, fromVersion: object.version };
+    }
+    const migrated = migrateV1(object);
+    return migrated ? { config: migrated, migrated: true, fromVersion: 1 } : null;
+  } catch {
+    return null;
+  }
+}
+
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+async function acquireConfigLock(file: string): Promise<() => Promise<void>> {
+  const lockDir = `${file}.lock`;
+  const ownerFile = join(lockDir, 'owner.json');
+  const startedAt = Date.now();
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  while (true) {
+    try {
+      await mkdir(lockDir, { mode: 0o700 });
+      await writeFile(ownerFile, JSON.stringify({ pid: process.pid, createdAt: Date.now() }), { mode: 0o600 });
+      return async () => { await rm(lockDir, { recursive: true, force: true }); };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      let stale = false;
+      try {
+        const [ownerRaw, info] = await Promise.all([readFile(ownerFile, 'utf8'), stat(lockDir)]);
+        const owner = JSON.parse(ownerRaw) as { pid?: number };
+        stale = typeof owner.pid === 'number' ? !processIsAlive(owner.pid) : Date.now() - info.mtimeMs > LOCK_STALE_MS;
+      } catch {
+        try {
+          const info = await stat(lockDir);
+          stale = Date.now() - info.mtimeMs > LOCK_STALE_MS;
+        } catch {
+          stale = false;
+        }
+      }
+      if (stale) { await rm(lockDir, { recursive: true, force: true }); continue; }
+      if (Date.now() - startedAt > LOCK_WAIT_MS) throw new Error('等待配置文件锁超时');
+      await new Promise((resolve) => setTimeout(resolve, 40));
+    }
+  }
+}
+
+async function writeConfigFile(file: string, config: MinimalAgentConfig): Promise<void> {
+  const release = await acquireConfigLock(file);
+  try {
+    await writeConfigFileUnlocked(file, config);
+  } finally {
+    await release();
+  }
+}
+
+async function writeConfigFileUnlocked(file: string, config: MinimalAgentConfig): Promise<void> {
+  const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    await writeFile(tmp, JSON.stringify(config, null, 2), { encoding: 'utf8', mode: 0o600 });
+    await rename(tmp, file);
+    await chmod(file, 0o600).catch(() => {});
+  } finally {
+    await unlink(tmp).catch(() => {});
+  }
+}
+
+function configCandidates(): string[] {
+  const override = process.env.MINIMAL_AGENT_CONFIG_FILE;
+  return override ? [override] : [homeConfigPath(), join(execSiblingDir(), 'config.json')];
+}
+
+export async function readMinimalAgentConfig(options: { migrate?: boolean } = {}): Promise<MinimalAgentConfig | null> {
+  for (const file of configCandidates()) {
+    const parsed = await parseConfigFile(file);
+    if (!parsed) continue;
+    if (options.migrate !== false && (parsed.migrated || file !== getConfigFilePath())) {
+      // 备份只在「原地迁移会覆盖源文件」时才有意义（file == 权威写入位）。
+      // exe 同级（U 盘预置）源文件永不被覆盖，且「绝不写 U 盘」是产品红线——
+      // 曾在此给 U 盘目录写出 config.json.v1.backup（绿色版冒烟实测抓到）。
+      // 备份文件名按来源版本号命名（而非固定 .v1.backup）：一台机器可能先后经历
+      // v1→v3、又 v3→v4 两次迁移，固定文件名会让第二次覆盖第一次的备份。
+      if (parsed.migrated && file === getConfigFilePath()) {
+        await copyFile(file, `${file}.v${parsed.fromVersion}.backup`).catch(() => {});
+      }
+      // A schema-only migration must not invalidate a revision already returned to
+      // another process during startup.
+      await writeConfigFile(getConfigFilePath(), parsed.config);
+    }
+    return parsed.config;
+  }
+  return null;
+}
+
+export async function saveMinimalAgentConfig(
+  config: Omit<MinimalAgentConfig, 'version' | 'savedAt' | 'subagents'> & { subagents?: SubagentsConfig },
+): Promise<MinimalAgentConfig> {
+  const next: MinimalAgentConfig = {
+    version: 4,
+    models: config.models,
+    baseModelId: config.baseModelId,
+    ...(config.compactRatio !== undefined ? { compactRatio: config.compactRatio } : {}),
+    advisor: config.advisor,
+    subagents: config.subagents ?? DEFAULT_SUBAGENTS_CONFIG,
+    browser: config.browser ?? DEFAULT_BROWSER_CONFIG,
+    computerUse: config.computerUse ?? DEFAULT_COMPUTER_USE_CONFIG,
+    tools: config.tools,
+    drafts: config.drafts,
+    savedAt: Date.now(),
+  };
+  await writeConfigFile(getConfigFilePath(), next);
+  return next;
+}
+
+/** Cross-process read-modify-write. The mutator never sees a partially written file. */
+export async function updateMinimalAgentConfig(
+  mutate: (current: MinimalAgentConfig | null) => Omit<MinimalAgentConfig, 'version' | 'savedAt'>,
+): Promise<MinimalAgentConfig> {
+  const file = getConfigFilePath();
+  const release = await acquireConfigLock(file);
+  try {
+    const current = (await parseConfigFile(file))?.config ?? null;
+    const value = mutate(current);
+    const next: MinimalAgentConfig = {
+      version: 4,
+      models: value.models,
+      baseModelId: value.baseModelId,
+      ...(value.compactRatio !== undefined ? { compactRatio: value.compactRatio } : {}),
+      advisor: value.advisor,
+      subagents: value.subagents ?? current?.subagents ?? DEFAULT_SUBAGENTS_CONFIG,
+      browser: value.browser ?? current?.browser ?? DEFAULT_BROWSER_CONFIG,
+      computerUse: value.computerUse ?? current?.computerUse ?? DEFAULT_COMPUTER_USE_CONFIG,
+      tools: value.tools,
+      drafts: value.drafts,
+      savedAt: Math.max(Date.now(), (current?.savedAt ?? 0) + 1),
+    };
+    await writeConfigFileUnlocked(file, next);
+    return next;
+  } finally {
+    await release();
+  }
+}