autosnippet/dist/lib/service/signal/HitRecorder.d.ts

Extract code patterns into a knowledge base for AI coding assistants

/**
 * HitRecorder — 批量使用信号采集器
 *
 * Phase 0 核心服务。将高频使用事件（Guard 命中、搜索命中、采用等）
 * 先写入内存 buffer，定时批量持久化到 Stats JSON，同时发射 SignalBus 信号。
 *
 * 设计要点：
 *   - 即时 emit Signal（信号不延迟）
 *   - buffer → 30s flush → 批量 UPDATE（减少 SQLite 写）
 *   - shutdown hook 保证进程退出前数据落盘
 *
 * @module service/signal/HitRecorder
 */
import type { SignalBus } from '#infra/signal/SignalBus.js';
/** better-sqlite3 兼容类型（与 GuardCheckEngine 相同模式） */
interface DatabaseLike {
    prepare(sql: string): {
        run(...params: unknown[]): unknown;
    };
}
/** 支持的命中事件类型 */
export type HitEventType = 'guardHit' | 'searchHit' | 'view' | 'adoption' | 'application';
/** HitRecorder 配置 */
export interface HitRecorderConfig {
    /** flush 间隔（ms），默认 30000 */
    flushIntervalMs?: number;
    /** 立即 flush 的最大缓冲条目数，默认 100 */
    maxBufferSize?: number;
}
export declare class HitRecorder {
    #private;
    constructor(bus: SignalBus, db: DatabaseLike | {
        getDb(): DatabaseLike;
    }, config?: HitRecorderConfig);
    /**
     * 启动定时 flush。通常在服务初始化时调用。
     */
    start(): void;
    /**
     * 停止定时 flush 并执行最后一次 flush。
     * 供 shutdown hook 调用。
     */
    stop(): Promise<void>;
    /**
     * 记录一次命中事件。
     *
     * 1. 立即通过 SignalBus 发射信号（信号不延迟）
     * 2. 事件写入内存 buffer，等待 flush 批量持久化
     *
     * @param recipeId  关联的知识条目 ID
     * @param eventType 事件类型
     * @param value     信号强度 0-1（默认 1）
     * @param metadata  附加元数据
     */
    record(recipeId: string, eventType: HitEventType, value?: number, metadata?: Record<string, unknown>): void;
    /**
     * 批量持久化 buffer 到数据库。
     * 使用 json_set 原子更新 Stats JSON 中对应字段。
     */
    flush(): Promise<number>;
    /** 当前 buffer 中的条目数（诊断用） */
    get bufferSize(): number;
    /** 累计记录次数 */
    get totalRecorded(): number;
    /** 累计已持久化次数 */
    get totalFlushed(): number;
}
export {};