autosnippet 3.2.21 → 3.3.2

package/dist/lib/service/panorama/ModuleDiscoverer.js

@@ -0,0 +1,185 @@
+/**
+ * ModuleDiscoverer — 模块发现与文件归属
+ *
+ * 从 DB（code_entities / knowledge_edges）读取已扫描的模块数据。
+ * 前提：PanoramaScanner.ensureData() 保证 DB 中已有结构数据。
+ *
+ *   策略 1:   code_entities entity_type='module' + is_part_of 边 → 完整数据
+ *   策略 1.5: module 实体存在但无 is_part_of 边 → 文件系统 + DB 路径补全
+ *
+ * 若 DB 中无 module 实体，返回空数组（由 PanoramaScanner 负责兜底扫描）。
+ *
+ * @module ModuleDiscoverer
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { inferTargetRole } from '../../external/mcp/handlers/TargetClassifier.js';
+/* ═══ Constants ═══════════════════════════════════════════ */
+const SOURCE_EXTS = new Set([
+    '.swift',
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.m',
+    '.mm',
+    '.h',
+    '.c',
+    '.cpp',
+    '.kt',
+    '.java',
+    '.py',
+    '.rb',
+    '.go',
+    '.rs',
+]);
+const SKIP_DIRS = new Set([
+    '.git',
+    '.build',
+    '.autosnippet',
+    'node_modules',
+    'build',
+    'Pods',
+    'DerivedData',
+    '.swiftpm',
+    '__pycache__',
+    'dist',
+]);
+/* ═══ ModuleDiscoverer Class ══════════════════════════════ */
+export class ModuleDiscoverer {
+    #db;
+    #projectRoot;
+    constructor(db, projectRoot) {
+        this.#db = db;
+        this.#projectRoot = projectRoot;
+    }
+    /**
+     * 从 DB 中读取已扫描的模块数据。
+     * 若无 module 实体，返回空数组（让调用侧决定是否重新扫描）。
+     */
+    discover() {
+        // 从 code_entities 查 entity_type = 'module'
+        const moduleEntities = this.#db
+            .prepare(`SELECT DISTINCT entity_id, name FROM code_entities
+         WHERE entity_type = 'module' AND project_root = ?`)
+            .all(this.#projectRoot);
+        if (moduleEntities.length === 0) {
+            return [];
+        }
+        // 收集 is_part_of 边关联的文件
+        const moduleFiles = new Map();
+        for (const me of moduleEntities) {
+            const moduleName = me.entity_id;
+            moduleFiles.set(moduleName, new Set());
+            const parts = this.#db
+                .prepare(`SELECT ke.from_id FROM knowledge_edges ke
+           WHERE ke.to_id = ? AND ke.to_type = 'module' AND ke.relation = 'is_part_of'`)
+                .all(moduleName);
+            for (const part of parts) {
+                const entity = this.#db
+                    .prepare(`SELECT file_path FROM code_entities
+             WHERE entity_id = ? AND project_root = ? LIMIT 1`)
+                    .get(part.from_id, this.#projectRoot);
+                if (entity?.file_path) {
+                    moduleFiles.get(moduleName).add(entity.file_path);
+                }
+            }
+        }
+        // 策略 1.5: module 实体有但文件为空（SPM 只建了模块节点）
+        const totalFileCount = [...moduleFiles.values()].reduce((sum, s) => sum + s.size, 0);
+        if (totalFileCount === 0) {
+            this.#enrichModuleFiles(moduleFiles);
+        }
+        return [...moduleFiles.entries()].map(([name, files]) => ({
+            name,
+            inferredRole: inferTargetRole(name),
+            files: [...files],
+        }));
+    }
+    /* ─── 策略 1.5: 模块文件充填 ───────────────────── */
+    /**
+     * 为已知模块名填充文件路径：
+     *   a. 文件系统扫描（递归 4 层找模块同名目录）
+     *   b. DB code_entities.file_path 路径段匹配
+     */
+    #enrichModuleFiles(moduleFiles) {
+        const moduleNames = [...moduleFiles.keys()];
+        // a. 文件系统扫描
+        for (const modName of moduleNames) {
+            const dir = this.#findModuleDir(this.#projectRoot, modName, 4);
+            if (dir) {
+                for (const f of this.#collectSourceFiles(dir)) {
+                    moduleFiles.get(modName).add(f);
+                }
+            }
+        }
+        // b. 如果 FS 扫描仍为空 → DB 路径匹配
+        const totalAfterFs = [...moduleFiles.values()].reduce((sum, s) => sum + s.size, 0);
+        if (totalAfterFs > 0) {
+            return;
+        }
+        const allFiles = this.#db
+            .prepare(`SELECT DISTINCT file_path FROM code_entities
+         WHERE project_root = ? AND file_path IS NOT NULL AND entity_type != 'module'`)
+            .all(this.#projectRoot);
+        // 长名优先，避免短名误匹配
+        const sorted = [...moduleNames].sort((a, b) => b.length - a.length);
+        for (const row of allFiles) {
+            const filePath = row.file_path;
+            if (!filePath) {
+                continue;
+            }
+            for (const modName of sorted) {
+                if (filePath.includes(`/${modName}/`) || filePath.startsWith(`${modName}/`)) {
+                    moduleFiles.get(modName).add(filePath);
+                    break; // 一个文件只属于一个模块
+                }
+            }
+        }
+    }
+    /* ─── 文件系统辅助 ────────────────────────────── */
+    #findModuleDir(rootDir, targetName, maxDepth) {
+        if (maxDepth <= 0) {
+            return null;
+        }
+        try {
+            const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) {
+                    continue;
+                }
+                const fullPath = path.join(rootDir, entry.name);
+                if (entry.name === targetName) {
+                    return fullPath;
+                }
+                const found = this.#findModuleDir(fullPath, targetName, maxDepth - 1);
+                if (found) {
+                    return found;
+                }
+            }
+        }
+        catch {
+            // 无法读取目录
+        }
+        return null;
+    }
+    #collectSourceFiles(dir) {
+        const files = [];
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory() && !entry.name.startsWith('.') && !SKIP_DIRS.has(entry.name)) {
+                    files.push(...this.#collectSourceFiles(fullPath));
+                }
+                else if (entry.isFile() && SOURCE_EXTS.has(path.extname(entry.name).toLowerCase())) {
+                    files.push(fullPath);
+                }
+            }
+        }
+        catch {
+            // 无法读取
+        }
+        return files;
+    }
+}

package/dist/lib/service/panorama/PanoramaAggregator.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PanoramaAggregator — 全景数据汇总
+ *
+ * 编排 RoleRefiner → CouplingAnalyzer → LayerInferrer，
+ * 汇总为统一的 PanoramaResult，附加知识覆盖率和空白区检测。
+ *
+ * @module PanoramaAggregator
+ */
+import type { CouplingAnalyzer } from './CouplingAnalyzer.js';
+import { DimensionAnalyzer } from './DimensionAnalyzer.js';
+import type { LayerInferrer } from './LayerInferrer.js';
+import type { CeDbLike, PanoramaResult } from './PanoramaTypes.js';
+import type { ModuleCandidate, RoleRefiner } from './RoleRefiner.js';
+export interface PanoramaAggregatorOptions {
+    roleRefiner: RoleRefiner;
+    couplingAnalyzer: CouplingAnalyzer;
+    layerInferrer: LayerInferrer;
+    db: CeDbLike;
+    projectRoot: string;
+    dimensionAnalyzer?: DimensionAnalyzer;
+}
+export declare class PanoramaAggregator {
+    #private;
+    constructor(opts: PanoramaAggregatorOptions);
+    /**
+     * 计算完整全景数据
+     */
+    compute(moduleCandidates: ModuleCandidate[]): PanoramaResult;
+}

package/dist/lib/service/panorama/PanoramaAggregator.js

@@ -0,0 +1,228 @@
+/**
+ * PanoramaAggregator — 全景数据汇总
+ *
+ * 编排 RoleRefiner → CouplingAnalyzer → LayerInferrer，
+ * 汇总为统一的 PanoramaResult，附加知识覆盖率和空白区检测。
+ *
+ * @module PanoramaAggregator
+ */
+var _a;
+import { DimensionAnalyzer } from './DimensionAnalyzer.js';
+/* ═══ PanoramaAggregator Class ════════════════════════════ */
+export class PanoramaAggregator {
+    #roleRefiner;
+    #couplingAnalyzer;
+    #layerInferrer;
+    #db;
+    #projectRoot;
+    #dimensionAnalyzer;
+    constructor(opts) {
+        this.#roleRefiner = opts.roleRefiner;
+        this.#couplingAnalyzer = opts.couplingAnalyzer;
+        this.#layerInferrer = opts.layerInferrer;
+        this.#db = opts.db;
+        this.#projectRoot = opts.projectRoot;
+        this.#dimensionAnalyzer = opts.dimensionAnalyzer ?? new DimensionAnalyzer(opts.db);
+    }
+    /**
+     * 计算完整全景数据
+     */
+    compute(moduleCandidates) {
+        // 1. RoleRefiner: 精化角色
+        const refinedRoles = this.#roleRefiner.refineAll(moduleCandidates);
+        // 2. 构建模块-文件映射
+        const moduleFiles = new Map();
+        for (const mc of moduleCandidates) {
+            moduleFiles.set(mc.name, mc.files);
+        }
+        // 3. CouplingAnalyzer: 耦合分析
+        const coupling = this.#couplingAnalyzer.analyze(moduleFiles);
+        // 4. LayerInferrer: 层级推断
+        const modules = moduleCandidates.map((m) => m.name);
+        const layers = this.#layerInferrer.infer(coupling.edges, modules, coupling.cycles);
+        // 5. 构建层级映射 (模块名 → 层级号)
+        const moduleLayerMap = new Map();
+        for (const level of layers.levels) {
+            for (const mod of level.modules) {
+                moduleLayerMap.set(mod, level.level);
+            }
+        }
+        // 6. 项目级 recipe 总数（recipe scope 通常为 universal，不做模块强关联）
+        const projectRecipeCount = this.#getProjectRecipeCount();
+        // 7. 计算总文件数
+        let totalFiles = 0;
+        for (const mc of moduleCandidates) {
+            totalFiles += mc.files.length;
+        }
+        // 8. 汇总 PanoramaModule
+        // 模块 recipeCount 按文件数等比分配项目级 recipe（反映覆盖贡献度）
+        const panoramaModules = new Map();
+        for (const mc of moduleCandidates) {
+            const refined = refinedRoles.get(mc.name);
+            const metrics = coupling.metrics.get(mc.name);
+            const recipeCount = totalFiles > 0 ? Math.round((projectRecipeCount * mc.files.length) / totalFiles) : 0;
+            panoramaModules.set(mc.name, {
+                name: mc.name,
+                inferredRole: mc.inferredRole,
+                refinedRole: refined?.refinedRole ?? mc.inferredRole,
+                roleConfidence: refined?.confidence ?? 0,
+                layer: moduleLayerMap.get(mc.name) ?? 0,
+                fanIn: metrics?.fanIn ?? 0,
+                fanOut: metrics?.fanOut ?? 0,
+                files: mc.files,
+                fileCount: mc.files.length,
+                recipeCount,
+                coverageRatio: mc.files.length > 0 ? recipeCount / mc.files.length : 0,
+            });
+        }
+        // 8.5 基于模块角色重命名层级（比模块名 pattern 更准确）
+        this.#renameLayersByRole(layers, panoramaModules);
+        // 9. 多维度知识健康分析 (替代旧的基于模块文件数的覆盖率模型)
+        const moduleRoles = moduleCandidates.map((m) => {
+            const pm = panoramaModules.get(m.name);
+            return pm?.refinedRole ?? m.inferredRole;
+        });
+        const { radar, gaps } = this.#dimensionAnalyzer.analyze(moduleRoles);
+        // 10. 调用流概要
+        const callFlowSummary = this.#computeCallFlowSummary();
+        return {
+            modules: panoramaModules,
+            layers,
+            cycles: coupling.cycles,
+            gaps,
+            healthRadar: radar,
+            callFlowSummary,
+            projectRecipeCount,
+            computedAt: Date.now(),
+        };
+    }
+    /* ─── Project Recipe Count ──────────────────────── */
+    #getProjectRecipeCount() {
+        try {
+            const row = this.#db
+                .prepare(`SELECT COUNT(*) as cnt FROM knowledge_entries WHERE lifecycle IN ('active', 'pending')`)
+                .get();
+            return Number(row?.cnt ?? 0);
+        }
+        catch {
+            return 0;
+        }
+    }
+    /* ─── Layer Naming (role-based) ─────────────────── */
+    /** 角色 → 层级名映射 */
+    static #ROLE_TO_LAYER = {
+        core: 'Foundation',
+        foundation: 'Foundation',
+        model: 'Model',
+        service: 'Service',
+        networking: 'Infrastructure',
+        storage: 'Infrastructure',
+        ui: 'UI',
+        feature: 'Feature',
+        config: 'Configuration',
+        test: 'Test',
+        app: 'Application',
+    };
+    /**
+     * 基于模块 refinedRole 投票重命名层级
+     * 比模块名 pattern 匹配更准确（避免 BDUIKit 被误匹配为 Foundation 等问题）
+     */
+    #renameLayersByRole(layers, panoramaModules) {
+        const usedNames = new Set();
+        const maxLevel = Math.max(...layers.levels.map((l) => l.level), 0);
+        for (const level of layers.levels) {
+            // 只统计有文件的模块（排除 0 文件的第三方依赖干扰）
+            const roleVotes = new Map();
+            for (const modName of level.modules) {
+                const mod = panoramaModules.get(modName);
+                if (mod && mod.fileCount > 0) {
+                    const role = mod.refinedRole || mod.inferredRole;
+                    roleVotes.set(role, (roleVotes.get(role) ?? 0) + 1);
+                }
+            }
+            let layerName;
+            if (roleVotes.size === 0) {
+                // 全部是 0 文件模块 → 用位置推断
+                layerName =
+                    level.level === 0 ? 'Foundation' : level.level === maxLevel ? 'Application' : 'Feature';
+            }
+            else {
+                // 选最高票角色
+                let bestRole = '';
+                let bestCount = 0;
+                for (const [role, count] of roleVotes) {
+                    if (count > bestCount) {
+                        bestRole = role;
+                        bestCount = count;
+                    }
+                }
+                layerName = _a.#ROLE_TO_LAYER[bestRole] ?? 'Feature';
+                // 位置修正：最底层优先 Foundation，最顶层优先 Application
+                if (level.level === 0 && roleVotes.has('core')) {
+                    layerName = 'Foundation';
+                }
+                else if (level.level === maxLevel && layers.levels.length > 1) {
+                    layerName = 'Application';
+                }
+            }
+            // 去重：已使用的名称追加 level 号
+            if (usedNames.has(layerName)) {
+                layerName = `${layerName} ${level.level}`;
+            }
+            usedNames.add(layerName);
+            level.name = layerName;
+        }
+    }
+    /* ─── Call Flow Summary ─────────────────────────── */
+    #computeCallFlowSummary() {
+        // 最频繁被调用的方法
+        const topCalled = 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 10`)
+            .all();
+        // 入口点: 只有出度没有入度的方法
+        const entryPoints = this.#db
+            .prepare(`SELECT DISTINCT ke.from_id
+         FROM knowledge_edges ke
+         WHERE ke.relation = 'calls'
+         AND ke.from_id NOT IN (
+           SELECT to_id FROM knowledge_edges WHERE relation = 'calls'
+         )
+         LIMIT 20`)
+            .all();
+        // 数据生产者: data_flow outFlow >> inFlow
+        const dataProducers = this.#db
+            .prepare(`SELECT from_id, COUNT(*) as out_cnt
+         FROM knowledge_edges
+         WHERE relation = 'data_flow'
+         GROUP BY from_id
+         HAVING out_cnt > 3
+         ORDER BY out_cnt DESC
+         LIMIT 10`)
+            .all();
+        // 数据消费者: data_flow inFlow >> outFlow
+        const dataConsumers = this.#db
+            .prepare(`SELECT to_id, COUNT(*) as in_cnt
+         FROM knowledge_edges
+         WHERE relation = 'data_flow'
+         GROUP BY to_id
+         HAVING in_cnt > 3
+         ORDER BY in_cnt DESC
+         LIMIT 10`)
+            .all();
+        return {
+            topCalledMethods: topCalled.map((r) => ({
+                id: r.to_id,
+                callCount: Number(r.call_count),
+            })),
+            entryPoints: entryPoints.map((r) => r.from_id),
+            dataProducers: dataProducers.map((r) => r.from_id),
+            dataConsumers: dataConsumers.map((r) => r.to_id),
+        };
+    }
+}
+_a = PanoramaAggregator;

package/dist/lib/service/panorama/PanoramaScanner.d.ts

@@ -0,0 +1,52 @@
+/**
+ * PanoramaScanner — 全景数据内置扫描器
+ *
+ * 在全景数据缺失时自动运行轻量级结构扫描（Phase 1→2.1），
+ * 填充 code_entities + knowledge_edges，使 PanoramaService 能产生有效数据。
+ *
+ * 非 MCP 操作，而是 PanoramaService 的内置依赖。
+ * 调用时机：
+ *   - PanoramaService 发现 DB 中无 code_entities 时自动触发
+ *   - 手动调用 invalidate + getResult 时检查并补充
+ *
+ * @module PanoramaScanner
+ */
+export interface PanoramaScannerOptions {
+    projectRoot: string;
+    container: ScannerContainer;
+    logger?: ScannerLogger;
+}
+export interface ScannerContainer {
+    get(name: string): any;
+}
+export interface ScannerLogger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+}
+export interface ScanResult {
+    entities: number;
+    edges: number;
+    modules: number;
+    durationMs: number;
+}
+export declare class PanoramaScanner {
+    #private;
+    constructor(opts: PanoramaScannerOptions);
+    /**
+     * 检测 DB 中是否已有该项目的 code_entities 数据
+     */
+    hasData(): boolean;
+    /**
+     * 确保全景数据存在。无数据时自动执行扫描。
+     * 幂等：扫描过一次后不再重复（重启进程或手动 reset 可重新触发）。
+     */
+    ensureData(): Promise<ScanResult | null>;
+    /**
+     * 执行完整扫描（强制，不检查缓存）
+     */
+    scan(): Promise<ScanResult>;
+    /**
+     * 重置扫描状态（允许下次 ensureData 重新扫描）
+     */
+    reset(): void;
+}

package/dist/lib/service/panorama/PanoramaScanner.js

@@ -0,0 +1,188 @@
+/**
+ * PanoramaScanner — 全景数据内置扫描器
+ *
+ * 在全景数据缺失时自动运行轻量级结构扫描（Phase 1→2.1），
+ * 填充 code_entities + knowledge_edges，使 PanoramaService 能产生有效数据。
+ *
+ * 非 MCP 操作，而是 PanoramaService 的内置依赖。
+ * 调用时机：
+ *   - PanoramaService 发现 DB 中无 code_entities 时自动触发
+ *   - 手动调用 invalidate + getResult 时检查并补充
+ *
+ * @module PanoramaScanner
+ */
+/* ═══ Silent Logger (fallback) ════════════════════════════ */
+const SILENT_LOGGER = {
+    info() { },
+    warn() { },
+};
+/* ═══ PanoramaScanner Class ═══════════════════════════════ */
+export class PanoramaScanner {
+    #projectRoot;
+    #container;
+    #logger;
+    #hasScanned = false;
+    constructor(opts) {
+        this.#projectRoot = opts.projectRoot;
+        this.#container = opts.container;
+        this.#logger = opts.logger ?? SILENT_LOGGER;
+    }
+    /**
+     * 检测 DB 中是否已有该项目的 code_entities 数据
+     */
+    hasData() {
+        try {
+            const db = this.#container.get('database');
+            const rawDb = db?.getDb ? db.getDb() : db;
+            if (!rawDb?.prepare) {
+                return false;
+            }
+            const row = rawDb
+                .prepare(`SELECT COUNT(*) as cnt FROM code_entities WHERE project_root = ?`)
+                .get(this.#projectRoot);
+            return (row?.cnt ?? 0) > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 确保全景数据存在。无数据时自动执行扫描。
+     * 幂等：扫描过一次后不再重复（重启进程或手动 reset 可重新触发）。
+     */
+    async ensureData() {
+        if (this.#hasScanned || this.hasData()) {
+            return null;
+        }
+        return this.scan();
+    }
+    /**
+     * 执行完整扫描（强制，不检查缓存）
+     */
+    async scan() {
+        const t0 = Date.now();
+        this.#logger.info('[PanoramaScanner] Starting structure scan...');
+        let entities = 0;
+        let edges = 0;
+        let modules = 0;
+        try {
+            const { runPhase1_FileCollection, runPhase1_5_AstAnalysis, runPhase1_6_EntityGraph, runPhase1_7_CallGraph, runPhase2_DependencyGraph, runPhase2_1_ModuleEntities, } = await import('../../external/mcp/handlers/bootstrap/shared/bootstrap-phases.js');
+            // Phase 1: 文件收集
+            const phase1 = await runPhase1_FileCollection(this.#projectRoot, this.#logger, {
+                maxFiles: 500,
+            });
+            if (!phase1.allFiles?.length) {
+                this.#logger.warn('[PanoramaScanner] No files found, skipping scan');
+                this.#hasScanned = true;
+                return { entities: 0, edges: 0, modules: 0, durationMs: Date.now() - t0 };
+            }
+            // Phase 1.5: AST 分析
+            const phase1_5 = await runPhase1_5_AstAnalysis(phase1.allFiles, phase1.langStats, this.#logger);
+            // Phase 1.6: Entity Graph 写入
+            if (phase1_5.astProjectSummary) {
+                const phase1_6 = await runPhase1_6_EntityGraph(phase1_5.astProjectSummary, this.#projectRoot, this.#container, this.#logger);
+                entities = phase1_6.codeEntityResult?.entitiesUpserted ?? 0;
+                edges = phase1_6.codeEntityResult?.edgesCreated ?? 0;
+            }
+            // Phase 1.7: Call Graph (增强耦合准确度)
+            if (phase1_5.astProjectSummary) {
+                try {
+                    await runPhase1_7_CallGraph(phase1_5.astProjectSummary, this.#projectRoot, this.#container, this.#logger);
+                }
+                catch {
+                    // Call graph 失败不阻塞
+                }
+            }
+            // Phase 2: 依赖图
+            if (phase1.discoverer) {
+                const phase2 = await runPhase2_DependencyGraph(phase1.discoverer, this.#container, this.#logger);
+                edges += phase2.depEdgesWritten;
+                // Phase 2.1: Module 实体
+                if (phase2.depGraphData) {
+                    await runPhase2_1_ModuleEntities(phase2.depGraphData, this.#projectRoot, this.#container, this.#logger);
+                    modules = phase2.depGraphData.nodes?.length ?? 0;
+                }
+            }
+            // Phase 2.2: 目录推断兜底
+            // 当 Phase 2.1 未产出 module 实体时（无 Package.swift / build.gradle 等），
+            // 从已有 code_entities 按顶层目录分组写入 module 实体
+            if (modules === 0 && entities > 0) {
+                modules = this.#inferModulesFromDirectories();
+            }
+        }
+        catch (err) {
+            this.#logger.warn(`[PanoramaScanner] Scan failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        this.#hasScanned = true;
+        const durationMs = Date.now() - t0;
+        this.#logger.info(`[PanoramaScanner] Scan complete: ${entities} entities, ${edges} edges, ${modules} modules (${durationMs}ms)`);
+        return { entities, edges, modules, durationMs };
+    }
+    /**
+     * 重置扫描状态（允许下次 ensureData 重新扫描）
+     */
+    reset() {
+        this.#hasScanned = false;
+    }
+    /* ─── 目录推断兜底 ─────────────────────────────── */
+    /**
+     * 从 code_entities 中按顶层目录分组写入 module 实体 + is_part_of 边。
+     * 仅在 Phase 2.1 未产出 module 时调用。
+     */
+    #inferModulesFromDirectories() {
+        try {
+            const db = this.#container.get('database');
+            const rawDb = db?.getDb ? db.getDb() : db;
+            if (!rawDb?.prepare) {
+                return 0;
+            }
+            // 查询所有非 module 实体的文件路径
+            const rows = rawDb
+                .prepare(`SELECT DISTINCT entity_id, file_path FROM code_entities
+           WHERE project_root = ? AND file_path IS NOT NULL AND entity_type != 'module'`)
+                .all(this.#projectRoot);
+            if (rows.length === 0) {
+                return 0;
+            }
+            // 按顶层目录分组
+            const groups = new Map();
+            for (const row of rows) {
+                const filePath = row.file_path;
+                if (!filePath) {
+                    continue;
+                }
+                const relative = filePath.startsWith(this.#projectRoot)
+                    ? filePath.slice(this.#projectRoot.length).replace(/^\//, '')
+                    : filePath;
+                const firstDir = relative.split('/')[0];
+                if (!firstDir || firstDir.startsWith('.')) {
+                    continue;
+                }
+                if (!groups.has(firstDir)) {
+                    groups.set(firstDir, []);
+                }
+                groups.get(firstDir).push(row.entity_id);
+            }
+            if (groups.size === 0) {
+                return 0;
+            }
+            // 写入 module 实体 + is_part_of 边
+            const insertEntity = rawDb.prepare(`INSERT OR IGNORE INTO code_entities (entity_id, name, entity_type, file_path, project_root)
+         VALUES (?, ?, 'module', NULL, ?)`);
+            const insertEdge = rawDb.prepare(`INSERT OR IGNORE INTO knowledge_edges (from_id, from_type, to_id, to_type, relation, weight)
+         VALUES (?, 'entity', ?, 'module', 'is_part_of', 1.0)`);
+            for (const [dirName, entityIds] of groups) {
+                insertEntity.run(dirName, dirName, this.#projectRoot);
+                for (const entityId of entityIds) {
+                    insertEdge.run(entityId, dirName);
+                }
+            }
+            this.#logger.info(`[PanoramaScanner] Directory fallback: inferred ${groups.size} modules from top-level dirs`);
+            return groups.size;
+        }
+        catch (err) {
+            this.#logger.warn(`[PanoramaScanner] Directory fallback failed: ${err instanceof Error ? err.message : String(err)}`);
+            return 0;
+        }
+    }
+}