autosnippet 3.2.13 → 3.2.15

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

@@ -0,0 +1,290 @@
+/**
+ * SyncCoordinator — 知识 CRUD → 向量索引事件驱动同步
+ *
+ * 监听 EventBus 的 `knowledge:changed` 事件，
+ * debounce 合并后批量执行 chunk → embed → upsert/remove。
+ *
+ * 设计:
+ *   - 2s debounce 窗口内合并多个 CRUD 事件
+ *   - maxBatchSize(20) 达到时立即触发
+ *   - 启动时可执行一次 DB↔Vector 对账
+ *
+ * @module service/vector/SyncCoordinator
+ */
+import Logger from '../../infrastructure/logging/Logger.js';
+// ── Coordinator ──
+export class SyncCoordinator {
+    #vectorStore;
+    #embedProvider;
+    #contextualEnricher;
+    #debounceMs;
+    #maxBatchSize;
+    #pendingChanges = new Map();
+    #debounceTimer = null;
+    #processing = false;
+    #logger = Logger.getInstance();
+    #eventBus = null;
+    #boundHandler = null;
+    constructor(config) {
+        this.#vectorStore = config.vectorStore;
+        this.#embedProvider = config.embedProvider;
+        this.#contextualEnricher = config.contextualEnricher;
+        this.#debounceMs = config.debounceMs;
+        this.#maxBatchSize = config.maxBatchSize ?? 20;
+    }
+    /**
+     * 绑定 EventBus，开始监听知识变更事件
+     */
+    bindEventBus(eventBus) {
+        this.#eventBus = eventBus;
+        this.#boundHandler = (data) => {
+            this.#onKnowledgeChanged(data);
+        };
+        eventBus.on('knowledge:changed', this.#boundHandler);
+        eventBus.on('knowledge:deleted', (data) => {
+            const d = data;
+            const entryId = d.entryId || d.id;
+            if (entryId) {
+                this.#enqueue({
+                    type: 'remove',
+                    entryId,
+                    timestamp: Date.now(),
+                });
+            }
+        });
+        this.#logger.info('[SyncCoordinator] Bound to EventBus');
+    }
+    /**
+     * 手动触发立即刷入（用于测试或 shutdown 前确保数据落盘）
+     */
+    async flush() {
+        if (this.#debounceTimer) {
+            clearTimeout(this.#debounceTimer);
+            this.#debounceTimer = null;
+        }
+        await this.#processBatch();
+    }
+    /**
+     * 启动对账: 比较 DB knowledge_entries 与向量索引，修复不一致
+     * - 孤儿向量 (在索引中但 DB 无对应) → 删除
+     * - 缺失向量 (在 DB 中但索引无对应) → 加入待同步队列
+     *
+     * @param db - 数据库连接 (better-sqlite3 style)
+     * @returns 对账结果
+     */
+    async reconcile(db) {
+        const result = { orphansRemoved: 0, missingSynced: 0, errors: [] };
+        try {
+            // 1. 获取向量索引中所有 ID
+            const vectorIds = new Set(await this.#vectorStore.listIds());
+            // 2. 获取 DB 中所有 active 知识条目 ID
+            let dbEntries = [];
+            try {
+                dbEntries = db
+                    .prepare(`SELECT id, title, content, kind FROM knowledge_entries WHERE lifecycle != 'deprecated'`)
+                    .all();
+            }
+            catch {
+                // 表可能不存在
+                return result;
+            }
+            const dbIdSet = new Set(dbEntries.map((e) => `entry_${e.id}`));
+            // 3. 找孤儿向量 (在索引中但 DB 无对应的 entry_ 前缀记录)
+            for (const vectorId of vectorIds) {
+                if (vectorId.startsWith('entry_') && !dbIdSet.has(vectorId)) {
+                    try {
+                        await this.#vectorStore.remove(vectorId);
+                        result.orphansRemoved++;
+                    }
+                    catch {
+                        // 删除失败不阻塞
+                    }
+                }
+            }
+            // 4. 找缺失向量 (在 DB 中但索引无对应)
+            for (const entry of dbEntries) {
+                const expectedId = `entry_${entry.id}`;
+                if (!vectorIds.has(expectedId)) {
+                    this.#enqueue({
+                        type: 'upsert',
+                        entryId: entry.id,
+                        title: entry.title,
+                        content: entry.content,
+                        kind: entry.kind,
+                        timestamp: Date.now(),
+                    });
+                    result.missingSynced++;
+                }
+            }
+            // 立即处理缺失的
+            if (result.missingSynced > 0) {
+                await this.flush();
+            }
+            this.#logger.info('[SyncCoordinator] Reconciliation complete', {
+                orphansRemoved: result.orphansRemoved,
+                missingSynced: result.missingSynced,
+            });
+        }
+        catch (err) {
+            result.errors.push(err instanceof Error ? err.message : String(err));
+        }
+        return result;
+    }
+    /**
+     * 销毁: 清理定时器和事件监听
+     */
+    destroy() {
+        if (this.#debounceTimer) {
+            clearTimeout(this.#debounceTimer);
+            this.#debounceTimer = null;
+        }
+        if (this.#eventBus && this.#boundHandler) {
+            this.#eventBus.off('knowledge:changed', this.#boundHandler);
+            this.#boundHandler = null;
+        }
+        this.#pendingChanges.clear();
+        this.#logger.info('[SyncCoordinator] Destroyed');
+    }
+    // ═══ Private ═══
+    #onKnowledgeChanged(data) {
+        const d = data;
+        const entryId = d.entryId || d.id || d.entry?.id;
+        if (!entryId) {
+            return;
+        }
+        if (d.action === 'delete') {
+            this.#enqueue({ type: 'remove', entryId, timestamp: Date.now() });
+        }
+        else {
+            this.#enqueue({
+                type: 'upsert',
+                entryId,
+                title: d.entry?.title,
+                content: d.entry?.content,
+                kind: d.entry?.kind,
+                timestamp: Date.now(),
+            });
+        }
+    }
+    #enqueue(change) {
+        // 同一 entryId 的后续操作覆盖前一个（最终一致性）
+        this.#pendingChanges.set(change.entryId, change);
+        // 达到批量上限时立即触发
+        if (this.#pendingChanges.size >= this.#maxBatchSize) {
+            if (this.#debounceTimer) {
+                clearTimeout(this.#debounceTimer);
+                this.#debounceTimer = null;
+            }
+            this.#processBatch().catch((err) => {
+                this.#logger.warn('[SyncCoordinator] processBatch error', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+            return;
+        }
+        // debounce
+        if (this.#debounceTimer) {
+            clearTimeout(this.#debounceTimer);
+        }
+        this.#debounceTimer = setTimeout(() => {
+            this.#debounceTimer = null;
+            this.#processBatch().catch((err) => {
+                this.#logger.warn('[SyncCoordinator] processBatch error', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }, this.#debounceMs);
+    }
+    async #processBatch() {
+        if (this.#processing || this.#pendingChanges.size === 0) {
+            return;
+        }
+        this.#processing = true;
+        const batch = new Map(this.#pendingChanges);
+        this.#pendingChanges.clear();
+        try {
+            const upserts = [];
+            const removes = [];
+            for (const change of batch.values()) {
+                if (change.type === 'remove') {
+                    removes.push(change.entryId);
+                }
+                else {
+                    upserts.push(change);
+                }
+            }
+            // 处理删除
+            for (const entryId of removes) {
+                try {
+                    await this.#vectorStore.remove(`entry_${entryId}`);
+                }
+                catch {
+                    // 删除失败不阻塞
+                }
+            }
+            // 处理 upsert: 提取文本 → embed → upsert
+            if (upserts.length > 0) {
+                const validUpserts = upserts.filter((u) => u.title || u.content);
+                if (validUpserts.length > 0) {
+                    const texts = validUpserts.map((u) => this.#extractText(u));
+                    try {
+                        const embedResult = await this.#embedProvider.embed(texts);
+                        const vectors = Array.isArray(embedResult[0])
+                            ? embedResult
+                            : [embedResult];
+                        const items = validUpserts.map((u, i) => ({
+                            id: `entry_${u.entryId}`,
+                            content: texts[i],
+                            vector: vectors[i] || [],
+                            metadata: {
+                                entryId: u.entryId,
+                                title: u.title || '',
+                                kind: u.kind || 'unknown',
+                                source: 'event_sync',
+                                updatedAt: Date.now(),
+                            },
+                        }));
+                        await this.#vectorStore.batchUpsert(items);
+                    }
+                    catch (err) {
+                        this.#logger.warn('[SyncCoordinator] batch embed/upsert failed', {
+                            count: validUpserts.length,
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                }
+            }
+            this.#logger.info('[SyncCoordinator] Batch processed', {
+                upserted: upserts.length,
+                removed: removes.length,
+            });
+        }
+        finally {
+            this.#processing = false;
+            // 处理期间可能有新的变更入队
+            if (this.#pendingChanges.size > 0) {
+                this.#enqueue(this.#pendingChanges.values().next().value);
+            }
+        }
+    }
+    #extractText(change) {
+        const parts = [];
+        if (change.title) {
+            parts.push(change.title);
+        }
+        if (typeof change.content === 'string') {
+            parts.push(change.content);
+        }
+        else if (change.content && typeof change.content === 'object') {
+            const c = change.content;
+            if (typeof c.body === 'string') {
+                parts.push(c.body);
+            }
+            if (typeof c.code === 'string') {
+                parts.push(c.code);
+            }
+        }
+        return parts.join('\n\n') || change.entryId;
+    }
+}
+//# sourceMappingURL=SyncCoordinator.js.map

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

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

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

@@ -0,0 +1,176 @@
+/**
+ * VectorService — 统一向量服务层
+ *
+ * 整合 IndexingPipeline、VectorStore、BatchEmbedder 等分散组件，
+ * 提供统一的索引构建、查询、CRUD 同步、维护接口。
+ *
+ * 设计原则:
+ *   1. 单一职责 — 统一管理向量生命周期（构建、更新、查询、维护）
+ *   2. 事件驱动 — 知识 CRUD → EventBus → 增量同步
+ *   3. 渐进增强 — 无 EmbedProvider 时 graceful degrade
+ *   4. CLI-first  — `asd embed` 与 API 同等一等公民
+ *
+ * @module service/vector/VectorService
+ */
+import type { EventBus } from '../../infrastructure/event/EventBus.js';
+import type { IndexingPipeline } from '../../infrastructure/vector/IndexingPipeline.js';
+import type { VectorStore } from '../../infrastructure/vector/VectorStore.js';
+import type { HybridRetriever } from '../search/HybridRetriever.js';
+import type { ContextualEnricher } from './ContextualEnricher.js';
+export interface EmbedProvider {
+    embed(texts: string | string[]): Promise<number[] | number[][]>;
+}
+export interface VectorServiceConfig {
+    vectorStore: VectorStore;
+    indexingPipeline: IndexingPipeline;
+    hybridRetriever: HybridRetriever | null;
+    eventBus: EventBus | null;
+    embedProvider: EmbedProvider | null;
+    contextualEnricher: ContextualEnricher | null;
+    autoSyncOnCrud: boolean;
+    syncDebounceMs: number;
+}
+export interface BuildResult {
+    scanned: number;
+    chunked: number;
+    enriched: number;
+    embedded: number;
+    upserted: number;
+    skipped: number;
+    errors: number;
+    duration: number;
+}
+export interface SyncResult {
+    added: number;
+    updated: number;
+    removed: number;
+    errors: string[];
+}
+export interface VectorStats {
+    count: number;
+    dimension: number;
+    indexSize: number;
+    quantized: boolean;
+    embedProviderAvailable: boolean;
+    autoSyncEnabled: boolean;
+}
+export interface ProgressInfo {
+    phase: string;
+    detail?: string;
+    [key: string]: unknown;
+}
+export type ProgressFn = (info: ProgressInfo) => void;
+export declare class VectorService {
+    #private;
+    constructor(config: VectorServiceConfig);
+    /**
+     * 初始化: 绑定 EventBus 事件监听
+     */
+    initialize(): Promise<void>;
+    /**
+     * 全量构建向量索引
+     * 委托给 IndexingPipeline.run()，增加 enrichment 步骤和计时
+     */
+    fullBuild(opts?: {
+        force?: boolean;
+        clear?: boolean;
+        dryRun?: boolean;
+        onProgress?: ProgressFn;
+    }): Promise<BuildResult>;
+    /**
+     * 增量更新: 只处理指定的变更文件
+     * 适用于文件系统级变更（watch 或 git diff）
+     */
+    incrementalUpdate(changedFiles: string[], opts?: {
+        onProgress?: ProgressFn;
+    }): Promise<BuildResult>;
+    /**
+     * 清空向量索引
+     */
+    clear(): Promise<void>;
+    /**
+     * 校验向量索引健康状态
+     * - 维度一致性
+     * - 孤儿向量检查 (向量有但 DB 无对应 entry)
+     * - Embed Provider 可用性
+     */
+    validate(): Promise<{
+        healthy: boolean;
+        issues: string[];
+    }>;
+    /**
+     * 语义搜索
+     * Embed query → vectorStore.searchVector → 返回结果
+     */
+    search(query: string, opts?: {
+        topK?: number;
+        filter?: Record<string, unknown>;
+        minScore?: number;
+    }): Promise<Array<{
+        item: Record<string, unknown>;
+        score: number;
+    }>>;
+    /**
+     * 混合搜索 (Dense + Sparse RRF 融合)
+     * 通过 HybridRetriever 执行向量 + BM25 关键词并行检索
+     */
+    hybridSearch(query: string, opts?: {
+        topK?: number;
+        alpha?: number;
+        sparseSearchFn?: ((q: string, limit: number) => Array<{
+            id: string;
+            score?: number;
+            [key: string]: unknown;
+        }>) | null;
+    }): Promise<Array<{
+        id: string;
+        score: number;
+        [key: string]: unknown;
+    }>>;
+    /**
+     * 通过 ID 查找相似向量
+     */
+    similarById(id: string, topK?: number): Promise<Array<{
+        item: Record<string, unknown>;
+        score: number;
+    }>>;
+    /**
+     * 手动同步单个知识条目到向量索引
+     * 用于 KnowledgeService CRUD 后的即时同步
+     */
+    syncEntry(entry: {
+        id: string;
+        title: string;
+        content: unknown;
+        kind?: string;
+    }): Promise<void>;
+    /**
+     * 从向量索引移除一个条目
+     */
+    removeEntry(entryId: string): Promise<void>;
+    /**
+     * 批量同步知识条目
+     */
+    batchSync(entries: Array<{
+        id: string;
+        title: string;
+        content: unknown;
+        kind?: string;
+    }>): Promise<SyncResult>;
+    /**
+     * 获取向量索引统计信息
+     */
+    getStats(): Promise<VectorStats>;
+    /**
+     * 迁移维度: 清空索引并使用新的 EmbedProvider 重建
+     * 用于 embedding 模型切换场景
+     */
+    migrateDimension(newProvider: EmbedProvider, opts?: {
+        onProgress?: ProgressFn;
+    }): Promise<BuildResult>;
+    /**
+     * 销毁: 清理 SyncCoordinator 的定时器和事件监听
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=VectorService.d.ts.map

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

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