evolcore 0.0.1 → 0.0.2

package/dist/core/daemon-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、config.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();

package/dist/core/event-bus.js

@@ -0,0 +1,32 @@
+import { EventEmitter } from 'events';
+export class EventBus extends EventEmitter {
+    publish(event) {
+        const handlers = [
+            ...this.listeners(event.type),
+            ...this.listeners('*'),
+        ];
+        for (const handler of handlers) {
+            try {
+                handler(event);
+            }
+            catch (err) {
+                console.error(`[EventBus] Handler error for ${event.type}:`, err);
+            }
+        }
+    }
+    subscribe(eventType, handler) {
+        this.on(eventType, handler);
+    }
+    subscribeAll(handler) {
+        this.on('*', handler);
+    }
+    subscribePrefix(prefix, handler) {
+        this.on('*', (event) => {
+            if (event.type.startsWith(prefix))
+                handler(event);
+        });
+    }
+    unsubscribe(eventType, handler) {
+        this.off(eventType, handler);
+    }
+}