minimal-agent 0.8.2 → 0.10.0

package/src/config/configService.js

@@ -0,0 +1,446 @@
+import { randomUUID } from 'node:crypto';
+import { readMinimalAgentConfig, updateMinimalAgentConfig, defaultMaxTokens, DEFAULT_SUBAGENTS_CONFIG, DEFAULT_BROWSER_CONFIG, } from './configFile.js';
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+function positiveInt(value, fallback) {
+    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() {
+    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 = {};
+    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 = {
+        id: 'env-base',
+        apiFormat: 'openai',
+        ...(name !== 'env' ? { displayName: name } : {}),
+        baseURL,
+        apiKey,
+        model,
+        contextWindow,
+        maxTokens: positiveInt(process.env.MINIMAL_AGENT_MAX_TOKENS, defaultMaxTokens(contextWindow)),
+        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,
+        tools,
+        savedAt: 0,
+    };
+}
+function resolveProvider(entry, compactRatio) {
+    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,
+        ...(compactRatio !== undefined ? { compactRatio } : {}),
+    };
+}
+function mergeRecord(base, patch) {
+    const out = { ...(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] : undefined, value);
+        }
+        else if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+function hasEntries(value) {
+    return !!value && Object.keys(value).length > 0;
+}
+function applyModelsPatch(models, ops) {
+    let out = [...models];
+    const now = Date.now();
+    for (const item of ops) {
+        if (item.op === 'add') {
+            const m = item.model;
+            const 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,
+                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 = {
+                ...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.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, patch) {
+    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: Math.min(128_000, Math.max(8_000, patch.advisor.inputTokenBudget ?? advisor?.inputTokenBudget ?? 128_000)),
+                timeoutMs: patch.advisor.timeoutMs ?? advisor?.timeoutMs ?? 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 };
+    }
+    const compactRatio = patch.compactRatio !== undefined
+        ? (patch.compactRatio > 0 && patch.compactRatio <= 1 ? patch.compactRatio : undefined)
+        : base?.compactRatio;
+    const tools = { ...(base?.tools ?? {}) };
+    const toolPatch = patch.tools;
+    if (toolPatch?.webSearch) {
+        if (toolPatch.webSearch.clear)
+            delete tools.webSearch;
+        else
+            tools.webSearch = mergeRecord(tools.webSearch, { provider: 'tavily', ...toolPatch.webSearch });
+    }
+    if (toolPatch?.imageGeneration) {
+        if (toolPatch.imageGeneration.clear)
+            delete tools.imageGeneration;
+        else {
+            const next = mergeRecord(tools.imageGeneration, toolPatch.imageGeneration);
+            if (toolPatch.imageGeneration.clearApiKey)
+                next.apiKey = '';
+            delete next.clear;
+            delete next.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;
+        else
+            tools.openRouter = mergeRecord(tools.openRouter, toolPatch.openRouter);
+    }
+    if (toolPatch?.textToSpeech) {
+        if (toolPatch.textToSpeech.clear)
+            delete tools.textToSpeech;
+        else {
+            const next = mergeRecord(tools.textToSpeech, { provider: 'minimax', ...toolPatch.textToSpeech });
+            if (toolPatch.textToSpeech.clearApiKey)
+                next.apiKey = '';
+            delete next.clear;
+            delete next.clearApiKey;
+            if (!next.apiKey || !next.groupId)
+                throw new Error('MiniMax 语音缺少 API Key 或 Group ID');
+            tools.textToSpeech = next;
+        }
+    }
+    const subagents = { ...(base?.subagents ?? DEFAULT_SUBAGENTS_CONFIG), ...(patch.subagents ?? {}) };
+    const browser = { ...(base?.browser ?? DEFAULT_BROWSER_CONFIG), ...(patch.browser ?? {}), profileId: 'default' };
+    return { models, baseModelId, ...(compactRatio !== undefined ? { compactRatio } : {}), advisor, subagents, browser, tools, drafts: base?.drafts };
+}
+export class ConfigService {
+    snapshot = { source: 'none', readOnly: false, config: null, revision: 0 };
+    get revision() { return this.snapshot.revision; }
+    async reload() {
+        const envOnly = process.env.MINIMAL_AGENT_CONFIG_MODE === 'env';
+        const json = envOnly ? null : await readMinimalAgentConfig();
+        const env = configFromEnv();
+        const next = {
+            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() {
+        if (this.snapshot.revision === 0)
+            await this.reload();
+        return structuredClone(this.snapshot);
+    }
+    async provider() {
+        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) {
+        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() {
+        return (await this.getSnapshot()).config?.models ?? [];
+    }
+    async model(id) {
+        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() {
+        // 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() {
+        return (await this.reload()).config?.subagents ?? DEFAULT_SUBAGENTS_CONFIG;
+    }
+    async browser() {
+        return (await this.reload()).config?.browser ?? DEFAULT_BROWSER_CONFIG;
+    }
+    async tool(key) {
+        return (await this.reload()).config?.tools[key];
+    }
+    async 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) {
+        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, patch) {
+        void section;
+        const current = await this.getSnapshot();
+        if (current.readOnly)
+            throw new Error('当前使用环境变量只读配置，不能从设置页修改');
+        if (!current.config)
+            throw new Error('请先添加至少一个模型');
+        let state = 'applied';
+        const draftFields = [];
+        await updateMinimalAgentConfig((latest) => {
+            let active = latest ?? current.config;
+            if (patch.subagents)
+                active = { version: 4, ...applyConfigPatch(active, { subagents: patch.subagents }), savedAt: active.savedAt };
+            const drafts = structuredClone(active.drafts ?? {});
+            for (const key of Object.keys(patch.tools ?? {})) {
+                const rawPiece = patch.tools[key];
+                if (!rawPiece)
+                    continue;
+                const previous = (drafts.tools ?? {})[key];
+                const merged = mergeRecord(previous, rawPiece);
+                try {
+                    active = { version: 4, ...applyConfigPatch(active, { tools: { [key]: merged } }), 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, 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 = process.env) {
+    const env = { ...source };
+    for (const key of SENSITIVE_ENV_KEYS)
+        delete env[key];
+    return env;
+}
+export async function trustedToolEnv(kind, service = configService) {
+    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.js

@@ -5,17 +5,33 @@
  *  只从环境变量读取，集中管理所有配置。
  *
  *  必需的环境变量：
- *    MINIMAL_AGENT_BASE_URL   - API 地址，如 https://api.minimax.chat/v1
+ *    MINIMAL_AGENT_BASE_URL   - API 完整端点地址，如 https://api.minimax.chat/v1/chat/completions
  *    MINIMAL_AGENT_API_KEY    - API key
  *    MINIMAL_AGENT_MODEL      - 模型名，如 MiniMax-M2.7
  *
  *  可选的环境变量：
  *    MINIMAL_AGENT_PROVIDER   - 友好名称，默认 "env"
  *    MINIMAL_AGENT_CONTEXT_WINDOW - 上下文窗口，默认 128000
+ *    MINIMAL_AGENT_MAX_TOKENS - 单次输出 token 上限，默认 16384（弱 provider 默认偏小会截断长输出）
  * ============================================================
  */
-import { readSavedConfig } from './config/configFile.js';
+import { configService } from './config/configService.js';
 const DEFAULT_CONTEXT_WINDOW = 128_000;
+/**
+ * 单次输出 token 上限的默认值。
+ *
+ * 16384：实测火山豆包接受、足够一次性写完整篇 PLAN.md（实测 ~6.5k token），又远低于
+ * 豆包 131072 的宽容上限。不发 max_tokens 的话豆包默认仅 4096，长输出会被硬截断。
+ * 个别 provider 若拒绝该值，client 会自动去掉 max_tokens 重发降级。
+ */
+const DEFAULT_MAX_TOKENS = 16_384;
+/** 解析正整数环境变量（NaN/≤0 → undefined，由调用方决定默认值）。 */
+function parsePositiveInt(raw) {
+    if (!raw)
+        return undefined;
+    const n = parseInt(raw, 10);
+    return !Number.isNaN(n) && n > 0 ? n : undefined;
+}
 /**
  * 解析压缩阈值比例（0~1 小数）。
  * 非法值（NaN、0、负数、>1）返回 undefined，由调用方决定是否用默认值 0.85。
@@ -60,78 +76,22 @@ export async function loadProvider() {
         }
     }
     const compactRatio = parseCompactRatio(process.env.MINIMAL_AGENT_COMPACT_RATIO);
+    const maxTokens = parsePositiveInt(process.env.MINIMAL_AGENT_MAX_TOKENS) ?? DEFAULT_MAX_TOKENS;
     return {
         name: process.env.MINIMAL_AGENT_PROVIDER ?? 'env',
         baseURL,
         apiKey,
         model,
         contextWindow,
+        maxTokens,
         ...(compactRatio !== undefined ? { compactRatio } : {}),
     };
 }
-/**
- * 层级加载：env 优先（模式 A），不全则回退到 ~/.minimal-agent/config.json（模式 B）。
- * 都没有时返回 null —— 调用方决定是触发向导还是直接退出。
- *
- * 与 loadProvider() 的区别：
- *   - loadProvider() 只读 env，全缺则抛错（给 -p 模式用，明确告知"先做配置"）
- *   - 本函数静默 fallback 到 JSON，全缺则返回 null（给 TUI 模式用，可触发向导）
- *
- * env 字段优先级是逐项的：只要 env 里有 BASE_URL 就用 env 的 BASE_URL，
- * 其它字段从 JSON 补；这样用户可以临时用 env 覆盖单个字段做调试。
- */
+/** Shared CLI/Desktop configuration: JSON first, environment only as bootstrap or env mode. */
 export async function loadProviderLayered() {
-    const envBaseURL = process.env.MINIMAL_AGENT_BASE_URL;
-    const envApiKey = process.env.MINIMAL_AGENT_API_KEY;
-    const envModel = process.env.MINIMAL_AGENT_MODEL;
-    const envName = process.env.MINIMAL_AGENT_PROVIDER;
-    const envContextRaw = process.env.MINIMAL_AGENT_CONTEXT_WINDOW;
-    let saved = null;
-    if (!envBaseURL || !envApiKey || !envModel) {
-        saved = await readSavedConfig();
-    }
-    const baseURL = envBaseURL ?? saved?.baseURL;
-    const apiKey = envApiKey ?? saved?.apiKey;
-    const model = envModel ?? saved?.model;
-    if (!baseURL || !apiKey || !model)
-        return null;
-    let contextWindow = DEFAULT_CONTEXT_WINDOW;
-    if (envContextRaw) {
-        const n = parseInt(envContextRaw, 10);
-        if (!Number.isNaN(n) && n > 0)
-            contextWindow = n;
-    }
-    else if (saved?.contextWindow) {
-        contextWindow = saved.contextWindow;
-    }
-    // compactRatio：env 优先（测试时临时 MINIMAL_AGENT_COMPACT_RATIO=0.2 即可），否则取 saved。
-    const envRatio = parseCompactRatio(process.env.MINIMAL_AGENT_COMPACT_RATIO);
-    const compactRatio = envRatio ??
-        (typeof saved?.compactRatio === 'number' ? saved.compactRatio : undefined);
-    return {
-        name: envName ?? saved?.provider ?? 'env',
-        baseURL,
-        apiKey,
-        model,
-        contextWindow,
-        ...(compactRatio !== undefined ? { compactRatio } : {}),
-    };
+    return configService.provider();
 }
-/**
- * 把 saved config 里的工具 key 注入 process.env（env 已设则不覆盖）。
- *
- * 解决 npm 全局安装场景：`node dist/main.js` 不会自动加载 .env，
- * Tavily 之类的工具 key 只能从 ~/.minimal-agent/config.json 取出再写回 env，
- * websearch.ts 才能在 call() 里读到。
- *
- * 应在 main() 最早期调用（initWorkingDir 之后即可），保证 ALL_TOOLS
- * 任何 call() 触发前 env 已就位。
- */
+/** @deprecated Compatibility hook. Trusted tools now read ConfigService directly. */
 export async function applyToolKeysToEnv() {
-    const saved = await readSavedConfig();
-    if (!saved)
-        return;
-    if (!process.env.TAVILY_API_KEY && saved.tavilyApiKey) {
-        process.env.TAVILY_API_KEY = saved.tavilyApiKey;
-    }
+    await configService.reload();
 }

package/src/context/agentHome.js

@@ -0,0 +1,9 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** 测试和嵌入宿主可覆盖 home 根，生产默认使用系统主目录。 */
+export function agentHomeBase() {
+    return process.env.MINIMAL_AGENT_HOME || homedir();
+}
+export function agentStateDir() {
+    return join(agentHomeBase(), '.minimal-agent');
+}

package/src/context/archive.js

@@ -26,6 +26,7 @@ import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { getWorkingDir } from '../bootstrap/workingDir.js';
+import { contentToPlainText } from '../multimodal.js';
 /** 解析 archive 根目录，支持 MINIMAL_AGENT_HOME 测试覆盖 */
 function agentHome() {
     return process.env.MINIMAL_AGENT_HOME ?? homedir();
@@ -51,6 +52,10 @@ export async function archiveCurrent(messages) {
     await mkdir(dir, { recursive: true });
     const id = new Date().toISOString().replace(/:/g, '-');
     const path = join(dir, `${id}.json`);
+    // 写入完整 messages（含 system）—— restoreArchive 期待原样还原以做 roundtrip
+    // 跳过判定单独用 nonSystem（空对话不归档）—— 这是有意分层的：
+    //   skip 判定 = "有没有用户/助手消息可归档"
+    //   write 内容 = "保留完整上下文供 /restore 还原"
     await writeFile(path, JSON.stringify({ updatedAt: Date.now(), messages }), 'utf8');
     return id;
 }
@@ -82,8 +87,8 @@ export async function listArchives() {
             if (!Array.isArray(data.messages))
                 continue;
             const firstUser = data.messages.find((m) => m.role === 'user');
-            const preview = firstUser && typeof firstUser.content === 'string'
-                ? firstUser.content.replace(/\s+/g, ' ').slice(0, 80)
+            const preview = firstUser
+                ? contentToPlainText(firstUser.content).replace(/\s+/g, ' ').slice(0, 80)
                 : '';
             entries.push({
                 id,

package/src/context/compact.js

@@ -299,7 +299,7 @@ export async function autoCompactIfNeeded(messages, provider, opts) {
         return { messages, compacted: false, before, after: before };
     }
     // 真正要压缩了
-    const compactedMessages = await runCompaction(messages, provider);
+    const compactedMessages = await runCompaction(messages, provider, opts?.signal, opts?.chat ?? chat);
     const after = countMessagesTokens(compactedMessages);
     return { messages: compactedMessages, compacted: true, before, after };
 }
@@ -309,9 +309,11 @@ export async function autoCompactIfNeeded(messages, provider, opts) {
  * 与 autoCompactIfNeeded 共用同一段 runCompaction 逻辑；区别仅在于此函数
  * 永远跑压缩、不返回 `compacted` 字段（由调用方决定如何反馈）。
  */
-export async function forceCompact(messages, provider) {
+export async function forceCompact(messages, provider, signal, 
+/** 注入 chat 实现（仅测试用；生产不传走默认实现）。 */
+chatFn = chat) {
     const before = countMessagesTokens(messages);
-    const compactedMessages = await runCompaction(messages, provider);
+    const compactedMessages = await runCompaction(messages, provider, signal, chatFn);
     const after = countMessagesTokens(compactedMessages);
     return { messages: compactedMessages, before, after };
 }
@@ -324,7 +326,7 @@ export async function forceCompact(messages, provider) {
  * ✅ 关键修复：使用 findTailWithCompleteToolChains() 替代简单的 slice(-N)
  * 保证压缩后的消息结构符合 OpenAI 协议要求（tool 消息必须有对应的 tool_call 父消息）。
  */
-async function runCompaction(messages, provider) {
+async function runCompaction(messages, provider, signal, chatFn = chat) {
     // 1. 找出原 system（保留它，避免 agent 失忆）
     const systemMsg = messages.find((m) => m.role === 'system');
     const nonSystem = messages.filter((m) => m.role !== 'system');
@@ -342,10 +344,11 @@ async function runCompaction(messages, provider) {
     // 3. 调 LLM（用同一个 chat() 但不传工具，避免模型尝试调用工具）
     let summary = '';
     try {
-        for await (const ev of chat({
+        for await (const ev of chatFn({
             provider,
             messages: compactRequest,
             tools: [],
+            signal,
         })) {
             if (ev.type === 'text_delta')
                 summary += ev.delta;