autosnippet 3.2.13 → 3.2.15

package/dist/lib/service/task/TaskKnowledgeBridge.js

@@ -1,17 +1,47 @@
+import { slimSearchResult } from '#service/search/SearchTypes.js';
 import { ioLimit } from '#shared/concurrency.js';
 import Logger from '../../infrastructure/logging/Logger.js';
+// ─── Constants ──────────────────────────────────────────
+/**
+ * 搜索结果相关性阈值 — 低于此分数的结果不注入
+ *
+ * 真实分数分布 (BiliDemo, auto 模式 RRF+Ranking):
+ *   min=0.434  P10=0.453  P25=0.460  median=0.479  P75=0.495  P90=0.505  max=0.534
+ *   所有结果集中在 [0.43, 0.54]，0.15 无法过滤任何噪声。
+ *
+ * 阈值设定依据:
+ *   0.44 — 过滤掉最边缘的低质量尾部结果（约过滤 P5 以下）
+ */
+const RELEVANCE_THRESHOLD = 0.44;
+/** 缓存 TTL (ms) — 5 分钟 */
+const CACHE_TTL_MS = 300_000;
+/** 技术术语提取正则 */
+const TECH_TERM_PATTERNS = [
+    // CamelCase 类名 — 含常见 iOS/Android/Web 后缀
+    /\b[A-Z][a-zA-Z]+(?:Controller|ViewController|Service|Manager|Handler|View|Model|Request|Response|Provider|Repository|Factory|Builder|Delegate|Protocol|Router|Coordinator|Cell|Layout|Adapter|Module|Plugin|Monitor|Loader|Store|Cache|Config|Helper|Util|Extension|Category)\b/g,
+    // BD / UI / NS 前缀类名 (常见 iOS 项目)
+    /\b(?:BD|UI|NS|CG|CA|MK|AV|WK|SK|CL)[A-Z][a-zA-Z]{2,}\b/g,
+    // 反引号包裹的代码引用
+    /`([^`]+)`/g,
+    // 文件名引用 (xxx.swift / xxx.ts / xxx.json 等)
+    /\b[\w.-]+\.(?:swift|ts|tsx|js|jsx|py|java|kt|go|rs|rb|cpp|h|m|mm|json|yaml|yml|xml|gradle|plist|xib|storyboard)\b/g,
+];
 /**
  * TaskKnowledgeBridge — 任务 ↔ 知识桥接服务
  *
  * AutoSnippet 独有能力：返回「带知识上下文的任务」，而非裸任务。
  *
- * 桥接策略：
- *   1. 任务标题/描述 → 搜索知识库 → 关联 pattern/rule/fact
- *   2. 关联的 Guard 规则 → 嵌入任务上下文
+ * 桥接策略（v2 — 用户输入感知 + Multi-Query + 上下文透传 + 缓存）：
+ *   1. 任务标题/描述 + 用户输入(userQuery) → Multi-Query 搜索知识库
+ *   2. 传递 language / intent 上下文信号 → SearchEngine ContextBoost 生效
+ *   3. 关联的 Guard 规则 → 优先嵌入任务上下文
+ *   4. 任务级缓存 → 避免重复搜索
  */
 export class TaskKnowledgeBridge {
     _search;
     logger;
+    /** 任务级知识缓存 (taskId → CacheEntry) */
+    _cache = new Map();
     /**
      * @param {import('../../service/search/SearchEngine.js').SearchEngine} searchEngine
      */
@@ -23,17 +53,17 @@ export class TaskKnowledgeBridge {
      * 为就绪任务附加知识上下文
      * 并行搜索，不阻塞主流程
      *
-     * @param {import('../../domain/task/Task.js').Task[]} tasks
-     * @returns {Promise<import('../../domain/task/Task.js').Task[]>}
+     * @param tasks  需要注入知识的任务列表
+     * @param options 上下文选项（userQuery / activeFile / language）
      */
-    async enrichWithKnowledge(tasks) {
+    async enrichWithKnowledge(tasks, options) {
         if (!tasks || tasks.length === 0) {
             return tasks;
         }
         if (!this._search) {
             return tasks;
         }
-        const results = await Promise.allSettled(tasks.map((task) => ioLimit(() => this._buildContext(task))));
+        const results = await Promise.allSettled(tasks.map((task) => ioLimit(() => this._buildContext(task, options))));
         return tasks.map((task, i) => {
             if (results[i].status === 'fulfilled' && results[i].value) {
                 task.knowledgeContext = results[i].value;
@@ -42,42 +72,94 @@ export class TaskKnowledgeBridge {
         });
     }
     /**
-     * 为单个任务构建知识上下文
-     * @private
+     * 独立搜索 — 仅基于 userQuery 搜索知识（不依赖任何 Task）
+     *
+     * 场景: prime() 时没有 ready tasks 但有用户输入，直接搜索知识库。
+     *
+     * @param userQuery 用户输入的原始文本
+     * @param options   可选的 language
      */
-    async _buildContext(task) {
-        const query = `${task.title} ${task.description}`.trim();
-        if (!query) {
+    async searchForQuery(userQuery, options) {
+        if (!this._search || !userQuery?.trim()) {
             return null;
         }
         try {
-            const searchResult = await this._search.search(query, {
+            const searchResult = await this._search.search(userQuery.trim(), {
                 mode: 'auto',
-                limit: 5,
+                limit: 8,
+                rank: true,
+                context: {
+                    language: options?.language,
+                    intent: 'user-query-knowledge',
+                },
             });
-            const allResults = (searchResult?.items || searchResult?.results || []);
-            const knowledge = allResults
-                .filter((r) => r.kind !== 'rule')
-                .slice(0, 3);
-            const guardRules = allResults
-                .filter((r) => r.kind === 'rule')
-                .slice(0, 5);
+            const allResults = (searchResult?.items || searchResult?.results || []).filter((r) => this._aboveThreshold(r));
+            if (allResults.length === 0) {
+                return null;
+            }
+            const knowledge = allResults.filter((r) => r.kind !== 'rule').slice(0, 5);
+            const guardRules = allResults.filter((r) => r.kind === 'rule').slice(0, 3);
             return {
-                relatedKnowledge: knowledge.map((k) => ({
-                    id: k.id,
-                    title: k.title,
-                    kind: k.kind,
-                    trigger: k.trigger,
-                    actionHint: k.actionHint || k.doClause || '',
-                })),
-                guardRules: guardRules.map((r) => ({
-                    id: r.id,
-                    title: r.title,
-                    trigger: r.trigger,
-                    actionHint: r.actionHint || r.doClause || '',
-                })),
-                searchQuery: query,
+                relatedKnowledge: knowledge.map((k) => this._projectItem(k)),
+                guardRules: guardRules.map((r) => this._projectItem(r)),
+                searchQuery: userQuery.trim(),
+            };
+        }
+        catch (err) {
+            this.logger.debug('TaskKnowledgeBridge.searchForQuery error', {
+                error: err.message,
+            });
+            return null;
+        }
+    }
+    // ═══ 私有方法 ═══════════════════════════════════════
+    /**
+     * 为单个任务构建知识上下文（v2 — multi-query + 上下文 + 缓存）
+     * @private
+     */
+    async _buildContext(task, options) {
+        const taskQuery = `${task.title} ${task.description}`.trim();
+        if (!taskQuery && !options?.userQuery) {
+            return null;
+        }
+        // ── P6: 缓存检查 ──
+        const contentKey = this._contentKey(taskQuery, options?.userQuery);
+        if (task.id) {
+            const cached = this._cache.get(task.id);
+            if (cached &&
+                cached.contentKey === contentKey &&
+                Date.now() - cached.timestamp < CACHE_TTL_MS) {
+                return cached.context;
+            }
+        }
+        try {
+            // ── P2: Multi-Query 策略 ──
+            const queries = this._buildSearchQueries(task, options?.userQuery);
+            const allResults = await this._multiQuerySearch(queries, {
+                language: options?.language,
+            });
+            // ── P4: 相关性阈值过滤 ──
+            const filtered = allResults.filter((r) => this._aboveThreshold(r));
+            // ── P4: 分类 & 增强投影 ──
+            const knowledge = filtered.filter((r) => r.kind !== 'rule').slice(0, 5);
+            const guardRules = filtered.filter((r) => r.kind === 'rule').slice(0, 3);
+            const context = {
+                relatedKnowledge: knowledge.map((k) => this._projectItem(k)),
+                guardRules: guardRules.map((r) => this._projectItem(r)),
+                searchQuery: queries.join(' | '),
             };
+            // ── P6: 写入缓存 ──
+            if (task.id) {
+                this._cache.set(task.id, { context, contentKey, timestamp: Date.now() });
+                // 限制缓存大小 — 超出 100 条时淘汰最旧的
+                if (this._cache.size > 100) {
+                    const firstKey = this._cache.keys().next().value;
+                    if (firstKey !== undefined) {
+                        this._cache.delete(firstKey);
+                    }
+                }
+            }
+            return context;
         }
         catch (err) {
             this.logger.debug('TaskKnowledgeBridge._buildContext error', {
@@ -87,6 +169,142 @@ export class TaskKnowledgeBridge {
             return null;
         }
     }
+    /**
+     * P2: 构建多条互补搜索查询
+     *
+     * 策略:
+     *   Q1 (精确): 任务标题 — 通常最精练
+     *   Q2 (语义): 用户输入 — 包含更丰富的自然语义
+     *   Q3 (关键词): 从描述/用户输入提取技术术语
+     *
+     * @private
+     */
+    _buildSearchQueries(task, userQuery) {
+        const queries = [];
+        // Q1: 任务标题（最精练）
+        const title = task.title?.trim();
+        if (title) {
+            queries.push(title);
+        }
+        // Q2: 用户原始输入（与标题不同才添加）
+        const uq = userQuery?.trim();
+        if (uq && uq !== title) {
+            queries.push(uq);
+        }
+        // Q3: 技术术语提取 — 从描述 + 用户输入中提取
+        const corpus = [task.description, userQuery].filter(Boolean).join(' ');
+        const techTerms = this._extractTechTerms(corpus);
+        if (techTerms.length > 0) {
+            const termQuery = techTerms.join(' ');
+            // 避免与已有查询重复
+            if (!queries.includes(termQuery)) {
+                queries.push(termQuery);
+            }
+        }
+        // 兜底: 若上述都为空，用 title + description
+        if (queries.length === 0) {
+            const fallback = `${task.title} ${task.description}`.trim();
+            if (fallback) {
+                queries.push(fallback);
+            }
+        }
+        return queries;
+    }
+    /**
+     * P2: 从文本中提取技术术语（类名、文件名、API 名等）
+     * @private
+     */
+    _extractTechTerms(text) {
+        if (!text) {
+            return [];
+        }
+        const terms = new Set();
+        for (const pattern of TECH_TERM_PATTERNS) {
+            // 重置 lastIndex（全局正则复用安全）
+            pattern.lastIndex = 0;
+            let match;
+            while ((match = pattern.exec(text)) !== null) {
+                // 优先取捕获组（反引号中的内容），否则取整个匹配
+                const term = (match[1] || match[0]).trim();
+                if (term.length >= 2) {
+                    terms.add(term);
+                }
+            }
+        }
+        return [...terms].slice(0, 8); // 最多 8 个术语
+    }
+    /**
+     * P2 + P3: Multi-Query 搜索 + 合并去重
+     *
+     * 对每个 query 执行搜索（并行），合并结果并按 score 去重保留最高分。
+     * @private
+     */
+    async _multiQuerySearch(queries, options) {
+        if (queries.length === 0) {
+            return [];
+        }
+        // 单 query 直接搜索（优化常见情况）
+        if (queries.length === 1) {
+            return this._singleSearch(queries[0], options);
+        }
+        // 多 query 并行搜索
+        const searchPromises = queries.map((q) => this._singleSearch(q, options).catch(() => []));
+        const resultSets = await Promise.all(searchPromises);
+        // 合并去重 — 按 id 保留最高 score
+        const merged = new Map();
+        for (const results of resultSets) {
+            for (const item of results) {
+                const existing = merged.get(item.id);
+                if (!existing || item.score > existing.score) {
+                    merged.set(item.id, item);
+                }
+            }
+        }
+        // 按 score 降序排序
+        return [...merged.values()].sort((a, b) => (b.score || 0) - (a.score || 0));
+    }
+    /**
+     * 执行单次搜索（含 P3 上下文透传）
+     * @private
+     */
+    async _singleSearch(query, options) {
+        const searchResult = await this._search.search(query, {
+            mode: 'auto',
+            limit: 8,
+            rank: true,
+            context: {
+                language: options.language,
+                intent: 'task-knowledge',
+            },
+        });
+        return (searchResult?.items || searchResult?.results || []).slice(0, 8);
+    }
+    /**
+     * P4: 相关性阈值判断
+     * @private
+     */
+    _aboveThreshold(item) {
+        const score = item.score || 0;
+        return score >= RELEVANCE_THRESHOLD;
+    }
+    /**
+     * P4: 增强投影 — 使用统一 slimSearchResult() 投影函数
+     * @private
+     */
+    _projectItem(item) {
+        return slimSearchResult(item);
+    }
+    /**
+     * P6: 缓存键 — 基于 taskQuery + userQuery 的内容指纹
+     * @private
+     */
+    _contentKey(taskQuery, userQuery) {
+        return `${taskQuery}||${userQuery || ''}`;
+    }
+    /** 清除全部缓存（测试 / 索引重建后使用） */
+    clearCache() {
+        this._cache.clear();
+    }
 }
 export default TaskKnowledgeBridge;
 //# sourceMappingURL=TaskKnowledgeBridge.js.map

package/dist/lib/service/task/TaskKnowledgeBridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"TaskKnowledgeBridge.js","sourceRoot":"","sources":["../../../../lib/service/task/TaskKnowledgeBridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TaskKnowledgeBridge.js","sourceRoot":"","sources":["../../../../lib/service/task/TaskKnowledgeBridge.ts"],"names":[],"mappings":"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"}

package/dist/lib/service/vector/ContextualEnricher.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ContextualEnricher — 上下文增强管线
+ *
+ * 基于 Anthropic Contextual Retrieval 论文 (2024-09) 的实现。
+ * 对每个 chunk 生成 50-100 token 的上下文前缀，使其嵌入时保留文档层面的语义。
+ *
+ * 效果: retrieval failure rate 降低 35-67% (with reranking)
+ *
+ * 成本控制:
+ *   - 使用轻量模型 (Haiku/Gemini Flash)
+ *   - Prompt Caching: 同一文档不同 chunk 共享 system prompt 缓存
+ *   - 增量模式: 只对新增/变更 chunk 做 enrichment
+ *   - 配置开关: contextualEnrich = false 时完全跳过
+ *
+ * @module service/vector/ContextualEnricher
+ */
+export interface AiProviderLike {
+    chat(prompt: string, options?: {
+        system?: string;
+        maxTokens?: number;
+        temperature?: number;
+    }): Promise<string>;
+}
+export interface ChunkData {
+    content: string;
+    metadata: Record<string, unknown>;
+}
+export interface DocumentInfo {
+    title: string;
+    content: string;
+    kind: string;
+    sourcePath?: string;
+}
+export interface EnricherConfig {
+    aiProvider: AiProviderLike;
+    /** 缓存 enrichment 结果防止重复调用 */
+    cacheEnabled?: boolean;
+}
+export declare class ContextualEnricher {
+    #private;
+    constructor(config: EnricherConfig);
+    /**
+     * 为多个 chunks 生成上下文前缀
+     *
+     * 策略: 将整篇文档作为 system prompt，逐 chunk 请求上下文描述。
+     * 利用 Prompt Caching: 文档只需编码一次，后续 chunk 查询只需增量 tokens。
+     *
+     * @param document - 文档整体信息
+     * @param chunks   - 分块后的内容数组
+     * @returns 带上下文前缀的 chunks
+     */
+    enrichChunks(document: DocumentInfo, chunks: ChunkData[]): Promise<ChunkData[]>;
+    /**
+     * 清除缓存
+     */
+    clearCache(): void;
+    /**
+     * 当前缓存大小
+     */
+    get cacheSize(): number;
+}
+//# sourceMappingURL=ContextualEnricher.d.ts.map

package/dist/lib/service/vector/ContextualEnricher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextualEnricher.d.ts","sourceRoot":"","sources":["../../../../lib/service/vector/ContextualEnricher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,MAAM,WAAW,cAAc;IAC7B,IAAI,CACF,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GACtE,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,cAAc,CAAC;IAC3B,6BAA6B;IAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAID,qBAAa,kBAAkB;;gBAMjB,MAAM,EAAE,cAAc;IAMlC;;;;;;;;;OASG;IACG,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAiDrF;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;CAgEF"}

package/dist/lib/service/vector/ContextualEnricher.js

@@ -0,0 +1,150 @@
+/**
+ * ContextualEnricher — 上下文增强管线
+ *
+ * 基于 Anthropic Contextual Retrieval 论文 (2024-09) 的实现。
+ * 对每个 chunk 生成 50-100 token 的上下文前缀，使其嵌入时保留文档层面的语义。
+ *
+ * 效果: retrieval failure rate 降低 35-67% (with reranking)
+ *
+ * 成本控制:
+ *   - 使用轻量模型 (Haiku/Gemini Flash)
+ *   - Prompt Caching: 同一文档不同 chunk 共享 system prompt 缓存
+ *   - 增量模式: 只对新增/变更 chunk 做 enrichment
+ *   - 配置开关: contextualEnrich = false 时完全跳过
+ *
+ * @module service/vector/ContextualEnricher
+ */
+import Logger from '../../infrastructure/logging/Logger.js';
+// ── Enricher ──
+export class ContextualEnricher {
+    #aiProvider;
+    #cache;
+    #cacheEnabled;
+    #logger = Logger.getInstance();
+    constructor(config) {
+        this.#aiProvider = config.aiProvider;
+        this.#cacheEnabled = config.cacheEnabled !== false;
+        this.#cache = new Map();
+    }
+    /**
+     * 为多个 chunks 生成上下文前缀
+     *
+     * 策略: 将整篇文档作为 system prompt，逐 chunk 请求上下文描述。
+     * 利用 Prompt Caching: 文档只需编码一次，后续 chunk 查询只需增量 tokens。
+     *
+     * @param document - 文档整体信息
+     * @param chunks   - 分块后的内容数组
+     * @returns 带上下文前缀的 chunks
+     */
+    async enrichChunks(document, chunks) {
+        if (chunks.length === 0) {
+            return [];
+        }
+        const systemPrompt = this.#buildSystemPrompt(document);
+        const enriched = [];
+        for (const chunk of chunks) {
+            try {
+                // 检查缓存
+                const cacheKey = this.#cacheEnabled
+                    ? this.#computeCacheKey(document.sourcePath || document.title, chunk.content)
+                    : '';
+                let context;
+                if (this.#cacheEnabled && this.#cache.has(cacheKey)) {
+                    context = this.#cache.get(cacheKey);
+                }
+                else {
+                    context = await this.#generateContext(systemPrompt, chunk.content);
+                    if (this.#cacheEnabled && context) {
+                        this.#cache.set(cacheKey, context);
+                    }
+                }
+                if (context) {
+                    enriched.push({
+                        content: `[${context.trim()}]\n\n${chunk.content}`,
+                        metadata: {
+                            ...chunk.metadata,
+                            contextEnriched: true,
+                            contextLength: context.length,
+                        },
+                    });
+                }
+                else {
+                    enriched.push(chunk);
+                }
+            }
+            catch (err) {
+                // 单个 chunk enrichment 失败不阻塞整个流程
+                this.#logger.warn('[ContextualEnricher] Failed to enrich chunk', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                enriched.push(chunk);
+            }
+        }
+        return enriched;
+    }
+    /**
+     * 清除缓存
+     */
+    clearCache() {
+        this.#cache.clear();
+    }
+    /**
+     * 当前缓存大小
+     */
+    get cacheSize() {
+        return this.#cache.size;
+    }
+    // ═══ Private ═══
+    #buildSystemPrompt(document) {
+        // 截断过长文档（避免超出模型 context window）
+        const maxDocLen = 8000;
+        const docContent = document.content.length > maxDocLen
+            ? `${document.content.slice(0, maxDocLen)}\n\n[... document truncated ...]`
+            : document.content;
+        return [
+            `<document title="${this.#escapeXml(document.title)}" kind="${document.kind}">`,
+            docContent,
+            '</document>',
+            '',
+            'Given the above document, provide 1-2 sentences of context that situate the following chunk within the document.',
+            'Focus on: what topic/function/section this chunk belongs to, and any key entities or concepts referenced.',
+            'Answer ONLY with the context sentences, nothing else.',
+        ].join('\n');
+    }
+    async #generateContext(systemPrompt, chunkContent) {
+        const userPrompt = `<chunk>\n${chunkContent}\n</chunk>`;
+        const response = await this.#aiProvider.chat(userPrompt, {
+            system: systemPrompt,
+            maxTokens: 120,
+            temperature: 0,
+        });
+        // 清理响应 — 移除可能的 XML tag 或多余引号
+        let cleaned = response.trim();
+        if (cleaned.startsWith('"') && cleaned.endsWith('"')) {
+            cleaned = cleaned.slice(1, -1);
+        }
+        // 限制长度
+        if (cleaned.length > 500) {
+            cleaned = cleaned.slice(0, 500);
+        }
+        return cleaned;
+    }
+    #computeCacheKey(sourcePath, content) {
+        // 简单的字符串 hash（不需要加密级别）
+        let hash = 0;
+        const str = `${sourcePath}::${content.slice(0, 200)}`;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = ((hash << 5) - hash + char) | 0;
+        }
+        return `ctx_${hash.toString(36)}`;
+    }
+    #escapeXml(str) {
+        return str
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;');
+    }
+}
+//# sourceMappingURL=ContextualEnricher.js.map

package/dist/lib/service/vector/ContextualEnricher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextualEnricher.js","sourceRoot":"","sources":["../../../../lib/service/vector/ContextualEnricher.ts"],"names":[],"mappings":"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"}

package/dist/lib/service/vector/SyncCoordinator.d.ts

@@ -0,0 +1,63 @@
+/**
+ * SyncCoordinator — 知识 CRUD → 向量索引事件驱动同步
+ *
+ * 监听 EventBus 的 `knowledge:changed` 事件，
+ * debounce 合并后批量执行 chunk → embed → upsert/remove。
+ *
+ * 设计:
+ *   - 2s debounce 窗口内合并多个 CRUD 事件
+ *   - maxBatchSize(20) 达到时立即触发
+ *   - 启动时可执行一次 DB↔Vector 对账
+ *
+ * @module service/vector/SyncCoordinator
+ */
+import type { EventBus } from '../../infrastructure/event/EventBus.js';
+import type { VectorStore } from '../../infrastructure/vector/VectorStore.js';
+import type { ContextualEnricher } from './ContextualEnricher.js';
+import type { EmbedProvider } from './VectorService.js';
+export interface SyncCoordinatorConfig {
+    vectorStore: VectorStore;
+    embedProvider: EmbedProvider;
+    contextualEnricher: ContextualEnricher | null;
+    debounceMs: number;
+    maxBatchSize?: number;
+}
+export declare class SyncCoordinator {
+    #private;
+    constructor(config: SyncCoordinatorConfig);
+    /**
+     * 绑定 EventBus，开始监听知识变更事件
+     */
+    bindEventBus(eventBus: EventBus): void;
+    /**
+     * 手动触发立即刷入（用于测试或 shutdown 前确保数据落盘）
+     */
+    flush(): Promise<void>;
+    /**
+     * 启动对账: 比较 DB knowledge_entries 与向量索引，修复不一致
+     * - 孤儿向量 (在索引中但 DB 无对应) → 删除
+     * - 缺失向量 (在 DB 中但索引无对应) → 加入待同步队列
+     *
+     * @param db - 数据库连接 (better-sqlite3 style)
+     * @returns 对账结果
+     */
+    reconcile(db: {
+        prepare(sql: string): {
+            all(...args: unknown[]): Array<{
+                id: string;
+                title?: string;
+                content?: string;
+                kind?: string;
+            }>;
+        };
+    }): Promise<{
+        orphansRemoved: number;
+        missingSynced: number;
+        errors: string[];
+    }>;
+    /**
+     * 销毁: 清理定时器和事件监听
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=SyncCoordinator.d.ts.map

package/dist/lib/service/vector/SyncCoordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncCoordinator.d.ts","sourceRoot":"","sources":["../../../../lib/service/vector/SyncCoordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wCAAwC,CAAC;AAEvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4CAA4C,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,WAAW,CAAC;IACzB,aAAa,EAAE,aAAa,CAAC;IAC7B,kBAAkB,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAaD,qBAAa,eAAe;;gBAad,MAAM,EAAE,qBAAqB;IAQzC;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAuBtC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;;;;;;OAOG;IACG,SAAS,CAAC,EAAE,EAAE;QAClB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;YACpB,GAAG,CACD,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,KAAK,CAAC;gBAAE,EAAE,EAAE,MAAM,CAAC;gBAAC,KAAK,CAAC,EAAE,MAAM,CAAC;gBAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SAC3E,CAAC;KACH,GAAG,OAAO,CAAC;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAkEhF;;OAEG;IACH,OAAO,IAAI,IAAI;CA6KhB"}