autosnippet 3.3.4 → 3.3.6

package/dist/lib/external/mcp/handlers/rescan-external.js

@@ -0,0 +1,335 @@
+/**
+ * MCP Handler — autosnippet_rescan (增量知识更新)
+ *
+ * 保留已审核 Recipe，清理衍生缓存，全量/指定维度重新扫描，
+ * 新知识通过批量提交走正常的进化架构。
+ *
+ * 流程:
+ *   1. snapshotRecipes — 快照保留知识
+ *   2. rescanClean — 清理衍生缓存
+ *   3. Phase 1-4 全量分析
+ *   4. RecipeRelevanceAuditor — 证据验证 + 快速衰退
+ *   5. 构建 Mission Briefing（含 allRecipes + evolutionGuide）
+ *   6. 返回给 Agent 按维度执行: evolve → gap-fill → dimension_complete
+ *
+ * @module handlers/rescan-external
+ */
+import path from 'node:path';
+import { CleanupService } from '#service/cleanup/CleanupService.js';
+import { RecipeRelevanceAuditor } from '#service/evolution/RecipeRelevanceAuditor.js';
+import { resolveProjectRoot } from '#shared/resolveProjectRoot.js';
+import { buildProjectSnapshot } from '#types/project-snapshot-builder.js';
+import { toSessionCache } from '#types/snapshot-views.js';
+import { envelope } from '../envelope.js';
+import { buildMissionBriefing } from './bootstrap/MissionBriefingBuilder.js';
+import { extractCodeEntities, extractDependencyEdges } from './bootstrap/shared/audit-helpers.js';
+import { runAllPhases } from './bootstrap/shared/bootstrap-phases.js';
+import { getOrCreateSessionManager } from './bootstrap/shared/session-helpers.js';
+import { buildLanguageExtension } from './LanguageExtensions.js';
+// ── Helpers ─────────────────────────────────────────────────
+function truncate(s, max) {
+    if (!s) {
+        return '';
+    }
+    return s.length <= max ? s : `${s.slice(0, max)}…`;
+}
+// ── 主入口 ─────────────────────────────────────────────────
+export async function rescanExternal(ctx, args) {
+    const t0 = Date.now();
+    const projectRoot = resolveProjectRoot(ctx.container);
+    const db = ctx.container.get('database');
+    // ═══════════════════════════════════════════════════════════
+    // Step 1: 快照现有知识
+    // ═══════════════════════════════════════════════════════════
+    const cleanupService = new CleanupService({
+        projectRoot,
+        db,
+        logger: ctx.logger,
+    });
+    const recipeSnapshot = await cleanupService.snapshotRecipes();
+    ctx.logger.info(`[Rescan] Preserved ${recipeSnapshot.count} recipes`, {
+        coverageByDimension: recipeSnapshot.coverageByDimension,
+    });
+    // ═══════════════════════════════════════════════════════════
+    // Step 2: 清理衍生缓存
+    // ═══════════════════════════════════════════════════════════
+    const cleanResult = await cleanupService.rescanClean();
+    // ═══════════════════════════════════════════════════════════
+    // Step 2.5: Recipe 文件 ↔ DB 一致性恢复 + 向量索引重建
+    // ═══════════════════════════════════════════════════════════
+    // 2.5a: KnowledgeSyncService — 恢复 Recipe 文件 ↔ DB 一致性
+    //   rescanClean 保留了 recipes/ 文件和 active/published/staging/evolving DB 记录，
+    //   但清除了 recipe_source_refs 等桥接表，需重新同步。
+    try {
+        const syncService = ctx.container.services.knowledgeSyncService
+            ? ctx.container.get('knowledgeSyncService')
+            : null;
+        if (syncService) {
+            const rawDb = typeof db?.getDb === 'function'
+                ? db.getDb()
+                : db;
+            const syncReport = syncService.sync(rawDb, {
+                force: true,
+            });
+            ctx.logger.info('[Rescan] KnowledgeSyncService sync complete', {
+                synced: syncReport.synced,
+                created: syncReport.created,
+                updated: syncReport.updated,
+            });
+        }
+    }
+    catch (e) {
+        ctx.logger.warn(`[Rescan] KnowledgeSyncService sync failed (non-blocking): ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // NOTE: 不在 rescan 中调用 VectorService.fullBuild()
+    // 理由：fullBuild 依赖外部 embedding API（LLM），在 MCP handler 同步路径中
+    // 引入 LLM 调用不合理（无超时、可能阻塞、需要 API key）。
+    // 向量索引会在后续 Agent 提交新知识时由 SyncCoordinator 增量更新。
+    // ═══════════════════════════════════════════════════════════
+    // Step 3: Phase 1-4 全量分析
+    // ═══════════════════════════════════════════════════════════
+    const phaseResults = await runAllPhases(projectRoot, ctx, {
+        maxFiles: 500,
+        contentMaxLines: 120,
+        sourceTag: 'rescan-external',
+        summaryPrefix: 'Rescan scan',
+        clearOldData: false, // 已由 rescanClean 清理
+        generateReport: true,
+        incremental: false,
+    });
+    // 空项目 fast-path
+    if (phaseResults.isEmpty) {
+        return envelope({
+            success: true,
+            data: { message: 'No source files found. Nothing to rescan.' },
+            meta: { tool: 'autosnippet_rescan', responseTimeMs: Date.now() - t0 },
+        });
+    }
+    const { allFiles, primaryLang, depGraphData, langStats, astProjectSummary, codeEntityResult, callGraphResult, guardAudit, activeDimensions: allDimensions, targetsSummary, localPackageModules, langProfile, } = phaseResults;
+    // ── Build immutable ProjectSnapshot ──
+    const snapshot = buildProjectSnapshot({
+        projectRoot,
+        sourceTag: 'rescan-external',
+        ...phaseResults,
+        report: phaseResults.report,
+    });
+    // ═══════════════════════════════════════════════════════════
+    // Step 4: Recipe 证据验证 + 快速衰退
+    // ═══════════════════════════════════════════════════════════
+    const auditor = new RecipeRelevanceAuditor({
+        db,
+        logger: ctx.logger,
+    });
+    const codeEntities = extractCodeEntities(astProjectSummary);
+    const dependencyEdges = extractDependencyEdges(depGraphData);
+    const auditSummary = await auditor.audit(recipeSnapshot.entries, {
+        fileList: allFiles.map((f) => f.relativePath || f.name),
+        codeEntities,
+        dependencyGraph: dependencyEdges,
+    });
+    // ═══════════════════════════════════════════════════════════
+    // Step 5: 构建 Mission Briefing + 过滤维度
+    // ═══════════════════════════════════════════════════════════
+    // 按需过滤维度
+    const dimensions = args.dimensions?.length
+        ? allDimensions.filter((d) => args.dimensions.includes(d.id))
+        : allDimensions;
+    // 创建 Session
+    const sessionManager = getOrCreateSessionManager(ctx.container);
+    const session = sessionManager.createSession({
+        projectRoot,
+        dimensions,
+        projectContext: {
+            projectName: path.basename(projectRoot),
+            primaryLang,
+            fileCount: allFiles.length,
+            modules: depGraphData?.nodes?.length || 0,
+        },
+    });
+    // 缓存 Phase 结果
+    session.setSnapshotCache(toSessionCache(snapshot));
+    // 构建 projectMeta
+    const projectMeta = {
+        name: path.basename(projectRoot),
+        primaryLanguage: primaryLang,
+        secondaryLanguages: langProfile.secondary || [],
+        isMultiLang: langProfile.isMultiLang || false,
+        fileCount: allFiles.length,
+        projectType: snapshot.discoverer.id,
+        projectRoot,
+    };
+    // 构建 Mission Briefing
+    const briefing = buildMissionBriefing({
+        projectMeta,
+        astData: astProjectSummary,
+        codeEntityResult,
+        callGraphResult,
+        depGraphData,
+        guardAudit,
+        targets: targetsSummary,
+        activeDimensions: dimensions,
+        session,
+        languageExtension: buildLanguageExtension(primaryLang),
+        languageStats: langStats,
+        panoramaResult: snapshot.panorama,
+        localPackageModules,
+    });
+    // 附加 warnings
+    if (phaseResults.warnings.length > 0) {
+        briefing.meta = briefing.meta || {};
+        briefing.meta.warnings = [...(briefing.meta.warnings || []), ...phaseResults.warnings];
+    }
+    // ═══════════════════════════════════════════════════════════
+    // Step 6: 注入 evidenceHints (含 trigger/维度/doClause)
+    // ═══════════════════════════════════════════════════════════
+    // 建立 recipeId → snapshot entry 映射，用于补充 audit 结果中缺少的字段
+    const snapshotById = new Map(recipeSnapshot.entries.map((e) => [e.id, e]));
+    // ── 构建 allRecipes: 全部 Recipe (healthy + decaying) 含完整内容 + auditHint ──
+    const allRecipes = auditSummary.results
+        .filter((r) => r.verdict !== 'dead') // dead 已直接 deprecated
+        .map((r) => {
+        const snap = snapshotById.get(r.recipeId);
+        const content = snap?.content;
+        const sourceRefs = (snap?.sourceRefs ?? []);
+        return {
+            id: r.recipeId,
+            title: r.title,
+            trigger: snap?.trigger || '',
+            knowledgeType: snap?.knowledgeType || '',
+            doClause: snap?.doClause || '',
+            lifecycle: snap?.lifecycle || 'active',
+            // 完整内容（截断控制）
+            content: content
+                ? {
+                    markdown: truncate(content.markdown, 500),
+                    rationale: truncate(content.rationale, 200),
+                    coreCode: truncate(content.coreCode, 400),
+                }
+                : null,
+            sourceRefs: sourceRefs.slice(0, 5),
+            // 系统预检
+            auditHint: {
+                relevanceScore: r.relevanceScore,
+                verdict: r.verdict,
+                decayReasons: r.decayReasons || [],
+            },
+        };
+    });
+    const decayCount = allRecipes.filter((r) => r.auditHint.verdict === 'decay' || r.auditHint.verdict === 'severe').length;
+    // ── 按维度分组现有 recipes，计算每维度的补齐配额 ──
+    // 覆盖采用加权策略：
+    //   - active/evolving: 确认知识，始终计入覆盖
+    //   - staging + audit healthy/watch: 待审但仍有效的候选，计入覆盖
+    //   - staging + audit decay/severe/dead: 已过时的候选，不计入覆盖但占位去重
+    const TARGET_PER_DIM = 5;
+    const auditVerdictMap = new Map(auditSummary.results.map((r) => [r.recipeId, r.verdict]));
+    const coverageByDim = {};
+    for (const entry of recipeSnapshot.entries) {
+        const dim = entry.knowledgeType || 'unknown';
+        const isConfirmed = entry.lifecycle === 'active' || entry.lifecycle === 'evolving';
+        const verdict = auditVerdictMap.get(entry.id);
+        // staging 条目：无 audit 结果时默认计入（首次冷启动后无 audit 数据），audit 通过时计入
+        const isHealthyStaging = entry.lifecycle === 'staging' && (!verdict || verdict === 'healthy' || verdict === 'watch');
+        if (isConfirmed || isHealthyStaging) {
+            if (!coverageByDim[dim]) {
+                coverageByDim[dim] = [];
+            }
+            coverageByDim[dim].push({
+                title: entry.title,
+                trigger: entry.trigger,
+                doClause: entry.doClause || '',
+            });
+        }
+    }
+    const dimensionGaps = dimensions.map((d) => {
+        const existing = coverageByDim[d.id] || [];
+        return {
+            dimensionId: d.id,
+            existingCount: existing.length,
+            gap: Math.max(0, TARGET_PER_DIM - existing.length),
+            existingTriggers: existing.map((e) => e.trigger).filter(Boolean),
+        };
+    });
+    const totalGap = dimensionGaps.reduce((sum, g) => sum + g.gap, 0);
+    // occupiedTriggers 包含全量（含 audit-failed 的 staging），防止 trigger 冲突
+    const occupiedTriggers = recipeSnapshot.entries.map((e) => e.trigger).filter(Boolean);
+    // ── 注入 evidenceHints (allRecipes + evolutionGuide + dimensionGaps) ──
+    briefing.evidenceHints = {
+        allRecipes,
+        rescanMode: true,
+        dimensionGaps,
+        evolutionGuide: {
+            decayCount,
+            totalCount: allRecipes.length,
+            instructions: decayCount > 0
+                ? `${decayCount} 个 Recipe 标记为衰退，需优先验证。每个维度内先 evolve 再补齐。`
+                : '所有 Recipe 状态健康，快速确认后补齐新知识。',
+        },
+        constraints: {
+            occupiedTriggers,
+            rules: [
+                '禁止提交 occupiedTriggers 列表中已存在的 trigger',
+                '每个维度的补齐数量参考 dimensionGaps[].gap，gap=0 的维度可以跳过或只提交真正的新发现',
+                '专注于尚未覆盖的新模式，不要重复已有知识的内容',
+            ],
+        },
+    };
+    // ── 覆盖 executionPlan.workflow 为 rescan 专属版本 (per-dimension evolve + gap-fill) ──
+    const briefingRecord = briefing;
+    if (briefingRecord.executionPlan && typeof briefingRecord.executionPlan === 'object') {
+        briefingRecord.executionPlan.workflow =
+            '【增量扫描模式 — 按维度 Evolve + Gap-Fill】 ' +
+                '对每个维度 (按 tiers 顺序): ' +
+                'Step 1 — Evolve (维度级首步): ' +
+                '过滤 allRecipes 中本维度的 Recipe，读 sourceRefs 源码验证 → ' +
+                '调用 autosnippet_evolve({ decisions: [本维度决策] }) → ' +
+                'Step 2 — Gap-Fill: ' +
+                '分析代码发现新模式 → 调用 autosnippet_submit_knowledge 提交 (数量参考 gap 值) → ' +
+                'Step 3 — Complete: 调用 autosnippet_dimension_complete 完成维度';
+    }
+    const dimGapLog = dimensionGaps
+        .map((g) => `${g.dimensionId}(${g.existingCount}→gap ${g.gap})`)
+        .join(', ');
+    ctx.logger.info(`[Rescan] Mission Briefing ready: ${allFiles.length} files, ${dimensions.length} dims, ` +
+        `preserved: ${recipeSnapshot.count}, decayed: ${decayCount}, totalGap: ${totalGap} — session ${session.id}`);
+    ctx.logger.info(`[Rescan] Dimension gaps: ${dimGapLog}`);
+    // ── 构建 gap 摘要信息 ──
+    const gapSummaryParts = dimensionGaps
+        .filter((g) => g.gap > 0)
+        .map((g) => `${g.dimensionId}(需补${g.gap}条)`);
+    const coveredDims = dimensionGaps.filter((g) => g.gap === 0).length;
+    const gapSummary = gapSummaryParts.length > 0
+        ? `需补齐维度: ${gapSummaryParts.join('、')}。`
+        : '所有维度已充分覆盖，仅在发现全新模式时提交。';
+    return envelope({
+        success: true,
+        data: {
+            rescan: {
+                preservedRecipes: recipeSnapshot.count,
+                cleanedTables: cleanResult.clearedTables.length,
+                cleanedFiles: cleanResult.deletedFiles,
+                reason: args.reason || null,
+            },
+            relevanceAudit: {
+                totalAudited: auditSummary.totalAudited,
+                healthy: auditSummary.healthy,
+                watch: auditSummary.watch,
+                decay: auditSummary.decay,
+                severe: auditSummary.severe,
+                dead: auditSummary.dead,
+                proposalsCreated: auditSummary.proposalsCreated,
+                immediateDeprecated: auditSummary.immediateDeprecated,
+            },
+            ...briefing,
+        },
+        message: `✅ Rescan 完成项目扫描，保留 ${recipeSnapshot.count} 个 Recipe（衰退 ${decayCount} 个），` +
+            `${coveredDims}/${dimensions.length} 个维度已充分覆盖。` +
+            `${gapSummary}` +
+            `对每个维度执行三步：` +
+            `(1) autosnippet_evolve — 过滤 allRecipes 中本维度 Recipe，读源码验证后提交决策 → ` +
+            `(2) autosnippet_submit_knowledge — 分析代码，发现未覆盖的新模式 → ` +
+            `(3) autosnippet_dimension_complete — 标记维度完成。` +
+            `注意: evidenceHints.constraints.occupiedTriggers 中的 trigger 已被占用，请勿重复。`,
+        meta: { tool: 'autosnippet_rescan', responseTimeMs: Date.now() - t0 },
+    });
+}

package/dist/lib/external/mcp/handlers/rescan-internal.d.ts

@@ -0,0 +1,120 @@
+/**
+ * rescan-internal.ts — 内部 Agent 增量扫描
+ *
+ * 与 rescan-external.ts（为外部 IDE Agent 生成 Mission Briefing）不同，
+ * 本文件由内置 AI pipeline（fillDimensionsV3）在服务端自动完成知识补齐。
+ *
+ * 流程:
+ *   1. snapshotRecipes — 快照保留知识
+ *   2. rescanClean — 清理衍生缓存
+ *   2.5 Recipe 文件 ↔ DB 一致性恢复
+ *   3. Phase 1-4 全量分析（文件收集→AST→依赖→Guard→维度）
+ *   4. RecipeRelevanceAuditor — 证据验证 + 快速衰退
+ *   5. 计算 gap 维度（需要补齐的维度）
+ *   5.5 BootstrapSessionManager — 缓存 Phase 结果供复用
+ *   6. 快速返回骨架 → 异步 fillDimensionsV3 填充 gap 维度
+ *   7. 前端通过 Socket.io 接收维度完成进度
+ *
+ * @module handlers/rescan-internal
+ */
+import type { RescanInput } from '#shared/schemas/mcp-tools.js';
+import type { McpContext } from './types.js';
+interface RescanLogger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+interface RescanMcpContext extends McpContext {
+    logger: RescanLogger;
+}
+interface RescanInternalArgs extends RescanInput {
+    /** 跳过异步填充（测试用） */
+    skipAsyncFill?: boolean;
+}
+/**
+ * rescanInternal — 内部 Agent 增量扫描
+ *
+ * 同步返回骨架（含 audit 摘要 + 异步会话 ID），
+ * 后台通过 fillDimensionsV3 对 gap 维度执行 AI 补齐。
+ */
+export declare function rescanInternal(ctx: RescanMcpContext, args: RescanInternalArgs): Promise<{
+    success: boolean;
+    errorCode: string | null;
+    message: string;
+    data: {
+        message: string;
+    } | null;
+    meta: {
+        source?: string | undefined;
+        responseTimeMs?: number | undefined;
+        version: string;
+        tool?: string | undefined;
+    };
+} | {
+    success: boolean;
+    errorCode: string | null;
+    message: string;
+    data: {
+        rescan: {
+            preservedRecipes: number;
+            cleanedTables: number;
+            cleanedFiles: number;
+            reason: string | null;
+        };
+        relevanceAudit: {
+            totalAudited: number;
+            healthy: number;
+            watch: number;
+            decay: number;
+            severe: number;
+            dead: number;
+            proposalsCreated: number;
+            immediateDeprecated: number;
+        };
+        gapAnalysis: {
+            totalDimensions: number;
+            gapDimensions: number;
+            skippedDimensions: string[];
+            gaps: {
+                dimensionId: string;
+                label: string | undefined;
+                existing: number;
+                gap: number;
+            }[];
+        };
+        languageStats: Record<string, number>;
+        primaryLanguage: string | null;
+        guardSummary: {
+            totalViolations: number;
+            errors: number;
+            warnings: number;
+        } | null;
+        astSummary: {
+            classes: number;
+            protocols: number;
+            categories: number;
+        } | null;
+        codeEntityGraph: {
+            totalEntities: number;
+            totalEdges: number;
+        } | null;
+        callGraph: {
+            entitiesUpserted: number;
+            edgesCreated: number;
+        } | null;
+        panorama: Record<string, unknown> | null;
+        bootstrapSession: Record<string, unknown> | null;
+        sessionId: string | null;
+        asyncFill: boolean;
+        status: string;
+        files: number;
+        targets: number;
+    } | null;
+    meta: {
+        source?: string | undefined;
+        responseTimeMs?: number | undefined;
+        version: string;
+        tool?: string | undefined;
+    };
+}>;
+export {};