skill-any-code 1.0.0 → 1.0.1

package/dist/domain/services/analysis.service.js

@@ -0,0 +1,696 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalysisService = void 0;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const errors_1 = require("../../common/errors");
+const logger_1 = require("../../common/logger");
+const utils_1 = require("../../common/utils");
+const openai_client_1 = require("../../infrastructure/llm/openai.client");
+const llm_usage_tracker_1 = require("../../infrastructure/llm/llm.usage.tracker");
+const code_splitter_1 = require("../../infrastructure/splitter/code.splitter");
+const file_hash_cache_1 = require("../../infrastructure/cache/file.hash.cache");
+const llm_analysis_service_1 = require("../../application/services/llm.analysis.service");
+const worker_pool_service_1 = require("../../infrastructure/worker-pool/worker-pool.service");
+const os_1 = __importDefault(require("os"));
+class AnalysisService {
+    gitService;
+    storageService;
+    blacklistService;
+    projectSlug;
+    currentCommit;
+    llmConfig;
+    onTokenUsageSnapshot;
+    llmAnalysisService;
+    tracker;
+    constructor(gitService, storageService, blacklistService, projectSlug, currentCommit, llmConfig, onTokenUsageSnapshot) {
+        this.gitService = gitService;
+        this.storageService = storageService;
+        this.blacklistService = blacklistService;
+        this.projectSlug = projectSlug;
+        this.currentCommit = currentCommit;
+        this.llmConfig = llmConfig;
+        this.onTokenUsageSnapshot = onTokenUsageSnapshot;
+        this.tracker = new llm_usage_tracker_1.LLMUsageTracker(this.onTokenUsageSnapshot);
+        const llmClient = new openai_client_1.OpenAIClient(llmConfig, this.tracker);
+        const fileSplitter = new code_splitter_1.CodeSplitter(llmClient);
+        const homeDir = os_1.default.homedir();
+        const resolvedCacheDir = llmConfig.cache_dir.replace(/^~(?=\/|\\|$)/, homeDir);
+        const cache = new file_hash_cache_1.FileHashCache({
+            cacheDir: resolvedCacheDir,
+            maxSizeMb: llmConfig.cache_max_size_mb,
+        });
+        this.llmAnalysisService = new llm_analysis_service_1.LLMAnalysisService(llmClient, fileSplitter, cache, llmConfig);
+    }
+    getTokenUsage() {
+        return this.tracker.getStats();
+    }
+    /**
+     * 统计将参与解析的对象总数（文件+目录），用于进度条 total。
+     * 与 fullAnalysis 使用相同的深度与黑名单规则。
+     */
+    async countObjects(projectRoot, depth = -1) {
+        const rootStat = await fs.stat(projectRoot);
+        if (rootStat.isFile())
+            return 1;
+        let count = 0;
+        const walk = async (dirPath, currentDepth) => {
+            if (depth >= 1 && currentDepth > depth) {
+                return false;
+            }
+            const entries = await fs.readdir(dirPath, { withFileTypes: true });
+            const valid = entries.filter(entry => {
+                const fullPath = path.join(dirPath, entry.name);
+                const relativePath = path.relative(projectRoot, fullPath);
+                const key = entry.isDirectory() ? `${relativePath}/` : relativePath;
+                return !this.blacklistService.isIgnored(key);
+            });
+            let hasContent = false;
+            for (const entry of valid) {
+                if (entry.isFile()) {
+                    count++;
+                    hasContent = true;
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    const childHas = await walk(path.join(dirPath, entry.name), currentDepth + 1);
+                    if (childHas) {
+                        hasContent = true;
+                    }
+                }
+            }
+            if (hasContent) {
+                count++;
+            }
+            return hasContent;
+        };
+        await walk(projectRoot, 1);
+        return count;
+    }
+    // ---------------------------------------------------------------------------
+    // 私有工具方法
+    // ---------------------------------------------------------------------------
+    async getFileGitMeta(projectRoot, relPath) {
+        const hasGitMeta = typeof this.gitService.getFileLastCommit === 'function' &&
+            typeof this.gitService.isFileDirty === 'function';
+        const fileGitCommitId = hasGitMeta
+            ? await this.gitService.getFileLastCommit(projectRoot, relPath)
+            : null;
+        const isDirty = hasGitMeta
+            ? await this.gitService.isFileDirty(projectRoot, relPath)
+            : false;
+        return { fileGitCommitId, isDirty };
+    }
+    /**
+     * Phase 1：遍历目录树，构建完整的任务图。
+     * 全量和增量共享此扫描逻辑，黑名单和深度限制在此阶段统一应用。
+     */
+    async scanProjectTree(projectRoot, depth, onScanProgress) {
+        const depthEnabled = depth !== undefined && depth >= 1;
+        const maxDepth = depthEnabled ? depth : Number.POSITIVE_INFINITY;
+        const dirNodes = new Map();
+        const fileAbsByRel = new Map();
+        let scannedObjectCount = 0;
+        const rootRel = '.';
+        dirNodes.set(rootRel, {
+            absPath: projectRoot,
+            relPath: rootRel,
+            depth: 1,
+            childDirs: [],
+            childFiles: [],
+        });
+        const queue = [
+            { rel: rootRel, abs: projectRoot, depth: 1 },
+        ];
+        const scanConcurrency = Math.max(1, Math.min(8, os_1.default.cpus()?.length || 4));
+        const processDir = async (current) => {
+            const node = dirNodes.get(current.rel);
+            if (!node)
+                return;
+            if (current.depth > maxDepth)
+                return;
+            const entries = await fs.readdir(current.abs, { withFileTypes: true });
+            const validEntries = entries
+                .filter(entry => {
+                const fullPath = path.join(current.abs, entry.name);
+                const relativePath = path.relative(projectRoot, fullPath);
+                const key = entry.isDirectory() ? `${relativePath}/` : relativePath;
+                return !this.blacklistService.isIgnored(key);
+            })
+                .sort((a, b) => a.name.localeCompare(b.name));
+            for (const entry of validEntries) {
+                const fullPath = path.join(current.abs, entry.name);
+                const relPath = path.relative(projectRoot, fullPath) || entry.name;
+                if (entry.isFile()) {
+                    node.childFiles.push(relPath);
+                    fileAbsByRel.set(relPath, fullPath);
+                    scannedObjectCount++;
+                    if (scannedObjectCount % 10 === 0)
+                        onScanProgress?.(scannedObjectCount);
+                }
+                else if (entry.isDirectory()) {
+                    node.childDirs.push(relPath);
+                    const childDepth = current.depth + 1;
+                    dirNodes.set(relPath, {
+                        absPath: fullPath,
+                        relPath: relPath,
+                        depth: childDepth,
+                        childDirs: [],
+                        childFiles: [],
+                    });
+                    queue.push({ rel: relPath, abs: fullPath, depth: childDepth });
+                }
+            }
+        };
+        const runScanQueue = async () => {
+            const workers = Array.from({ length: scanConcurrency }, async () => {
+                // eslint-disable-next-line no-constant-condition
+                while (true) {
+                    const current = queue.shift();
+                    if (!current)
+                        return;
+                    await processDir(current);
+                }
+            });
+            await Promise.all(workers);
+        };
+        await runScanQueue();
+        // 目录剪枝：自底向上移除空目录
+        const allScannedDirs = Array.from(dirNodes.values());
+        const scannedDirsByDepthDesc = allScannedDirs
+            .slice()
+            .sort((a, b) => {
+            if (b.depth !== a.depth)
+                return b.depth - a.depth;
+            return a.relPath.localeCompare(b.relPath);
+        });
+        const keptDirs = new Set();
+        for (const d of scannedDirsByDepthDesc) {
+            const node = dirNodes.get(d.relPath);
+            if (!node)
+                continue;
+            node.childDirs = node.childDirs.filter(child => keptDirs.has(child));
+            const hasContent = node.childFiles.length > 0 || node.childDirs.length > 0;
+            if (hasContent) {
+                keptDirs.add(d.relPath);
+                scannedObjectCount++;
+                if (scannedObjectCount % 10 === 0)
+                    onScanProgress?.(scannedObjectCount);
+            }
+        }
+        if (scannedObjectCount > 0 && scannedObjectCount % 10 !== 0) {
+            onScanProgress?.(scannedObjectCount);
+        }
+        return { dirNodes, fileAbsByRel, keptDirs };
+    }
+    /**
+     * 增量专用：扫描存储目录，找出"有解析结果但对应源文件/目录已不存在"的孤立条目并清理。
+     */
+    async cleanOrphanedResults(storageRoot, projectRoot, currentFileRels, keptDirs, removedSourcePaths) {
+        logger_1.logger.info('Scanning storage directory for orphaned result files...');
+        // 构建当前源码树的预期结果路径集合
+        const expectedResultPaths = new Set();
+        for (const relPath of currentFileRels.keys()) {
+            expectedResultPaths.add(path.resolve((0, utils_1.getFileOutputPath)(storageRoot, relPath)));
+        }
+        for (const dirRel of keptDirs) {
+            expectedResultPaths.add(path.resolve((0, utils_1.getDirOutputPath)(storageRoot, dirRel)));
+        }
+        const orphaned = [];
+        const walk = async (dirAbs) => {
+            if (!(await fs.pathExists(dirAbs)))
+                return;
+            const entries = await fs.readdir(dirAbs, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dirAbs, entry.name);
+                if (entry.isDirectory()) {
+                    if (entry.name.startsWith('.'))
+                        continue;
+                    await walk(fullPath);
+                }
+                else if (entry.isFile() && entry.name.endsWith('.md')) {
+                    if (!expectedResultPaths.has(path.resolve(fullPath))) {
+                        orphaned.push(fullPath);
+                    }
+                }
+            }
+        };
+        await walk(storageRoot);
+        if (orphaned.length > 0) {
+            logger_1.logger.info(`Found ${orphaned.length} orphaned result file(s). Cleaning up...`);
+            for (const p of orphaned) {
+                try {
+                    const content = await fs.readFile(p, 'utf-8');
+                    const match = content.match(/(?:^|\n)-\s*(?:Path|路径)\s*[：:]\s*(.+)\s*$/m);
+                    const sourcePath = match?.[1]?.trim();
+                    if (sourcePath) {
+                        removedSourcePaths.push(path.resolve(projectRoot, sourcePath));
+                    }
+                }
+                catch { /* 无法读取则仅删除 */ }
+                await fs.remove(p);
+            }
+            // 自底向上清理因删除 .md 而变为空的存储子目录
+            const resolvedStorageRoot = path.resolve(storageRoot);
+            const removeEmptyDirs = async (dirAbs) => {
+                if (!(await fs.pathExists(dirAbs)))
+                    return true;
+                const entries = await fs.readdir(dirAbs, { withFileTypes: true });
+                for (const entry of entries) {
+                    const fullPath = path.join(dirAbs, entry.name);
+                    if (entry.isDirectory() && !entry.name.startsWith('.')) {
+                        await removeEmptyDirs(fullPath);
+                    }
+                }
+                // 重新读取：子目录可能刚被删除
+                const remaining = await fs.readdir(dirAbs);
+                if (remaining.length === 0 && path.resolve(dirAbs) !== resolvedStorageRoot) {
+                    await fs.remove(dirAbs);
+                    return true;
+                }
+                return false;
+            };
+            await removeEmptyDirs(storageRoot);
+        }
+        else {
+            logger_1.logger.info('No orphaned result files found');
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // 统一解析入口
+    // ---------------------------------------------------------------------------
+    async analyze(params) {
+        const startTime = Date.now();
+        const errors = [];
+        const completedFiles = [];
+        const completedDirs = [];
+        const indexEntries = [];
+        const removedSourcePaths = [];
+        const storageRoot = this.storageService.getStoragePath(this.projectSlug);
+        // --- 单文件特殊处理 ---
+        const rootStat = await fs.stat(params.projectRoot);
+        if (rootStat.isFile()) {
+            try {
+                const content = await fs.readFile(params.projectRoot, 'utf-8');
+                const fileHash = (0, crypto_1.createHash)('sha256').update(content).digest('hex');
+                const parseResult = await this.llmAnalysisService.analyzeFile(params.projectRoot, content, fileHash);
+                const relativePath = path.basename(params.projectRoot);
+                const fileResult = {
+                    ...parseResult,
+                    path: relativePath,
+                    commitHash: params.commitHash,
+                };
+                await this.storageService.saveFileAnalysis(this.projectSlug, relativePath, fileResult);
+                completedFiles.push(relativePath);
+                params.onTotalKnown?.(1);
+                params.onObjectPlanned?.({ type: 'file', path: relativePath });
+                params.onObjectCompleted?.({ type: 'file', path: relativePath }, { status: 'parsed' });
+                const sourceAbsPath = path.resolve(params.projectRoot);
+                const resultAbsPath = path.resolve(storageRoot, (0, utils_1.getFileOutputPath)(storageRoot, relativePath));
+                indexEntries.push({ sourcePath: sourceAbsPath, resultPath: resultAbsPath, type: 'file' });
+            }
+            catch (e) {
+                errors.push({ path: params.projectRoot, message: e.message });
+            }
+            return {
+                success: errors.length === 0,
+                analyzedFilesCount: completedFiles.length,
+                analyzedDirsCount: 0,
+                duration: Date.now() - startTime,
+                errors,
+                projectSlug: this.projectSlug,
+                summaryPath: path.join(storageRoot, 'index.md'),
+                indexEntries,
+                removedSourcePaths: [],
+            };
+        }
+        // ===================================================================
+        // Phase 1：统一遍历目录树
+        // ===================================================================
+        logger_1.logger.debug('Phase 1: scanning directory tree...');
+        const { dirNodes, fileAbsByRel, keptDirs } = await this.scanProjectTree(params.projectRoot, params.depth, params.onScanProgress);
+        logger_1.logger.debug(`Scan completed: ${fileAbsByRel.size} file(s), ${keptDirs.size} non-empty directory(ies)`);
+        // 清理被剪枝（空）目录的残留结果文件
+        for (const d of dirNodes.values()) {
+            if (!keptDirs.has(d.relPath) && d.relPath !== '.') {
+                const out = (0, utils_1.getDirOutputPath)(storageRoot, d.relPath);
+                if (await fs.pathExists(out)) {
+                    await fs.remove(out);
+                }
+            }
+        }
+        // ===================================================================
+        // Phase 2：应用文件过滤策略，构建文件任务队列
+        // ===================================================================
+        logger_1.logger.debug(`Phase 2: applying file filter (mode=${params.mode})...`);
+        const includedFiles = new Set();
+        const filterConcurrency = Math.max(1, Math.min(8, os_1.default.cpus()?.length || 4));
+        await (0, utils_1.mapLimit)(Array.from(fileAbsByRel.entries()), filterConcurrency, async ([relPath, absPath]) => {
+            if (await params.fileFilter(relPath, absPath)) {
+                includedFiles.add(relPath);
+            }
+        });
+        logger_1.logger.debug(`File filtering done: ${includedFiles.size}/${fileAbsByRel.size} file(s) queued`);
+        // ===================================================================
+        // Phase 2.5：增量模式 — 清理孤立的解析结果
+        // ===================================================================
+        if (params.mode === 'incremental') {
+            await this.cleanOrphanedResults(storageRoot, params.projectRoot, fileAbsByRel, keptDirs, removedSourcePaths);
+        }
+        // ===================================================================
+        // Phase 3：构建目录任务队列
+        //   规则：
+        //   - 至少有 1 个子项（文件或子目录）在任务队列中 → 目录进入队列
+        //   - 目录自身的结果 md 缺失 → 目录进入队列
+        //   - 自底向上传播：底层文件变更会驱动整条祖先链重新聚合
+        // ===================================================================
+        logger_1.logger.debug('Phase 3: building directory task queue...');
+        const includedDirs = new Set();
+        const allKeptDirsSorted = Array.from(dirNodes.values())
+            .filter(d => keptDirs.has(d.relPath))
+            .sort((a, b) => {
+            if (b.depth !== a.depth)
+                return b.depth - a.depth;
+            return a.relPath.localeCompare(b.relPath);
+        });
+        for (const dir of allKeptDirsSorted) {
+            let shouldInclude = dir.childFiles.some(f => includedFiles.has(f)) ||
+                dir.childDirs.some(d => includedDirs.has(d));
+            if (!shouldInclude) {
+                const dirMdPath = (0, utils_1.getDirOutputPath)(storageRoot, dir.relPath);
+                shouldInclude = !(await fs.pathExists(dirMdPath));
+            }
+            if (shouldInclude) {
+                includedDirs.add(dir.relPath);
+            }
+        }
+        logger_1.logger.debug(`Directory filtering done: ${includedDirs.size}/${keptDirs.size} directory(ies) queued`);
+        // ===================================================================
+        // Phase 4：排序 + 通知总数
+        // ===================================================================
+        const plannedFiles = Array.from(includedFiles).sort((a, b) => a.localeCompare(b));
+        const plannedDirs = allKeptDirsSorted
+            .filter(d => includedDirs.has(d.relPath))
+            .map(d => d.relPath);
+        const totalObjects = plannedFiles.length + plannedDirs.length;
+        params.onTotalKnown?.(totalObjects);
+        for (const f of plannedFiles) {
+            params.onObjectPlanned?.({ type: 'file', path: f });
+        }
+        for (const d of plannedDirs) {
+            params.onObjectPlanned?.({ type: 'directory', path: d });
+        }
+        if (totalObjects === 0) {
+            logger_1.logger.info('No objects to (re)analyze');
+            return {
+                success: true,
+                analyzedFilesCount: 0,
+                analyzedDirsCount: 0,
+                duration: Date.now() - startTime,
+                errors: [],
+                projectSlug: this.projectSlug,
+                summaryPath: path.join(storageRoot, 'index.md'),
+                indexEntries: [],
+                removedSourcePaths,
+            };
+        }
+        // ===================================================================
+        // Phase 5：统一执行管线 — 文件解析 + 目录聚合
+        // ===================================================================
+        const workerPool = new worker_pool_service_1.WorkerPoolService(this.llmConfig, params.concurrency);
+        const fileResults = new Map();
+        const dirResults = new Map();
+        try {
+            // --- 5a：文件解析 ---
+            await (0, utils_1.mapLimit)(plannedFiles, params.concurrency, async (relPath) => {
+                const fileObj = { type: 'file', path: relPath };
+                try {
+                    const absPath = fileAbsByRel.get(relPath);
+                    const content = await fs.readFile(absPath, 'utf-8');
+                    const fileHash = (0, crypto_1.createHash)('sha256').update(content).digest('hex');
+                    const { fileGitCommitId, isDirty } = await this.getFileGitMeta(params.projectRoot, relPath);
+                    params.onObjectStarted?.(fileObj);
+                    const workerRes = await workerPool.submitFileAnalysisTask(absPath, content, fileHash);
+                    const parseResult = workerRes?.analysis ?? workerRes;
+                    if (workerRes?.usage) {
+                        this.tracker.addTotals(workerRes.usage);
+                    }
+                    const fileResult = {
+                        ...parseResult,
+                        path: relPath,
+                        commitHash: params.commitHash,
+                        fileGitCommitId: fileGitCommitId ?? undefined,
+                        isDirtyWhenAnalyzed: isDirty,
+                        fileHashWhenAnalyzed: fileHash,
+                    };
+                    await this.storageService.saveFileAnalysis(this.projectSlug, relPath, fileResult);
+                    completedFiles.push(relPath);
+                    fileResults.set(relPath, fileResult);
+                    params.onObjectCompleted?.(fileObj, { status: 'parsed' });
+                    const sourceAbsPath = path.resolve(params.projectRoot, relPath);
+                    const resultAbsPath = path.resolve(storageRoot, (0, utils_1.getFileOutputPath)(storageRoot, relPath));
+                    indexEntries.push({ sourcePath: sourceAbsPath, resultPath: resultAbsPath, type: 'file' });
+                }
+                catch (e) {
+                    errors.push({ path: relPath, message: e.message });
+                    params.onObjectCompleted?.(fileObj, { status: 'failed', reason: e.message });
+                }
+            });
+            // --- 5b：目录聚合（叶子优先，按深度分组） ---
+            const dirsByDepth = new Map();
+            for (const dirRel of plannedDirs) {
+                const node = dirNodes.get(dirRel);
+                if (!node)
+                    continue;
+                const arr = dirsByDepth.get(node.depth) ?? [];
+                arr.push(dirRel);
+                dirsByDepth.set(node.depth, arr);
+            }
+            const sortedDepths = Array.from(dirsByDepth.keys()).sort((a, b) => b - a);
+            for (const depth of sortedDepths) {
+                const batch = dirsByDepth.get(depth);
+                await (0, utils_1.mapLimit)(batch, params.concurrency, async (dirRel) => {
+                    const dirObj = { type: 'directory', path: dirRel };
+                    const node = dirNodes.get(dirRel);
+                    if (!node) {
+                        params.onObjectCompleted?.(dirObj, { status: 'skipped', reason: 'dir node not found' });
+                        return;
+                    }
+                    // 收集子项结果：优先从内存 Map 读取（刚解析的），回退到存储层（未变更的）
+                    const childResults = [];
+                    for (const f of node.childFiles) {
+                        const fr = fileResults.get(f);
+                        if (fr) {
+                            childResults.push(fr);
+                        }
+                        else {
+                            const stored = await this.storageService.getFileAnalysis(this.projectSlug, f, 'summary');
+                            if (stored)
+                                childResults.push(stored);
+                        }
+                    }
+                    for (const d of node.childDirs) {
+                        const dr = dirResults.get(d);
+                        if (dr) {
+                            childResults.push(dr);
+                        }
+                        else {
+                            const stored = await this.storageService.getDirectoryAnalysis(this.projectSlug, d, 'summary');
+                            if (stored)
+                                childResults.push(stored);
+                        }
+                    }
+                    const fileChildren = childResults.filter(c => c.type === 'file');
+                    const dirChildren = childResults.filter(c => c.type === 'directory');
+                    if (fileChildren.length === 0 && dirChildren.length === 0) {
+                        const out = (0, utils_1.getDirOutputPath)(storageRoot, dirRel);
+                        if (await fs.pathExists(out)) {
+                            await fs.remove(out);
+                        }
+                        params.onObjectCompleted?.(dirObj, { status: 'skipped', reason: 'empty directory' });
+                        return;
+                    }
+                    const childrenDirsPayload = dirChildren.map(d => ({
+                        name: d.name,
+                        summary: d.summary,
+                        description: d.description,
+                    }));
+                    const childrenFilesPayload = fileChildren.map(f => ({
+                        name: f.name,
+                        summary: f.summary,
+                        description: f.description ?? f.summary,
+                    }));
+                    params.onObjectStarted?.(dirObj);
+                    let description = '';
+                    let summary = '';
+                    try {
+                        const llmRes = await workerPool.submitDirectoryAggregationTask(node.absPath, {
+                            childrenDirs: childrenDirsPayload,
+                            childrenFiles: childrenFilesPayload,
+                        });
+                        if (llmRes?.usage) {
+                            this.tracker.addTotals(llmRes.usage);
+                        }
+                        description = llmRes.description;
+                        summary = llmRes.summary;
+                    }
+                    catch (e) {
+                        const dirName = path.basename(dirRel);
+                        const fileCount = fileChildren.length;
+                        const dirCount = dirChildren.length;
+                        const fallback = `The "${dirName}" directory contains ${fileCount} file(s) and ${dirCount} subdirectory(ies) and helps organize related source code and modules.`;
+                        description = fallback;
+                        summary = fallback;
+                    }
+                    const dirResult = {
+                        type: 'directory',
+                        path: dirRel,
+                        name: path.basename(dirRel),
+                        description,
+                        summary,
+                        childrenDirsCount: dirChildren.length,
+                        childrenFilesCount: fileChildren.length,
+                        structure: childResults.map(child => ({
+                            name: child.name,
+                            type: child.type,
+                            description: child.summary,
+                        })),
+                        lastAnalyzedAt: new Date().toISOString(),
+                        commitHash: params.commitHash,
+                    };
+                    try {
+                        await this.storageService.saveDirectoryAnalysis(this.projectSlug, dirRel, dirResult);
+                        dirResults.set(dirRel, dirResult);
+                        completedDirs.push(dirRel);
+                        const dirSourceAbsPath = path.resolve(params.projectRoot, dirRel);
+                        const dirResultAbsPath = path.resolve(storageRoot, (0, utils_1.getDirOutputPath)(storageRoot, dirRel));
+                        indexEntries.push({ sourcePath: dirSourceAbsPath, resultPath: dirResultAbsPath, type: 'directory' });
+                        params.onObjectCompleted?.(dirObj, { status: 'parsed' });
+                    }
+                    catch (e) {
+                        const msg = e?.message ?? String(e);
+                        errors.push({ path: dirRel, message: msg });
+                        params.onObjectCompleted?.(dirObj, { status: 'failed', reason: msg });
+                        return;
+                    }
+                    // 内存回收：子项结果在上层目录仅需 summary/description，可安全释放
+                    for (const f of node.childFiles) {
+                        fileResults.delete(f);
+                    }
+                    for (const d of node.childDirs) {
+                        dirResults.delete(d);
+                    }
+                });
+            }
+        }
+        catch (e) {
+            if (typeof workerPool.terminate === 'function') {
+                await workerPool.terminate(true).catch(() => { });
+            }
+            else {
+                workerPool.cancelAll();
+            }
+            throw e;
+        }
+        finally {
+            if (typeof workerPool.terminate === 'function') {
+                await workerPool.terminate(true).catch(() => { });
+            }
+            else {
+                workerPool.cancelAll();
+            }
+        }
+        const duration = Date.now() - startTime;
+        const summaryPath = path.join(storageRoot, 'index.md');
+        return {
+            success: errors.length === 0,
+            analyzedFilesCount: completedFiles.length,
+            analyzedDirsCount: completedDirs.length,
+            duration,
+            errors,
+            projectSlug: this.projectSlug,
+            summaryPath,
+            indexEntries,
+            removedSourcePaths,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // 向后兼容包装
+    // ---------------------------------------------------------------------------
+    async fullAnalysis(params) {
+        return this.analyze({
+            projectRoot: params.projectRoot,
+            depth: params.depth,
+            concurrency: params.concurrency,
+            mode: 'full',
+            commitHash: this.currentCommit,
+            fileFilter: async () => true,
+            onObjectPlanned: params.onObjectPlanned,
+            onObjectStarted: params.onObjectStarted,
+            onObjectCompleted: params.onObjectCompleted,
+            onScanProgress: params.onScanProgress,
+        });
+    }
+    async incrementalAnalysis(params) {
+        const changedFilesSet = new Set(params.changedFiles || []);
+        const storageRoot = this.storageService.getStoragePath(this.projectSlug);
+        const fileFilter = async (relPath, _absPath) => {
+            if (changedFilesSet.has(relPath))
+                return true;
+            const resultPath = (0, utils_1.getFileOutputPath)(storageRoot, relPath);
+            return !(await fs.pathExists(resultPath));
+        };
+        return this.analyze({
+            projectRoot: params.projectRoot,
+            concurrency: params.concurrency,
+            mode: 'incremental',
+            commitHash: params.targetCommit,
+            fileFilter,
+            onObjectPlanned: params.onObjectPlanned,
+            onObjectStarted: params.onObjectStarted,
+            onObjectCompleted: params.onObjectCompleted,
+            onScanProgress: params.onScanProgress,
+        });
+    }
+    async resumeAnalysis(params) {
+        throw new errors_1.AppError(errors_1.ErrorCode.ANALYSIS_EXCEPTION, 'Resume/checkpoint feature is not implemented yet');
+    }
+}
+exports.AnalysisService = AnalysisService;