autosnippet 3.2.7 → 3.2.9

package/lib/service/{chat/HandoffProtocol.js → agent/domain/insight-gate.js}

@@ -1,12 +1,18 @@
 /**
- * HandoffProtocol.js — Analyst → Producer 交接协议
+ * insight-gate.js — Insight 质量门控领域函数
  *
- * 职责:
- * 1. 从 Analyst 执行结果构建 AnalysisReport
- * 2. 质量门控: 判断分析是否足够深入
- * 3. 提供重试提示构建
+ * 从旧 HandoffProtocol.js 完整迁移的纯函数模块:
+ * - 分析文本清洗 (sanitizeAnalysisText)
+ * - AnalysisReport 构建 (v1)
+ * - AnalysisArtifact 构建 (v2, 含 evidenceMap/findings/negativeSignals)
+ * - 多维度质量评分 (buildQualityScores)
+ * - 质量门控 (v1 + v2)
+ * - 重试 Prompt 构建
+ * - PipelineStrategy gate.evaluator 适配器 (insightGateEvaluator)
  *
- * @module HandoffProtocol
+ * 被 PipelineStrategy 的 bootstrap preset 直接引用。
+ *
+ * @module insight-gate
  */
 
 import { EvidenceCollector } from './EvidenceCollector.js';
@@ -19,94 +25,58 @@ import { EvidenceCollector } from './EvidenceCollector.js';
  * 清理 Analyst 分析文本中可能泄漏的系统 nudge / graceful exit 指令。
  * 这些内容如果传给 Producer，会干扰其正常工作流。
  */
-function sanitizeAnalysisText(text) {
+export function sanitizeAnalysisText(text) {
   if (!text) {
     return '';
   }
-  // 移除 graceful exit nudge 及 digest 模板指令
   const patterns = [
     /\*{0,2}⚠️?\s*(?:你已使用|轮次即将耗尽|仅剩|请立即停止|必须立即结束)[^\n]*\n?/gi,
     /\*{0,2}请立即停止所有工具调用[^\n]*\*{0,2}\n?/gi,
     /请在回复中直接输出\s*dimensionDigest\s*JSON[^\n]*\n?/gi,
     /> ?(?:remainingTasks|如果所有信号都已覆盖)[^\n]*\n?/gi,
     /> ?⚠️ 严禁输出任何非 JSON 内容[^\n]*\n?/gi,
-    // 移除 AI 回显的 dimensionDigest JSON 块（对 Producer 无价值且会干扰）
     /```json\s*\n\s*\{\s*"dimensionDigest"\s*:[\s\S]*?\n```/g,
-
-    // ── AI 思考伪影清理 ──
-
-    // 轮次/阶段计数器（如 "第 18/24 轮 | 验证阶段 | 剩余 6 轮"）
     /^-{2,3}\s*\n\s*第\s*\d+\/\d+\s*轮[^\n]*\n(-{2,3}\s*\n)?/gm,
-    // 独立分隔线 + 空内容
     /^-{3}\s*$/gm,
-
-    // AI 规划/反思段落（"计划偏差分析"、"最终总结阶段" 等）
     /^#{1,3}\s*(?:计划偏差分析|最终总结阶段|执行计划|下一步计划|分析计划)\s*\n[\s\S]*?(?=\n#{1,3}\s|\n\n(?=[^#\s-]))/gm,
-
-    // 系统提示回显（"(提示: ...)"）
     /^\(提示[:：][^)]*\)\s*\n?/gm,
-
-    // AI 英文思考泄漏（"Wait, I have enough information..."、"Let me..."、"I'll stop here..."）
     /^(?:Wait,|Let me|I'll stop here|I will stop|I need to|I should|I have enough)[^\n]*\n?/gm,
-
-    // 工具提示循环（"尝试使用 `tool_name`..."、"- 尝试使用..."）
     /^[-•]\s*尝试使用\s*`[^`]+`[^\n]*\n?/gm,
     /^💡\s*提示[:：]?\s*\n?/gm,
-
-    // 请继续 / 请接续 单行（AI 被截断后的续写请求）
     /^请(?:继续|接续)[。.]?\s*$/gm,
-
-    // 📊 中期反思块（"📊 中期反思 (第 N/M 轮, X% 预算):" 及后续所有内容直到下一个 ## 或 📊）
     /📊\s*中期反思\s*\([^)]*\):?\s*\n(?:[\s\S]*?(?=\n#{1,3}\s(?!探索计划|第\s*\d)|\n(?=📊)|$))/gm,
-
-    // AI 思考方向列表（"你最近的思考方向:" + 编号列表 + 嵌套的探索计划）
     /^你最近的思考方向:\s*\n(?:[\s\S]*?(?=\n#{1,3}\s(?!探索计划|第\s*\d)|\n(?=📊)|$))/gm,
-
-    // AI 探索计划标题（"### 探索计划"）— 这是 AI 内部规划，不应出现在最终输出中
     /^#{1,3}\s*探索计划\s*\n(?:[\s\S]*?(?=\n#{1,3}\s(?!探索计划)|\n\n(?=[^#\s\d-])|\n(?=📊)|$))/gm,
-    // 编号前缀的探索计划（"  1. ### 探索计划" + 紧随的编号列表项）
     /^\s*\d+\.\s+#{1,3}\s*探索计划[^\n]*\n(?:\d+\.\s+\*{0,2}[^\n]*\n?)*/gm,
-
-    // AI 轮次标题（"### 第 N 轮：..." 开头的规划/反思段落）
     /^#{1,3}\s*第\s*\d+\s*轮[:：][^\n]*\n(?:[\s\S]*?(?=\n#{1,3}\s(?!探索计划|第\s*\d)|\n\n(?=#{1,3}\s)|\n(?=📊)|$))/gm,
-
-    // 行动效率统计行（"行动效率: 最近 N 轮中 X% 获取到新信息"）
     /^行动效率[:：][^\n]*\n?/gm,
     /^累计[:：]\s*\d+\s*文件[^\n]*\n?/gm,
-
-    // 计划进度（"📋 计划进度: 0/1 步骤已完成"）
     /^📋\s*计划进度[:：][^\n]*\n?/gm,
-
-    // 请评估提示块（"请评估: 1. ..."）
     /^请评估[:：]\s*\n(?:\s*\d+\.\s+[^\n]*\n?)*/gm,
-
-    // AI 对话提示回显（"(请在继续调用工具前...)", "(由于当前已是第 N 轮...)",  "(注意: 每一轮都必须...)"）
     /^\([请由注](?:在继续|于当前|意[:：])[^)]*\)\s*\n?/gm,
-
-    // AI 步骤进度与计划更新（"已经读取，未完成步骤..."、"计划更新：..."、"更新后的计划：..."）
     /^(?:\d+\.\s+)?(?:`[^`]*`\s+)?(?:已经读取|未完成步骤仅剩|计划更新|更新后的计划)[^\n]*\n?/gm,
     /^更新后的计划[:：]\s*\n(?:\s*\d+\.\s+[^\n]*\n?)*/gm,
-
-    // 纯数字编号残留行（清理被上面 pattern 删除后留下的孤立编号）
     /^\s*\d+\.\s*$/gm,
+    /^>\s*(?:searchHints|remainingTasks|candidateCount|crossRefs|keyFindings|gaps)\s*[:：][^\n]*\n?/gm,
+    /^\*{0,2}(?:请在|请直接|请确保|请务必|现在开始|输出你的|不要输出|不要再|不要包含)\s*[^。\n]*(?:分析文本|分析总结|分析报告|JSON|工具|输出|文本|报告)[^。\n]*[。.]?\s*\*{0,2}$/gm,
+    /^\*{0,2}重要\s*[：:][^。\n]*\*{0,2}$/gm,
+    /^注意[：:]\s*到达第\s*\d+\s*轮时[^\n]*$/gm,
+    /^第\s*\d+\/\d+\s*轮\s*\|[^\n]*$/gm,
   ];
   let cleaned = text;
   for (const pat of patterns) {
     cleaned = cleaned.replace(pat, '');
   }
-  // 移除可能残留的空行堆积
   cleaned = cleaned.replace(/\n{3,}/g, '\n\n').trim();
   return cleaned;
 }
 
 /**
- * 从 Analyst 的执行结果构建 AnalysisReport
+ * 从 Analyst 的执行结果构建 AnalysisReport (v1)
  *
- * @param {object} analystResult — ChatAgent.execute() 返回值
- * @param {string} analystResult.reply — Analyst 的自然语言分析文本
- * @param {Array} analystResult.toolCalls — 工具调用记录
+ * @param {object} analystResult — { reply, toolCalls }
  * @param {string} dimensionId — 维度 ID
- * @param {object} [projectGraph] — ProjectGraph 实例 (用于从 className 反查文件路径)
+ * @param {object} [projectGraph] — ProjectGraph 实例
  * @returns {AnalysisReport}
  */
 export function buildAnalysisReport(analystResult, dimensionId, projectGraph = null) {
@@ -129,7 +99,6 @@ export function buildAnalysisReport(analystResult, dimensionId, projectGraph = n
         if (args.pattern || args.query) {
           searchQueries.push(args.pattern || args.query);
         }
-        // 从搜索结果中提取文件路径
         if (typeof result === 'string') {
           const fileMatches = result.match(
             /(?:^|\n)([\w/.-]+\.(?:go|mod|sum|py|pyi|java|kt|kts|js|ts|jsx|tsx|mjs|cjs|swift|m|h|c|cpp|cc|hpp|cs|rb|rs|sql|json|yaml|yml|toml|xml|html|css|scss|less|sh|md|txt|gradle|properties|proto|vue|svelte|graphql|cfg|conf|ini|env|lock|rst))(?::\d+)?/gi
@@ -147,7 +116,6 @@ export function buildAnalysisReport(analystResult, dimensionId, projectGraph = n
       case 'get_class_info':
         if (args.className) {
           classesExplored.push(args.className);
-          // 从 ProjectGraph 反查文件路径
           if (projectGraph) {
             const info = projectGraph.getClassInfo(args.className);
             if (info?.filePath) {
@@ -172,7 +140,7 @@ export function buildAnalysisReport(analystResult, dimensionId, projectGraph = n
     }
   }
 
-  // 从分析文本中提取文件路径（支持多语言项目）
+  // 从分析文本中提取文件路径
   const text = sanitizeAnalysisText(analystResult.reply || '');
   const FILE_EXT_RE =
     /[\w/.-]+\.(?:go|mod|sum|py|pyi|java|kt|kts|js|ts|jsx|tsx|mjs|cjs|swift|m|h|c|cpp|cc|hpp|cs|rb|rs|sql|json|yaml|yml|toml|xml|html|css|scss|less|sh|md|txt|gradle|properties|proto|vue|svelte|graphql|cfg|conf|ini|env|lock|rst)\b/gi;
@@ -208,80 +176,72 @@ export function buildAnalysisReport(analystResult, dimensionId, projectGraph = n
  * 从 Analyst 执行结果构建 AnalysisArtifact (v2 增强版)
  *
  * 在 v1 AnalysisReport 基础上增加:
- * - evidenceMap: 文件 → 代码片段 + 摘要 (Producer 可直接引用)
+ * - evidenceMap: 文件 → 代码片段 + 摘要
  * - explorationLog: 工具调用意图 + 结果摘要序列
- * - negativeSignals: 搜索但未找到的模式 (告知 Producer 不要猜测)
+ * - negativeSignals: 搜索但未找到的模式
  * - findings: 来自 ActiveContext 的结构化发现
  * - qualityReport: 多维度质量评分
  *
- * 向后兼容: 返回对象包含 v1 的所有字段 (analysisText, referencedFiles, searchQueries, classesExplored, metadata)
- *
- * @param {object} analystResult — ChatAgent.execute() 返回值
+ * @param {object} analystResult — { reply, toolCalls }
  * @param {string} dimensionId — 维度 ID
  * @param {object} [projectGraph] — ProjectGraph 实例
- * @param {object} [activeContext] — ActiveContext 实例 (提供 distill 结果)
+ * @param {object} [activeContext] — ActiveContext 实例
  * @returns {AnalysisArtifact}
  */
 export function buildAnalysisArtifact(analystResult, dimensionId, projectGraph = null, activeContext = null) {
   const toolCalls = analystResult.toolCalls || [];
 
-  // §1: 构建 v1 报告 (复用已有逻辑获取 referencedFiles, searchQueries 等)
   const baseReport = buildAnalysisReport(analystResult, dimensionId, projectGraph);
 
-  // §2: 从工具调用中收集结构化证据
   const collector = new EvidenceCollector();
   for (let i = 0; i < toolCalls.length; i++) {
     collector.processToolCall(toolCalls[i], i);
   }
   const evidence = collector.build();
 
-  // §3: 从 ActiveContext 获取结构化发现 (保持与 distill() 一致的规范形状)
   const distilled = activeContext?.distill() || { keyFindings: [], toolCallSummary: [] };
   const findings = distilled.keyFindings.map((f) => ({
     finding: f.finding,
-    evidence: f.evidence || '',
+    evidence: typeof f.evidence === 'string' ? f.evidence : Array.isArray(f.evidence) ? f.evidence.join(', ') : f.evidence ? String(f.evidence) : '',
     importance: f.importance,
   }));
 
-  // §4: 合并引用文件 (v1 提取 + evidenceMap 中的文件)
   const allFiles = new Set(baseReport.referencedFiles);
   for (const filePath of evidence.evidenceMap.keys()) {
     allFiles.add(filePath);
   }
 
-  // §5: 计算多维度质量评分
   const qualityReport = buildQualityScores(
     baseReport.analysisText,
     findings,
     evidence,
   );
 
-  // §6: 构建 AnalysisArtifact (v1 超集)
   return {
-    // ═══ Layer 1: Core (注入 Producer prompt) ═══
+    // Layer 1: Core
     analysisText: baseReport.analysisText,
     findings,
     referencedFiles: [...allFiles],
     dimensionId,
 
-    // ═══ Layer 2: Detail (按需检索) ═══
+    // Layer 2: Detail
     evidenceMap: evidence.evidenceMap,
     explorationLog: evidence.explorationLog,
     negativeSignals: evidence.negativeSignals,
 
-    // ═══ Layer 3: Raw (仅审计/debug) ═══
+    // Layer 3: Raw
     fullToolTrace: toolCalls,
 
-    // ═══ Quality ═══
+    // Quality
     qualityReport,
 
-    // ═══ Metadata (v1 超集) ═══
+    // Metadata
     metadata: {
       ...baseReport.metadata,
       artifactVersion: 2,
     },
 
-    // ═══ v1 backward compat ═══
+    // v1 backward compat
     searchQueries: baseReport.searchQueries,
     classesExplored: baseReport.classesExplored,
   };
@@ -294,21 +254,15 @@ export function buildAnalysisArtifact(analystResult, dimensionId, projectGraph =
 /**
  * 计算 AnalysisArtifact 的多维度质量评分
  *
- * 4 个维度各 0-100 分, 加权计算总分:
- *   depthScore (30%)   — 文件覆盖深度
+ * 4 维度各 0-100, 加权:
+ *   depthScore (30%) — 文件覆盖深度
  *   breadthScore (20%) — 工具使用广度
  *   evidenceScore (30%) — 证据充分性
  *   coherenceScore (20%) — 分析连贯性
- *
- * @param {string} analysisText — 清洗后分析文本
- * @param {Array} findings — 结构化发现
- * @param {object} evidence — EvidenceCollector.build() 结果
- * @returns {{ scores: object, totalScore: number, suggestions: string[] }}
  */
 function buildQualityScores(analysisText, findings, evidence) {
   const scores = {};
 
-  // §1: depthScore — 文件覆盖深度
   const uniqueFilesRead = evidence.evidenceMap?.size || 0;
   const snippetCount = [...(evidence.evidenceMap?.values() || [])].reduce(
     (sum, e) => sum + e.codeSnippets.length,
@@ -316,7 +270,6 @@ function buildQualityScores(analysisText, findings, evidence) {
   );
   scores.depthScore = Math.min(100, uniqueFilesRead * 15 + snippetCount * 5);
 
-  // §2: breadthScore — 工具种类 + 有效率
   const toolTypes = new Set((evidence.explorationLog || []).map((e) => e.tool));
   const logLen = evidence.explorationLog?.length || 0;
   const effectiveRatio = logLen > 0
@@ -324,7 +277,6 @@ function buildQualityScores(analysisText, findings, evidence) {
     : 0;
   scores.breadthScore = Math.min(100, toolTypes.size * 20 + effectiveRatio * 40);
 
-  // §3: evidenceScore — 发现数量 + 有证据的发现比例
   const findingCount = findings?.length || 0;
   const evidencedFindings = (findings || []).filter((f) => f.evidence && f.evidence.length > 0).length;
   scores.evidenceScore =
@@ -332,7 +284,6 @@ function buildQualityScores(analysisText, findings, evidence) {
       ? Math.min(100, (evidencedFindings / findingCount) * 60 + findingCount * 10)
       : 0;
 
-  // §4: coherenceScore — 文本长度 + 结构标记
   const textLen = analysisText?.length || 0;
   const hasHeaders = /#{1,3}\s/.test(analysisText || '');
   const hasLists = /\d+\.\s|[-•]\s/.test(analysisText || '');
@@ -344,7 +295,6 @@ function buildQualityScores(analysisText, findings, evidence) {
       (findingCount >= 3 ? 20 : findingCount * 7),
   );
 
-  // 加权总分
   const totalScore = Math.round(
     scores.depthScore * 0.3 +
       scores.breadthScore * 0.2 +
@@ -352,7 +302,6 @@ function buildQualityScores(analysisText, findings, evidence) {
       scores.coherenceScore * 0.2,
   );
 
-  // 改进建议
   const suggestions = [];
   if (scores.depthScore < 50) suggestions.push('Need more read_project_file to examine code');
   if (scores.evidenceScore < 50) suggestions.push('Findings lack file-level evidence');
@@ -366,11 +315,11 @@ function buildQualityScores(analysisText, findings, evidence) {
 // ──────────────────────────────────────────────────────────────────
 
 /**
- * 分析质量门控 — 判断 Analyst 的输出是否足够好
+ * 分析质量门控
  *
  * 自动检测 v1 (AnalysisReport) 和 v2 (AnalysisArtifact):
- * - v2: 从 qualityReport.totalScore 计算门控结果
- * - v1: 使用原有的 4 条规则
+ * - v2: 从 qualityReport.totalScore 计算
+ * - v1: 使用 4 条规则
  *
  * @param {AnalysisReport|AnalysisArtifact} report
  * @param {object} [options]
@@ -378,17 +327,12 @@ function buildQualityScores(analysisText, findings, evidence) {
  * @returns {{ pass: boolean, reason?: string, action?: 'retry' | 'degrade' }}
  */
 export function analysisQualityGate(report, options = {}) {
-  // v2: AnalysisArtifact 带有 qualityReport
   if (report.qualityReport?.scores) {
     return applyGateThresholds(report.qualityReport, options);
   }
-  // v1: 原有逻辑
   return analysisQualityGateV1(report, options);
 }
 
-/**
- * v2 质量门控 — 基于多维度评分 + 阈值
- */
 function applyGateThresholds(qualityReport, options = {}) {
   const { totalScore } = qualityReport;
   const needsCandidates = options.outputType === 'dual' || options.outputType === 'candidate';
@@ -411,26 +355,18 @@ function applyGateThresholds(qualityReport, options = {}) {
   };
 }
 
-/**
- * v1 质量门控 — 原有 4 条规则 (保留向后兼容)
- */
 function analysisQualityGateV1(report, options = {}) {
   const needsCandidates = options.outputType === 'dual' || options.outputType === 'candidate';
-  // 需要产出候选的维度要求更高门槛
   const minChars = needsCandidates ? 400 : 200;
   const minFileRefs = needsCandidates ? 3 : 2;
 
-  // 规则 1: 最少字符数 — 分析太短说明未充分探索
   if (report.analysisText.length < minChars) {
     return { pass: false, reason: 'Analysis too short', action: 'retry' };
   }
-
-  // 规则 2: 最少引用文件数 — 未引用文件说明未看代码
   if (report.referencedFiles.length < minFileRefs) {
     return { pass: false, reason: 'Too few file references', action: 'retry' };
   }
 
-  // 规则 3: 检测"拒绝回答"模式
   const refusalPatterns = [
     /I cannot|I'm unable|I don't have access/i,
     /无法分析|无法访问|没有足够/,
@@ -439,9 +375,6 @@ function analysisQualityGateV1(report, options = {}) {
     return { pass: false, reason: 'Agent refused to analyze', action: 'degrade' };
   }
 
-  // 规则 4: 内容实质性检查 — 有结构化内容或足够多的探索
-  // v3.1: 放宽条件 — tool calling 模式下 AI 往往不输出 markdown 格式
-  // 只要分析足够长且引用了足够多的文件，就认为有实质性内容
   const hasStructure =
     /#{1,3}\s/.test(report.analysisText) ||
     /\d+\.\s/.test(report.analysisText) ||
@@ -457,7 +390,7 @@ function analysisQualityGateV1(report, options = {}) {
 }
 
 /**
- * 构建重试提示 — Gate 失败时给 Analyst 的追加指令
+ * 构建重试提示
  *
  * @param {string} reason — Gate 失败原因
  * @returns {string}
@@ -475,32 +408,67 @@ export function buildRetryPrompt(reason) {
   return hints[reason] || '请更深入地分析代码，引用至少 3 个具体文件，每个发现都要有代码证据。';
 }
 
+// ──────────────────────────────────────────────────────────────────
+// PipelineStrategy gate.evaluator 适配器
+// ──────────────────────────────────────────────────────────────────
+
+/**
+ * 面向 PipelineStrategy gate.evaluator 的包装函数。
+ *
+ * 将 PipelineStrategy 的 (source, phaseResults, strategyContext) 签名
+ * 适配到 buildAnalysisArtifact + analysisQualityGate 调用链。
+ *
+ * @param {object} source — 前一阶段 (analyze) 的 reactLoop 返回值
+ * @param {object} phaseResults — 所有阶段结果
+ * @param {object} strategyContext — orchestrator 注入的运行时上下文
+ * @returns {{ action: 'pass'|'retry'|'degrade', reason: string, artifact: object }}
+ */
+export function insightGateEvaluator(source, phaseResults, strategyContext = {}) {
+  if (!source?.reply) {
+    return { action: 'degrade', reason: 'No analysis output', artifact: null };
+  }
+
+  const { projectGraph, activeContext, dimId, outputType } = strategyContext;
+
+  const artifact = activeContext
+    ? buildAnalysisArtifact(source, dimId, projectGraph, activeContext)
+    : buildAnalysisReport(source, dimId, projectGraph);
+
+  const gate = analysisQualityGate(artifact, { outputType: outputType || 'analysis' });
+
+  return {
+    action: gate.action || (gate.pass ? 'pass' : 'retry'),
+    reason: gate.reason || '',
+    artifact,
+  };
+}
+
 // ──────────────────────────────────────────────────────────────────
 // 类型定义 (JSDoc)
 // ──────────────────────────────────────────────────────────────────
 
 /**
  * @typedef {object} AnalysisReport
- * @property {string} analysisText — Analyst 的完整回复文本
- * @property {string[]} referencedFiles — 从 toolCalls 中提取的已引用文件路径
- * @property {string[]} searchQueries — 从 toolCalls 中提取的搜索查询
- * @property {string[]} classesExplored — 从 toolCalls 中提取的已查看类名
- * @property {string} dimensionId — 维度 ID
+ * @property {string} analysisText
+ * @property {string[]} referencedFiles
+ * @property {string[]} searchQueries
+ * @property {string[]} classesExplored
+ * @property {string} dimensionId
  * @property {object} metadata — { iterations, toolCallCount }
  */
 
 /**
  * @typedef {object} AnalysisArtifact
- * @property {string} analysisText — 清洗后的分析全文
- * @property {Array<{claim: string, evidence: string[], importance: number, source: string}>} findings — 结构化发现
- * @property {string[]} referencedFiles — 引用文件列表
- * @property {string} dimensionId — 维度 ID
- * @property {Map<string, import('./EvidenceCollector.js').EvidenceEntry>} evidenceMap — 证据地图
- * @property {import('./EvidenceCollector.js').ExplorationEntry[]} explorationLog — 探索日志
- * @property {import('./EvidenceCollector.js').NegativeSignal[]} negativeSignals — 负空间信号
- * @property {Array} [fullToolTrace] — 完整工具调用追踪 (Layer 3)
- * @property {{ scores: object, totalScore: number, suggestions: string[] }} qualityReport — 质量评分
- * @property {object} metadata — { iterations, toolCallCount, artifactVersion: 2 }
- * @property {string[]} searchQueries — 搜索查询 (v1 兼容)
- * @property {string[]} classesExplored — 查看的类 (v1 兼容)
+ * @property {string} analysisText
+ * @property {Array<{claim: string, evidence: string[], importance: number, source: string}>} findings
+ * @property {string[]} referencedFiles
+ * @property {string} dimensionId
+ * @property {Map<string, import('./EvidenceCollector.js').EvidenceEntry>} evidenceMap
+ * @property {import('./EvidenceCollector.js').ExplorationEntry[]} explorationLog
+ * @property {import('./EvidenceCollector.js').NegativeSignal[]} negativeSignals
+ * @property {Array} [fullToolTrace]
+ * @property {{ scores: object, totalScore: number, suggestions: string[] }} qualityReport
+ * @property {object} metadata
+ * @property {string[]} searchQueries
+ * @property {string[]} classesExplored
  */