autosnippet 3.3.6 → 3.3.8

package/dist/lib/service/knowledge/CodeEntityGraph.js

@@ -26,15 +26,14 @@ import Logger from '../../infrastructure/logging/Logger.js';
 const logger = Logger.getInstance();
 export class CodeEntityGraph {
     projectRoot;
-    db;
+    #entityRepo;
+    #edgeRepo;
     log;
-    stmts;
-    constructor(db, options = {}) {
-        this.db = typeof db?.getDb === 'function' ? db.getDb() : db;
+    constructor(entityRepo, edgeRepo, options = {}) {
+        this.#entityRepo = entityRepo;
+        this.#edgeRepo = edgeRepo;
         this.projectRoot = options.projectRoot || '';
         this.log = options.logger || logger;
-        this.#ensureTable();
-        this.#prepareStatements();
     }
     // ────────────────────────────────────────────
     // Public API — 图谱构建
@@ -46,102 +45,99 @@ export class CodeEntityGraph {
      *
      * @param astSummary analyzeProject() 产出的 ProjectAstSummary
      */
-    populateFromAst(astSummary) {
+    async populateFromAst(astSummary) {
         if (!astSummary) {
             return { entitiesUpserted: 0, edgesCreated: 0, durationMs: 0 };
         }
         const t0 = Date.now();
         let entities = 0;
         let edges = 0;
-        const run = this.db.transaction(() => {
-            // ── 类 ──
-            for (const cls of astSummary.classes || []) {
-                this.#upsertEntity({
-                    entityId: cls.name,
-                    entityType: cls.isCategory ? 'category' : 'class',
-                    name: cls.name,
-                    filePath: cls.file || null,
-                    line: cls.line || null,
-                    superclass: cls.superclass || null,
-                    protocols: cls.protocols || [],
-                    metadata: {
-                        endLine: cls.endLine,
-                        isCategory: cls.isCategory || false,
-                    },
-                });
-                entities++;
-            }
-            // ── 协议 ──
-            for (const proto of astSummary.protocols || []) {
-                this.#upsertEntity({
-                    entityId: proto.name,
-                    entityType: 'protocol',
-                    name: proto.name,
-                    filePath: proto.file || null,
-                    line: proto.line || null,
-                    protocols: proto.inherits || [],
-                    metadata: {
-                        methodCount: proto.methods?.length || 0,
-                    },
-                });
-                entities++;
-            }
-            // ── Category ──
-            for (const cat of astSummary.categories || []) {
-                const catId = `${cat.className}(${cat.categoryName})`;
-                this.#upsertEntity({
-                    entityId: catId,
-                    entityType: 'category',
-                    name: catId,
-                    filePath: cat.file || null,
-                    line: cat.line || null,
-                    protocols: cat.protocols || [],
-                    metadata: {
-                        className: cat.className,
-                        categoryName: cat.categoryName,
-                        methodCount: cat.methods?.length || 0,
-                    },
-                });
-                entities++;
-            }
-            // ── 继承/遵循/扩展 边 (从 AST inheritanceGraph) ──
-            for (const edge of astSummary.inheritanceGraph || []) {
-                const fromType = this.#inferEntityType(edge.from, astSummary);
-                const toType = this.#inferEntityType(edge.to, astSummary);
-                this.#addEdge(edge.from, fromType, edge.to, toType, edge.type, {
-                    weight: 1.0,
-                    source: 'ast-bootstrap',
-                });
-                edges++;
-            }
-            // ── 设计模式 (从 patternStats) ──
-            for (const [patternType, stat] of Object.entries(astSummary.patternStats || {})) {
-                const patternId = `pattern:${patternType}`;
-                this.#upsertEntity({
-                    entityId: patternId,
-                    entityType: 'pattern',
-                    name: patternType,
-                    metadata: {
-                        count: stat.count,
-                        files: stat.files?.slice(0, 10),
-                    },
-                });
-                entities++;
-                // 实例 → uses_pattern 边
-                for (const inst of (stat.instances || []).slice(0, 50)) {
-                    const className = inst.className || inst.name;
-                    if (className) {
-                        this.#addEdge(className, 'class', patternId, 'pattern', 'uses_pattern', {
-                            weight: 0.8,
-                            source: 'ast-pattern-detection',
-                            file: inst.file,
-                        });
-                        edges++;
-                    }
+        // ── 类 ──
+        for (const cls of astSummary.classes || []) {
+            await this.#upsertEntity({
+                entityId: cls.name,
+                entityType: cls.isCategory ? 'category' : 'class',
+                name: cls.name,
+                filePath: cls.file || null,
+                line: cls.line || null,
+                superclass: cls.superclass || null,
+                protocols: cls.protocols || [],
+                metadata: {
+                    endLine: cls.endLine,
+                    isCategory: cls.isCategory || false,
+                },
+            });
+            entities++;
+        }
+        // ── 协议 ──
+        for (const proto of astSummary.protocols || []) {
+            await this.#upsertEntity({
+                entityId: proto.name,
+                entityType: 'protocol',
+                name: proto.name,
+                filePath: proto.file || null,
+                line: proto.line || null,
+                protocols: proto.inherits || [],
+                metadata: {
+                    methodCount: proto.methods?.length || 0,
+                },
+            });
+            entities++;
+        }
+        // ── Category ──
+        for (const cat of astSummary.categories || []) {
+            const catId = `${cat.className}(${cat.categoryName})`;
+            await this.#upsertEntity({
+                entityId: catId,
+                entityType: 'category',
+                name: catId,
+                filePath: cat.file || null,
+                line: cat.line || null,
+                protocols: cat.protocols || [],
+                metadata: {
+                    className: cat.className,
+                    categoryName: cat.categoryName,
+                    methodCount: cat.methods?.length || 0,
+                },
+            });
+            entities++;
+        }
+        // ── 继承/遵循/扩展 边 (从 AST inheritanceGraph) ──
+        for (const edge of astSummary.inheritanceGraph || []) {
+            const fromType = this.#inferEntityType(edge.from, astSummary);
+            const toType = this.#inferEntityType(edge.to, astSummary);
+            await this.#addEdge(edge.from, fromType, edge.to, toType, edge.type, {
+                weight: 1.0,
+                source: 'ast-bootstrap',
+            });
+            edges++;
+        }
+        // ── 设计模式 (从 patternStats) ──
+        for (const [patternType, stat] of Object.entries(astSummary.patternStats || {})) {
+            const patternId = `pattern:${patternType}`;
+            await this.#upsertEntity({
+                entityId: patternId,
+                entityType: 'pattern',
+                name: patternType,
+                metadata: {
+                    count: stat.count,
+                    files: stat.files?.slice(0, 10),
+                },
+            });
+            entities++;
+            // 实例 → uses_pattern 边
+            for (const inst of (stat.instances || []).slice(0, 50)) {
+                const className = inst.className || inst.name;
+                if (className) {
+                    await this.#addEdge(className, 'class', patternId, 'pattern', 'uses_pattern', {
+                        weight: 0.8,
+                        source: 'ast-pattern-detection',
+                        file: inst.file,
+                    });
+                    edges++;
                 }
             }
-        });
-        run();
+        }
         const result = { entitiesUpserted: entities, edgesCreated: edges, durationMs: Date.now() - t0 };
         this.log.info(`[CodeEntityGraph] AST populate: ${entities} entities, ${edges} edges (${result.durationMs}ms)`);
         return result;
@@ -154,27 +150,40 @@ export class CodeEntityGraph {
      *
      * @param depGraphData spm.getDependencyGraph() 产出
      */
-    populateFromSpm(depGraphData) {
+    async populateFromSpm(depGraphData) {
         if (!depGraphData) {
             return { entitiesUpserted: 0, edgesCreated: 0, durationMs: 0 };
         }
         const t0 = Date.now();
         let entities = 0;
-        const run = this.db.transaction(() => {
-            for (const node of depGraphData.nodes || []) {
-                const nodeObj = typeof node === 'string' ? { id: node, label: node } : node;
-                this.#upsertEntity({
-                    entityId: nodeObj.id || nodeObj.label || String(node),
-                    entityType: 'module',
-                    name: nodeObj.label || nodeObj.id || String(node),
-                    metadata: {
-                        nodeType: nodeObj.type || 'module',
-                    },
-                });
-                entities++;
-            }
-        });
-        run();
+        for (const node of depGraphData.nodes || []) {
+            const nodeObj = typeof node === 'string' ? { id: node, label: node } : node;
+            await this.#upsertEntity({
+                entityId: nodeObj.id || nodeObj.label || String(node),
+                entityType: 'module',
+                name: nodeObj.label || nodeObj.id || String(node),
+                metadata: {
+                    nodeType: nodeObj.type || 'module',
+                    ...(nodeObj.layer != null ? { layer: nodeObj.layer } : {}),
+                    ...(nodeObj.version != null ? { version: nodeObj.version } : {}),
+                    ...(nodeObj.group != null ? { group: nodeObj.group } : {}),
+                    ...(nodeObj.fullPath != null ? { fullPath: nodeObj.fullPath } : {}),
+                    ...(nodeObj.indirect != null ? { indirect: nodeObj.indirect } : {}),
+                },
+            });
+            entities++;
+        }
+        // 存储 layers 元数据（如果存在）到特殊实体
+        const layers = depGraphData.layers;
+        if (layers?.length) {
+            await this.#upsertEntity({
+                entityId: '__config_layers__',
+                entityType: 'config',
+                name: 'Config Layers',
+                metadata: { layers },
+            });
+            entities++;
+        }
         const result = { entitiesUpserted: entities, edgesCreated: 0, durationMs: Date.now() - t0 };
         this.log.info(`[CodeEntityGraph] SPM populate: ${entities} module entities (${result.durationMs}ms)`);
         return result;
@@ -184,55 +193,52 @@ export class CodeEntityGraph {
      *
      * @param candidates 扁平关系数组或 Relations 对象
      */
-    populateFromCandidateRelations(candidates) {
+    async populateFromCandidateRelations(candidates) {
         if (!candidates?.length) {
             return { entitiesUpserted: 0, edgesCreated: 0, durationMs: 0 };
         }
         const t0 = Date.now();
         let edges = 0;
-        const run = this.db.transaction(() => {
-            for (const candidate of candidates) {
-                const title = candidate.title || candidate.id || '';
-                if (!title) {
-                    continue;
-                }
-                // 处理 Relations 对象或扁平数组
-                let flatRelations;
-                const rels = candidate.relations;
-                if (typeof rels?.toFlatArray === 'function') {
-                    flatRelations = rels.toFlatArray();
-                }
-                else if (Array.isArray(candidate.relations)) {
-                    flatRelations = candidate.relations;
-                }
-                else if (candidate.relations && typeof candidate.relations === 'object') {
-                    // 桶结构 → 扁平
-                    flatRelations = [];
-                    for (const [type, list] of Object.entries(candidate.relations)) {
-                        for (const r of Array.isArray(list) ? list : []) {
-                            flatRelations.push({ type, target: r.target, description: r.description });
-                        }
+        for (const candidate of candidates) {
+            const title = candidate.title || candidate.id || '';
+            if (!title) {
+                continue;
+            }
+            // 处理 Relations 对象或扁平数组
+            let flatRelations;
+            const rels = candidate.relations;
+            if (typeof rels?.toFlatArray === 'function') {
+                flatRelations = rels.toFlatArray();
+            }
+            else if (Array.isArray(candidate.relations)) {
+                flatRelations = candidate.relations;
+            }
+            else if (candidate.relations && typeof candidate.relations === 'object') {
+                // 桶结构 → 扁平
+                flatRelations = [];
+                for (const [type, list] of Object.entries(candidate.relations)) {
+                    for (const r of Array.isArray(list) ? list : []) {
+                        flatRelations.push({ type, target: r.target, description: r.description });
                     }
                 }
-                else {
+            }
+            else {
+                continue;
+            }
+            for (const rel of flatRelations) {
+                if (!rel.target) {
                     continue;
                 }
-                for (const rel of flatRelations) {
-                    if (!rel.target) {
-                        continue;
-                    }
-                    // 映射关系类型到边类型
-                    const relation = this.#mapRelationType(rel.type);
-                    this.#addEdge(title, 'recipe', rel.target, 'recipe', relation, {
-                        weight: 0.7,
-                        source: 'candidate-relations',
-                        description: rel.description || '',
-                    });
-                    edges++;
-                }
+                // 映射关系类型到边类型
+                const relation = this.#mapRelationType(rel.type);
+                await this.#addEdge(title, 'recipe', rel.target, 'recipe', relation, {
+                    weight: 0.7,
+                    source: 'candidate-relations',
+                    description: rel.description || '',
+                });
+                edges++;
             }
-        });
-        run();
+        }
         const result = { entitiesUpserted: 0, edgesCreated: edges, durationMs: Date.now() - t0 };
         this.log.info(`[CodeEntityGraph] Candidate relations: ${edges} edges (${result.durationMs}ms)`);
         return result;
@@ -241,97 +247,83 @@ export class CodeEntityGraph {
     // Public API — 图谱查询
     // ────────────────────────────────────────────
     /** 获取单个实体信息 */
-    getEntity(entityId, entityType) {
-        let row;
+    async getEntity(entityId, entityType) {
+        let entity;
         if (entityType) {
-            row = this.stmts.getEntity.get(entityId, entityType, this.projectRoot);
+            entity = await this.#entityRepo.findByEntityId(entityId, entityType, this.projectRoot);
         }
         else {
-            row = this.db
-                .prepare(`SELECT * FROM code_entities WHERE entity_id = ? AND project_root = ? LIMIT 1`)
-                .get(entityId, this.projectRoot);
+            entity = await this.#entityRepo.findByEntityIdOnly(entityId, this.projectRoot);
         }
-        return row ? this.#mapEntity(row) : null;
+        return entity ? this.#mapRepoEntity(entity) : null;
     }
     /**
      * 按类型列出所有实体
      * @param entityType 'class'|'protocol'|'category'|'module'|'pattern'
      */
-    listEntities(entityType, limit = 200) {
-        const rows = this.stmts.listByType.all(entityType, this.projectRoot, limit);
-        return rows.map((r) => this.#mapEntity(r));
+    async listEntities(entityType, limit = 200) {
+        const entities = await this.#entityRepo.listByType(entityType, this.projectRoot, limit);
+        return entities.map((e) => this.#mapRepoEntity(e));
     }
     /**
      * 搜索实体 (名称模糊匹配)
      * @param [options.type] 过滤类型
      */
-    searchEntities(query, options = {}) {
-        const pattern = `%${query}%`;
-        let sql = `SELECT * FROM code_entities WHERE project_root = ? AND name LIKE ?`;
-        const params = [this.projectRoot, pattern];
-        if (options.type) {
-            sql += ` AND entity_type = ?`;
-            params.push(options.type);
-        }
-        sql += ` ORDER BY name LIMIT ?`;
-        params.push(options.limit || 20);
-        return this.db
-            .prepare(sql)
-            .all(...params)
-            .map((r) => this.#mapEntity(r));
+    async searchEntities(query, options = {}) {
+        const entities = await this.#entityRepo.searchByName(query, this.projectRoot, {
+            entityType: options.type,
+            limit: options.limit || 20,
+        });
+        return entities.map((e) => this.#mapRepoEntity(e));
     }
     /**
      * 获取实体的所有关系边
-     * @returns }
      */
-    getEntityEdges(entityId, entityType, direction = 'both') {
+    async getEntityEdges(entityId, entityType, direction = 'both') {
         const outgoing = direction === 'both' || direction === 'out'
-            ? this.db
-                .prepare(`SELECT * FROM knowledge_edges WHERE from_id = ? AND from_type = ?`)
-                .all(entityId, entityType)
-                .map((row) => this.#mapEdge(row))
+            ? await this.#edgeRepo.findOutgoing(entityId, entityType)
             : [];
         const incoming = direction === 'both' || direction === 'in'
-            ? this.db
-                .prepare(`SELECT * FROM knowledge_edges WHERE to_id = ? AND to_type = ?`)
-                .all(entityId, entityType)
-                .map((row) => this.#mapEdge(row))
+            ? await this.#edgeRepo.findIncoming(entityId, entityType)
             : [];
-        return { outgoing, incoming };
+        return {
+            outgoing: outgoing.map((e) => this.#mapRepoEdge(e)),
+            incoming: incoming.map((e) => this.#mapRepoEdge(e)),
+        };
     }
     /**
      * 获取继承链 (向上遍历 inherits 边)
      * @returns 继承链 [class, parent, grandparent, ...]
      */
-    getInheritanceChain(className, maxDepth = 10) {
+    async getInheritanceChain(className, maxDepth = 10) {
         const chain = [className];
         let current = className;
         for (let i = 0; i < maxDepth; i++) {
-            const parent = this.db
-                .prepare(`SELECT to_id FROM knowledge_edges 
-         WHERE from_id = ? AND from_type = 'class' AND relation = 'inherits' LIMIT 1`)
-                .get(current);
-            if (!parent) {
+            const parentId = await this.#edgeRepo.findOutgoingToId(current, 'class', 'inherits');
+            if (!parentId) {
                 break;
             }
-            chain.push(parent.to_id);
-            current = parent.to_id;
+            chain.push(parentId);
+            current = parentId;
         }
         return chain;
     }
     /**
      * 获取所有子类/实现者 (向下遍历)
      * @param entityType 'class'|'protocol'
-     * @returns >}
      */
-    getDescendants(entityId, entityType, maxDepth = 3) {
+    async getDescendants(entityId, entityType, maxDepth = 3) {
         const results = [];
         const visited = new Set();
         const queue = [{ id: entityId, type: entityType, depth: 0 }];
         // 类的子类/Category + 协议的遵循者
         const relations = entityType === 'protocol' ? ['conforms', 'inherits'] : ['inherits', 'extends'];
         while (queue.length > 0) {
-            const { id, type, depth } = queue.shift();
+            const current = queue.shift();
+            if (!current) {
+                break;
+            }
+            const { id, type, depth } = current;
             if (depth >= maxDepth) {
                 continue;
             }
@@ -341,22 +333,19 @@ export class CodeEntityGraph {
             }
             visited.add(key);
             for (const rel of relations) {
-                const children = this.db
-                    .prepare(`SELECT from_id, from_type FROM knowledge_edges 
-           WHERE to_id = ? AND to_type = ? AND relation = ?`)
-                    .all(id, type, rel);
+                const children = await this.#edgeRepo.findIncomingByFromTypes(id, type, rel);
                 for (const child of children) {
-                    const childKey = `${child.from_type}:${child.from_id}`;
+                    const childKey = `${child.fromType}:${child.fromId}`;
                     if (!visited.has(childKey)) {
                         results.push({
-                            id: child.from_id,
-                            type: child.from_type,
+                            id: child.fromId,
+                            type: child.fromType,
                             depth: depth + 1,
                             relation: rel,
                         });
                         queue.push({
-                            id: child.from_id,
-                            type: child.from_type,
+                            id: child.fromId,
+                            type: child.fromType,
                             depth: depth + 1,
                         });
                     }
@@ -366,18 +355,13 @@ export class CodeEntityGraph {
         return results;
     }
     /** 获取协议遵循关系 (className → 遵循的协议列表) */
-    getConformances(className) {
-        const rows = this.db
-            .prepare(`SELECT to_id FROM knowledge_edges 
-       WHERE from_id = ? AND from_type IN ('class', 'category') AND relation = 'conforms'`)
-            .all(className);
-        return rows.map((r) => r.to_id);
+    async getConformances(className) {
+        return this.#edgeRepo.findConformances(className);
     }
     /**
      * 查找两个实体间的路径 (BFS)
-     * @returns }
      */
-    findPath(fromId, fromType, toId, toType, maxDepth = 5) {
+    async findPath(fromId, fromType, toId, toType, maxDepth = 5) {
         const visited = new Set();
         const queue = [
             {
@@ -387,7 +371,11 @@ export class CodeEntityGraph {
             },
         ];
         while (queue.length > 0) {
-            const { id, type, path } = queue.shift();
+            const current = queue.shift();
+            if (!current) {
+                break;
+            }
+            const { id, type, path } = current;
             if (path.length >= maxDepth) {
                 continue;
             }
@@ -396,20 +384,18 @@ export class CodeEntityGraph {
                 continue;
             }
             visited.add(key);
-            const neighbors = this.db
-                .prepare(`SELECT to_id, to_type, relation, weight FROM knowledge_edges WHERE from_id = ? AND from_type = ?`)
-                .all(id, type);
+            const neighbors = await this.#edgeRepo.findOutgoing(id, type);
             for (const n of neighbors) {
                 const step = {
                     from: { id, type },
-                    to: { id: n.to_id, type: n.to_type },
+                    to: { id: n.toId, type: n.toType },
                     relation: n.relation,
                 };
                 const newPath = [...path, step];
-                if (n.to_id === toId && n.to_type === toType) {
+                if (n.toId === toId && n.toType === toType) {
                     return { found: true, path: newPath, depth: newPath.length };
                 }
-                queue.push({ id: n.to_id, type: n.to_type, path: newPath });
+                queue.push({ id: n.toId, type: n.toType, path: newPath });
             }
         }
         return {
@@ -420,14 +406,17 @@ export class CodeEntityGraph {
     }
     /**
      * 影响分析: 修改某实体后，哪些实体可能受影响
-     * @returns >}
      */
-    getImpactRadius(entityId, entityType, maxDepth = 3) {
+    async getImpactRadius(entityId, entityType, maxDepth = 3) {
         const impacted = [];
         const visited = new Set();
         const queue = [{ id: entityId, type: entityType, depth: 0 }];
         while (queue.length > 0) {
-            const { id, type, depth } = queue.shift();
+            const current = queue.shift();
+            if (!current) {
+                break;
+            }
+            const { id, type, depth } = current;
             if (depth >= maxDepth) {
                 continue;
             }
@@ -437,22 +426,19 @@ export class CodeEntityGraph {
             }
             visited.add(key);
             // 找出所有"依赖/引用此实体"的上游
-            const dependents = this.db
-                .prepare(`SELECT from_id, from_type, relation FROM knowledge_edges 
-         WHERE to_id = ? AND to_type = ?`)
-                .all(id, type);
+            const dependents = await this.#edgeRepo.findIncoming(id, type);
             for (const dep of dependents) {
-                const depKey = `${dep.from_type}:${dep.from_id}`;
+                const depKey = `${dep.fromType}:${dep.fromId}`;
                 if (!visited.has(depKey)) {
                     impacted.push({
-                        id: dep.from_id,
-                        type: dep.from_type,
+                        id: dep.fromId,
+                        type: dep.fromType,
                         relation: dep.relation,
                         depth: depth + 1,
                     });
                     queue.push({
-                        id: dep.from_id,
-                        type: dep.from_type,
+                        id: dep.fromId,
+                        type: dep.fromType,
                         depth: depth + 1,
                     });
                 }
@@ -461,44 +447,28 @@ export class CodeEntityGraph {
         return impacted;
     }
     /** 项目拓扑概览 — 统计信息 + 关键度排名 */
-    getTopology() {
-        const entityStats = this.db
-            .prepare(`SELECT entity_type, COUNT(*) as count FROM code_entities 
-       WHERE project_root = ? GROUP BY entity_type`)
-            .all(this.projectRoot);
-        const edgeStats = this.db
-            .prepare(`SELECT relation, COUNT(*) as count FROM knowledge_edges GROUP BY relation`)
-            .all();
-        // 入度最高的实体 = 被依赖最多
-        const hotNodes = this.db
-            .prepare(`SELECT to_id, to_type, COUNT(*) as in_degree 
-       FROM knowledge_edges 
-       GROUP BY to_id, to_type 
-       ORDER BY in_degree DESC LIMIT 15`)
-            .all();
+    async getTopology() {
+        const entityStats = await this.#entityRepo.countByType(this.projectRoot);
+        const edgeStats = await this.#edgeRepo.countByRelation();
+        const hotNodes = await this.#edgeRepo.getHotNodes(15);
+        const totalEntities = Object.values(entityStats).reduce((sum, c) => sum + c, 0);
+        const totalEdges = Object.values(edgeStats).reduce((sum, c) => sum + c, 0);
         return {
-            entities: Object.fromEntries(entityStats.map((s) => [
-                s.entity_type,
-                s.count,
-            ])),
-            edges: Object.fromEntries(edgeStats.map((s) => [
-                s.relation,
-                s.count,
-            ])),
-            totalEntities: entityStats.reduce((sum, s) => sum + (s.count || 0), 0),
-            totalEdges: edgeStats.reduce((sum, s) => sum + (s.count || 0), 0),
+            entities: entityStats,
+            edges: edgeStats,
+            totalEntities,
+            totalEdges,
             hotNodes: hotNodes.map((n) => ({
-                id: n.to_id,
-                type: n.to_type,
-                inDegree: n.in_degree,
+                id: n.id,
+                type: n.type,
+                inDegree: n.inDegree,
             })),
         };
     }
     /** 生成 Agent 可用的图谱上下文 (Markdown) */
-    generateContextForAgent(options = {}) {
+    async generateContextForAgent(options = {}) {
         const maxEntities = options.maxEntities || 30;
-        const _maxEdges = options.maxEdges || 50;
-        const topo = this.getTopology();
+        const topo = await this.getTopology();
         if (topo.totalEntities === 0) {
             return '';
         }
@@ -519,11 +489,11 @@ export class CodeEntityGraph {
             lines.push('');
         }
         // 类继承概览
-        const classes = this.listEntities('class', maxEntities);
+        const classes = await this.listEntities('class', maxEntities);
         if (classes.length > 0) {
             lines.push('### 类继承关系');
             for (const cls of classes) {
-                const chain = this.getInheritanceChain(cls.entityId, 5);
+                const chain = await this.getInheritanceChain(cls.entityId, 5);
                 if (chain.length > 1) {
                     lines.push(`- \`${chain.join(' → ')}\``);
                 }
@@ -531,11 +501,11 @@ export class CodeEntityGraph {
             lines.push('');
         }
         // 协议
-        const protocols = this.listEntities('protocol', 15);
+        const protocols = await this.listEntities('protocol', 15);
         if (protocols.length > 0) {
             lines.push('### 协议');
             for (const p of protocols) {
-                const conformers = this.getDescendants(p.entityId, 'protocol', 1);
+                const conformers = await this.getDescendants(p.entityId, 'protocol', 1);
                 const cNames = conformers.map((c) => c.id).slice(0, 5);
                 lines.push(`- \`${p.name}\` ← ${cNames.length > 0 ? cNames.map((n) => `\`${n}\``).join(', ') : '(无遵循者)'}`);
             }
@@ -543,37 +513,36 @@ export class CodeEntityGraph {
         }
         // 调用图热路径 (Phase 5)
         try {
-            const hotCallees = this.db
-                .prepare(`SELECT to_id, COUNT(*) as call_count
-           FROM knowledge_edges
-           WHERE relation = 'calls'
-           GROUP BY to_id
-           ORDER BY call_count DESC
-           LIMIT 15`)
-                .all();
-            if (hotCallees.length > 0) {
-                lines.push('### 调用图热路径 (Call Graph Hot Paths)');
-                for (const row of hotCallees) {
-                    // 查找前几个调用者
-                    const topCallers = this.db
-                        .prepare(`SELECT from_id FROM knowledge_edges
-               WHERE relation = 'calls' AND to_id = ?
-               LIMIT 3`)
-                        .all(row.to_id);
+            const hotCallees = await this.#edgeRepo.getHotNodes(15);
+            // Filter for 'calls' relation — use countIncomingByRelation for each
+            const callHotPaths = [];
+            for (const node of hotCallees) {
+                const callCount = await this.#edgeRepo.countIncomingByRelation(node.id, 'calls');
+                if (callCount > 0) {
+                    const topCallers = await this.#edgeRepo.findIncomingByRelation(node.id, 'calls');
                     const callerNames = topCallers
-                        .map((c) => `\`${c.from_id}\``)
+                        .slice(0, 3)
+                        .map((c) => `\`${c.fromId}\``)
                         .join(', ');
-                    lines.push(`- \`${row.to_id}\` ← ${row.call_count} 次调用 (${callerNames}${topCallers.length < row.call_count ? '...' : ''})`);
+                    callHotPaths.push({
+                        toId: node.id,
+                        callCount,
+                        callerNames: `${callerNames}${topCallers.length > 3 ? '...' : ''}`,
+                    });
+                }
+            }
+            if (callHotPaths.length > 0) {
+                lines.push('### 调用图热路径 (Call Graph Hot Paths)');
+                for (const row of callHotPaths.slice(0, 15)) {
+                    lines.push(`- \`${row.toId}\` ← ${row.callCount} 次调用 (${row.callerNames})`);
                 }
                 lines.push('');
             }
             // 数据流边摘要
-            const dataFlowCount = this.db
-                .prepare(`SELECT COUNT(*) as cnt FROM knowledge_edges WHERE relation = 'data_flow'`)
-                .get();
-            if (dataFlowCount && dataFlowCount.cnt > 0) {
+            const dataFlowCount = await this.#edgeRepo.countByRelationType('data_flow');
+            if (dataFlowCount > 0) {
                 lines.push(`### 数据流`);
-                lines.push(`- 数据流边: ${dataFlowCount.cnt} 条`);
+                lines.push(`- 数据流边: ${dataFlowCount} 条`);
                 lines.push('');
             }
         }
@@ -591,90 +560,87 @@ export class CodeEntityGraph {
      * @param callEdges
      * @param dataFlowEdges
      */
-    populateCallGraph(callEdges, dataFlowEdges) {
+    async populateCallGraph(callEdges, dataFlowEdges) {
         const t0 = Date.now();
         let edges = 0;
         let entities = 0;
-        const run = this.db.transaction(() => {
-            // ── 注册方法实体 (确保 from/to 的 entity 存在) ──
-            const registeredMethods = new Set();
-            for (const edge of callEdges) {
-                for (const fqn of [edge.caller, edge.callee]) {
-                    if (registeredMethods.has(fqn)) {
-                        continue;
-                    }
-                    registeredMethods.add(fqn);
-                    const entityId = this._extractEntityId(fqn);
-                    const entityName = entityId; // 短名
-                    const filePath = fqn.includes('::') ? fqn.split('::')[0] : null;
-                    this.#upsertEntity({
-                        entityId,
-                        entityType: 'method',
-                        name: entityName,
-                        filePath,
-                        metadata: { fqn, source: 'phase5-call-graph' },
-                    });
-                    entities++;
+        // ── 注册方法实体 (确保 from/to 的 entity 存在) ──
+        const registeredMethods = new Set();
+        for (const edge of callEdges) {
+            for (const fqn of [edge.caller, edge.callee]) {
+                if (registeredMethods.has(fqn)) {
+                    continue;
                 }
+                registeredMethods.add(fqn);
+                const entityId = this._extractEntityId(fqn);
+                const entityName = entityId; // 短名
+                const filePath = fqn.includes('::') ? fqn.split('::')[0] : null;
+                await this.#upsertEntity({
+                    entityId,
+                    entityType: 'method',
+                    name: entityName,
+                    filePath,
+                    metadata: { fqn, source: 'phase5-call-graph' },
+                });
+                entities++;
             }
-            // ── 调用边 (聚合同一 caller-callee 对的多次调用，解决 Issue #4) ──
-            const aggregated = new Map(); // key = "callerId|calleeId" → aggregated metadata
-            for (const edge of callEdges) {
-                const callerId = this._extractEntityId(edge.caller);
-                const calleeId = this._extractEntityId(edge.callee);
-                const key = `${callerId}|${calleeId}`;
-                if (aggregated.has(key)) {
-                    const agg = aggregated.get(key);
-                    agg.callCount++;
-                    agg.callSites.push({ line: edge.line, isAwait: edge.isAwait });
-                    // 提升权重: direct 优先
-                    if (edge.resolveMethod === 'direct') {
-                        agg.resolveMethod = 'direct';
-                    }
-                    if (edge.isAwait) {
-                        agg.hasAwait = true;
-                    }
+        }
+        // ── 调用边 (聚合同一 caller-callee 对的多次调用，解决 Issue #4) ──
+        const aggregated = new Map(); // key = "callerId|calleeId" → aggregated metadata
+        for (const edge of callEdges) {
+            const callerId = this._extractEntityId(edge.caller);
+            const calleeId = this._extractEntityId(edge.callee);
+            const key = `${callerId}|${calleeId}`;
+            if (aggregated.has(key)) {
+                const agg = aggregated.get(key);
+                agg.callCount++;
+                agg.callSites.push({ line: edge.line, isAwait: edge.isAwait });
+                // 提升权重: direct 优先
+                if (edge.resolveMethod === 'direct') {
+                    agg.resolveMethod = 'direct';
                 }
-                else {
-                    aggregated.set(key, {
-                        callerId,
-                        calleeId,
-                        callType: edge.callType,
-                        resolveMethod: edge.resolveMethod,
-                        file: edge.file,
-                        hasAwait: edge.isAwait,
-                        callCount: 1,
-                        callSites: [{ line: edge.line, isAwait: edge.isAwait }],
-                    });
+                if (edge.isAwait) {
+                    agg.hasAwait = true;
                 }
             }
-            for (const agg of aggregated.values()) {
-                this.#addEdge(agg.callerId, 'method', agg.calleeId, 'method', 'calls', {
-                    weight: agg.resolveMethod === 'direct' ? 1.0 : 0.6,
-                    source: 'phase5-call-graph',
-                    callType: agg.callType,
-                    resolveMethod: agg.resolveMethod,
-                    file: agg.file,
-                    isAwait: agg.hasAwait,
-                    callCount: agg.callCount,
-                    callSites: agg.callSites.slice(0, 10), // 最多保留 10 个调用点
-                });
-                edges++;
-            }
-            // ── 数据流边 ──
-            for (const flow of dataFlowEdges) {
-                const fromId = this._extractEntityId(flow.from || '');
-                const toId = this._extractEntityId(flow.to || '');
-                this.#addEdge(fromId, 'method', toId, 'method', 'data_flow', {
-                    weight: 0.5,
-                    source: 'phase5-data-flow',
-                    flowType: flow.flowType || '',
-                    direction: flow.direction || '',
+            else {
+                aggregated.set(key, {
+                    callerId,
+                    calleeId,
+                    callType: edge.callType,
+                    resolveMethod: edge.resolveMethod,
+                    file: edge.file,
+                    hasAwait: edge.isAwait,
+                    callCount: 1,
+                    callSites: [{ line: edge.line, isAwait: edge.isAwait }],
                 });
-                edges++;
             }
-        });
-        run();
+        }
+        for (const agg of aggregated.values()) {
+            await this.#addEdge(agg.callerId, 'method', agg.calleeId, 'method', 'calls', {
+                weight: agg.resolveMethod === 'direct' ? 1.0 : 0.6,
+                source: 'phase5-call-graph',
+                callType: agg.callType,
+                resolveMethod: agg.resolveMethod,
+                file: agg.file,
+                isAwait: agg.hasAwait,
+                callCount: agg.callCount,
+                callSites: agg.callSites.slice(0, 10), // 最多保留 10 个调用点
+            });
+            edges++;
+        }
+        // ── 数据流边 ──
+        for (const flow of dataFlowEdges) {
+            const fromId = this._extractEntityId(flow.from || '');
+            const toId = this._extractEntityId(flow.to || '');
+            await this.#addEdge(fromId, 'method', toId, 'method', 'data_flow', {
+                weight: 0.5,
+                source: 'phase5-data-flow',
+                flowType: flow.flowType || '',
+                direction: flow.direction || '',
+            });
+            edges++;
+        }
         const result = { entitiesUpserted: entities, edgesCreated: edges, durationMs: Date.now() - t0 };
         this.log.info(`[CodeEntityGraph] Call graph: ${callEdges.length} call edges, ${dataFlowEdges.length} data flow edges, ${entities} method entities (${result.durationMs}ms)`);
         return result;
@@ -685,26 +651,29 @@ export class CodeEntityGraph {
      * @param methodId "ClassName.methodName" 或 FQN
      * @returns >}
      */
-    getCallers(methodId, maxDepth = 2) {
+    async getCallers(methodId, maxDepth = 2) {
         const results = [];
         const visited = new Set();
         const queue = [{ id: methodId, depth: 0 }];
         while (queue.length > 0) {
-            const { id, depth } = queue.shift();
+            const current = queue.shift();
+            if (!current) {
+                break;
+            }
+            const { id, depth } = current;
             if (depth >= maxDepth || visited.has(id)) {
                 continue;
             }
             visited.add(id);
-            const callers = this.stmts.getCallers.all(id);
-            for (const row of callers) {
-                const meta = JSON.parse(row.metadata_json || '{}');
+            const callers = await this.#edgeRepo.findIncomingByRelation(id, 'calls');
+            for (const edge of callers) {
                 results.push({
-                    caller: row.from_id,
+                    caller: edge.fromId,
                     depth: depth + 1,
-                    callType: meta.callType || 'unknown',
+                    callType: edge.metadata?.callType || 'unknown',
                 });
                 if (depth + 1 < maxDepth) {
-                    queue.push({ id: row.from_id, depth: depth + 1 });
+                    queue.push({ id: edge.fromId, depth: depth + 1 });
                 }
             }
         }
@@ -716,26 +685,29 @@ export class CodeEntityGraph {
      * @param methodId "ClassName.methodName" 或 FQN
      * @returns >}
      */
-    getCallees(methodId, maxDepth = 2) {
+    async getCallees(methodId, maxDepth = 2) {
         const results = [];
         const visited = new Set();
         const queue = [{ id: methodId, depth: 0 }];
         while (queue.length > 0) {
-            const { id, depth } = queue.shift();
+            const current = queue.shift();
+            if (!current) {
+                break;
+            }
+            const { id, depth } = current;
             if (depth >= maxDepth || visited.has(id)) {
                 continue;
             }
             visited.add(id);
-            const callees = this.stmts.getCallees.all(id);
-            for (const row of callees) {
-                const meta = JSON.parse(row.metadata_json || '{}');
+            const callees = await this.#edgeRepo.findOutgoingByRelation(id, 'calls');
+            for (const edge of callees) {
                 results.push({
-                    callee: row.to_id,
+                    callee: edge.toId,
                     depth: depth + 1,
-                    callType: meta.callType || 'unknown',
+                    callType: edge.metadata?.callType || 'unknown',
                 });
                 if (depth + 1 < maxDepth) {
-                    queue.push({ id: row.to_id, depth: depth + 1 });
+                    queue.push({ id: edge.toId, depth: depth + 1 });
                 }
             }
         }
@@ -748,11 +720,11 @@ export class CodeEntityGraph {
      * @param methodId "ClassName.methodName"
      * @returns }
      */
-    getCallImpactRadius(methodId) {
-        const callers = this.getCallers(methodId, 3);
+    async getCallImpactRadius(methodId) {
+        const callers = await this.getCallers(methodId, 3);
         const affectedFiles = new Set();
         for (const c of callers) {
-            const entity = this.getEntity(c.caller, 'method');
+            const entity = await this.getEntity(c.caller, 'method');
             if (entity?.filePath) {
                 affectedFiles.add(entity.filePath);
             }
@@ -776,15 +748,12 @@ export class CodeEntityGraph {
         return fqn;
     }
     /** 清除项目的所有代码实体 (重新 populate 前调用) */
-    clearProject() {
-        const run = this.db.transaction(() => {
-            this.stmts.clearEntities.run(this.projectRoot);
-            // 清除 AST 产出的边 + Phase 5 调用图边 (保留 recipe/module 边)
-            this.db
-                .prepare(`DELETE FROM knowledge_edges WHERE metadata_json LIKE '%ast-bootstrap%' OR metadata_json LIKE '%ast-pattern-detection%' OR metadata_json LIKE '%phase5-%'`)
-                .run();
-        });
-        run();
+    async clearProject() {
+        await this.#entityRepo.clearProject(this.projectRoot);
+        // 清除 AST 产出的边 + Phase 5 调用图边 (保留 recipe/module 边)
+        await this.#edgeRepo.deleteByMetadataLike('%ast-bootstrap%');
+        await this.#edgeRepo.deleteByMetadataLike('%ast-pattern-detection%');
+        await this.#edgeRepo.deleteByMetadataLike('%phase5-%');
         this.log.info(`[CodeEntityGraph] Cleared entities for project: ${this.projectRoot}`);
     }
     /**
@@ -793,104 +762,57 @@ export class CodeEntityGraph {
      * @param filePaths 变更文件的相对路径列表
      * @returns }
      */
-    clearCallGraphForFiles(filePaths) {
+    async clearCallGraphForFiles(filePaths) {
         if (!filePaths?.length) {
             return { deletedEdges: 0, deletedEntities: 0 };
         }
         let deletedEdges = 0;
         let deletedEntities = 0;
-        const run = this.db.transaction(() => {
-            // 1. 删除相关 call edges (metadata_json 包含 file 字段)
-            const deleteEdgesStmt = this.db.prepare(`DELETE FROM knowledge_edges 
-         WHERE metadata_json LIKE ? 
-         AND (relation = 'calls' OR relation = 'data_flow')
-         AND metadata_json LIKE '%phase5-%'`);
-            for (const filePath of filePaths) {
-                // 匹配 metadata 中 "file":"xxx" 字段
-                const result = deleteEdgesStmt.run(`%"file":"${filePath}"%`);
-                deletedEdges += result.changes;
-            }
-            // 2. 删除相关 method 实体
-            const deleteEntitiesStmt = this.db.prepare(`DELETE FROM code_entities 
-         WHERE file_path = ? AND entity_type = 'method' AND project_root = ?`);
-            for (const filePath of filePaths) {
-                const result = deleteEntitiesStmt.run(filePath, this.projectRoot);
-                deletedEntities += result.changes;
-            }
-        });
-        run();
+        // 1. 删除相关 call edges (metadata_json 包含 file 字段)
+        for (const filePath of filePaths) {
+            // 匹配 metadata 中 "file":"xxx" 字段
+            const changes = await this.#edgeRepo.deleteByMetadataLike(`%"file":"${filePath}"%`, [
+                'calls',
+                'data_flow',
+            ]);
+            deletedEdges += changes;
+        }
+        // 2. 删除相关 method 实体
+        for (const filePath of filePaths) {
+            const changes = await this.#entityRepo.deleteByFileAndType(filePath, 'method', this.projectRoot);
+            deletedEntities += changes;
+        }
         this.log.info(`[CodeEntityGraph] Incremental clear: ${deletedEdges} edges, ${deletedEntities} entities ` +
             `for ${filePaths.length} files`);
         return { deletedEdges, deletedEntities };
     }
     // ────────────────────────────────────────────
-    // Private — Schema & Statements
-    // ────────────────────────────────────────────
-    #ensureTable() {
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS code_entities (
-        id            INTEGER PRIMARY KEY AUTOINCREMENT,
-        entity_id     TEXT NOT NULL,
-        entity_type   TEXT NOT NULL,
-        project_root  TEXT NOT NULL,
-        name          TEXT NOT NULL,
-        file_path     TEXT,
-        line_number   INTEGER,
-        superclass    TEXT,
-        protocols     TEXT DEFAULT '[]',
-        metadata_json TEXT DEFAULT '{}',
-        created_at    INTEGER NOT NULL,
-        updated_at    INTEGER NOT NULL,
-        UNIQUE (entity_id, entity_type, project_root)
-      );
-      CREATE INDEX IF NOT EXISTS idx_ce_project    ON code_entities(project_root);
-      CREATE INDEX IF NOT EXISTS idx_ce_type       ON code_entities(entity_type);
-      CREATE INDEX IF NOT EXISTS idx_ce_name       ON code_entities(name);
-      CREATE INDEX IF NOT EXISTS idx_ce_file       ON code_entities(file_path);
-      CREATE INDEX IF NOT EXISTS idx_ce_superclass ON code_entities(superclass);
-    `);
-    }
-    #prepareStatements() {
-        this.stmts = {
-            upsert: this.db.prepare(`
-        INSERT INTO code_entities (entity_id, entity_type, project_root, name, file_path, line_number, superclass, protocols, metadata_json, created_at, updated_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        ON CONFLICT (entity_id, entity_type, project_root) DO UPDATE SET
-          name = excluded.name,
-          file_path = COALESCE(excluded.file_path, code_entities.file_path),
-          line_number = COALESCE(excluded.line_number, code_entities.line_number),
-          superclass = COALESCE(excluded.superclass, code_entities.superclass),
-          protocols = excluded.protocols,
-          metadata_json = excluded.metadata_json,
-          updated_at = excluded.updated_at
-      `),
-            getEntity: this.db.prepare(`SELECT * FROM code_entities WHERE entity_id = ? AND entity_type = ? AND project_root = ?`),
-            listByType: this.db.prepare(`SELECT * FROM code_entities WHERE entity_type = ? AND project_root = ? ORDER BY name LIMIT ?`),
-            clearEntities: this.db.prepare(`DELETE FROM code_entities WHERE project_root = ?`),
-            addEdge: this.db.prepare(`
-        INSERT OR REPLACE INTO knowledge_edges (from_id, from_type, to_id, to_type, relation, weight, metadata_json, created_at, updated_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `),
-            // Phase 5: 调用图查询 (pre-prepared 避免每次调用都创建)
-            getCallers: this.db.prepare(`SELECT from_id, from_type, metadata_json FROM knowledge_edges
-         WHERE to_id = ? AND relation = 'calls'`),
-            getCallees: this.db.prepare(`SELECT to_id, to_type, metadata_json FROM knowledge_edges
-         WHERE from_id = ? AND relation = 'calls'`),
-            getEdge: this.db.prepare(`SELECT metadata_json FROM knowledge_edges
-         WHERE from_id = ? AND from_type = ? AND to_id = ? AND to_type = ? AND relation = ?`),
-        };
-    }
-    // ────────────────────────────────────────────
     // Private — Helpers
     // ────────────────────────────────────────────
-    #upsertEntity(entity) {
-        const now = Math.floor(Date.now() / 1000);
-        this.stmts.upsert.run(entity.entityId, entity.entityType, this.projectRoot, entity.name, entity.filePath || null, entity.line || null, entity.superclass || null, JSON.stringify(entity.protocols || []), JSON.stringify(entity.metadata || {}), now, now);
+    async #upsertEntity(entity) {
+        await this.#entityRepo.upsert({
+            entityId: entity.entityId,
+            entityType: entity.entityType,
+            projectRoot: this.projectRoot,
+            name: entity.name,
+            filePath: entity.filePath ?? null,
+            lineNumber: entity.line ?? null,
+            superclass: entity.superclass ?? null,
+            protocols: entity.protocols ?? [],
+            metadata: entity.metadata ?? {},
+        });
     }
-    #addEdge(fromId, fromType, toId, toType, relation, metadata = {}) {
-        const now = Math.floor(Date.now() / 1000);
+    async #addEdge(fromId, fromType, toId, toType, relation, metadata = {}) {
         try {
-            this.stmts.addEdge.run(fromId, fromType, toId, toType, relation, metadata.weight || 1.0, JSON.stringify(metadata), now, now);
+            await this.#edgeRepo.upsertEdge({
+                fromId,
+                fromType,
+                toId,
+                toType,
+                relation,
+                weight: metadata.weight || 1.0,
+                metadata,
+            });
         }
         catch (err) {
             // Ignore duplicate edge errors
@@ -932,30 +854,30 @@ export class CodeEntityGraph {
         };
         return mapping[type] || 'related';
     }
-    #mapEdge(row) {
+    #mapRepoEdge(edge) {
         return {
-            fromId: row.from_id,
-            fromType: row.from_type,
-            toId: row.to_id,
-            toType: row.to_type,
-            relation: row.relation,
-            weight: row.weight,
-            metadata: JSON.parse(row.metadata_json || '{}'),
+            fromId: edge.fromId,
+            fromType: edge.fromType,
+            toId: edge.toId,
+            toType: edge.toType,
+            relation: edge.relation,
+            weight: edge.weight,
+            metadata: edge.metadata,
         };
     }
-    #mapEntity(row) {
+    #mapRepoEntity(entity) {
         return {
-            entityId: row.entity_id,
-            entityType: row.entity_type,
-            name: row.name,
-            filePath: row.file_path,
-            line: row.line_number,
-            superclass: row.superclass,
-            protocols: JSON.parse(row.protocols || '[]'),
-            metadata: JSON.parse(row.metadata_json || '{}'),
-            projectRoot: row.project_root,
-            createdAt: row.created_at,
-            updatedAt: row.updated_at,
+            entityId: entity.entityId,
+            entityType: entity.entityType,
+            name: entity.name,
+            filePath: entity.filePath,
+            line: entity.lineNumber,
+            superclass: entity.superclass,
+            protocols: entity.protocols,
+            metadata: entity.metadata,
+            projectRoot: entity.projectRoot,
+            createdAt: entity.createdAt,
+            updatedAt: entity.updatedAt,
         };
     }
 }