evolclaw 3.1.10 → 3.2.0

package/dist/cli/init.js

@@ -4,7 +4,9 @@ import readline from 'readline';
 import { resolvePaths, ensureDataDirs } from '../paths.js';
 import { commandExists } from '../utils/cross-platform.js';
 import { scanInstances } from '../utils/instance-registry.js';
-import { saveDefaultsSafe, loadAllAgents } from '../config-store.js';
+import { saveDefaultsSafe, loadAllAgents, migrateProcessConfigIfNeeded } from '../config-store.js';
+import { loadEvolclawConfig, saveEvolclawConfig } from '../evolclaw-config.js';
+import { generateControlAid } from '../aun/aid/control-aid.js';
 import { isCodexSdkAvailable } from '../agents/codex-runner.js';
 // ==================== Helpers ====================
 function ask(rl, question) {
@@ -36,10 +38,35 @@ function buildDefaults(chosen, available, projectsDefaultPath) {
 function writeDefaults(chosen, available, projectsDefaultPath) {
     saveDefaultsSafe(buildDefaults(chosen, available, projectsDefaultPath));
 }
+/** 启动门禁判定：缺控制 AID 且处于交互式终端时，应进 init 向导补全。
+ *  非 TTY（restart-monitor/systemd/管道）即使缺 aid 也不进 init（无法交互），由 daemon 侧 warn 兜底。 */
+export function needsControlAidInit(aid, isTty) {
+    return !aid && isTty;
+}
+/** 解析用户输入的 owner AID 列表：按空白/逗号分隔，去空、去重、按 isValid 分流。
+ *  空输入 → valid:[]（视为跳过）。 */
+export function parseOwnerAids(raw, isValid) {
+    const tokens = raw.split(/[\s,]+/).map(t => t.trim()).filter(Boolean);
+    const valid = [];
+    const invalid = [];
+    for (const t of tokens) {
+        if (isValid(t)) {
+            if (!valid.includes(t))
+                valid.push(t);
+        }
+        else {
+            invalid.push(t);
+        }
+    }
+    return { valid, invalid };
+}
 // ==================== Main ====================
 export async function cmdInit(options) {
     const p = resolvePaths();
     ensureDataDirs();
+    // config.json → evolclaw.json：init 路径也可能先于 daemon 触发 AID 生成（走 getAidStore），
+    // 须在任何 getAidStore 之前迁移 encryptionSeed。
+    migrateProcessConfigIfNeeded();
     // ── 1. 单进程互斥 ──
     const aliveMains = scanInstances().mains.filter(m => m.alive);
     if (aliveMains.length > 0) {
@@ -66,110 +93,163 @@ export async function cmdInit(options) {
     // ── 3. 非交互式分支 ──
     if (options?.nonInteractive) {
         if (exists && !options.force) {
-            console.log(`❌ 配置已存在: ${defaultsPath}（加 --force 可覆盖）`);
-            return;
+            // 配置已存在且未 --force：不重写 defaults，但仍落到共享 tail（幂等补生成控制 AID）
+            console.log(`配置已存在: ${defaultsPath}（加 --force 可覆盖）`);
         }
-        let chosen;
-        if (options.baseagent) {
-            if (!BASEAGENT_CANDIDATES.includes(options.baseagent)) {
-                console.log(`❌ 无效 baseagent: ${options.baseagent}（可选: ${BASEAGENT_CANDIDATES.join('/')}）`);
-                return;
+        else {
+            let chosen;
+            if (options.baseagent) {
+                if (!BASEAGENT_CANDIDATES.includes(options.baseagent)) {
+                    console.log(`❌ 无效 baseagent: ${options.baseagent}（可选: ${BASEAGENT_CANDIDATES.join('/')}）`);
+                    return; // 硬错误：不落 tail
+                }
+                if (!available.includes(options.baseagent)) {
+                    console.log(`❌ ${options.baseagent} 当前环境不可用（可用: ${available.join('/')}）`);
+                    return; // 硬错误：不落 tail
+                }
+                chosen = options.baseagent;
             }
-            if (!available.includes(options.baseagent)) {
-                console.log(`❌ ${options.baseagent} 当前环境不可用（可用: ${available.join('/')}）`);
-                return;
+            else {
+                chosen = pickDefault(available);
             }
-            chosen = options.baseagent;
-        }
-        else {
-            chosen = pickDefault(available);
-        }
-        writeDefaults(chosen, available);
-        console.log(`✓ 已${exists ? '覆盖' : '创建'}: ${defaultsPath}`);
-        console.log(`  active_baseagent: ${chosen}`);
-        const { agents } = loadAllAgents();
-        if (agents.length === 0) {
-            console.log('\n提示：尚无 agent，运行以下命令创建：');
-            console.log('  evolclaw agent new <aid>.agentid.pub');
+            writeDefaults(chosen, available);
+            console.log(`✓ 已${exists ? '覆盖' : '创建'}: ${defaultsPath}`);
+            console.log(`  active_baseagent: ${chosen}`);
         }
-        return;
+        // 落到共享 tail（不 return）
     }
-    // ── 4. 交互式分支 ──
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    async function askBaseagent() {
-        const defaultBa = pickDefault(available);
-        if (available.length === 1) {
-            console.log(`  baseagent: ${defaultBa}`);
-            return defaultBa;
-        }
-        let chosen = null;
-        while (chosen === null) {
-            const input = (await ask(rl, `默认 baseagent (${available.join('/')}) [${defaultBa}]: `)).trim() || defaultBa;
-            if (!BASEAGENT_CANDIDATES.includes(input)) {
-                console.log(`  无效选择，可选: ${BASEAGENT_CANDIDATES.join('/')}`);
-                continue;
+    else {
+        // ── 4. 交互式分支（rl 生命周期封装在内部函数，tail 不引用 rl）──
+        await runInteractive();
+    }
+    // ── 共享 tail（单一出口）：提示创建 agent + 生成控制 AID ──
+    await initTail();
+    // ── 内部函数 ──
+    async function runInteractive() {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        async function askBaseagent() {
+            const defaultBa = pickDefault(available);
+            if (available.length === 1) {
+                console.log(`  baseagent: ${defaultBa}`);
+                return defaultBa;
             }
-            if (!available.includes(input)) {
-                console.log(`  ${input} 当前环境不可用（可用: ${available.join('/')}）`);
-                continue;
+            let chosen = null;
+            while (chosen === null) {
+                const input = (await ask(rl, `默认 baseagent (${available.join('/')}) [${defaultBa}]: `)).trim() || defaultBa;
+                if (!BASEAGENT_CANDIDATES.includes(input)) {
+                    console.log(`  无效选择，可选: ${BASEAGENT_CANDIDATES.join('/')}`);
+                    continue;
+                }
+                if (!available.includes(input)) {
+                    console.log(`  ${input} 当前环境不可用（可用: ${available.join('/')}）`);
+                    continue;
+                }
+                chosen = input;
             }
-            chosen = input;
+            return chosen;
         }
-        return chosen;
-    }
-    async function askProjectsDefaultPath() {
-        const defaultDir = path.join(p.root, 'projects', 'default');
-        const input = (await ask(rl, `项目默认目录 [${defaultDir}]: `)).trim();
-        const resolved = input || defaultDir;
-        if (!path.isAbsolute(resolved)) {
-            console.log('  ⚠ 需要绝对路径，已跳过');
-            return undefined;
-        }
-        if (!fs.existsSync(resolved)) {
-            const create = (await ask(rl, `  目录不存在，是否创建？[Y/n]: `)).trim().toLowerCase();
-            if (create === '' || create === 'y' || create === 'yes') {
-                fs.mkdirSync(resolved, { recursive: true });
-                console.log(`  ✓ 已创建 ${resolved}`);
-            }
-            else {
+        async function askProjectsDefaultPath() {
+            const defaultDir = path.join(p.root, 'projects', 'default');
+            const input = (await ask(rl, `项目默认目录 [${defaultDir}]: `)).trim();
+            const resolved = input || defaultDir;
+            if (!path.isAbsolute(resolved)) {
+                console.log('  ⚠ 需要绝对路径，已跳过');
                 return undefined;
             }
+            if (!fs.existsSync(resolved)) {
+                const create = (await ask(rl, `  目录不存在，是否创建？[Y/n]: `)).trim().toLowerCase();
+                if (create === '' || create === 'y' || create === 'yes') {
+                    fs.mkdirSync(resolved, { recursive: true });
+                    console.log(`  ✓ 已创建 ${resolved}`);
+                }
+                else {
+                    return undefined;
+                }
+            }
+            return resolved;
         }
-        return resolved;
-    }
-    try {
-        if (exists) {
-            const ans = (await ask(rl, `配置文件已存在: ${defaultsPath}\n  是否覆盖？[y/N] `)).trim().toLowerCase();
-            if (ans === 'y' || ans === 'yes') {
+        try {
+            if (exists) {
+                const ans = (await ask(rl, `配置文件已存在: ${defaultsPath}\n  是否覆盖？[y/N] `)).trim().toLowerCase();
+                if (ans === 'y' || ans === 'yes') {
+                    const chosen = await askBaseagent();
+                    const projectsDefaultPath = await askProjectsDefaultPath();
+                    writeDefaults(chosen, available, projectsDefaultPath);
+                    console.log(`\n✓ 已覆盖: ${defaultsPath}`);
+                    console.log(`  active_baseagent: ${chosen}\n`);
+                }
+                else {
+                    console.log('  已跳过（保留现有配置）\n');
+                }
+            }
+            else {
                 const chosen = await askBaseagent();
                 const projectsDefaultPath = await askProjectsDefaultPath();
                 writeDefaults(chosen, available, projectsDefaultPath);
-                console.log(`\n✓ 已覆盖: ${defaultsPath}`);
+                console.log(`\n✓ 已创建: ${defaultsPath}`);
                 console.log(`  active_baseagent: ${chosen}\n`);
             }
-            else {
-                console.log('  已跳过（保留现有配置）\n');
+        }
+        finally {
+            try {
+                rl.close();
             }
+            catch { /* ignore */ }
         }
-        else {
-            const chosen = await askBaseagent();
-            const projectsDefaultPath = await askProjectsDefaultPath();
-            writeDefaults(chosen, available, projectsDefaultPath);
-            console.log(`\n✓ 已创建: ${defaultsPath}`);
-            console.log(`  active_baseagent: ${chosen}\n`);
+    }
+}
+/** 补全控制 AID + owners（可单独调用，不走 baseagent 向导）。 */
+export async function initTail() {
+    // 提示创建 agent（两分支汇合后执行一次）
+    const { agents } = loadAllAgents();
+    if (agents.length === 0) {
+        console.log('\n提示：尚无 agent，运行以下命令创建：');
+        console.log('  evolclaw agent new <aid>.agentid.pub');
+    }
+    // 控制 AID：daemon 进程身份。缺失则生成并写回 evolclaw.json（幂等：已存在则跳过）。
+    const evc = loadEvolclawConfig();
+    if (evc.aid) {
+        console.log(`✓ 控制 AID 已存在: ${evc.aid}`);
+    }
+    else {
+        try {
+            const { aid } = await generateControlAid();
+            saveEvolclawConfig({ ...evc, $schema_version: evc.$schema_version ?? 1, aid });
+            console.log(`✓ 已生成控制 AID: ${aid}`);
         }
-        // ── 5. 提示创建 agent ──
-        const { agents } = loadAllAgents();
-        if (agents.length === 0) {
-            console.log('提示：尚无 agent，运行以下命令创建：');
-            console.log('  evolclaw agent new <aid>.agentid.pub');
+        catch (e) {
+            console.error(`⚠️ 控制 AID 生成失败（Gateway 不可达？联网后重跑 evolclaw init 补全）: ${e?.message || e}`);
         }
     }
-    finally {
+    // 配置进程级管理者（owners）：仅交互式 + aid 已配置 + owners 未配置时询问
+    const evcForOwners = loadEvolclawConfig();
+    if (process.stdin.isTTY && evcForOwners.aid && (!evcForOwners.owners || evcForOwners.owners.length === 0)) {
+        const { isValidAid } = await import('../aun/aid/index.js');
+        const rlOwners = readline.createInterface({ input: process.stdin, output: process.stdout });
         try {
-            rl.close();
+            const raw = (await ask(rlOwners, '\n请输入 EvolClaw 管理者 AID: ')).trim();
+            if (raw) {
+                const { valid, invalid } = parseOwnerAids(raw, isValidAid);
+                if (invalid.length > 0)
+                    console.log(`  ⚠ 跳过非法 AID: ${invalid.join(', ')}`);
+                if (valid.length > 0) {
+                    saveEvolclawConfig({ ...loadEvolclawConfig(), owners: valid });
+                    console.log(`  ✓ 已配置管理者: ${valid.join(', ')}`);
+                }
+                else {
+                    console.log('  未输入合法 AID，已跳过 owners 配置');
+                }
+            }
+            else {
+                console.log('  已跳过 owners 配置（可日后编辑 evolclaw.json 或重跑 evolclaw init）');
+            }
+        }
+        finally {
+            try {
+                rlOwners.close();
+            }
+            catch { /* ignore */ }
         }
-        catch { /* ignore */ }
     }
 }
 /**

package/dist/config-store.js

@@ -17,6 +17,7 @@ import fs from 'fs';
 import path from 'path';
 import { resolvePaths, agentConfig as agentConfigPath, agentDir, } from './paths.js';
 import { atomicReadJson, atomicWriteJson } from './utils/atomic-write.js';
+import * as evolclawConfigModule from './evolclaw-config.js';
 import { checkAgentDir, isValidAid } from './aun/aid/validation.js';
 import { isValidChannelName } from './core/channel-loader.js';
 import { CONFIG_SCHEMA_VERSION } from './types.js';
@@ -122,14 +123,42 @@ export function saveDefaultsSafe(patch) {
         : { $schema_version: CONFIG_SCHEMA_VERSION, ...patch };
     atomicWriteJson(p, merged);
 }
-export function loadProcessConfig() {
-    const raw = atomicReadJson(resolvePaths().processConfig);
+// ── 进程配置迁移（旧 {root}/config.json ProcessConfig → evolclaw.json）──────
+//
+// ProcessConfig 类型 + loadProcessConfig/saveProcessConfig 已废弃并删除：
+// 唯一有效字段 aun.encryptionSeed 已迁入 evolclaw.json（见 migrateProcessConfigIfNeeded），
+// 读取源切到 loadEvolclawConfig（store.ts）。log / aun.gateway / aun.keystorePath 是死字段。
+/**
+ * 一次性迁移：{root}/config.json（旧 ProcessConfig）→ {root}/evolclaw.json。
+ * - 仅搬运 aun.encryptionSeed（逐字节原样，含 null）；log / aun.gateway / aun.keystorePath 是死字段，丢弃。
+ * - 合并写入（不覆盖 evolclaw.json 已有字段如 aid）。
+ * - 完成后归档 config.json → config.json.migrated（保留备份，不直接删）。
+ *
+ * ⚠️ encryptionSeed 是 AID 私钥的加密种子，迁移前后 getAidStore 拿到的 seed 必须逐字节一致，
+ * 否则所有已注册 AID 私钥解不开。这里只搬运不改值（含 null）。
+ */
+export function migrateProcessConfigIfNeeded() {
+    const p = resolvePaths();
+    const oldPath = p.processConfig; // {root}/config.json
+    const raw = atomicReadJson(oldPath);
     if (raw === null)
-        return {};
-    return expandEnvRefs(raw);
-}
-export function saveProcessConfig(value) {
-    atomicWriteJson(resolvePaths().processConfig, value);
+        return; // 不存在 → no-op
+    const { loadEvolclawConfig, saveEvolclawConfig } = evolclawConfigModule;
+    const evc = loadEvolclawConfig();
+    // 仅当旧文件确实带 aun.encryptionSeed 字段时才搬（hasOwnProperty，保 null 语义）
+    const didMigrateSeed = !!(raw.aun && Object.prototype.hasOwnProperty.call(raw.aun, 'encryptionSeed'));
+    if (didMigrateSeed) {
+        evc.aun = { ...(evc.aun ?? {}), encryptionSeed: raw.aun.encryptionSeed };
+    }
+    evc.$schema_version = evc.$schema_version ?? 1;
+    saveEvolclawConfig(evc);
+    // 归档旧文件（不删，留备份）
+    try {
+        fs.renameSync(oldPath, oldPath + '.migrated');
+    }
+    catch { /* ignore */ }
+    const what = didMigrateSeed ? 'aun.encryptionSeed 已搬运' : 'aun.encryptionSeed 不存在（无需搬运）';
+    logger.info(`[migrate] config.json → evolclaw.json (${what}，config.json 已归档为 .migrated)`);
 }
 // ── 自动迁移 ───────────────────────────────────────────────────────────
 /**
@@ -492,6 +521,8 @@ export function mergeForAgent(agent, defaults) {
         debounce: agent.debounce ?? d.debounce,
         debug: deepMergeBlocks(d.debug, agent.debug),
         enable_rich_content: agent.enable_rich_content ?? d.enable_rich_content,
+        dispatch: agent.dispatch,
+        observable: agent.observable,
     };
     return merged;
 }

package/dist/core/cache/file-cache.js

@@ -0,0 +1,216 @@
+/**
+ * FileCache —— 统一的文件缓存（daemon-only）。
+ *
+ * daemon 每条消息处理时读大量文件（manifest、fragment、md、working memory、
+ * 关系级 preferences 等）。本类统一缓存"文件 → 解析后内容"，按策略门控变化检查。
+ *
+ * 设计与边界详见 docs/file-cache-design.md：
+ *  - 不接管 EvolAgent 的 merged config（agent/defaults 由 EvolAgent 持有权威副本）。
+ *  - daemon-only：CLI 短命进程仍直读最新盘值，不用本缓存。
+ *  - 只缓存"文件 → 解析后内容"，不缓存按 vars 渲染后的结果。
+ *
+ * 策略（reload/重启永远全量失效，无视策略；策略只决定"平时每次读怎么检查"）：
+ *  - on-reload：平时不检查，直接用缓存（kits 文件、persona）。靠 reload/重启刷新。
+ *  - manual：同 on-reload，额外支持显式 invalidate(file) 单刷。
+ *  - mtime：每次读 statSync 门控 mtime，变了自动重读（working.md、preferences.json）。
+ *
+ * 容量：项数可无界增长的组（如 relation-prefs，每 peer 一文件）设 LRU 硬上限
+ * （见 GROUP_CAPS），命中/写入移到末尾、超限驱逐同组最旧项；无 timer。
+ * 项数固定的组（kits、per-agent 身份层）不设限。
+ *
+ * 监控：内置命中/读盘/驱逐/失效计数（总计 + 按 group + 按 policy），stats() 导出
+ * 快照供 watch web 的 Cache 页展示（经 IPC 'cache-stats'）。计数是整数自增，热路径无感。
+ */
+import fs from 'fs';
+const GROUP_NONE = '(none)'; // group 未指定时的归类键
+function newCounters() {
+    return { gets: 0, hits: 0, misses: 0, statChecks: 0, reReads: 0, evictions: 0, invalidations: 0 };
+}
+/**
+ * 按组的容量上限（LRU）。只有"项数可无界增长"的组才设限——典型是关系级
+ * preferences，每个 peer 一个文件，daemon 长跑接触的 peer 越来越多。
+ * kits（项数随包固定）、per-agent 身份层（agent 数量有限）不设限，不在此表即无限。
+ * 命中/写入都把 key 移到 Map 末尾（Map 保留插入序 → 头部即最久未用），
+ * 超限时从头部驱逐同组最旧项。无 timer，确定性 bound。
+ */
+const GROUP_CAPS = {
+    'relation-prefs': 512,
+};
+export class FileCache {
+    cache = new Map();
+    // 监控计数器（总计 + 按 group + 按 policy）。group 未指定归入 GROUP_NONE。
+    since = Date.now();
+    totals = newCounters();
+    byGroup = new Map();
+    byPolicy = {
+        'on-reload': newCounters(), 'manual': newCounters(), 'mtime': newCounters(),
+    };
+    /** 取（或建）某 group 的计数器。 */
+    groupCounters(group) {
+        const key = group ?? GROUP_NONE;
+        let c = this.byGroup.get(key);
+        if (!c) {
+            c = newCounters();
+            this.byGroup.set(key, c);
+        }
+        return c;
+    }
+    /** 同一事件按 总计/group/policy 三维各加一次。delta 缺省 1。 */
+    bump(group, policy, field, delta = 1) {
+        this.totals[field] += delta;
+        this.groupCounters(group)[field] += delta;
+        this.byPolicy[policy][field] += delta;
+    }
+    /**
+     * 读取并缓存文件。loader 把原始内容（UTF-8 字符串；文件不存在时为 null）转成目标值。
+     * 同一 file 的 policy/group 以首次注册为准。
+     * opts.read 可注入自定义读取器（如 atomicRead 保留崩溃恢复）；缺省 readFileOrNull。
+     */
+    get(file, loader, opts) {
+        const existing = this.cache.get(file);
+        const read = opts.read ?? readFileOrNull;
+        this.bump(opts.group, opts.policy, 'gets');
+        if (opts.policy === 'mtime') {
+            const mtimeMs = statMtime(file);
+            this.bump(opts.group, opts.policy, 'statChecks');
+            if (existing && existing.mtimeMs === mtimeMs) {
+                this.bump(opts.group, opts.policy, 'hits');
+                this.touch(file, existing);
+                return existing.value;
+            }
+            // 已有条目但 mtime 变了 → 带外改后重读（区别于首次 miss）
+            if (existing)
+                this.bump(opts.group, opts.policy, 'reReads');
+            this.bump(opts.group, opts.policy, 'misses');
+            const raw = read(file);
+            const value = loader(raw);
+            this.store(file, { policy: 'mtime', group: opts.group, mtimeMs, value, bytes: approxBytes(raw) });
+            return value;
+        }
+        // on-reload / manual：命中即用，不检查文件
+        if (existing) {
+            this.bump(opts.group, opts.policy, 'hits');
+            this.touch(file, existing);
+            return existing.value;
+        }
+        this.bump(opts.group, opts.policy, 'misses');
+        const raw = read(file);
+        const value = loader(raw);
+        this.store(file, { policy: opts.policy, group: opts.group, value, bytes: approxBytes(raw) });
+        return value;
+    }
+    /** 命中时把 key 移到 Map 末尾，维持 LRU 顺序（仅对设了容量上限的组有意义）。 */
+    touch(file, entry) {
+        if (entry.group === undefined || GROUP_CAPS[entry.group] === undefined)
+            return;
+        this.cache.delete(file);
+        this.cache.set(file, entry);
+    }
+    /** 写入并对设限组做 LRU 驱逐（踢同组最久未用项）。 */
+    store(file, entry) {
+        this.cache.delete(file); // 确保重写时移到末尾
+        this.cache.set(file, entry);
+        const cap = entry.group !== undefined ? GROUP_CAPS[entry.group] : undefined;
+        if (cap === undefined)
+            return;
+        // Map 按插入序遍历，头部即最久未用；驱逐同组超出容量的最旧项。
+        let count = 0;
+        for (const e of this.cache.values())
+            if (e.group === entry.group)
+                count++;
+        if (count <= cap)
+            return;
+        for (const [k, e] of this.cache) {
+            if (count <= cap)
+                break;
+            if (e.group === entry.group) {
+                this.cache.delete(k);
+                count--;
+                this.bump(e.group, e.policy, 'evictions');
+            }
+        }
+    }
+    /** 读纯文本的便捷封装（文件不存在返回 null）。 */
+    getText(file, opts) {
+        return this.get(file, (raw) => raw, opts);
+    }
+    /** 单文件失效（manual 策略单刷 / 精确失效）。 */
+    invalidate(file) {
+        const entry = this.cache.get(file);
+        if (this.cache.delete(file) && entry)
+            this.bump(entry.group, entry.policy, 'invalidations');
+    }
+    /** 按组失效（reload 钩子失效一组，如 'kits' / 'agent-files:<aid>'）。 */
+    invalidateGroup(group) {
+        for (const [file, entry] of this.cache) {
+            if (entry.group === group) {
+                this.cache.delete(file);
+                this.bump(entry.group, entry.policy, 'invalidations');
+            }
+        }
+    }
+    /** 全量失效（reload / 升级兜底）。 */
+    invalidateAll() {
+        for (const entry of this.cache.values())
+            this.bump(entry.group, entry.policy, 'invalidations');
+        this.cache.clear();
+    }
+    /** 当前缓存条目数（诊断用）。 */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * 运行时统计快照（监控用）。累计计数 O(1) 取出；占用（size/内存/容量）即时遍历
+     * 当前 entries 算出——条目数有限（kits 固定、relation-prefs 有 LRU 上限），便宜。
+     */
+    stats() {
+        const occupancy = {};
+        for (const entry of this.cache.values()) {
+            const key = entry.group ?? GROUP_NONE;
+            let occ = occupancy[key];
+            if (!occ) {
+                occ = { size: 0, bytes: 0, cap: GROUP_CAPS[key] ?? null };
+                occupancy[key] = occ;
+            }
+            occ.size++;
+            occ.bytes += entry.bytes;
+        }
+        const byGroup = {};
+        for (const [k, c] of this.byGroup)
+            byGroup[k] = { ...c };
+        return {
+            since: this.since,
+            size: this.cache.size,
+            totals: { ...this.totals },
+            byGroup,
+            byPolicy: {
+                'on-reload': { ...this.byPolicy['on-reload'] },
+                'manual': { ...this.byPolicy['manual'] },
+                'mtime': { ...this.byPolicy['mtime'] },
+            },
+            occupancy,
+        };
+    }
+}
+function statMtime(file) {
+    try {
+        return fs.statSync(file).mtimeMs;
+    }
+    catch {
+        return null; // 文件不存在
+    }
+}
+function readFileOrNull(file) {
+    try {
+        return fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/** 缓存值内存占用近似：用读入的原始字符串长度（字节级近似），null 记 0。 */
+function approxBytes(raw) {
+    return raw === null ? 0 : raw.length;
+}
+/** daemon 单例。CLI 进程不应使用本实例。 */
+export const fileCache = new FileCache();