autosnippet 3.3.0 → 3.3.3

package/dist/lib/infrastructure/report/ReportStore.js

@@ -0,0 +1,133 @@
+/**
+ * ReportStore — 报告持久化服务
+ *
+ * 管道产物（governance / compliance / metrics / analysis）写入 JSONL，
+ * 供 API 查询历史报告。
+ *
+ * @module infrastructure/report/ReportStore
+ */
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+// ── Constants ───────────────────────────────────────
+const VALID_CATEGORIES = new Set([
+    'governance',
+    'compliance',
+    'metrics',
+    'analysis',
+]);
+// ── ReportStore ─────────────────────────────────────
+export class ReportStore {
+    #baseDir;
+    constructor(baseDir) {
+        this.#baseDir = baseDir;
+    }
+    /** 写入一条报告（追加 JSONL） */
+    async write(entry) {
+        const id = ReportStore.#generateId(entry.timestamp);
+        const full = { id, ...entry };
+        const filePath = this.#resolveFile(entry.category, entry.timestamp);
+        const dir = path.dirname(filePath);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.appendFileSync(filePath, `${JSON.stringify(full)}\n`, 'utf8');
+        return full;
+    }
+    /** 查询报告列表 */
+    async query(opts = {}) {
+        const categories = opts.category?.length
+            ? opts.category.filter((c) => VALID_CATEGORIES.has(c))
+            : [...VALID_CATEGORIES];
+        const all = [];
+        for (const cat of categories) {
+            const catDir = path.join(this.#baseDir, cat);
+            if (!fs.existsSync(catDir)) {
+                continue;
+            }
+            const files = fs
+                .readdirSync(catDir)
+                .filter((f) => f.endsWith('.jsonl'))
+                .sort()
+                .reverse();
+            for (const file of files) {
+                const entries = this.#readJsonl(path.join(catDir, file));
+                all.push(...entries);
+            }
+        }
+        // 过滤
+        let filtered = all;
+        if (opts.type) {
+            filtered = filtered.filter((e) => e.type === opts.type);
+        }
+        if (opts.from) {
+            filtered = filtered.filter((e) => e.timestamp >= opts.from);
+        }
+        if (opts.to) {
+            filtered = filtered.filter((e) => e.timestamp <= opts.to);
+        }
+        // 按时间倒序
+        filtered.sort((a, b) => b.timestamp - a.timestamp);
+        const total = filtered.length;
+        const offset = opts.offset ?? 0;
+        const limit = opts.limit ?? 20;
+        const reports = filtered.slice(offset, offset + limit);
+        return { reports, total };
+    }
+    /** 分类统计 */
+    async stats(opts = {}) {
+        const result = {};
+        for (const cat of VALID_CATEGORIES) {
+            const catDir = path.join(this.#baseDir, cat);
+            if (!fs.existsSync(catDir)) {
+                result[cat] = 0;
+                continue;
+            }
+            const files = fs.readdirSync(catDir).filter((f) => f.endsWith('.jsonl'));
+            let count = 0;
+            for (const file of files) {
+                const entries = this.#readJsonl(path.join(catDir, file));
+                for (const e of entries) {
+                    if (opts.from && e.timestamp < opts.from) {
+                        continue;
+                    }
+                    if (opts.to && e.timestamp > opts.to) {
+                        continue;
+                    }
+                    count++;
+                }
+            }
+            result[cat] = count;
+        }
+        return result;
+    }
+    // ── Private ───────────────────────────────────────
+    #resolveFile(category, timestamp) {
+        const d = new Date(timestamp);
+        const dateStr = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+        return path.join(this.#baseDir, category, `${dateStr}.jsonl`);
+    }
+    #readJsonl(filePath) {
+        try {
+            const content = fs.readFileSync(filePath, 'utf8');
+            const lines = content.split('\n').filter((l) => l.trim());
+            const entries = [];
+            for (const line of lines) {
+                try {
+                    entries.push(JSON.parse(line));
+                }
+                catch {
+                    // 跳过损坏行
+                }
+            }
+            return entries;
+        }
+        catch {
+            return [];
+        }
+    }
+    static #generateId(timestamp) {
+        const d = new Date(timestamp);
+        const dateStr = `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, '0')}${String(d.getDate()).padStart(2, '0')}`;
+        const rand = randomBytes(4).toString('hex');
+        return `rpt-${dateStr}-${rand}`;
+    }
+}

package/dist/lib/infrastructure/signal/SignalAggregator.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SignalAggregator — 滑窗统计 + 异常检测
+ *
+ * 订阅可聚合的事实型信号，周期性写入 Report（统计）并在异常时发射 Signal。
+ *
+ * @module infrastructure/signal/SignalAggregator
+ */
+import type { ReportStore } from '../report/ReportStore.js';
+import type { SignalBus } from './SignalBus.js';
+export declare class SignalAggregator {
+    #private;
+    constructor(signalBus: SignalBus, reportStore: ReportStore, opts?: {
+        intervalMs?: number;
+        windowMs?: number;
+    });
+    start(): void;
+    stop(): void;
+}

package/dist/lib/infrastructure/signal/SignalAggregator.js

@@ -0,0 +1,84 @@
+/**
+ * SignalAggregator — 滑窗统计 + 异常检测
+ *
+ * 订阅可聚合的事实型信号，周期性写入 Report（统计）并在异常时发射 Signal。
+ *
+ * @module infrastructure/signal/SignalAggregator
+ */
+export class SignalAggregator {
+    #bus;
+    #reportStore;
+    #windows = new Map();
+    #intervalMs;
+    #windowMs;
+    #timer = null;
+    constructor(signalBus, reportStore, opts = {}) {
+        this.#bus = signalBus;
+        this.#reportStore = reportStore;
+        this.#intervalMs = opts.intervalMs ?? 60_000;
+        this.#windowMs = opts.windowMs ?? 300_000;
+        // 订阅可聚合的事实型信号
+        signalBus.subscribe('guard|search|usage|lifecycle|forge|decay|quality', (signal) => {
+            this.#record(signal);
+        });
+    }
+    start() {
+        if (this.#timer) {
+            return;
+        }
+        this.#timer = setInterval(() => {
+            void this.#flush();
+        }, this.#intervalMs);
+    }
+    stop() {
+        if (this.#timer) {
+            clearInterval(this.#timer);
+            this.#timer = null;
+        }
+    }
+    #record(signal) {
+        const key = signal.type;
+        if (!this.#windows.has(key)) {
+            this.#windows.set(key, { entries: [], baseline: 0 });
+        }
+        const win = this.#windows.get(key);
+        win.entries.push({ value: signal.value, ts: signal.timestamp });
+    }
+    async #flush() {
+        const now = Date.now();
+        for (const [type, win] of this.#windows) {
+            // 清理过期条目
+            win.entries = win.entries.filter((e) => now - e.ts < this.#windowMs);
+            if (win.entries.length === 0) {
+                continue;
+            }
+            const count = win.entries.length;
+            const avg = win.entries.reduce((s, e) => s + e.value, 0) / count;
+            const max = Math.max(...win.entries.map((e) => e.value));
+            const min = Math.min(...win.entries.map((e) => e.value));
+            // 周期统计 → Report
+            await this.#reportStore.write({
+                category: 'metrics',
+                type: `aggregate_${type}`,
+                producer: 'SignalAggregator',
+                data: {
+                    window: `${this.#windowMs / 1000}s`,
+                    count,
+                    avg,
+                    max,
+                    min,
+                    baseline: win.baseline,
+                },
+                timestamp: now,
+            });
+            // 异常检测 → Signal（信号量突增 3 倍）
+            if (win.baseline > 0 && count > win.baseline * 3) {
+                this.#bus.send('anomaly', `Aggregator.${type}`, 1, {
+                    metadata: { reason: 'spike', count, baseline: win.baseline },
+                });
+            }
+            // 更新 baseline（指数移动平均）
+            win.baseline = win.baseline === 0 ? count : win.baseline * 0.8 + count * 0.2;
+        }
+    }
+}

package/dist/lib/infrastructure/signal/SignalBridge.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SignalBridge — SignalBus → EventBus 单点桥接
+ *
+ * 将 SignalBus 信号转发到 EventBus，实现 SignalBus 纯内核化。
+ * HttpServer 等端口层只需监听 EventBus，不再直接消费 SignalBus。
+ *
+ * @module infrastructure/signal/SignalBridge
+ */
+import type { EventBus } from '../event/EventBus.js';
+import type { SignalBus } from './SignalBus.js';
+export declare class SignalBridge {
+    constructor(signalBus: SignalBus, eventBus: EventBus);
+}

package/dist/lib/infrastructure/signal/SignalBridge.js

@@ -0,0 +1,20 @@
+/**
+ * SignalBridge — SignalBus → EventBus 单点桥接
+ *
+ * 将 SignalBus 信号转发到 EventBus，实现 SignalBus 纯内核化。
+ * HttpServer 等端口层只需监听 EventBus，不再直接消费 SignalBus。
+ *
+ * @module infrastructure/signal/SignalBridge
+ */
+export class SignalBridge {
+    constructor(signalBus, eventBus) {
+        // 全量转发
+        signalBus.subscribe('*', (signal) => {
+            eventBus.emit('signal:event', signal);
+        });
+        // Guard 专用通道
+        signalBus.subscribe('guard', (signal) => {
+            eventBus.emit('guard:updated', signal);
+        });
+    }
+}

package/dist/lib/infrastructure/signal/SignalBus.d.ts

@@ -0,0 +1,63 @@
+/**
+ * SignalBus — 统一信号总线
+ *
+ * Phase 0 核心基础设施。所有子系统（Guard、Search、Agent、Governance）
+ * 通过 Signal Bus 发射和消费结构化信号，替代各自为政的事件分发。
+ *
+ * 设计公理：
+ *   - 同步分发，<0.1ms per emit（消费者自行决定是否 buffer）
+ *   - 支持精确类型订阅和通配符 '*'
+ *   - 支持 pattern 订阅 'guard|search|usage'
+ *
+ * @module infrastructure/signal/SignalBus
+ */
+/** 信号类型枚举 */
+export type SignalType = 'guard' | 'guard_blind_spot' | 'search' | 'usage' | 'lifecycle' | 'exploration' | 'quality' | 'panorama' | 'decay' | 'forge' | 'intent' | 'anomaly';
+/** 信号结构 */
+export interface Signal {
+    /** 信号类别 */
+    type: SignalType;
+    /** 产出模块标识 */
+    source: string;
+    /** 关联 Recipe/Module ID（可选） */
+    target: string | null;
+    /** 标准化信号值 0-1 */
+    value: number;
+    /** 原始数据载荷 */
+    metadata: Record<string, unknown>;
+    /** 信号产生时间戳（ms） */
+    timestamp: number;
+}
+/** 信号处理器 */
+export type SignalHandler = (signal: Signal) => void;
+export declare class SignalBus {
+    #private;
+    /**
+     * 发射信号。同步分发给所有匹配的订阅者。
+     *
+     * @param signal 完整的 Signal 对象
+     */
+    emit(signal: Signal): void;
+    /**
+     * 订阅信号。支持三种模式：
+     * - 精确类型: `subscribe('guard', handler)`
+     * - 多类型:   `subscribe('guard|search|usage', handler)`
+     * - 通配符:   `subscribe('*', handler)`
+     *
+     * @returns 取消订阅函数
+     */
+    subscribe(pattern: string, handler: SignalHandler): () => void;
+    /**
+     * 创建并发射信号的便捷方法。自动填充 timestamp。
+     */
+    send(type: SignalType, source: string, value: number, opts?: {
+        target?: string | null;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /** 已发射的信号总数（诊断用） */
+    get emitCount(): number;
+    /** 活跃订阅者数量（诊断用） */
+    get listenerCount(): number;
+    /** 移除所有订阅者（测试用） */
+    clear(): void;
+}

package/dist/lib/infrastructure/signal/SignalBus.js

@@ -0,0 +1,106 @@
+/**
+ * SignalBus — 统一信号总线
+ *
+ * Phase 0 核心基础设施。所有子系统（Guard、Search、Agent、Governance）
+ * 通过 Signal Bus 发射和消费结构化信号，替代各自为政的事件分发。
+ *
+ * 设计公理：
+ *   - 同步分发，<0.1ms per emit（消费者自行决定是否 buffer）
+ *   - 支持精确类型订阅和通配符 '*'
+ *   - 支持 pattern 订阅 'guard|search|usage'
+ *
+ * @module infrastructure/signal/SignalBus
+ */
+/** 通配符常量 */
+const WILDCARD = '*';
+// ── SignalBus ───────────────────────────────────────
+export class SignalBus {
+    #listeners = new Map();
+    #emitCount = 0;
+    /**
+     * 发射信号。同步分发给所有匹配的订阅者。
+     *
+     * @param signal 完整的 Signal 对象
+     */
+    emit(signal) {
+        this.#emitCount++;
+        // 精确类型匹配
+        const exact = this.#listeners.get(signal.type);
+        if (exact) {
+            for (const handler of exact) {
+                try {
+                    handler(signal);
+                }
+                catch {
+                    // 消费者异常不阻断信号分发
+                }
+            }
+        }
+        // 通配符匹配
+        const wildcard = this.#listeners.get(WILDCARD);
+        if (wildcard) {
+            for (const handler of wildcard) {
+                try {
+                    handler(signal);
+                }
+                catch {
+                    // 消费者异常不阻断信号分发
+                }
+            }
+        }
+    }
+    /**
+     * 订阅信号。支持三种模式：
+     * - 精确类型: `subscribe('guard', handler)`
+     * - 多类型:   `subscribe('guard|search|usage', handler)`
+     * - 通配符:   `subscribe('*', handler)`
+     *
+     * @returns 取消订阅函数
+     */
+    subscribe(pattern, handler) {
+        const types = pattern === WILDCARD ? [WILDCARD] : pattern.split('|');
+        for (const type of types) {
+            let set = this.#listeners.get(type);
+            if (!set) {
+                set = new Set();
+                this.#listeners.set(type, set);
+            }
+            set.add(handler);
+        }
+        return () => {
+            for (const type of types) {
+                this.#listeners.get(type)?.delete(handler);
+            }
+        };
+    }
+    /**
+     * 创建并发射信号的便捷方法。自动填充 timestamp。
+     */
+    send(type, source, value, opts = {}) {
+        this.emit({
+            type,
+            source,
+            target: opts.target ?? null,
+            value: Math.max(0, Math.min(1, value)),
+            metadata: opts.metadata ?? {},
+            timestamp: Date.now(),
+        });
+    }
+    /** 已发射的信号总数（诊断用） */
+    get emitCount() {
+        return this.#emitCount;
+    }
+    /** 活跃订阅者数量（诊断用） */
+    get listenerCount() {
+        let count = 0;
+        for (const set of this.#listeners.values()) {
+            count += set.size;
+        }
+        return count;
+    }
+    /** 移除所有订阅者（测试用） */
+    clear() {
+        this.#listeners.clear();
+        this.#emitCount = 0;
+    }
+}

package/dist/lib/infrastructure/signal/SignalTraceWriter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SignalTraceWriter — 全类型信号 JSONL 留痕
+ *
+ * 订阅 SignalBus 全量信号，按类型分文件写入 JSONL。
+ * 替代 SignalModule 中 intent-only 的 JSONL 写入逻辑，统一处理全部类型。
+ *
+ * @module infrastructure/signal/SignalTraceWriter
+ */
+import type { Signal, SignalBus } from './SignalBus.js';
+export interface SignalTraceQueryOptions {
+    type?: string[];
+    source?: string;
+    target?: string;
+    from?: number;
+    to?: number;
+    limit?: number;
+    offset?: number;
+}
+export declare class SignalTraceWriter {
+    #private;
+    constructor(signalBus: SignalBus, baseDir: string);
+    /** 查询历史信号 */
+    query(opts?: SignalTraceQueryOptions): Promise<{
+        signals: Signal[];
+        total: number;
+    }>;
+    /** 统计信息 */
+    stats(opts?: {
+        from?: number;
+        to?: number;
+    }): Promise<{
+        total: number;
+        byType: Record<string, number>;
+        bySource: Record<string, number>;
+    }>;
+}

package/dist/lib/infrastructure/signal/SignalTraceWriter.js

@@ -0,0 +1,130 @@
+/**
+ * SignalTraceWriter — 全类型信号 JSONL 留痕
+ *
+ * 订阅 SignalBus 全量信号，按类型分文件写入 JSONL。
+ * 替代 SignalModule 中 intent-only 的 JSONL 写入逻辑，统一处理全部类型。
+ *
+ * @module infrastructure/signal/SignalTraceWriter
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export class SignalTraceWriter {
+    #baseDir;
+    constructor(signalBus, baseDir) {
+        this.#baseDir = baseDir;
+        fs.mkdirSync(baseDir, { recursive: true });
+        signalBus.subscribe('*', (signal) => {
+            this.#write(signal);
+        });
+    }
+    #write(signal) {
+        try {
+            const fileName = this.#resolveFile(signal.type);
+            fs.appendFileSync(fileName, `${JSON.stringify({
+                type: signal.type,
+                source: signal.source,
+                value: signal.value,
+                target: signal.target,
+                metadata: signal.metadata,
+                timestamp: signal.timestamp,
+            })}\n`, 'utf8');
+        }
+        catch {
+            // 写入失败不阻断信号分发
+        }
+    }
+    /** 查询历史信号 */
+    async query(opts = {}) {
+        const types = opts.type?.length ? opts.type : this.#listTypes();
+        const all = [];
+        for (const t of types) {
+            const filePath = this.#resolveFile(t);
+            if (!fs.existsSync(filePath)) {
+                continue;
+            }
+            const entries = this.#readJsonl(filePath);
+            all.push(...entries);
+        }
+        // 过滤
+        let filtered = all;
+        if (opts.source) {
+            filtered = filtered.filter((s) => s.source === opts.source);
+        }
+        if (opts.target) {
+            filtered = filtered.filter((s) => s.target === opts.target);
+        }
+        if (opts.from) {
+            filtered = filtered.filter((s) => s.timestamp >= opts.from);
+        }
+        if (opts.to) {
+            filtered = filtered.filter((s) => s.timestamp <= opts.to);
+        }
+        // 按时间倒序
+        filtered.sort((a, b) => b.timestamp - a.timestamp);
+        const total = filtered.length;
+        const offset = opts.offset ?? 0;
+        const limit = opts.limit ?? 50;
+        const signals = filtered.slice(offset, offset + limit);
+        return { signals, total };
+    }
+    /** 统计信息 */
+    async stats(opts = {}) {
+        const types = this.#listTypes();
+        const byType = {};
+        const bySource = {};
+        let total = 0;
+        for (const t of types) {
+            const filePath = this.#resolveFile(t);
+            if (!fs.existsSync(filePath)) {
+                continue;
+            }
+            const entries = this.#readJsonl(filePath);
+            for (const e of entries) {
+                if (opts.from && e.timestamp < opts.from) {
+                    continue;
+                }
+                if (opts.to && e.timestamp > opts.to) {
+                    continue;
+                }
+                total++;
+                byType[e.type] = (byType[e.type] ?? 0) + 1;
+                bySource[e.source] = (bySource[e.source] ?? 0) + 1;
+            }
+        }
+        return { total, byType, bySource };
+    }
+    // ── Private ───────────────────────────────────────
+    #resolveFile(type) {
+        return path.join(this.#baseDir, `${type}.jsonl`);
+    }
+    #listTypes() {
+        try {
+            return fs
+                .readdirSync(this.#baseDir)
+                .filter((f) => f.endsWith('.jsonl'))
+                .map((f) => f.replace('.jsonl', ''));
+        }
+        catch {
+            return [];
+        }
+    }
+    #readJsonl(filePath) {
+        try {
+            const content = fs.readFileSync(filePath, 'utf8');
+            const lines = content.split('\n').filter((l) => l.trim());
+            const entries = [];
+            for (const line of lines) {
+                try {
+                    entries.push(JSON.parse(line));
+                }
+                catch {
+                    // 跳过损坏行
+                }
+            }
+            return entries;
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/lib/infrastructure/vector/HnswVectorAdapter.js

@@ -121,8 +121,13 @@ export class HnswVectorAdapter extends VectorStore {
             // 迁移完成, 数据已加载到内存
             await this.#persist();
         }
-        // 初始化 WAL (即使是空索引也创建, 以便后续操作写 WAL)
+        // 初始化 WAL + replay 未刷盘操作 (即使是空索引也创建, 以便后续操作写 WAL)
         this.#initWal();
+        const { replayed } = this.#wal?.recover() || { replayed: 0 };
+        if (replayed > 0) {
+            this.#dirty = true;
+            await this.#persist();
+        }
     }
     /**
      * 同步初始化 (兼容 JsonVectorAdapter)
@@ -171,8 +176,19 @@ export class HnswVectorAdapter extends VectorStore {
         }
         // 同步迁移: 读取 JSON 索引并加载到内存
         this.#syncMigrateFromJson();
-        // 初始化 WAL
+        // 初始化 WAL + replay 未刷盘操作
         this.#initWal();
+        const { replayed } = this.#wal?.recover() || { replayed: 0 };
+        if (replayed > 0) {
+            this.#dirty = true;
+            BinaryPersistence.save(this.#indexPath, {
+                index: this.#index,
+                quantizer: this.#quantizer,
+                metadata: this.#metadata,
+                contents: this.#contents,
+            });
+            this.#dirty = false;
+        }
     }
     /** 同步从 JSON 索引迁移 (用于 initSync 路径) */
     #syncMigrateFromJson() {

package/dist/lib/injection/ServiceContainer.js

@@ -15,6 +15,8 @@ import * as GuardModule from './modules/GuardModule.js';
 // ─── DI Modules ──────────────────────────────────────
 import * as InfraModule from './modules/InfraModule.js';
 import * as KnowledgeModule from './modules/KnowledgeModule.js';
+import { PanoramaModule } from './modules/PanoramaModule.js';
+import * as SignalModule from './modules/SignalModule.js';
 import * as VectorModule from './modules/VectorModule.js';
 /**
  * DependencyInjection 容器
@@ -107,12 +109,16 @@ export class ServiceContainer {
             // ═══ 容器级语言偏好 ═══
             this.singletons._lang = null;
             // 注册模块 (顺序重要: AppModule 先注册 qualityScorer 等基础服务)
+            // SignalModule 优先注册并预热，确保后续模块可访问 signalBus
+            SignalModule.register(this);
+            this.get('signalBus'); // eager: 确保 singletons.signalBus 在后续工厂可用
             AppModule.register(this);
             KnowledgeModule.register(this);
             VectorModule.register(this);
             GuardModule.register(this);
             AgentModule.register(this);
             AiModule.register(this);
+            PanoramaModule.register(this);
             // v3.1: 初始化 Enhancement Pack 注册表（异步加载所有框架增强包）
             try {
                 await initEnhancementRegistry();
@@ -124,6 +130,8 @@ export class ServiceContainer {
             }
             // v3.3: 初始化 VectorService（绑定 EventBus 事件监听）
             await VectorModule.initializeVectorService(this);
+            // v3.4: 初始化 Knowledge 服务（绑定 EventBus → SearchEngine.refreshIndex + sourceRefs）
+            KnowledgeModule.initializeKnowledgeServices(this);
             this.logger.info('Service container initialized successfully');
         }
         catch (error) {