autosnippet/dist/lib/agent/domain/insight-gate.d.ts

Extract code patterns into a knowledge base for AI coding assistants

/**
 * insight-gate.js — Insight 质量门控领域函数
 *
 * 从旧 HandoffProtocol.js 完整迁移的纯函数模块:
 * - 分析文本清洗 (sanitizeAnalysisText)
 * - AnalysisReport 构建 (v1)
 * - AnalysisArtifact 构建 (v2, 含 evidenceMap/findings/negativeSignals)
 * - 多维度质量评分 (buildQualityScores)
 * - 质量门控 (v1 + v2)
 * - 重试 Prompt 构建
 * - PipelineStrategy gate.evaluator 适配器 (insightGateEvaluator)
 *
 * 被 PipelineStrategy 的 bootstrap preset 直接引用。
 *
 * @module insight-gate
 */
import { type ToolCall } from './EvidenceCollector.js';
/** Analyst 执行结果 */
interface AnalystResult {
    reply?: string;
    toolCalls?: ToolCall[];
    tokenUsage?: unknown;
    reasoningQuality?: unknown;
}
/** ProjectGraph 最小接口 */
interface ProjectGraphLike {
    getClassInfo(className: string): {
        filePath?: string;
    } | null | undefined;
    getProtocolInfo(protocolName: string): {
        filePath?: string;
    } | null | undefined;
}
/** ActiveContext 最小接口 */
interface ActiveContextLike {
    distill(): {
        keyFindings: RawFinding[];
        toolCallSummary: unknown[];
    };
}
/** 原始发现 (来自 ActiveContext.distill()) */
interface RawFinding {
    finding: string;
    evidence: string | string[] | unknown;
    importance: number;
}
/** 多维度质量评分 */
interface QualityScores {
    depthScore: number;
    breadthScore: number;
    evidenceScore: number;
    coherenceScore: number;
}
/** 质量报告 */
interface QualityReport {
    scores: QualityScores;
    totalScore: number;
    suggestions: string[];
}
/** 门控选项 */
interface GateOptions {
    outputType?: string;
}
/** 门控结果 */
interface GateResult {
    pass: boolean;
    reason?: string;
    action?: 'retry' | 'degrade';
}
/** 可进行门控评估的分析报告 */
interface GateableReport {
    analysisText: string;
    referencedFiles: string[];
    qualityReport?: QualityReport;
}
/**
 * 清理 Analyst 分析文本中可能泄漏的系统 nudge / graceful exit 指令。
 * 这些内容如果传给 Producer，会干扰其正常工作流。
 */
export declare function sanitizeAnalysisText(text: string): string;
/**
 * 从 Analyst 的执行结果构建 AnalysisReport (v1)
 *
 * @param analystResult { reply, toolCalls }
 * @param dimensionId 维度 ID
 * @param [projectGraph] ProjectGraph 实例
 */
export declare function buildAnalysisReport(analystResult: AnalystResult, dimensionId: string, projectGraph?: ProjectGraphLike | null): {
    analysisText: string;
    referencedFiles: string[];
    searchQueries: string[];
    classesExplored: string[];
    dimensionId: string;
    metadata: {
        iterations: number;
        toolCallCount: number;
        tokenUsage: {} | null;
        reasoningQuality: {} | null;
    };
};
/**
 * 从 Analyst 执行结果构建 AnalysisArtifact (v2 增强版)
 *
 * 在 v1 AnalysisReport 基础上增加:
 * - evidenceMap: 文件 → 代码片段 + 摘要
 * - explorationLog: 工具调用意图 + 结果摘要序列
 * - negativeSignals: 搜索但未找到的模式
 * - findings: 来自 ActiveContext 的结构化发现
 * - qualityReport: 多维度质量评分
 *
 * @param analystResult { reply, toolCalls }
 * @param dimensionId 维度 ID
 * @param [projectGraph] ProjectGraph 实例
 * @param [activeContext] ActiveContext 实例
 */
export declare function buildAnalysisArtifact(analystResult: AnalystResult, dimensionId: string, projectGraph?: ProjectGraphLike | null, activeContext?: ActiveContextLike | null): {
    analysisText: string;
    findings: {
        finding: string;
        evidence: string;
        importance: number;
    }[];
    referencedFiles: string[];
    dimensionId: string;
    evidenceMap: Map<string, import("./EvidenceCollector.js").EvidenceEntry>;
    explorationLog: import("./EvidenceCollector.js").ExplorationEntry[];
    negativeSignals: import("./EvidenceCollector.js").NegativeSignal[];
    fullToolTrace: ToolCall[];
    qualityReport: {
        scores: QualityScores;
        totalScore: number;
        suggestions: string[];
    };
    metadata: {
        artifactVersion: number;
        iterations: number;
        toolCallCount: number;
        tokenUsage: {} | null;
        reasoningQuality: {} | null;
    };
    searchQueries: string[];
    classesExplored: string[];
};
/**
 * 分析质量门控
 *
 * 自动检测 v1 (AnalysisReport) 和 v2 (AnalysisArtifact):
 * - v2: 从 qualityReport.totalScore 计算
 * - v1: 使用 4 条规则
 *
 * @param [options.outputType] 'analysis' | 'dual' | 'candidate'
 * @returns }
 */
export declare function analysisQualityGate(report: GateableReport, options?: GateOptions): GateResult;
/**
 * 构建重试提示
 *
 * @param reason Gate 失败原因
 */
export declare function buildRetryPrompt(reason: string): string;
/**
 * 面向 PipelineStrategy gate.evaluator 的包装函数。
 *
 * 将 PipelineStrategy 的 (source, phaseResults, strategyContext) 签名
 * 适配到 buildAnalysisArtifact + analysisQualityGate 调用链。
 *
 * @param source 前一阶段 (analyze) 的 reactLoop 返回值
 * @param phaseResults 所有阶段结果
 * @param strategyContext orchestrator 注入的运行时上下文
 * @returns }
 */
export declare function insightGateEvaluator(source: unknown, phaseResults: Record<string, unknown>, strategyContext?: Record<string, unknown>): {
    action: string;
    reason: string;
    artifact: null;
} | {
    action: string;
    reason: string;
    artifact: {
        analysisText: string;
        referencedFiles: string[];
        searchQueries: string[];
        classesExplored: string[];
        dimensionId: string;
        metadata: {
            iterations: number;
            toolCallCount: number;
            tokenUsage: {} | null;
            reasoningQuality: {} | null;
        };
    };
};
/** Tool call record for evolution gate */
interface EvolutionToolCallRecord {
    tool?: string;
    name?: string;
    args?: Record<string, unknown>;
    result?: unknown;
}
/**
 * Evolution Gate 评估器 — 面向 PipelineStrategy gate.evaluator
 *
 * 检查 Evolution Agent 是否对所有现有 Recipe 做出了决策:
 * - evolved (submit_knowledge with supersedes)
 * - deprecated (confirm_deprecation)
 * - skipped (skip_evolution)
 *
 * 如果还有未处理的 Recipe，返回 retry 要求补充决策。
 *
 * 兼容旧字段: 优先读 existingRecipes，回退 decayedRecipes。
 */
export declare function evolutionGateEvaluator(source: {
    toolCalls?: EvolutionToolCallRecord[];
} | null | undefined, _phaseResults: unknown, strategyContext?: {
    existingRecipes?: Array<{
        id: string;
    }>;
    decayedRecipes?: Array<{
        id: string;
    }>;
}): {
    action: string;
    reason: string;
    artifact?: undefined;
} | {
    action: string;
    artifact: {
        evolved: number;
        deprecated: number;
        skipped: number;
        totalRecipes: number;
    };
    reason?: undefined;
};
export {};