speccore 8.3.312 → 8.3.332

package/dist/core/analyze-engine.js

@@ -59,8 +59,6 @@ const logger_1 = require("../utils/logger");
 const task_utils_1 = require("../utils/task-utils");
 const feature_source_1 = require("./feature-source");
 const code_scanner_1 = require("./code-scanner");
-// v8.3.183+: tree-sitter 结构化摘要，替代原文 slice(0,N) 硬切
-const multi_lang_parser_1 = require("./multi-lang-parser");
 // v8.3.125+: 同义词扩展，解决中英文/缩写匹配失败问题
 const synonyms_1 = require("../utils/synonyms");
 const ai_context_generator_1 = require("./ai-context-generator");
@@ -121,6 +119,22 @@ async function runAnalysis(input) {
     const hasReqs = effectiveInput.requirements.length > 0;
     const hasSrc = effectiveInput.sources.length > 0;
     const type = hasReqs && hasSrc ? 'combined' : hasReqs ? 'req' : 'code';
+    // ── 统一刷新知识底座（RAG 索引 + 代码索引 + 知识图谱）──
+    // v8.3.184+: 收拢到 refresh-scheduler 统一调度（按 scope 分文件 + stale 判定）
+    // v8.3.328: 前移到分析之前——RAG 兑底召回依赖索引新鲜，首次分析即生效
+    try {
+        const { refreshKnowledgeBase } = await Promise.resolve().then(() => __importStar(require('./refresh-scheduler')));
+        await refreshKnowledgeBase({
+            cwd: process.cwd(),
+            iteration: effectiveInput.iteration,
+            scope: effectiveInput.scope,
+            taskId: effectiveInput.taskId,
+            force: true, // 分析命令强制刷新，保证上下文最新
+        });
+    }
+    catch (e) {
+        logger_1.logger.debug('知识底座刷新失败（非关键）:', e);
+    }
     let result;
     switch (type) {
         case 'req':
@@ -148,21 +162,6 @@ async function runAnalysis(input) {
         }
         catch { } // 非关键，静默失败
     }
-    // ── 统一刷新知识底座（RAG 索引 + 代码索引 + 知识图谱）──
-    // v8.3.184+: 收拢到 refresh-scheduler 统一调度（按 scope 分文件 + stale 判定）
-    try {
-        const { refreshKnowledgeBase } = await Promise.resolve().then(() => __importStar(require('./refresh-scheduler')));
-        await refreshKnowledgeBase({
-            cwd: process.cwd(),
-            iteration: effectiveInput.iteration,
-            scope: effectiveInput.scope,
-            taskId: effectiveInput.taskId,
-            force: true, // 分析命令强制刷新，保证上下文最新
-        });
-    }
-    catch (e) {
-        logger_1.logger.debug('知识底座刷新失败（非关键）:', e);
-    }
     return result;
 }
 // ================================================================
@@ -189,46 +188,41 @@ async function analyzeRequirements(input) {
     const fullContent = allContent.join('\n\n---\n\n');
     const issues = scanCompleteness(fullContent);
     const archImpact = await analyzeArchitectureImpact(fullContent);
-    // ── 需求分析时默认读取关联代码（避免分析不接地气 + 减少重复 token 消耗） ──
-    // v8.3.122+: 增加文件数和字节配额，确保深入阅读业务逻辑
-    let sourceContents = {};
-    let sourceSummaries = {};
+    // ── 需求分析默认关联代码（v8.3.329：阅读清单模式，不拼源码原文） ──
+    // findRelevantCode 相关性导航 → 报告输出「源码阅读清单」（路径+优先级+符号行号），
+    // 全文由宿主 AI 用 Read / Grep / LSP 工具按需获取。
+    let sourceMatches = [];
     const shouldReadSource = input.readSource !== false;
     if (shouldReadSource && (input.iteration || input.taskId)) {
         // v8.3.3xx+: 消费前兜底——索引缺失/过期时自动重建 + 无索引告警
         const codeIndexScope = input.sourceScope || await (0, code_scanner_1.resolveIterationScope)(input.iteration);
         await (0, code_scanner_1.ensureCodeIndexFresh)(codeIndexScope);
         const limit = input.depth === 'deep' ? 25 : (input.depth === 'quick' ? 5 : 12);
-        const maxBytes = input.depth === 'deep' ? 150000 : (input.depth === 'quick' ? 30000 : 70000);
-        const rawMatches = await (0, code_scanner_1.findRelevantCode)(fullContent, limit, input.sourceScope, input.iteration, input.taskId);
-        sourceContents = await (0, code_scanner_1.readRelevantSource)(rawMatches, maxBytes, limit);
-        if (Object.keys(sourceContents).length > 0) {
+        sourceMatches = await (0, code_scanner_1.findRelevantCode)(fullContent, limit, input.sourceScope, input.iteration, input.taskId);
+        if (sourceMatches.length > 0) {
             const scopeHint = input.sourceScope ? ` (范围: ${input.sourceScope})` : '';
-            const totalChars = Object.values(sourceContents).reduce((a, c) => a + c.length, 0);
-            logger_1.logger.info(`   📖 需求分析已关联 ${Object.keys(sourceContents).length} 个源码文件 (${Math.round(totalChars / 1000)}K 字符)${scopeHint}`);
-            // tree-sitter 结构化摘要（替代原文硬切，失败静默降级原文截断）
-            try {
-                sourceSummaries = await (0, multi_lang_parser_1.summarizeSources)(sourceContents);
-            }
-            catch { }
+            logger_1.logger.info(`   📖 需求分析已关联 ${sourceMatches.length} 个源码文件（阅读清单模式，原文按需深读）${scopeHint}`);
         }
     }
+    const sourceReadingList = sourceMatches.length > 0 ? await (0, code_scanner_1.formatSourceReadingList)(sourceMatches) : '';
     let outputPath;
     let report;
+    // v8.3.328: L2 规范注入 + RAG 兑底召回（此前需求分析链路未接入知识库）
+    const kctx = await collectKnowledgeContext(input, sourceMatches.length, fullContent);
     if (input.scope === 'global') {
         outputPath = (0, path_1.join)((0, task_utils_1.getProjectRoot)(), '.speccore', 'GLOBAL', input.output || 'REQ_CONSISTENCY.md');
-        report = buildReqConsistencyReport(input, issues, archImpact);
+        report = buildReqConsistencyReport(input, issues, archImpact, kctx);
     }
     else if (input.scope === 'task') {
         // task scope — 已在入口校验
         outputPath = (0, path_1.join)((0, task_utils_1.getProjectRoot)(), `Iteration-${input.iteration}`, '030-tasks', input.taskId, '00-specs', input.output || 'ANALYSIS.md');
-        report = buildTaskReqReport(input, issues, archImpact, sourceContents, sourceSummaries);
+        report = buildTaskReqReport(input, issues, archImpact, sourceReadingList, kctx);
     }
     else {
         // iteration (default)
         const iterDir = `Iteration-${input.iteration || 'current'}`;
         outputPath = (0, path_1.join)(iterDir, '020-specs', input.output || 'ANALYSIS.md');
-        report = buildIterationReqReport(input, issues, archImpact, sourceContents, sourceSummaries);
+        report = buildIterationReqReport(input, issues, archImpact, sourceReadingList, kctx);
         // 按端分目录输出
         await writePerPlatform(iterDir, report, input.output || 'ANALYSIS.md');
         // 按功能模块输出到 020-specs/features/
@@ -262,7 +256,7 @@ async function analyzeRequirements(input) {
         summary: {
             issues: issues.length,
             blockers: issues.filter(i => i.severity === 'blocker').length,
-            filesAnalyzed: input.requirements.length + Object.keys(sourceContents).length,
+            filesAnalyzed: input.requirements.length + sourceMatches.length,
             apisFound: archImpact.apis?.length || 0,
             risks: archImpact.risks?.length || 0,
         },
@@ -355,35 +349,33 @@ async function analyzeCombined(input) {
     logger_1.logger.info(`   🤖 AI 上下文已生成 → ${aiContext.promptPath}`);
     logger_1.logger.info(`   📁 源码文件: ${aiContext.totalFiles} 个`);
     logger_1.logger.info(`   🔗 API: ${aiContext.totalApis} 个`);
-    // 默认读取相关源码内容注入分析（除非明确关闭）
+    // 默认关联相关代码（v8.3.329：阅读清单模式，不拼源码原文）
     // 解耦设计：从完整索引中按 sourceScope 筛选，不是按 scope 建索引
-    // v8.3.122+: 增加配额，确保深入阅读业务逻辑和公共模块
-    let sourceContents = {};
+    let sourceMatches = [];
     const shouldReadSource = input.readSource !== false;
     if (shouldReadSource) {
         const limit = input.depth === 'deep' ? 30 : (input.depth === 'quick' ? 8 : 15);
-        const maxBytes = input.depth === 'deep' ? 200000 : (input.depth === 'quick' ? 40000 : 100000);
-        const rawMatches = await (0, code_scanner_1.findRelevantCode)(fullReqContent, limit, input.sourceScope, input.iteration, input.taskId);
-        sourceContents = await (0, code_scanner_1.readRelevantSource)(rawMatches, maxBytes, limit);
-        if (Object.keys(sourceContents).length > 0) {
+        sourceMatches = await (0, code_scanner_1.findRelevantCode)(fullReqContent, limit, input.sourceScope, input.iteration, input.taskId);
+        if (sourceMatches.length > 0) {
             const scopeHint = input.sourceScope ? ` (范围: ${input.sourceScope})` : '';
-            logger_1.logger.info(`   📖 已读取 ${Object.keys(sourceContents).length} 个源码文件${scopeHint} (${Object.values(sourceContents).reduce((a, c) => a + c.length, 0)} 字符)`);
+            logger_1.logger.info(`   📖 已关联 ${sourceMatches.length} 个源码文件${scopeHint}（阅读清单模式，原文按需深读）`);
         }
     }
+    const sourceReadingList = sourceMatches.length > 0 ? await (0, code_scanner_1.formatSourceReadingList)(sourceMatches) : '';
     let outputPath;
     let report;
     if (input.scope === 'global') {
         outputPath = (0, path_1.join)('.speccore', 'GLOBAL', input.output || 'ARCH_IMPACT.md');
-        report = await buildAIEnhancedReport(input, 'global', { issues, archImpact, fileStats, apiInventory, aiContext, sourceContents });
+        report = await buildAIEnhancedReport(input, 'global', { issues, archImpact, fileStats, apiInventory, aiContext, sourceMatches, sourceReadingList, reqContent: fullReqContent });
     }
     else if (input.scope === 'task') {
         outputPath = (0, path_1.join)((0, task_utils_1.getProjectRoot)(), `Iteration-${input.iteration}`, '030-tasks', input.taskId, '00-specs', input.output || 'ANALYSIS.md');
-        report = await buildAIEnhancedReport(input, 'task', { issues, archImpact, fileStats, apiInventory, aiContext, sourceContents });
+        report = await buildAIEnhancedReport(input, 'task', { issues, archImpact, fileStats, apiInventory, aiContext, sourceMatches, sourceReadingList, reqContent: fullReqContent });
     }
     else {
         const iterDir = `Iteration-${input.iteration || 'current'}`;
         outputPath = (0, path_1.join)(iterDir, '020-specs', input.output || 'ANALYSIS.md');
-        report = await buildAIEnhancedReport(input, 'iteration', { issues, archImpact, fileStats, apiInventory, aiContext, sourceContents });
+        report = await buildAIEnhancedReport(input, 'iteration', { issues, archImpact, fileStats, apiInventory, aiContext, sourceMatches, sourceReadingList, reqContent: fullReqContent });
         await writePerPlatform(iterDir, report, input.output || 'ANALYSIS.md');
         await writePerFeature(iterDir, report, input.output || 'ANALYSIS.md');
     }
@@ -423,7 +415,7 @@ async function scanSourceDirs(sources, depth) {
         if (!(await (0, fs_extra_1.pathExists)(srcDir)))
             continue;
         await walkDir(srcDir, srcDir, async (filePath) => {
-            const relPath = (0, path_1.relative)(process.cwd(), filePath);
+            const relPath = (0, path_1.relative)(process.cwd(), filePath).replace(/\\/g, '/');
             const ext = filePath.split('.').pop()?.toLowerCase() || '';
             const lang = LANG_MAP[ext];
             if (!lang)
@@ -464,7 +456,7 @@ async function walkDir(root, dir, callback, maxDepth = 5, visited = new Set()) {
                 continue;
             if (entry.isDirectory()) {
                 // 使用 path.relative 计算深度，避免尾部斜杠不一致问题
-                const relPath = (0, path_1.relative)(root, fullPath);
+                const relPath = (0, path_1.relative)(root, fullPath).replace(/\\/g, '/');
                 const curDepth = relPath.split('/').filter(Boolean).length;
                 if (curDepth < maxDepth)
                     await walkDir(root, fullPath, callback, maxDepth, visited);
@@ -501,7 +493,7 @@ async function buildApiInventory(sources) {
                 return;
             try {
                 const content = await (0, fs_extra_1.readFile)(filePath, 'utf-8');
-                const relPath = (0, path_1.relative)(process.cwd(), filePath);
+                const relPath = (0, path_1.relative)(process.cwd(), filePath).replace(/\\/g, '/');
                 // Java: @XXXMapping("/api/...")
                 const javaApis = content.match(/@\w*Mapping\s*\(\s*"(\/[^"]+)"/g) || [];
                 for (const m of javaApis) {
@@ -553,7 +545,7 @@ async function detectHotspots(sources) {
             try {
                 const content = await (0, fs_extra_1.readFile)(filePath, 'utf-8');
                 const lines = content.split('\n');
-                const relPath = (0, path_1.relative)(process.cwd(), filePath);
+                const relPath = (0, path_1.relative)(process.cwd(), filePath).replace(/\\/g, '/');
                 if (lines.length > 800) {
                     hotspots.push({ file: relPath, severity: 'high', reason: `超大文件 (${lines.length} 行)`, lines: lines.length });
                 }
@@ -600,7 +592,7 @@ async function analyzeDependencies(sources) {
                 return;
             try {
                 const content = await (0, fs_extra_1.readFile)(filePath, 'utf-8');
-                const relPath = (0, path_1.relative)(process.cwd(), filePath);
+                const relPath = (0, path_1.relative)(process.cwd(), filePath).replace(/\\/g, '/');
                 allFiles.push(relPath);
                 // TS/JS imports — 只匹配项目内部引用 (相对路径)
                 const importMatches = content.match(/import\s+.*?\s+from\s+['"]([^'"]+)['"]/g) || [];
@@ -762,11 +754,14 @@ async function analyzeArchitectureImpact(content) {
 // ================================================================
 // 报告生成: 纯需求
 // ================================================================
-function buildReqConsistencyReport(input, issues, archImpact) {
+function buildReqConsistencyReport(input, issues, archImpact, kctx) {
     const now = new Date().toISOString().split('T')[0];
     let r = `# 全局需求一致性分析\n\n`;
     r += `> 分析时间: ${now} | 需求文档: ${input.requirements.length} 个 | 模式: 全局\n\n`;
     r += `---\n\n`;
+    // v8.3.328: 全局知识库（L2 注入）+ RAG 召回结果
+    if (kctx)
+        r += renderKnowledgeSections(kctx);
     r += `## 1. 需求覆盖\n\n`;
     r += `| # | 文档 |\n| :--- | :--- |\n`;
     for (let i = 0; i < input.requirements.length; i++) {
@@ -786,13 +781,16 @@ function buildReqConsistencyReport(input, issues, archImpact) {
         r += `- ⚠️ ${risk}\n`;
     return r;
 }
-function buildIterationReqReport(input, issues, archImpact, sourceContents, sourceSummaries) {
+function buildIterationReqReport(input, issues, archImpact, sourceReadingList, kctx) {
     const now = new Date().toISOString().split('T')[0];
     const iter = input.iteration || 'current';
     const blockerCount = issues.filter(i => i.severity === 'blocker').length;
     let r = `# 需求分析报告\n\n`;
     r += `> 迭代: ${iter} | 分析时间: ${now} | 状态: ${blockerCount > 0 ? '🔴 有阻断' : '🟢 可拆分'}\n\n`;
     r += `---\n\n`;
+    // v8.3.328: 全局知识库（L2 注入）+ RAG 召回结果
+    if (kctx)
+        r += renderKnowledgeSections(kctx);
     r += `## 1. 需求完整性检查\n\n`;
     r += `| 严重度 | 分类 | 问题 |\n| :--- | :--- | :--- |\n`;
     for (const issue of issues) {
@@ -828,23 +826,12 @@ function buildIterationReqReport(input, issues, archImpact, sourceContents, sour
         r += `- [ ] ${rk}\n`;
     if (archImpact.newDependencies.length > 0)
         r += `- [ ] 确认新增依赖的引入方案和排期\n`;
-    // ── 代码关联分析（v6.8.0 新增：需求分析默认关联代码） ──
-    // v8.3.122+: 按深度动态调整代码展示配额，确保业务逻辑可见
-    if (sourceContents && Object.keys(sourceContents).length > 0) {
-        r += `\n---\n\n## 3.5 关联代码现状\n\n`;
-        r += `> 以下源码文件与当前需求相关，供技术方案参考\n\n`;
-        const previewLimit = input.depth === 'deep' ? 3000 : (input.depth === 'quick' ? 800 : 1500);
-        for (const [path, content] of Object.entries(sourceContents)) {
-            const summary = sourceSummaries?.[path];
-            if (summary) {
-                // 结构化摘要：签名 + 符号 + 接口，避免原文被按字符腰斩
-                r += `### \`${path}\`\n\n\`\`\`\n${summary}\n\`\`\`\n\n`;
-            }
-            else {
-                const preview = content.slice(0, previewLimit).replace(/\n/g, '\n  ');
-                r += `### \`${path}\`\n\n\`\`\`${path.split('.').pop() || 'ts'}\n${preview}${content.length > previewLimit ? '\n  // ... 截断 ...' : ''}\n\`\`\`\n\n`;
-            }
-        }
+    // ── 代码关联分析（v8.3.329：源码阅读清单，不拼原文） ──
+    // CLI 负责导航（路径+优先级+符号行号），全文由宿主 AI 按需深读
+    if (sourceReadingList) {
+        r += `\n---\n\n## 3.5 关联代码导航\n\n`;
+        r += sourceReadingList;
+        r += `\n`;
     }
     r += `\n---\n\n## 4. 技术方案（待填写）\n\n`;
     r += `| 模块 | 技术方案 | 负责人 | 预计工时 |\n| :--- | :--- | :--- | :--- |\n| | | | |\n\n`;
@@ -854,10 +841,13 @@ function buildIterationReqReport(input, issues, archImpact, sourceContents, sour
     r += `- [ ] 需求确认无遗漏\n- [ ] 技术方案评审通过\n- [ ] 工时评估合理\n- [ ] 可以开始拆分任务\n`;
     return r;
 }
-function buildTaskReqReport(input, issues, archImpact, sourceContents, sourceSummaries) {
+function buildTaskReqReport(input, issues, archImpact, sourceReadingList, kctx) {
     const now = new Date().toISOString().split('T')[0];
     let r = `# 任务需求分析\n\n`;
     r += `> 迭代: ${input.iteration} | 任务: ${input.taskId} | 分析: ${now}\n\n---\n\n`;
+    // v8.3.328: 全局知识库（L2 注入）+ RAG 召回结果
+    if (kctx)
+        r += renderKnowledgeSections(kctx);
     r += `## 问题清单\n`;
     if (issues.length === 0)
         r += `> ✅ 无问题\n`;
@@ -869,20 +859,11 @@ function buildTaskReqReport(input, issues, archImpact, sourceContents, sourceSum
         for (const rk of archImpact.risks)
             r += `- ⚠️ ${rk}\n`;
     }
-    // ── 代码关联分析（v6.8.0 新增） ──
-    if (sourceContents && Object.keys(sourceContents).length > 0) {
-        r += `\n## 关联代码\n\n`;
-        r += `> 以下源码与当前任务相关\n\n`;
-        for (const [path, content] of Object.entries(sourceContents)) {
-            const summary = sourceSummaries?.[path];
-            if (summary) {
-                r += `- **\`${path}\`**\n\n  \`\`\`\n  ${summary}\n  \`\`\`\n\n`;
-            }
-            else {
-                const preview = content.slice(0, 400).replace(/\n/g, '\n  ');
-                r += `- **\`${path}\`**\n\n  \`\`\`${path.split('.').pop() || 'ts'}\n  ${preview}${content.length > 400 ? '\n  // ... 截断 ...' : ''}\n  \`\`\`\n\n`;
-            }
-        }
+    // ── 代码关联分析（v8.3.329：源码阅读清单，不拼原文） ──
+    if (sourceReadingList) {
+        r += `\n## 关联代码导航\n\n`;
+        r += sourceReadingList;
+        r += `\n`;
     }
     return r;
 }
@@ -1022,11 +1003,59 @@ function buildTaskCodeReport(input, stats, apis, hotspots) {
         r += `- [ ] API 文档已更新 (${apis.length} 个接口)\n`;
     return r;
 }
+/**
+ * 收集知识上下文：L2 规范注入（loadGlobalContext）+ RAG 兑底召回（searchRagIndex）
+ *
+ * 此前 analyze 链路对 RAG 索引只刷新不检索（索引只被体检从未被使用），
+ * L2 规范也只注入 taskify/execute 的 prompt，analyze 链路完全未接入。
+ */
+async function collectKnowledgeContext(input, sourceMatchesCount, queryText) {
+    let globalContextStr = '';
+    let ragHits = [];
+    try {
+        const { loadGlobalContext, formatGlobalContext } = await Promise.resolve().then(() => __importStar(require('./prompt-builder')));
+        const gctx = await loadGlobalContext(process.cwd(), 'analyze', undefined, undefined);
+        // 仅当知识库有实质内容才注入（formatGlobalContext 对空 ctx 也输出标题行）
+        const hasContent = !!(gctx.indexSummary ||
+            (gctx.keyFileSummaries && gctx.keyFileSummaries.length > 0) ||
+            (gctx.toc && gctx.toc.length > 0));
+        globalContextStr = hasContent ? formatGlobalContext(gctx) : '';
+        if (sourceMatchesCount === 0) {
+            const { searchRagIndex } = await Promise.resolve().then(() => __importStar(require('./rag-engine')));
+            ragHits = await searchRagIndex(process.cwd(), queryText, {
+                iteration: input.iteration,
+            });
+            if (ragHits.length > 0) {
+                logger_1.logger.info(`   🔎 RAG 语义召回 ${ragHits.length} 条规范文档（源码索引零命中兑底）`);
+            }
+        }
+    }
+    catch { /* 非关键，静默失败 */ }
+    return { globalContextStr, ragHits };
+}
+/** 渲染知识库注入小节（全局知识库 + RAG 召回命中） */
+function renderKnowledgeSections(kctx) {
+    let out = '';
+    if (kctx.globalContextStr) {
+        out += `${kctx.globalContextStr}\n`;
+    }
+    if (kctx.ragHits.length > 0) {
+        out += `## 🔎 相关规范与模式（RAG 召回）\n\n`;
+        out += `> 源码索引零命中，以下为语义检索命中的规范/模式文档，请结合其内容完成分析。\n\n`;
+        for (const hit of kctx.ragHits) {
+            out += `- **${hit.title}**（\`${hit.filePath}\`）: ${hit.summary.slice(0, 120)}\n`;
+        }
+        out += `\n`;
+    }
+    return out;
+}
 async function buildAIEnhancedReport(input, scope, params) {
-    const { issues, archImpact, fileStats, apiInventory, aiContext, sourceContents } = params;
+    const { issues, archImpact, fileStats, apiInventory, aiContext, sourceMatches, sourceReadingList } = params;
     const now = new Date().toISOString().split('T')[0];
     const iter = input.iteration || 'current';
     const blockerCount = issues.filter(i => i.severity === 'blocker').length;
+    // v8.3.328: L2 规范注入 + RAG 兑底召回（此前 analyze 链路未接入；RAG 索引只被体检从未被使用）
+    const kctx = await collectKnowledgeContext(input, sourceMatches.length, params.reqContent || input.requirements.join('\n'));
     let r = `# ${scope === 'global' ? '全局架构影响分析' : scope === 'task' ? '任务综合分析' : '需求分析报告'}\n\n`;
     r += `> 迭代: ${iter} | 时间: ${now} | 状态: ${blockerCount > 0 ? '🔴 有阻断' : '🟢 可拆分'}\n`;
     r += `> 需求: ${input.requirements.length} 个 | 源码文件: ${fileStats.totalFiles} 个 | API: ${apiInventory.length} 个\n`;
@@ -1041,7 +1070,11 @@ async function buildAIEnhancedReport(input, scope, params) {
     r += `| 阻断问题 | ${blockerCount} |\n`;
     r += `| API 接口 | ${apiInventory.length} |\n`;
     r += `| 架构风险 | ${archImpact.risks.length} |\n`;
+    r += `| 全局知识库 | ${kctx.globalContextStr ? '已注入' : '未发现'} |\n`;
+    r += `| RAG 召回 | ${kctx.ragHits.length} 条 |\n`;
     r += `\n`;
+    // v8.3.328: 全局知识库（L2 注入）+ RAG 召回结果
+    r += renderKnowledgeSections(kctx);
     // 2. 问题清单 (基础规则检查)
     r += `## 🔍 自动检查结果\n\n`;
     if (issues.length > 0) {
@@ -1091,35 +1124,29 @@ async function buildAIEnhancedReport(input, scope, params) {
     // 6. 文件级变更预测
     r += `## 📄 预计变更文件\n\n`;
     r += `| 文件 | 变更类型 | 影响评估 | 风险等级 |\n| :--- | :--- | :--- | :--- |\n`;
-    if (Object.keys(sourceContents).length > 0) {
-        for (const [file] of Object.entries(sourceContents).slice(0, 8)) {
-            r += `| \`${file}\` | _AI 分析_ | _AI 分析_ | — |\n`;
+    if (sourceMatches.length > 0) {
+        for (const m of sourceMatches.slice(0, 8)) {
+            r += `| \`${m.file}\` | _AI 分析_ | _AI 分析_ | — |\n`;
         }
     }
     r += `| _其他_ | _待 AI 分析_ | — | — |\n\n`;
     r += `> 📌 请 AI 读取上下文文件完成文件级对标\n\n`;
-    // 6.5 源码分析清单（已读 + 未覆盖，方便用户发现遗漏并补充）
+    // 6.5 源码关联清单（已关联 + 未覆盖，方便用户发现遗漏并补充）
     {
-        const readFiles = Object.keys(sourceContents);
+        const readFiles = sourceMatches.map((m) => m.file);
         const fullIndex = await (0, code_scanner_1.loadFullIndex)();
         const allIndexedFiles = fullIndex?.files?.map(f => f.path) || [];
         const uncoveredFiles = allIndexedFiles.filter(f => !readFiles.includes(f));
         if (readFiles.length > 0 || uncoveredFiles.length > 0) {
             r += `## 📚 源码分析清单\n\n`;
-            // 已分析文件
-            // v8.3.122+: 增加代码内容预览，确保 AI 能看到业务逻辑
+            // 已关联文件（阅读清单模式，不拼原文）
             if (readFiles.length > 0) {
-                r += `### ✅ 已分析（${readFiles.length} 个文件）\n\n`;
-                const previewLimit = input.depth === 'deep' ? 3000 : (input.depth === 'quick' ? 800 : 1500);
-                for (const [file, content] of Object.entries(sourceContents)) {
-                    const lines = content.split('\n').length;
-                    const size = (content.length / 1024).toFixed(1);
-                    r += `- \`${file}\` (${lines} 行, ${size}KB)\n`;
-                    // 展示代码预览
-                    if (content.length > 0) {
-                        const preview = content.slice(0, previewLimit).replace(/\n/g, '\n  ');
-                        r += `\n  \`\`\`${file.split('.').pop() || 'ts'}\n  ${preview}${content.length > previewLimit ? '\n  // ... 截断 ...' : ''}\n  \`\`\`\n\n`;
-                    }
+                r += `### ✅ 已关联（${readFiles.length} 个文件，阅读清单模式）\n\n`;
+                for (const file of readFiles) {
+                    r += `- \`${file}\`\n`;
+                }
+                if (sourceReadingList) {
+                    r += `\n${sourceReadingList}\n`;
                 }
             }
             // 未覆盖文件（按目录分组）
@@ -1174,12 +1201,9 @@ async function buildAIEnhancedReport(input, scope, params) {
     r += `- [ ] **任务拆分建议**: 推荐任务粒度和依赖关系\n`;
     r += `- [ ] **技术方案推荐**: 架构方案、DB 设计、API 设计建议\n`;
     r += `- [ ] **工时评估**: 基于改动范围的工时估算\n`;
-    if (Object.keys(sourceContents).length > 0) {
-        r += `\n### 相关源码摘要 (${Object.keys(sourceContents).length} 个文件)\n\n`;
-        for (const [file, content] of Object.entries(sourceContents).slice(0, 5)) {
-            const lines = content.split('\n').slice(0, 12).join('\n');
-            r += `<details><summary><code>${file}</code></summary>\n\n\`\`\`\n${lines}\n\`\`\`\n\n</details>\n\n`;
-        }
+    if (sourceMatches.length > 0) {
+        r += `\n### 相关源码导航 (${sourceMatches.length} 个文件)\n\n`;
+        r += `> 详情见上文「源码阅读清单」，全文请用 Read / Grep / LSP 按需深读。\n\n`;
     }
     // 8. 确认清单
     r += `\n---\n\n## ✅ 确认清单\n\n`;
@@ -2015,7 +2039,7 @@ async function generateSpecsFromRequirements(reqPaths, iteration, specDir) {
     const archImpactForAnalysis = await analyzeArchitectureImpact(fullContent);
     files.push({
         filename: 'ANALYSIS.md',
-        content: buildIterationReqReport({}, issues, archImpactForAnalysis, {}),
+        content: buildIterationReqReport({}, issues, archImpactForAnalysis, undefined),
     });
     // DEPS.md — 依赖清单（全局公共依赖）
     files.push({