autosnippet 3.3.0 → 3.3.3

package/dist/lib/service/search/SearchTypes.d.ts

@@ -20,6 +20,25 @@ export interface BM25SearchResult {
     score: number;
     meta: Record<string, unknown>;
 }
+/**
+ * Scorer 通用接口 — BM25Scorer 与 FieldWeightedScorer 共同实现
+ *
+ * SearchEngine 通过此接口与具体评分器解耦，可在运行时切换。
+ */
+export interface Scorer {
+    totalDocs: number;
+    avgLength: number;
+    docFreq: Record<string, number>;
+    documents: ({
+        id: string;
+    } | null)[];
+    addDocument(id: string, text: string, meta: Record<string, unknown>): void;
+    removeDocument(id: string): boolean;
+    updateDocument(id: string, text: string, meta: Record<string, unknown>): void;
+    hasDocument(id: string): boolean;
+    search(query: string, limit?: number): BM25SearchResult[];
+    clear(): void;
+}
 /** Meta structure produced by _buildDocMeta */
 export interface BM25DocMeta {
     type: string;
@@ -56,7 +75,6 @@ export interface SearchResultItem {
     headers?: string;
     moduleName?: string;
     knowledgeType?: string;
-    bm25Score?: number;
     qualityScore?: number;
     usageCount?: number;
     authorityScore?: number;
@@ -178,6 +196,7 @@ export interface RrfHit {
     [key: string]: unknown;
 }
 /** Cross-encoder reranker abstraction */
+import type { SignalBus } from '../../infrastructure/signal/SignalBus.js';
 export interface SearchCrossEncoder {
     rerank(query: string, candidates: SearchResultItem[]): Promise<SearchResultItem[]>;
 }
@@ -188,8 +207,9 @@ export interface SearchEngineOptions {
     vectorService?: SearchVectorService | null;
     hybridRetriever?: SearchHybridRetriever | null;
     crossEncoderReranker?: SearchCrossEncoder | null;
+    signalBus?: SignalBus | null;
     cacheMaxAge?: number;
-    fusionBm25Weight?: number;
+    fusionRecallWeight?: number;
     fusionSemanticWeight?: number;
     [key: string]: unknown;
 }
@@ -208,12 +228,14 @@ export interface SlimSearchResult {
     actionHint?: string;
     /** 知识类型 (code-standard/code-pattern/...) — Bridge 场景需要 */
     knowledgeType?: string;
+    /** 已验证的项目来源文件路径（可信度证据链） */
+    sourceRefs?: string[];
 }
 /**
  * 统一投影函数 — 将 SearchResultItem 投影为 SlimSearchResult。
  *
  * 合并了 mcp/search.ts#_slimSearchItem() 和 TaskKnowledgeBridge#_projectItem() 的逻辑：
- * - 去除内部信号 (bm25Score, coarseScore, rankerScore, contextScore, content, code...)
+ * - 去除内部信号 (recallScore, coarseScore, rankerScore, contextScore, content, code...)
  * - description 截断 120 字符
  * - 生成 actionHint (whenClause → doClause)
  *

package/dist/lib/service/search/SearchTypes.js

@@ -10,7 +10,7 @@
  * 统一投影函数 — 将 SearchResultItem 投影为 SlimSearchResult。
  *
  * 合并了 mcp/search.ts#_slimSearchItem() 和 TaskKnowledgeBridge#_projectItem() 的逻辑：
- * - 去除内部信号 (bm25Score, coarseScore, rankerScore, contextScore, content, code...)
+ * - 去除内部信号 (recallScore, coarseScore, rankerScore, contextScore, content, code...)
  * - description 截断 120 字符
  * - 生成 actionHint (whenClause → doClause)
  *
@@ -23,6 +23,10 @@ export function slimSearchResult(item) {
     const actionHint = doText || whenText
         ? `${whenText ? `${whenText} → ` : ''}${doText}`.replace(/ → $/, '')
         : undefined;
+    const rawRefs = item.sourceRefs;
+    const sourceRefs = Array.isArray(rawRefs) && rawRefs.length > 0
+        ? rawRefs.filter((s) => typeof s === 'string' && s.length > 0)
+        : undefined;
     return {
         id: item.id,
         title: item.title || '',
@@ -33,6 +37,7 @@ export function slimSearchResult(item) {
         description: (item.description || '').slice(0, 120),
         actionHint,
         knowledgeType: item.knowledgeType || undefined,
+        sourceRefs,
     };
 }
 /** items → byKind 分组（统一实现） */

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

@@ -0,0 +1,68 @@
+/**
+ * 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 {};

package/dist/lib/service/signal/HitRecorder.js

@@ -0,0 +1,173 @@
+/**
+ * HitRecorder — 批量使用信号采集器
+ *
+ * Phase 0 核心服务。将高频使用事件（Guard 命中、搜索命中、采用等）
+ * 先写入内存 buffer，定时批量持久化到 Stats JSON，同时发射 SignalBus 信号。
+ *
+ * 设计要点：
+ *   - 即时 emit Signal（信号不延迟）
+ *   - buffer → 30s flush → 批量 UPDATE（减少 SQLite 写）
+ *   - shutdown hook 保证进程退出前数据落盘
+ *
+ * @module service/signal/HitRecorder
+ */
+/** 事件类型 → Stats JSON 字段 映射 */
+const EVENT_TO_STATS_FIELD = {
+    guardHit: 'guardHits',
+    searchHit: 'searchHits',
+    view: 'views',
+    adoption: 'adoptions',
+    application: 'applications',
+};
+/** 事件类型 → SignalBus 信号类型 映射 */
+const EVENT_TO_SIGNAL_TYPE = {
+    guardHit: 'guard',
+    searchHit: 'search',
+    view: 'usage',
+    adoption: 'usage',
+    application: 'usage',
+};
+// ── HitRecorder ─────────────────────────────────────
+export class HitRecorder {
+    #bus;
+    #db;
+    #buffer = new Map();
+    #flushIntervalMs;
+    #maxBufferSize;
+    #timer = null;
+    #totalRecorded = 0;
+    #totalFlushed = 0;
+    constructor(bus, db, config = {}) {
+        this.#bus = bus;
+        this.#db =
+            'getDb' in db && typeof db.getDb === 'function'
+                ? db.getDb()
+                : db;
+        this.#flushIntervalMs = config.flushIntervalMs ?? 30_000;
+        this.#maxBufferSize = config.maxBufferSize ?? 100;
+    }
+    /**
+     * 启动定时 flush。通常在服务初始化时调用。
+     */
+    start() {
+        if (this.#timer) {
+            return;
+        }
+        this.#timer = setInterval(() => {
+            void this.flush();
+        }, this.#flushIntervalMs);
+        this.#timer.unref(); // 不阻止进程退出
+    }
+    /**
+     * 停止定时 flush 并执行最后一次 flush。
+     * 供 shutdown hook 调用。
+     */
+    async stop() {
+        if (this.#timer) {
+            clearInterval(this.#timer);
+            this.#timer = null;
+        }
+        await this.flush();
+    }
+    /**
+     * 记录一次命中事件。
+     *
+     * 1. 立即通过 SignalBus 发射信号（信号不延迟）
+     * 2. 事件写入内存 buffer，等待 flush 批量持久化
+     *
+     * @param recipeId  关联的知识条目 ID
+     * @param eventType 事件类型
+     * @param value     信号强度 0-1（默认 1）
+     * @param metadata  附加元数据
+     */
+    record(recipeId, eventType, value = 1, metadata = {}) {
+        this.#totalRecorded++;
+        // 1. 即时发射信号
+        this.#bus.send(EVENT_TO_SIGNAL_TYPE[eventType], `HitRecorder.${eventType}`, value, {
+            target: recipeId,
+            metadata: { ...metadata, eventType },
+        });
+        // 2. 聚合进 buffer
+        const key = `${recipeId}:${eventType}`;
+        const now = Date.now();
+        const existing = this.#buffer.get(key);
+        if (existing) {
+            existing.count++;
+            existing.lastAt = now;
+        }
+        else {
+            this.#buffer.set(key, {
+                recipeId,
+                eventType,
+                count: 1,
+                firstAt: now,
+                lastAt: now,
+            });
+        }
+        // 3. buffer 满时立即 flush
+        if (this.#buffer.size >= this.#maxBufferSize) {
+            void this.flush();
+        }
+    }
+    /**
+     * 批量持久化 buffer 到数据库。
+     * 使用 json_set 原子更新 Stats JSON 中对应字段。
+     */
+    async flush() {
+        if (this.#buffer.size === 0) {
+            return 0;
+        }
+        // 取出当前 buffer 并清空（后续 record 写入新 buffer）
+        const entries = [...this.#buffer.values()];
+        this.#buffer.clear();
+        let flushed = 0;
+        const now = Math.floor(Date.now() / 1000);
+        try {
+            const stmt = this.#db.prepare(`UPDATE knowledge_entries
+         SET stats = json_set(
+               COALESCE(stats, '{}'),
+               '$.' || ?,
+               COALESCE(json_extract(stats, '$.' || ?), 0) + ?
+             ),
+             updatedAt = ?
+         WHERE id = ?`);
+            for (const entry of entries) {
+                const field = EVENT_TO_STATS_FIELD[entry.eventType];
+                try {
+                    stmt.run(field, field, entry.count, now, entry.recipeId);
+                    flushed += entry.count;
+                }
+                catch {
+                    // Recipe 可能已被删除，静默忽略
+                }
+            }
+        }
+        catch {
+            // DB statement prepare 失败（表可能不存在），回填 buffer
+            for (const entry of entries) {
+                const key = `${entry.recipeId}:${entry.eventType}`;
+                const existing = this.#buffer.get(key);
+                if (existing) {
+                    existing.count += entry.count;
+                }
+                else {
+                    this.#buffer.set(key, entry);
+                }
+            }
+        }
+        this.#totalFlushed += flushed;
+        return flushed;
+    }
+    /** 当前 buffer 中的条目数（诊断用） */
+    get bufferSize() {
+        return this.#buffer.size;
+    }
+    /** 累计记录次数 */
+    get totalRecorded() {
+        return this.#totalRecorded;
+    }
+    /** 累计已持久化次数 */
+    get totalFlushed() {
+        return this.#totalFlushed;
+    }
+}

package/dist/lib/service/skills/SignalCollector.d.ts

@@ -41,6 +41,7 @@ interface SignalCollectorOpts {
     database?: DatabaseLike | null;
     agentFactory?: AgentFactoryLike | null;
     container?: ContainerLike | null;
+    signalBus?: import('../../infrastructure/signal/SignalBus.js').SignalBus | null;
     mode?: string;
     intervalMs?: number;
     onSuggestions?: ((suggestions: Record<string, unknown>[]) => void) | null;
@@ -80,11 +81,12 @@ export declare class SignalCollector {
      * @param [opts.database] better-sqlite3 实例
      * @param [opts.agentFactory] AgentFactory 实例
      * @param [opts.container] ServiceContainer 实例
+     * @param [opts.signalBus] SignalBus 实例（实时信号订阅）
      * @param [opts.mode] 'off' | 'suggest' | 'auto'
      * @param [opts.intervalMs] 初始收集间隔（毫秒），后续由 AI 动态调整
      * @param [opts.onSuggestions] 新建议回调 (suggestions[]) => void
      */
-    constructor({ projectRoot, database, agentFactory, container, mode, intervalMs, onSuggestions, }: SignalCollectorOpts);
+    constructor({ projectRoot, database, agentFactory, container, signalBus, mode, intervalMs, onSuggestions, }: SignalCollectorOpts);
     start(): void;
     stop(): void;
     /**

package/dist/lib/service/skills/SignalCollector.js

@@ -62,16 +62,19 @@ export class SignalCollector {
     #onSuggestions;
     /** 信号聚类引擎 */
     #aggregator;
+    /** 各维度最新信号快照（由 SignalBus 实时更新） */
+    #dimensionSignals = {};
     /**
      * @param opts.projectRoot 用户项目根目录
      * @param [opts.database] better-sqlite3 实例
      * @param [opts.agentFactory] AgentFactory 实例
      * @param [opts.container] ServiceContainer 实例
+     * @param [opts.signalBus] SignalBus 实例（实时信号订阅）
      * @param [opts.mode] 'off' | 'suggest' | 'auto'
      * @param [opts.intervalMs] 初始收集间隔（毫秒），后续由 AI 动态调整
      * @param [opts.onSuggestions] 新建议回调 (suggestions[]) => void
      */
-    constructor({ projectRoot, database = null, agentFactory = null, container = null, mode = 'auto', intervalMs = DEFAULT_INTERVAL_MS, onSuggestions = null, }) {
+    constructor({ projectRoot, database = null, agentFactory = null, container = null, signalBus = null, mode = 'auto', intervalMs = DEFAULT_INTERVAL_MS, onSuggestions = null, }) {
         this.#projectRoot = projectRoot;
         this.#db = database;
         this.#agentFactory = agentFactory;
@@ -94,6 +97,12 @@ export class SignalCollector {
                 this.#timer = setTimeout(() => this.#tick(), 3000); // 3 秒后执行，留出更多聚合时间
             }
         });
+        // Phase 2: 订阅 SignalBus 全量信号，维护维度快照
+        if (signalBus) {
+            signalBus.subscribe('*', (signal) => {
+                this.#updateDimension(signal);
+            });
+        }
     }
     // ═══════════════════════════════════════════════════════
     //  公共 API
@@ -144,6 +153,27 @@ export class SignalCollector {
     getSnapshot() {
         return { ...this.#snapshot };
     }
+    /** 由 SignalBus 实时更新的维度信号快照 */
+    #updateDimension(signal) {
+        switch (signal.type) {
+            case 'guard':
+            case 'guard_blind_spot':
+                this.#dimensionSignals.compliance = signal;
+                break;
+            case 'usage':
+                this.#dimensionSignals.adoption = signal;
+                break;
+            case 'quality':
+                this.#dimensionSignals.quality = signal;
+                break;
+            case 'decay':
+                this.#dimensionSignals.decay = signal;
+                break;
+            case 'lifecycle':
+                this.#dimensionSignals.evolution = signal;
+                break;
+        }
+    }
     getMode() {
         return this.#mode;
     }

package/dist/lib/service/task/IntentExtractor.d.ts

@@ -0,0 +1,66 @@
+/**
+ * IntentExtractor — Intake Layer
+ *
+ * Pure functions: extract intent signals from user query + active file.
+ * Builds multi-query set, infers language/module/scenario for search routing.
+ *
+ * @module service/task/IntentExtractor
+ */
+export type SearchScenario = 'lint' | 'generate' | 'search' | 'learning';
+export interface ExtractedIntent {
+    /** Multi-query set: Q1 raw + Q2 tech terms + Q3 file context */
+    queries: string[];
+    /** Cross-language synonym queries (run in keyword mode to bypass semantic normalization) */
+    keywordQueries: string[];
+    /** Inferred language from activeFile or args */
+    language: string | null;
+    /** Inferred module path from activeFile */
+    module: string | null;
+    /** Search scenario for MultiSignalRanker routing */
+    scenario: SearchScenario;
+    /** Original inputs */
+    raw: {
+        userQuery: string;
+        activeFile?: string;
+        language?: string;
+    };
+}
+export interface TechTermOptions {
+    /** Project-specific class prefixes, e.g. ['BD', 'BBA', 'KS'] */
+    projectPrefixes?: string[];
+    /** Language/platform common prefixes, e.g. ObjC: ['UI', 'NS', 'CA', 'AV'] */
+    platformPrefixes?: string[];
+}
+/**
+ * Extract intent signals from user query and active file.
+ * Pure function — no side effects, no DI.
+ */
+export declare function extract(userQuery: string, activeFile?: string, language?: string, termOpts?: TechTermOptions): ExtractedIntent;
+/**
+ * Build multi-query set from user query + active file.
+ * Q1: raw query, Q2: extracted tech terms, Q3: file context.
+ * Q1 is enriched with cross-language synonyms to bridge EN↔CJK matching.
+ */
+export declare function buildQueries(userQuery: string, activeFile?: string, termOpts?: TechTermOptions): string[];
+/**
+ * Build keyword-mode queries for cross-language synonym matching.
+ * Uses keyword mode to preserve raw FWS scores without CoarseRanker semantic normalization.
+ */
+export declare function buildKeywordQueries(userQuery: string): string[];
+/**
+ * Extract tech terms from query using universal patterns + dynamic project prefixes.
+ */
+export declare function extractTechTerms(query: string, opts?: TechTermOptions): string[];
+/**
+ * Infer file context string from file path for search augmentation.
+ * Returns module path + class name, e.g. "Services/Network BDNetworkManager"
+ */
+export declare function inferFileContext(filePath: string): string | null;
+/**
+ * Infer language from file extension.
+ */
+export declare function inferLanguage(filePath: string): string | null;
+/**
+ * Classify search scenario from user query (lightweight rule-based).
+ */
+export declare function classifyScenario(userQuery: string): SearchScenario;