speccore 7.1.0 → 7.2.1

package/dist/commands/analyze.js

@@ -70,6 +70,8 @@ const requirement_clarifier_1 = require("../core/requirement-clarifier");
 const agents_1 = require("../core/agents");
 // v6.91.0+: 代码知识图谱摘要注入
 const code_graph_1 = require("../core/code-graph");
+// v7.2.0+: 结构化代码数据提取
+const structured_extractor_1 = require("../core/structured-extractor");
 async function analyzeCommand(options) {
     // v6.97.0+ 修复：全局分析时统一设置 iteration 为 'GLOBAL'，避免任何 fallback 到 getDefaultIteration()
     // 这是根治方案：后面所有 "options.iteration || await getDefaultIteration()" 都会命中 options.iteration
@@ -506,17 +508,17 @@ async function analyzeCommand(options) {
         if (options.scope === 'global') {
             // 全局分析：预创建 .speccore/GLOBAL/ 目录结构，不写迭代目录
             // v6.81.0+: 需求文档单独放在 requirements/ 下，技术文档放在 platforms/ 下
-            // v6.98.0+: 全局技术文档统一放在 global/ 子目录下，不与 platforms/requirements 平级
+            // v7.2.0+: 全局技术文档统一放在 overview/ 子目录下，与迭代层 020-specs/overview/ 命名一致
             const globalDir = (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL');
             await (0, fs_extra_1.ensureDir)(globalDir);
-            await (0, fs_extra_1.ensureDir)((0, path_1.join)(globalDir, 'global'));
+            await (0, fs_extra_1.ensureDir)((0, path_1.join)(globalDir, 'overview'));
             await (0, fs_extra_1.ensureDir)((0, path_1.join)(globalDir, 'platforms'));
             await (0, fs_extra_1.ensureDir)((0, path_1.join)(globalDir, 'requirements'));
             await (0, fs_extra_1.ensureDir)((0, path_1.join)(globalDir, 'requirements', 'images'));
             await (0, fs_extra_1.ensureDir)((0, path_1.join)(globalDir, 'requirements', 'prototypes'));
             // v7.0.0+: 图表可视化目录
             await (0, fs_extra_1.ensureDir)((0, path_1.join)(globalDir, 'diagrams'));
-            logger_1.logger.info(`📁 已预创建 .speccore/GLOBAL/ 目录结构（global/ + platforms/ + requirements/ + diagrams/）`);
+            logger_1.logger.info(`📁 已预创建 .speccore/GLOBAL/ 目录结构（overview/ + platforms/ + requirements/ + diagrams/）`);
         }
         else {
             const iterForDirs = options.iteration || await (0, context_1.getDefaultIteration)();
@@ -805,13 +807,13 @@ async function analyzeCommand(options) {
                             targetFilename = filename;
                         }
                         else if (globalSet.has(filename)) {
-                            // v6.98.0+: 全局技术文档统一放入 global/ 子目录
-                            targetDir = (0, path_1.join)(globalBaseDir, 'global');
+                            // v7.2.0+: 全局技术文档统一放入 overview/ 子目录，与迭代层命名一致
+                            targetDir = (0, path_1.join)(globalBaseDir, 'overview');
                             targetFilename = filename;
                         }
                         else {
-                            // v6.98.0+: 未知文件也归入 global/ 子目录，避免与 platforms/requirements 平级
-                            targetDir = (0, path_1.join)(globalBaseDir, 'global');
+                            // v7.2.0+: 未知文件也归入 overview/ 子目录
+                            targetDir = (0, path_1.join)(globalBaseDir, 'overview');
                             targetFilename = filename;
                         }
                         await (0, fs_extra_1.ensureDir)(targetDir);
@@ -829,6 +831,13 @@ async function analyzeCommand(options) {
                         count++;
                     }
                     logger_1.logger.success(`✅ ${count} 个全局文档已写入 .speccore/GLOBAL/`);
+                    // v7.2.0+: 全局文档质量门禁
+                    const { runGlobalQualityGate, printQualityReport } = await Promise.resolve().then(() => __importStar(require('../core/doc-quality-gate')));
+                    const reports = await runGlobalQualityGate();
+                    printQualityReport(reports);
+                    // v7.2.0+: 自动生成文档间交叉引用
+                    const { generateCrossReferences } = await Promise.resolve().then(() => __importStar(require('../core/doc-cross-reference')));
+                    await generateCrossReferences();
                 }
                 else {
                     // 迭代级：写 020-specs/（综合文档写入 global/ 子目录，v6.41.0+）
@@ -903,6 +912,8 @@ async function analyzeCommand(options) {
                         logger_1.logger.warn(`⚠️ 共跳过 ${skippedCount} 个非法目录的文档，请检查 AI 输出是否包含非端名目录`);
                     }
                     logger_1.logger.success(`✅ ${count} 个 Spec 文档已写入 020-specs/`);
+                    // v6.90.0+: 事后校验——检测并清理 AI 绕过 --apply 创建的非法目录/文件
+                    await sanitizeSpecDirectories(iterDir);
                     // v6.74.0+: 流式分析自动检查（回退检测 + 最终核对）
                     if (options.streamingPhase) {
                         const phase = options.streamingPhase;
@@ -1205,8 +1216,29 @@ async function analyzeCommand(options) {
     if (options.prompt) {
         // v6.97.0+ 修复：全局分析时不应 fallback 到当前迭代
         const iter = options.scope === 'global' ? 'GLOBAL' : (options.iteration || await (0, context_1.getDefaultIteration)());
+        // v7.2.0+: 保存分析上下文到临时目录
+        if (iter && iter !== 'GLOBAL') {
+            try {
+                const { saveAnalysisContext } = await Promise.resolve().then(() => __importStar(require('../core/iteration-cache')));
+                await saveAnalysisContext({
+                    iteration: iter,
+                    docName: options.docName,
+                    featureName: options.featureName,
+                    withCode: options.withCode,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            catch { /* ignore */ }
+        }
         const prompt = await buildMultiDocPrompt('analyze', { iteration: iter, task: options.task, type: options.type, scope: options.scope, withCode: options.withCode, platform: options.platform, phase: options.phase, autoMode: options.auto }, options);
         process.stdout.write(`[SPECCORE_PROMPT]\n${prompt}`);
+        // v7.2.0+: 全局分析完成后输出下一步引导
+        if (options.scope === 'global') {
+            const guide = await buildGlobalAnalysisGuide(options);
+            if (guide) {
+                process.stdout.write(`\n[SPECCORE_GUIDE]\n${guide}`);
+            }
+        }
         process.exitCode = 10;
         return;
     }
@@ -1219,7 +1251,7 @@ async function preCreateSpecDirectories(iteration) {
     const iterDir = await (0, context_1.getIterationDir)(iteration);
     const specDir = (0, path_1.join)(iterDir, '020-specs');
     await (0, fs_extra_1.ensureDir)(specDir);
-    // 预创建 global/ 子目录
+    // 预创建 overview/ 子目录（v6.78.0+ 从 global/ 改名）
     const globalDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
     await (0, fs_extra_1.ensureDir)(globalDir);
     // 读取端列表并预创建各端目录
@@ -1228,10 +1260,103 @@ async function preCreateSpecDirectories(iteration) {
         await (0, fs_extra_1.ensureDir)((0, path_1.join)(specDir, platform));
     }
     if (platforms.length > 0) {
-        logger_1.logger.info(`📁 已预创建 020-specs/ 目录结构: global/ + ${platforms.length} 个端目录 (${platforms.join(', ')})`);
+        logger_1.logger.info(`📁 已预创建 020-specs/ 目录结构: ${spec_paths_1.GLOBAL_SPECS_DIR}/ + ${platforms.length} 个端目录 (${platforms.join(', ')})`);
     }
     else {
-        logger_1.logger.info(`📁 已预创建 020-specs/ 目录结构: global/`);
+        logger_1.logger.info(`📁 已预创建 020-specs/ 目录结构: ${spec_paths_1.GLOBAL_SPECS_DIR}/`);
+    }
+}
+/**
+ * v6.90.0+: 事后校验——检测并清理 020-specs/ 下 AI 绕过 --apply 创建的非法目录和文件
+ *
+ * 解决的问题：AI 用 Write 工具直接写文件，绕过 CLI --apply，导致：
+ * - 非法子目录（如 1001/、工程标识/、错误码/）
+ * - 遗留的 global/ 旧目录（应迁移到 overview/）
+ * - 根目录散落的 .md 文件（应在 overview/ 内）
+ */
+async function sanitizeSpecDirectories(iterDir) {
+    const specDir = (0, path_1.join)(iterDir, '020-specs');
+    if (!await (0, fs_extra_1.pathExists)(specDir))
+        return;
+    const platforms = await (0, spec_paths_1.parsePlatformList)();
+    const validDirs = new Set([spec_paths_1.GLOBAL_SPECS_DIR, ...platforms]);
+    const globalSet = new Set(spec_paths_1.GLOBAL_SPEC_FILES);
+    const entries = await (0, fs_extra_2.readdir)(specDir);
+    let illegalDirCount = 0;
+    let orphanFileCount = 0;
+    let legacyGlobalMigrated = false;
+    for (const entry of entries) {
+        const entryPath = (0, path_1.join)(specDir, entry);
+        const entryStat = await (0, fs_extra_1.stat)(entryPath);
+        if (entryStat.isDirectory()) {
+            // 检测遗留的 global/ 目录（v6.78.0+ 已改名为 overview/）
+            if (entry === 'global') {
+                logger_1.logger.warn(`⚠️ 检测到遗留 global/ 目录（v6.78.0+ 已改名为 ${spec_paths_1.GLOBAL_SPECS_DIR}/）`);
+                // 将 global/ 中的文件迁移到 overview/
+                const globalFiles = await (0, fs_extra_2.readdir)(entryPath);
+                const overviewDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
+                await (0, fs_extra_1.ensureDir)(overviewDir);
+                for (const f of globalFiles) {
+                    const src = (0, path_1.join)(entryPath, f);
+                    const dest = (0, path_1.join)(overviewDir, f);
+                    if (!await (0, fs_extra_1.pathExists)(dest)) {
+                        await (0, fs_extra_1.rename)(src, dest);
+                        logger_1.logger.info(`   📦 迁移: global/${f} → ${spec_paths_1.GLOBAL_SPECS_DIR}/${f}`);
+                    }
+                }
+                // 删除空的 global/ 目录
+                const remaining = await (0, fs_extra_2.readdir)(entryPath);
+                if (remaining.length === 0) {
+                    await (0, fs_extra_1.rename)(entryPath, (0, path_1.join)(specDir, `global.migrated-${Date.now()}`));
+                    logger_1.logger.info(`   🗑️ global/ 已迁移并归档`);
+                }
+                else {
+                    logger_1.logger.warn(`   ⚠️ global/ 仍有 ${remaining.length} 个文件未迁移，已重命名归档`);
+                    await (0, fs_extra_1.rename)(entryPath, (0, path_1.join)(specDir, `global.archived-${Date.now()}`));
+                }
+                legacyGlobalMigrated = true;
+                continue;
+            }
+            // 白名单校验：非 overview/ 且非端名的目录 → 非法
+            if (!validDirs.has(entry)) {
+                const archivedName = `${entry}.invalid-${Date.now()}`;
+                await (0, fs_extra_1.rename)(entryPath, (0, path_1.join)(specDir, archivedName));
+                logger_1.logger.warn(`⚠️ 非法目录已归档: 020-specs/${entry}/ → ${archivedName}/`);
+                illegalDirCount++;
+            }
+        }
+        else if (entryStat.isFile()) {
+            // 根目录散落的 .md 文件 → 检查是否应归入 overview/
+            if (entry.endsWith('.md') && globalSet.has(entry)) {
+                const overviewDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
+                await (0, fs_extra_1.ensureDir)(overviewDir);
+                const dest = (0, path_1.join)(overviewDir, entry);
+                if (!await (0, fs_extra_1.pathExists)(dest)) {
+                    await (0, fs_extra_1.rename)(entryPath, dest);
+                    logger_1.logger.warn(`⚠️ 散落文件已归位: 020-specs/${entry} → ${spec_paths_1.GLOBAL_SPECS_DIR}/${entry}`);
+                    orphanFileCount++;
+                }
+                else {
+                    // overview/ 中已有同名文件，归档根目录版本
+                    const archivedName = `${entry}.orphan-${Date.now()}`;
+                    await (0, fs_extra_1.rename)(entryPath, (0, path_1.join)(specDir, archivedName));
+                    logger_1.logger.warn(`⚠️ 重复散落文件已归档: 020-specs/${entry} → ${archivedName}`);
+                    orphanFileCount++;
+                }
+            }
+        }
+    }
+    // 汇总报告
+    if (illegalDirCount > 0 || orphanFileCount > 0 || legacyGlobalMigrated) {
+        logger_1.logger.info('');
+        logger_1.logger.info(`🔍 020-specs/ 目录校验报告:`);
+        if (illegalDirCount > 0)
+            logger_1.logger.warn(`   ⚠️ ${illegalDirCount} 个非法目录已归档（AI 绕过 --apply 创建）`);
+        if (orphanFileCount > 0)
+            logger_1.logger.warn(`   ⚠️ ${orphanFileCount} 个散落文件已归位到 ${spec_paths_1.GLOBAL_SPECS_DIR}/`);
+        if (legacyGlobalMigrated)
+            logger_1.logger.info(`   📦 遗留 global/ 已迁移到 ${spec_paths_1.GLOBAL_SPECS_DIR}/`);
+        logger_1.logger.info(`   ✅ 当前合法目录: ${Array.from(validDirs).join(', ')}`);
     }
 }
 /**
@@ -1658,6 +1783,148 @@ async function injectGraphSummary(prompt) {
         return prompt;
     }
 }
+// ── v7.2.0+: 检测全局分析当前进度 ──
+// Layer 4 拆分为子层: 4a=产品文档, 4b=全局技术核心, 4c=全局技术扩展, 4d=各端技术
+async function detectGlobalLayerProgress() {
+    const globalDir = (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL');
+    let completedLayer = 0;
+    const missing = [];
+    // Layer 1: 检查各端 _INDEX.md
+    try {
+        const platformsDir = (0, path_1.join)(globalDir, 'platforms');
+        const entries = await (0, fs_extra_2.readdir)(platformsDir, { withFileTypes: true });
+        const platformDirs = entries.filter(e => e.isDirectory() && e.name !== '_shared').map(e => e.name);
+        const hasIndex = platformDirs.length > 0 && (await Promise.all(platformDirs.map(async (d) => (0, fs_extra_1.pathExists)((0, path_1.join)(platformsDir, d, '_INDEX.md'))))).some(Boolean);
+        if (hasIndex)
+            completedLayer = 1;
+        else
+            missing.push('Layer 1: platforms/{端}/_INDEX.md');
+    }
+    catch {
+        missing.push('Layer 1: platforms/{端}/_INDEX.md');
+    }
+    // Layer 2: 检查 _ASSOCIATION.md
+    if (completedLayer >= 1) {
+        if (await (0, fs_extra_1.pathExists)((0, path_1.join)(globalDir, 'platforms', '_shared', '_ASSOCIATION.md'))) {
+            completedLayer = 2;
+        }
+        else {
+            missing.push('Layer 2: platforms/_shared/_ASSOCIATION.md + _MODULES.md');
+        }
+    }
+    // Layer 3: 检查 _MODULES.md
+    if (completedLayer >= 2) {
+        if (await (0, fs_extra_1.pathExists)((0, path_1.join)(globalDir, 'platforms', '_shared', '_MODULES.md'))) {
+            completedLayer = 3;
+        }
+        else {
+            missing.push('Layer 3: platforms/_shared/_MODULES.md（功能模块候选清单）');
+        }
+    }
+    // Layer 4 子层检测
+    let subLayer;
+    if (completedLayer >= 3) {
+        const overviewDir = (0, path_1.join)(globalDir, 'overview');
+        const requirementsDir = (0, path_1.join)(globalDir, 'requirements');
+        const completedSubLayers = [];
+        // 4a: 产品文档
+        const hasReq = await (0, fs_extra_1.pathExists)((0, path_1.join)(requirementsDir, 'REQUIREMENT.md'));
+        if (hasReq)
+            completedSubLayers.push('4a');
+        // 4b: 全局技术核心文档
+        const hasCoreTech = await (0, fs_extra_1.pathExists)((0, path_1.join)(overviewDir, 'ARCHITECTURE.md'))
+            && await (0, fs_extra_1.pathExists)((0, path_1.join)(overviewDir, 'FUNCTION_MAP.md'));
+        if (hasCoreTech)
+            completedSubLayers.push('4b');
+        // 4c: 全局技术扩展文档
+        const hasExtTech = await (0, fs_extra_1.pathExists)((0, path_1.join)(overviewDir, 'SECURITY_AUDIT.md'))
+            || await (0, fs_extra_1.pathExists)((0, path_1.join)(overviewDir, 'DATA_FLOW.md'));
+        if (hasExtTech)
+            completedSubLayers.push('4c');
+        // 4d: 各端技术文档
+        try {
+            const platformsDir = (0, path_1.join)(globalDir, 'platforms');
+            const entries = await (0, fs_extra_2.readdir)(platformsDir, { withFileTypes: true });
+            const platformDirs = entries.filter(e => e.isDirectory() && e.name !== '_shared').map(e => e.name);
+            const hasPlatformDoc = platformDirs.length > 0 && (await Promise.all(platformDirs.map(async (d) => (0, fs_extra_1.pathExists)((0, path_1.join)(platformsDir, d, 'API_INVENTORY.md'))
+                || (0, fs_extra_1.pathExists)((0, path_1.join)(platformsDir, d, 'UI_FLOW.md'))))).some(Boolean);
+            if (hasPlatformDoc)
+                completedSubLayers.push('4d');
+        }
+        catch { /* ignore */ }
+        if (completedSubLayers.length === 4) {
+            completedLayer = 4;
+        }
+        else {
+            const subLayerOrder = ['4a', '4b', '4c', '4d'];
+            const nextSub = subLayerOrder.find(s => !completedSubLayers.includes(s)) || '4d';
+            missing.push(`Layer 4${nextSub}: 全局汇总文档子层`);
+            subLayer = { completed: completedSubLayers, next: nextSub };
+        }
+    }
+    return { completedLayer, nextLayer: Math.min(completedLayer + 1, 4), missing, subLayer };
+}
+// ── v7.2.0+: 全局分析下一步引导 ──
+async function buildGlobalAnalysisGuide(options) {
+    const progress = await detectGlobalLayerProgress();
+    const { completedLayer, nextLayer, subLayer } = progress;
+    const deepDoc = options?.deep;
+    let guide = '';
+    // 进度条
+    const layers = ['Layer 1 索引扫描', 'Layer 2 跨端关联', 'Layer 3 模块深入', 'Layer 4 全局汇总'];
+    guide += `\n📊 全局分析进度: ${completedLayer}/4 层完成\n`;
+    guide += layers.map((l, i) => {
+        const status = i < completedLayer ? '✅' : i === completedLayer ? '▶️' : '⬜';
+        return `   ${status} ${l}`;
+    }).join('\n');
+    guide += '\n';
+    if (completedLayer === 4 && (!subLayer || subLayer.completed.length === 4)) {
+        guide += '\n🎉 全局分析全部完成！\n';
+        guide += '   所有文档已生成在 .speccore/GLOBAL/ 目录\n';
+        guide += '   如需补充某份文档: speccore analyze --scope global --layer 4 --deep <文档名>\n';
+        return guide;
+    }
+    // 下一步命令
+    guide += '\n➡️  下一步:\n';
+    if (deepDoc && options?.iterative) {
+        const outlinePath = (0, path_1.join)(process.cwd(), '.speccore', 'cache', `deep-outline-${deepDoc.replace(/\//g, '-')}.md`);
+        const hasOutline = await (0, fs_extra_1.pathExists)(outlinePath);
+        if (!hasOutline) {
+            guide += `   1. 将 AI 输出的大纲保存到: ${outlinePath}\n`;
+            guide += `   2. 审核/修改大纲\n`;
+            guide += `   3. 再次执行: speccore analyze --scope global --layer 4 --deep ${deepDoc} --iterative\n`;
+        }
+        else {
+            guide += `   1. 将 AI 输出的本节内容追加到文档\n`;
+            guide += `   2. 继续下一节: speccore analyze --scope global --layer 4 --deep ${deepDoc} --iterative\n`;
+        }
+    }
+    else if (deepDoc) {
+        guide += `   speccore analyze --scope global --layer 4 --deep ${deepDoc}\n`;
+        guide += `   （如需迭代式补全: 加 --iterative 参数）\n`;
+    }
+    else if (nextLayer === 4 && subLayer) {
+        const subNames = {
+            '4a': '产品视角文档（requirements/）',
+            '4b': '全局技术核心文档（overview/）',
+            '4c': '全局技术扩展文档（overview/）',
+            '4d': '各端技术文档（platforms/）',
+        };
+        guide += `   speccore analyze --scope global --layer 4\n`;
+        guide += `   （即将生成: ${subNames[subLayer.next] || subLayer.next}）\n`;
+    }
+    else {
+        guide += `   speccore analyze --scope global --layer ${nextLayer}\n`;
+    }
+    // 快捷命令提示
+    guide += '\n💡 快捷命令:\n';
+    guide += `   查看进度: speccore status\n`;
+    if (completedLayer >= 3) {
+        guide += `   深度分析单文档: speccore analyze --scope global --layer 4 --deep ARCHITECTURE.md\n`;
+    }
+    guide += `   全量重新分析: speccore analyze --scope global --with-code\n`;
+    return guide;
+}
 // ── buildMultiDocPrompt: 多文档协议 ──
 async function buildMultiDocPrompt(command, ctx, options) {
     const iter = ctx.iteration || '当前迭代';
@@ -1673,21 +1940,78 @@ async function buildMultiDocPrompt(command, ctx, options) {
         if (ctx.withCode && (options?.streaming || options?.streamingPhase)) {
             return buildStreamingGlobalPrompt(command, ctx, options);
         }
+        // v7.2.0+: 全局分析分层执行 — 检测当前进度，自动分配 layer
+        const progress = await detectGlobalLayerProgress();
+        const targetLayer = options?.layer || progress.nextLayer;
+        const isLayered = !!options?.layer || progress.completedLayer < 4;
+        // v7.2.0+: 结构化代码数据提取 — Layer 1 之前自动执行
+        let structuredDataHint = '';
+        if (targetLayer === 1 && ctx.withCode) {
+            try {
+                // 读取 CONSTITUTION.md 获取源码路径
+                const constitutionPath = (0, path_1.join)(process.cwd(), '.speccore', 'CONSTITUTION.md');
+                let sourcePaths = ['src'];
+                if (await (0, fs_extra_1.pathExists)(constitutionPath)) {
+                    const content = await (0, fs_extra_2.readFile)(constitutionPath, 'utf-8');
+                    const match = content.match(/源码路径[\s\S]*?\n\s*-\s*`?([^`\n]+)`?/g);
+                    if (match) {
+                        sourcePaths = match.map(m => m.replace(/.*-\s*`?/, '').replace(/`?$/, '').trim()).filter(Boolean);
+                    }
+                }
+                await (0, structured_extractor_1.extractStructuredData)(process.cwd(), sourcePaths);
+                structuredDataHint = '\n> 📊 **结构化数据**: 已提取到 `.speccore/cache/structured-data.json`，包含 API/Entity/Route/Component 清单\n';
+            }
+            catch (e) {
+                logger_1.logger.warn(`   ⚠️ 结构化数据提取失败: ${e.message}`);
+            }
+        }
+        // Layer 角色定义
+        const LAYER_ROLES = {
+            1: { role: '代码索引专家', focus: '全面扫描各端源码结构，提取目录/接口/实体/配置等索引信息', output: '各端 _INDEX.md + PATTERNS 模式提取 + semantic-tags.json' },
+            2: { role: '系统架构师', focus: '基于 Layer 1 索引进行跨端关联分析、接口匹配、模块聚类', output: '_ASSOCIATION.md + _MODULES.md' },
+            3: { role: '业务分析师', focus: '按功能模块深入分析业务逻辑、数据流、规则、时序', output: '各端功能模块深入文档 + 模块级 PATTERNS' },
+            4: { role: '产品总监 + 技术负责人', focus: '全局汇总，分 4 个子层执行（4a产品→4b技术核心→4c技术扩展→4d各端）', output: 'requirements/ + overview/ + platforms/' },
+        };
+        const layerMeta = LAYER_ROLES[targetLayer];
         let prompt = `\n# 任务: ${command} (全局分析${ctx.withCode ? '+源码' : ''})\n\n`;
+        // v7.2.0+: 分层专注指令 — 强烈约束 AI 只执行当前 layer
+        prompt += `## 🎯 当前执行层级: Layer ${targetLayer}/4 — ${layerMeta.role}\n\n`;
+        prompt += `> ⚠️ **重要约束**: 你当前只需要完成 **Layer ${targetLayer}** 的工作。不要提前做后续层的内容。\n`;
+        prompt += `> 每层完成后通过 \`speccore analyze --scope global --layer ${targetLayer + 1 <= 4 ? targetLayer + 1 : 4}\` 进入下一层。\n\n`;
+        prompt += `| 层级 | 角色 | 核心任务 | 产出物 |\n`;
+        prompt += `| :--- | :--- | :--- | :--- |\n`;
+        prompt += `| 1 | 代码索引专家 | 扫描源码结构，提取索引 | platforms/{端}/_INDEX.md |\n`;
+        prompt += `| 2 | 系统架构师 | 跨端关联、接口匹配、模块聚类 | platforms/_shared/_ASSOCIATION.md + _MODULES.md |\n`;
+        prompt += `| 3 | 业务分析师 | 功能模块深入分析 | 各端功能模块文档 |\n`;
+        prompt += `| 4 | 产品总监+技术负责人 | 全局汇总、需求总纲、一致性校验 | overview/ + requirements/ |\n\n`;
+        if (progress.completedLayer > 0) {
+            prompt += `📊 检测进度: 已完成 Layer ${progress.completedLayer}/4`;
+            if (progress.missing.length > 0) {
+                prompt += `，待补齐: ${progress.missing.join('; ')}`;
+            }
+            prompt += `\n\n`;
+        }
+        prompt += `## 你的专注任务（Layer ${targetLayer}）\n`;
+        prompt += `- **角色**: ${layerMeta.role}\n`;
+        prompt += `- **核心任务**: ${layerMeta.focus}\n`;
+        prompt += `- **预期产出**: ${layerMeta.output}\n\n`;
         prompt += `## 要求\n`;
-        prompt += `1. **先读宪法**: Read .speccore/CONSTITUTION.md，这是项目配置的唯一权威来源。获取:\n`;
-        prompt += `   - 「工程」列 → 所有工程名（如 meeting-system, booking-service）\n`;
-        prompt += `   - 「源码路径」列 → 各工程的代码目录（用于 Read 源码）\n`;
-        prompt += `   - 「## 端列表」章节 → 全局权威端名列表（如 backend/h5/admin）\n`;
-        prompt += `   - 每个工程独立分析，文档输出到: .speccore/GLOBAL/platforms/{端名}/\n`;
-        prompt += `2. Read .speccore/GLOBAL/ 下所有文档了解跨项目需求\n`;
-        prompt += `3. **禁止行为（重要）**: 不要打开浏览器、不要模拟用户操作、不要访问 URL。所有分析必须基于直接 Read 源码文件完成。如果文件不存在，跳过即可，不要尝试其他方式获取。\n`;
+        prompt += `1. **先读宪法**: Read .speccore/CONSTITUTION.md，获取工程名、源码路径、端列表。\n`;
+        prompt += `2. Read .speccore/GLOBAL/ 下已有文档（特别是前一层的产物）作为输入。\n`;
+        prompt += `3. **禁止行为**: 不要打开浏览器、不要模拟用户操作、不要访问 URL。所有分析基于直接 Read 源码。\n`;
         if (ctx.withCode) {
-            // v6.71.2+: 双层扫描 + 功能模块驱动（替代原来的按端顺序分析）
-            prompt += `4. 从 CONSTITUTION.md 的「源码路径」列读取所有工程目录\n`;
-            prompt += `\n## 📊 Layer 1: 快速扫描所有端（并行，只提取索引）\n\n`;
-            prompt += `对每个端，读取关键索引文件和配置，提取全面索引（不深入代码逻辑）：\n\n`;
-            prompt += `**后端端扫描维度（10项）**：\n`;
+            prompt += `4. 从 CONSTITUTION.md 的「源码路径」列读取所有工程目录。\n`;
+        }
+        // 根据 targetLayer 注入对应的专注内容
+        if (targetLayer === 1) {
+            prompt += `\n## 📊 Layer 1: 快速扫描所有端（基于结构化数据生成索引）\n\n`;
+            prompt += `${structuredDataHint}`;
+            prompt += `**重要**: 不要直接扫描源码文件。已使用代码扫描工具提取了结构化数据，你只需要读取这些数据并整理成 _INDEX.md。\n\n`;
+            prompt += `**步骤**: \n`;
+            prompt += `1. Read \`.speccore/cache/structured-data.json\` — 获取所有端的 API/Entity/Route/Component 清单\n`;
+            prompt += `2. 对每个端，基于结构化数据生成 \`_INDEX.md\`（补充扫描工具未覆盖的内容）\n`;
+            prompt += `3. 扫描工具未覆盖的维度（消息队列、定时任务、配置、外部集成、日志监控、错误处理），需要 Read 相关配置文件补充\n\n`;
+            prompt += `**后端端 _INDEX.md 维度（基于 structured-data.json + 补充扫描）**：\n`;
             prompt += `| 扫描项 | 读取位置 | 提取内容 |\n`;
             prompt += `| :--- | :--- | :--- |\n`;
             prompt += `| 接口层 | Controller/Handler/Resource 目录 | 接口类名、接口路径（从注解/装饰器推断）、鉴权注解 |\n`;
@@ -1759,7 +2083,8 @@ async function buildMultiDocPrompt(command, ctx, options) {
             prompt += `  }\n`;
             prompt += `]\n`;
             prompt += `\`\`\`\n\n`;
-            prompt += `## 🔗 Layer 2: 跨端关联分析（基于 Layer 1 的索引）\n\n`;
+            prompt += `## 🔗 Layer 2: 跨端关联分析（基于 Layer 1 索引 + structured-data.json）\n\n`;
+            prompt += `> 📊 **结构化数据**: Read \`.speccore/cache/structured-data.json\` 获取 API/Entity 清单，与 Layer 1 索引交叉验证\n\n`;
             prompt += `1. **匹配前后端接口**：\n`;
             prompt += `   - 前端 \`_INDEX.md\` 中的 API 调用路径 vs 后端 \`_INDEX.md\` 中的接口路径\n`;
             prompt += `   - **匹配上** → 建立「前端页面 → 前端 API 调用 → 后端接口 → 后端服务」链路\n`;
@@ -1863,23 +2188,23 @@ async function buildMultiDocPrompt(command, ctx, options) {
             prompt += `     - **响应式/适配策略**：不同设备尺寸下的布局变化、断点设计\n`;
             prompt += `     - **无障碍要求**：键盘导航、屏幕阅读器、色彩对比度（如有要求）\n`;
             prompt += `     - 每个前端端需求目录下可放 images/（截图/流程图/原型图）和 prototypes/（可交互原型文件）\n`;
-            prompt += `   **技术视角 → 存放到 .speccore/GLOBAL/global/（不与 platforms/requirements 平级）：**\n`;
-            prompt += `   - \`global/FUNCTION_MAP.md\`：功能单元 × 端映射表\n`;
-            prompt += `   - \`global/INTERACTION_MAP.md\`：跨端交互时序图（含同步 API + 异步消息，从 Layer 3 汇总）\n`;
+            prompt += `   **技术视角 → 存放到 .speccore/GLOBAL/overview/（不与 platforms/requirements 平级）：**\n`;
+            prompt += `   - \`overview/FUNCTION_MAP.md\`：功能单元 × 端映射表\n`;
+            prompt += `   - \`overview/INTERACTION_MAP.md\`：跨端交互时序图（含同步 API + 异步消息，从 Layer 3 汇总）\n`;
             prompt += `     - 必须包含 **Mermaid sequenceDiagram**，展示各端之间的核心交互时序\n`;
-            prompt += `   - \`global/API_CONTRACT.yaml\`：全局接口契约（汇总所有后端 API_INVENTORY，含 rate limit、幂等性、版本策略）\n`;
-            prompt += `   - \`global/ARCHITECTURE.md\`：全局架构文档（服务拓扑、数据流、部署关系、容错设计、降级策略、扩容方案）\n`;
+            prompt += `   - \`overview/API_CONTRACT.yaml\`：全局接口契约（汇总所有后端 API_INVENTORY，含 rate limit、幂等性、版本策略）\n`;
+            prompt += `   - \`overview/ARCHITECTURE.md\`：全局架构文档（服务拓扑、数据流、部署关系、容错设计、降级策略、扩容方案）\n`;
             prompt += `     - 必须包含 **Mermaid architecture diagram**（graph TB），展示服务拓扑和部署关系\n`;
             prompt += `     - 必须包含 **Mermaid graph LR**，展示模块间的依赖关系\n`;
-            prompt += `   - \`global/SECURITY_AUDIT.md\`：全局安全审计（鉴权策略矩阵、敏感数据流、攻击面分析、CVE 清单、合规检查）\n`;
-            prompt += `   - \`global/PERFORMANCE_BASELINE.md\`：性能基线（慢查询清单、缓存策略矩阵、并发承载评估、关键路径耗时）\n`;
-            prompt += `   - \`global/DATA_FLOW.md\`：数据流与隐私分析（PII 识别与追踪、数据生命周期、存储/传输/归档策略、GDPR 合规检查）\n`;
+            prompt += `   - \`overview/SECURITY_AUDIT.md\`：全局安全审计（鉴权策略矩阵、敏感数据流、攻击面分析、CVE 清单、合规检查）\n`;
+            prompt += `   - \`overview/PERFORMANCE_BASELINE.md\`：性能基线（慢查询清单、缓存策略矩阵、并发承载评估、关键路径耗时）\n`;
+            prompt += `   - \`overview/DATA_FLOW.md\`：数据流与隐私分析（PII 识别与追踪、数据生命周期、存储/传输/归档策略、GDPR 合规检查）\n`;
             prompt += `     - 必须包含 **Mermaid flowchart**，展示数据从产生到销毁的完整生命周期\n`;
-            prompt += `   - \`global/EXTERNAL_INTEGRATIONS.md\`：外部集成审计（第三方服务清单、SDK 版本与风险、Webhook 接收分布、重复集成识别）\n`;
-            prompt += `   - \`global/DEPLOYMENT.md\`：部署运维分析（容器化状态、CI/CD 流水线、健康检查端点、环境配置差异、日志聚合方案）\n`;
+            prompt += `   - \`overview/EXTERNAL_INTEGRATIONS.md\`：外部集成审计（第三方服务清单、SDK 版本与风险、Webhook 接收分布、重复集成识别）\n`;
+            prompt += `   - \`overview/DEPLOYMENT.md\`：部署运维分析（容器化状态、CI/CD 流水线、健康检查端点、环境配置差异、日志聚合方案）\n`;
             prompt += `     - 必须包含 **Mermaid flowchart**，展示 CI/CD 流水线流程\n`;
-            prompt += `   - \`global/OBSERVABILITY.md\`：可观测性分析（日志链路追踪、错误码体系、监控埋点清单、告警策略、SLA 定义）\n`;
-            prompt += `   - \`global/CONSISTENCY_CHECK.md\`：一致性校验报告（字段/状态/接口/消息/配置）\n\n`;
+            prompt += `   - \`overview/OBSERVABILITY.md\`：可观测性分析（日志链路追踪、错误码体系、监控埋点清单、告警策略、SLA 定义）\n`;
+            prompt += `   - \`overview/CONSISTENCY_CHECK.md\`：一致性校验报告（字段/状态/接口/消息/配置）\n\n`;
             prompt += `3. **生成各端详细文档**（技术视角，从 Layer 3 汇总）：\n`;
             prompt += `   > 存放: .speccore/GLOBAL/platforms/{端名}/\n`;
             prompt += `   **后端端（9项）**：\n`;
@@ -2022,21 +2347,21 @@ async function buildMultiDocPrompt(command, ctx, options) {
             prompt += `| :--- | :--- | :--- |\n`;
             prompt += `| requirements/REQUIREMENT.md | 产品总监视角 | 需求总纲：愿景、用户画像、场景地图、功能全景、优先级矩阵、里程碑、风险预判 |\n`;
             prompt += `| requirements/{前端端}/REQUIREMENT.md | 前端产品经理视角 | 信息架构、用户旅程、页面清单、交互设计、状态反馈、权限角色、响应式策略 |\n`;
-            prompt += `\n### 全局技术性文档（Layer 4 汇总生成，v6.98.0+）\n`;
-            prompt += `> 存放: .speccore/GLOBAL/global/（不与 platforms/requirements 平级）\n\n`;
+            prompt += `\n### 全局技术性文档（Layer 4 汇总生成，v7.2.0+）\n`;
+            prompt += `> 存放: .speccore/GLOBAL/overview/（不与 platforms/requirements 平级）\n\n`;
             prompt += `| 文档 | 视角 | 内容 |\n`;
             prompt += `| :--- | :--- | :--- |\n`;
-            prompt += `| global/FUNCTION_MAP.md | 架构视角 | 功能单元 × 端映射表 |\n`;
-            prompt += `| global/INTERACTION_MAP.md | 架构视角 | 跨端交互时序图（同步 API + 异步消息） |\n`;
-            prompt += `| global/API_CONTRACT.yaml | 技术视角 | 全局接口契约（含 rate limit、幂等性、版本策略、废弃标记） |\n`;
-            prompt += `| global/ARCHITECTURE.md | 技术视角 | 全局架构（服务拓扑、数据流、部署关系、容错、降级、扩容） |\n`;
-            prompt += `| global/SECURITY_AUDIT.md | 安全视角 | 鉴权矩阵、敏感数据流、攻击面、CVE 清单、合规检查 |\n`;
-            prompt += `| global/PERFORMANCE_BASELINE.md | 性能视角 | 慢查询清单、缓存策略矩阵、并发承载、关键路径耗时 |\n`;
-            prompt += `| global/DATA_FLOW.md | 数据视角 | PII 识别追踪、数据生命周期、存储/传输/归档、GDPR 合规 |\n`;
-            prompt += `| global/EXTERNAL_INTEGRATIONS.md | 集成视角 | 第三方服务清单、SDK 风险、Webhook 分布、重复集成识别 |\n`;
-            prompt += `| global/DEPLOYMENT.md | 运维视角 | 容器化、CI/CD、健康检查、环境差异、日志聚合 |\n`;
-            prompt += `| global/OBSERVABILITY.md | 可观测视角 | 日志链路、错误码体系、监控埋点、告警策略、SLA |\n`;
-            prompt += `| global/CONSISTENCY_CHECK.md | 质量视角 | 一致性校验报告（字段/状态/接口/消息/配置） |\n`;
+            prompt += `| overview/FUNCTION_MAP.md | 架构视角 | 功能单元 × 端映射表 |\n`;
+            prompt += `| overview/INTERACTION_MAP.md | 架构视角 | 跨端交互时序图（同步 API + 异步消息） |\n`;
+            prompt += `| overview/API_CONTRACT.yaml | 技术视角 | 全局接口契约（含 rate limit、幂等性、版本策略、废弃标记） |\n`;
+            prompt += `| overview/ARCHITECTURE.md | 技术视角 | 全局架构（服务拓扑、数据流、部署关系、容错、降级、扩容） |\n`;
+            prompt += `| overview/SECURITY_AUDIT.md | 安全视角 | 鉴权矩阵、敏感数据流、攻击面、CVE 清单、合规检查 |\n`;
+            prompt += `| overview/PERFORMANCE_BASELINE.md | 性能视角 | 慢查询清单、缓存策略矩阵、并发承载、关键路径耗时 |\n`;
+            prompt += `| overview/DATA_FLOW.md | 数据视角 | PII 识别追踪、数据生命周期、存储/传输/归档、GDPR 合规 |\n`;
+            prompt += `| overview/EXTERNAL_INTEGRATIONS.md | 集成视角 | 第三方服务清单、SDK 风险、Webhook 分布、重复集成识别 |\n`;
+            prompt += `| overview/DEPLOYMENT.md | 运维视角 | 容器化、CI/CD、健康检查、环境差异、日志聚合 |\n`;
+            prompt += `| overview/OBSERVABILITY.md | 可观测视角 | 日志链路、错误码体系、监控埋点、告警策略、SLA |\n`;
+            prompt += `| overview/CONSISTENCY_CHECK.md | 质量视角 | 一致性校验报告（字段/状态/接口/消息/配置） |\n`;
             prompt += `\n### 后端端技术性文档（9项，Layer 3/4 汇总）\n`;
             prompt += `> 存放: .speccore/GLOBAL/platforms/{后端端名}/\n\n`;
             prompt += `| 文档 | 内容 |\n`;
@@ -2097,6 +2422,175 @@ async function buildMultiDocPrompt(command, ctx, options) {
         prompt += `\n⚠️ 如 CONSTITUTION.md 中「源码路径」为空或路径不存在: 提示用户先配置，给出三个选项：\n`;
         prompt += `   [1] 停止分析 → 配置后重来 | [2] 跳过源码 → 只用文档分析 | [3] 手动指定路径后继续\n`;
         prompt += '\n' + (0, questions_1.buildAutoModeInstruction)('analyze', iter) + '\n';
+        // v7.2.0+: Layer 专注指令 — 在 Prompt 末尾再次强化约束
+        prompt += `\n## 🎯 Layer ${targetLayer} 执行清单（必须逐项完成）\n\n`;
+        prompt += `> ⚠️ **再次强调**: 你只执行 Layer ${targetLayer}，不要提前做其他层。\n\n`;
+        if (targetLayer === 1) {
+            prompt += `- [ ] Read CONSTITUTION.md 获取所有端和源码路径\n`;
+            prompt += `- [ ] 对每个端扫描 10 个维度，生成 _INDEX.md\n`;
+            prompt += `- [ ] 提取可复用模式写入 PATTERNS/\n`;
+            prompt += `- [ ] 提取语义标签写入 semantic-tags.json\n`;
+            prompt += `- [ ] 写入完成后执行: \`speccore analyze --scope global --layer 2\`\n`;
+        }
+        else if (targetLayer === 2) {
+            prompt += `- [ ] Read 所有 Layer 1 生成的 _INDEX.md\n`;
+            prompt += `- [ ] 匹配前后端接口，生成关联矩阵\n`;
+            prompt += `- [ ] 识别公共服务、消息流、定时任务影响\n`;
+            prompt += `- [ ] 归纳功能模块，生成 _MODULES.md\n`;
+            prompt += `- [ ] 写入 _ASSOCIATION.md + _MODULES.md\n`;
+            prompt += `- [ ] 写入完成后执行: \`speccore analyze --scope global --layer 3\`\n`;
+        }
+        else if (targetLayer === 3) {
+            const filter = options?.filter;
+            prompt += `- [ ] Read Layer 2 的 _MODULES.md 获取功能模块清单\n`;
+            if (filter) {
+                prompt += `> 🔍 **按需分析**: 只分析与 "${filter}" 匹配的模块\n`;
+                prompt += `> 从 _MODULES.md 中筛选涉及 ${filter} 的功能模块，其他模块跳过\n`;
+            }
+            prompt += `- [ ] ${filter ? '筛选匹配的模块，逐个' : '逐个功能模块'}深入分析（读详细源码）\n`;
+            prompt += `- [ ] 每个模块生成：API 设计、数据模型、业务规则、交互时序\n`;
+            prompt += `- [ ] 时序图/流程图/状态图用 Mermaid 嵌入\n`;
+            prompt += `- [ ] 提取模块级模式补充到 PATTERNS/\n`;
+            prompt += `- [ ] 写入完成后执行: \`speccore analyze --scope global --layer 4${filter ? ' --filter ' + filter : ''}\`\n`;
+        }
+        else if (targetLayer === 4) {
+            // v7.2.0+: Layer 4 拆分子层或单文档深度分析
+            const deepDoc = options?.deep;
+            const subLayerTarget = progress.subLayer?.next || '4a';
+            if (deepDoc) {
+                // --deep 模式：单文档深度分析
+                const outlinePath = (0, path_1.join)(process.cwd(), '.speccore', 'cache', `deep-outline-${deepDoc.replace(/\//g, '-')}.md`);
+                const hasOutline = await (0, fs_extra_1.pathExists)(outlinePath);
+                if (options?.iterative && !hasOutline) {
+                    // 迭代模式第一步：输出大纲
+                    prompt += `## 🎯 Layer 4 — 单文档深度分析: ${deepDoc}（大纲阶段）\n\n`;
+                    prompt += `> ⚠️ **当前阶段**: 你只需要输出 **${deepDoc} 的文档大纲**。\n`;
+                    prompt += `> 不要写详细内容，只输出章节结构 + 每个章节的一句话说明。\n\n`;
+                    prompt += `**强制输入**: \n`;
+                    prompt += `- Read Layer 1 的所有 _INDEX.md\n`;
+                    prompt += `- Read Layer 2 的 _ASSOCIATION.md + _MODULES.md\n`;
+                    prompt += `- Read Layer 3 的功能模块深入文档\n`;
+                    prompt += `- Read \`.speccore/cache/structured-data.json\`（API/Entity 结构化数据）\n\n`;
+                    prompt += `**输出格式**: \n`;
+                    prompt += `\`\`\`markdown\n`;
+                    prompt += `# ${deepDoc.replace('.md', '')}\n`;
+                    prompt += `\n`;
+                    prompt += `## 1. 章节标题\n`;
+                    prompt += `> 一句话说明该章节内容\n`;
+                    prompt += `\n`;
+                    prompt += `## 2. 章节标题\n`;
+                    prompt += `> 一句话说明该章节内容\n`;
+                    prompt += `\`\`\`\n\n`;
+                    prompt += `**下一步**: 大纲输出后，用户会审核修改，然后执行 \`speccore analyze --scope global --layer 4 --deep ${deepDoc} --iterative\` 进入逐节填充阶段。\n`;
+                }
+                else if (options?.iterative && hasOutline) {
+                    // 迭代模式第二步：根据大纲逐节填充
+                    const outlineContent = await (0, fs_extra_2.readFile)(outlinePath, 'utf-8');
+                    prompt += `## 🎯 Layer 4 — 单文档深度分析: ${deepDoc}（逐节填充阶段）\n\n`;
+                    prompt += `> ⚠️ **当前阶段**: 根据已确认的大纲，逐节填充详细内容。\n`;
+                    prompt += `> 每次只填充 **一节**，确保深度和质量。\n\n`;
+                    prompt += `**已确认大纲**: \n`;
+                    prompt += outlineContent.slice(0, 2000); // 限制长度
+                    prompt += `\n\n`;
+                    prompt += `**强制输入**: \n`;
+                    prompt += `- Read Layer 1-3 的所有产物\n`;
+                    prompt += `- Read \`.speccore/cache/structured-data.json\`\n`;
+                    prompt += `- 如涉及代码细节，Read 相关源码文件\n\n`;
+                    prompt += `**深度要求**: \n`;
+                    prompt += `- 不要写"待导入"、"待补充"等占位内容\n`;
+                    prompt += `- 每个表格必须有真实数据\n`;
+                    prompt += `- 每个结论必须有证据（引用文件名/类名/方法名）\n`;
+                    prompt += `- 必须包含 Mermaid 图表（如适用）\n\n`;
+                    prompt += `**输出**: 只输出当前节的完整内容（不是整份文档）\n`;
+                }
+                else {
+                    // 非迭代模式：一次性输出完整文档
+                    prompt += `## 🎯 Layer 4 — 单文档深度分析: ${deepDoc}\n\n`;
+                    prompt += `> ⚠️ **专注约束**: 你只生成 **${deepDoc}** 这一份文档，不要生成其他文档。\n`;
+                    prompt += `> 你必须深入分析，不要写框架/占位符。每节必须有实质性内容。\n\n`;
+                    prompt += `**强制输入**: \n`;
+                    prompt += `- Read Layer 1 的所有 _INDEX.md（获取源码结构索引）\n`;
+                    prompt += `- Read Layer 2 的 _ASSOCIATION.md + _MODULES.md（获取跨端关联）\n`;
+                    prompt += `- Read Layer 3 的功能模块深入文档（获取详细分析结果）\n`;
+                    prompt += `- Read \`.speccore/cache/structured-data.json\`（API/Entity 结构化数据）\n`;
+                    prompt += `- 如果涉及代码细节，直接 Read 相关源码文件，引用具体代码片段\n\n`;
+                    prompt += `**深度要求**: \n`;
+                    prompt += `- 不要写"待导入"、"待补充"、"示例"等占位内容\n`;
+                    prompt += `- 每个表格必须有真实数据（从 Layer 1-3 提取）\n`;
+                    prompt += `- 每个结论必须有证据（引用具体文件名/类名/方法名）\n`;
+                    prompt += `- 如果信息不足，明确标注"信息不足: 需要读取 xxx 文件"\n`;
+                    prompt += `- 必须包含 Mermaid 图表（如适用）\n\n`;
+                    prompt += `**输出**: 只输出 \`${deepDoc}\` 的完整内容\n`;
+                }
+            }
+            else {
+                // 子层模式：每次只生成一个子层
+                prompt += `## 🌍 Layer 4: 全局汇总 — 子层 ${subLayerTarget}/4\n\n`;
+                prompt += `> ⚠️ **专注约束**: 你当前只执行 **子层 ${subLayerTarget}**，不要生成其他子层的文档。\n`;
+                prompt += `> 子层完成后执行: \`speccore analyze --scope global --layer 4\` 进入下一子层。\n\n`;
+                prompt += `**强制输入**: \n`;
+                prompt += `- Read Layer 1 的所有 _INDEX.md\n`;
+                prompt += `- Read Layer 2 的 _ASSOCIATION.md + _MODULES.md\n`;
+                prompt += `- Read Layer 3 的功能模块深入文档\n\n`;
+                if (subLayerTarget === '4a') {
+                    prompt += `**子层 4a: 产品视角文档（2-3 份）**\n`;
+                    prompt += `1. \`requirements/REQUIREMENT.md\` — 全局需求总纲\n`;
+                    prompt += `   - 产品愿景、目标用户画像、核心场景地图\n`;
+                    prompt += `   - 按业务场景组织：用户故事 → 操作流程 → 业务规则 → 边界条件 → 验收标准\n`;
+                    prompt += `   - 功能优先级矩阵（P0/P1/P2）\n`;
+                    prompt += `   - 必须从 Layer 3 的功能模块分析中提取真实内容，不要臆造\n`;
+                    prompt += `2. 各前端端 \`requirements/{端}/REQUIREMENT.md\` — 只生成已有前端端的需求\n`;
+                    prompt += `   - 信息架构、用户旅程、页面清单、交互设计\n`;
+                    prompt += `   - 从 Layer 1 的前端 _INDEX.md 提取页面/路由信息\n`;
+                    prompt += `   - 从 Layer 3 的模块分析提取交互流程\n`;
+                }
+                else if (subLayerTarget === '4b') {
+                    prompt += `**子层 4b: 全局技术核心文档（3-4 份）**\n`;
+                    prompt += `1. \`overview/FUNCTION_MAP.md\` — 功能单元 × 端映射表\n`;
+                    prompt += `   - 从 Layer 2 的 _MODULES.md 提取功能模块\n`;
+                    prompt += `   - 每个功能单元标注：涉及端、核心页面、核心接口、状态枚举\n`;
+                    prompt += `2. \`overview/ARCHITECTURE.md\` — 全局架构\n`;
+                    prompt += `   - 服务拓扑（从 Layer 1 的后端 _INDEX.md 提取服务名和依赖）\n`;
+                    prompt += `   - 数据流（从 Layer 3 的模块分析提取）\n`;
+                    prompt += `   - 必须包含 Mermaid architecture diagram\n`;
+                    prompt += `3. \`overview/API_CONTRACT.yaml\` — 全局接口契约\n`;
+                    prompt += `   - 汇总所有后端端的 API_INVENTORY（从 Layer 1 提取）\n`;
+                    prompt += `   - 标注 rate limit、幂等性、版本策略\n`;
+                    prompt += `4. \`overview/INTERACTION_MAP.md\` — 跨端交互时序图\n`;
+                    prompt += `   - 从 Layer 3 的模块时序图汇总\n`;
+                    prompt += `   - 必须包含 Mermaid sequenceDiagram\n`;
+                }
+                else if (subLayerTarget === '4c') {
+                    prompt += `**子层 4c: 全局技术扩展文档（4-5 份）**\n`;
+                    prompt += `1. \`overview/SECURITY_AUDIT.md\` — 安全审计\n`;
+                    prompt += `2. \`overview/PERFORMANCE_BASELINE.md\` — 性能基线\n`;
+                    prompt += `3. \`overview/DATA_FLOW.md\` — 数据流与隐私\n`;
+                    prompt += `4. \`overview/DEPLOYMENT.md\` — 部署运维\n`;
+                    prompt += `5. \`overview/CONSISTENCY_CHECK.md\` — 一致性校验\n`;
+                    prompt += `   - 从 Layer 2 的关联分析提取不一致项\n`;
+                }
+                else if (subLayerTarget === '4d') {
+                    prompt += `**子层 4d: 各端技术文档**\n`;
+                    prompt += `后端端（每端 9 项，但本次只生成核心 3 项，其余后续补充）:\n`;
+                    prompt += `1. \`API_INVENTORY.md\` — 从 Layer 1 的 _INDEX.md 提取完整接口清单\n`;
+                    prompt += `2. \`DATA_MODEL.md\` — 从 Layer 1 的 Entity 目录 + Layer 3 的模块分析提取\n`;
+                    prompt += `3. \`BUSINESS_RULES.md\` — 从 Layer 3 的模块分析提取业务规则\n`;
+                    prompt += `前端端（每端 9 项，但本次只生成核心 3 项）:\n`;
+                    prompt += `1. \`UI_FLOW.md\` — 从 Layer 1 的路由 + Layer 3 的模块分析提取\n`;
+                    prompt += `2. \`API_CALL_MAP.md\` — 从 Layer 1 的 API 调用提取\n`;
+                    prompt += `3. \`STATE_MANAGEMENT.md\` — 从 Layer 1 的 store 目录提取\n`;
+                }
+                prompt += `\n**质量要求**: \n`;
+                prompt += `- 禁止写"待导入"、"待补充"等占位符\n`;
+                prompt += `- 每个表格必须有真实数据（从 Layer 1-3 提取）\n`;
+                prompt += `- 如果信息不足，明确标注"信息不足: 需要读取 xxx"\n`;
+            }
+        }
+        prompt += `\n## 📝 写入方式\n`;
+        prompt += `使用 \`speccore analyze --apply '{"文件路径":"内容"}' --scope global\` 写入。\n`;
+        prompt += `- platforms/ 和 requirements/ 下的文件按原路径写（如 \`platforms/backend/_INDEX.md\`）\n`;
+        prompt += `- overview/ 下的文件写纯文件名即可（如 \`ARCHITECTURE.md\` 自动路由到 overview/）\n`;
+        prompt += `- PATTERNS/ 下的文件写 \`PATTERNS/{分类}/{模式名}.md\`\n`;
         return await injectGraphSummary(prompt);
     }
     const docs = [
@@ -2445,6 +2939,18 @@ sequenceDiagram
             }
         }
     }
+    // v7.2.0+: 细粒度分析 — 只生成指定文档的指定功能
+    if (options?.docName && options?.featureName && !isGlobal) {
+        const targetDoc = options.docName.endsWith('.md') ? options.docName : `${options.docName}.md`;
+        const filtered = taskDocs.filter(([n]) => n === targetDoc || n === options.docName);
+        if (filtered.length > 0) {
+            taskDocs = filtered;
+        }
+        else {
+            // 不在默认文档列表中，创建单文档分析任务
+            taskDocs = [[targetDoc, `# ${targetDoc.replace('.md', '')} — ${options.featureName}\n\n> ${iter} | ${now}\n> 分析范围: 仅「${options.featureName}」功能单元\n\n## 写作要求\n针对「${options.featureName}」进行深入分析，基于需求文档和代码上下文补充详细内容。\n`]];
+        }
+    }
     // ── 用户自定义模板集成（v6.45.0+）──
     const templateLevel = isGlobal ? 'global' : (isTask ? 'task' : 'iteration');
     const userTemplates = await loadUserTemplates(templateLevel, isTask ? taskType : undefined, ctx.platform);
@@ -2470,6 +2976,51 @@ sequenceDiagram
         techDoc[1] = `# 技术架构（跨端全局）\n\n> ${iter}\n\n## 写作要求\n撰写整体技术架构，覆盖所有端的交互关系：\n- 系统整体分层设计（各端在架构中的位置）\n- 跨端交互协议（前端↔后端通信方式、数据流向）\n- 中间件选型（缓存、消息队列、网关等）\n- 数据库整体设计（核心表结构、ER 关系）\n- 技术栈选型及理由\n`;
     }
     let prompt = `\n# 任务: ${command}${task} (${taskDocs.length}个文档 · ${isTask ? `类型:${taskType}` : '迭代全量'}${ctx.phase ? ` · Phase ${ctx.phase}` : ''})\n\n`;
+    // v7.2.0+: 迭代分析代码关联 — 注入结构化数据和语义定位上下文
+    if (!isGlobal && ctx.withCode && ctx.iteration && ctx.iteration !== 'GLOBAL') {
+        try {
+            // 1. 提取结构化数据（如果还没有）
+            const structuredDataPath = (0, path_1.join)(process.cwd(), '.speccore', 'cache', 'structured-data.json');
+            if (!(await (0, fs_extra_1.pathExists)(structuredDataPath))) {
+                const constitutionPath = (0, path_1.join)(process.cwd(), '.speccore', 'CONSTITUTION.md');
+                let sourcePaths = ['src'];
+                if (await (0, fs_extra_1.pathExists)(constitutionPath)) {
+                    const content = await (0, fs_extra_2.readFile)(constitutionPath, 'utf-8');
+                    const match = content.match(/源码路径[\s\S]*?\n\s*-\s*`?([^`\n]+)`?/g);
+                    if (match) {
+                        sourcePaths = match.map(m => m.replace(/.*-\s*`?/, '').replace(/`?$/, '').trim()).filter(Boolean);
+                    }
+                }
+                const { extractStructuredData } = await Promise.resolve().then(() => __importStar(require('../core/structured-extractor')));
+                await extractStructuredData(process.cwd(), sourcePaths);
+            }
+            // 2. 注入结构化数据摘要到 Prompt
+            if (await (0, fs_extra_1.pathExists)(structuredDataPath)) {
+                const data = await (0, fs_extra_2.readFile)(structuredDataPath, 'utf-8');
+                const structured = JSON.parse(data);
+                const stats = structured.stats || {};
+                prompt += `## 📊 代码结构化数据（自动提取）\n\n`;
+                prompt += `> 已扫描项目源码，提取以下结构化信息供分析参考：\n\n`;
+                prompt += `- API 接口: ${stats.totalApis || 0} 个\n`;
+                prompt += `- 数据实体: ${stats.totalEntities || 0} 个\n`;
+                prompt += `- 页面路由: ${stats.totalRoutes || 0} 个\n`;
+                prompt += `- 前端组件: ${stats.totalComponents || 0} 个\n`;
+                prompt += `- 扫描文件: ${stats.totalFiles || 0} 个\n\n`;
+                prompt += `> 💡 分析技术方案时，可参考 \`.speccore/cache/structured-data.json\` 中的 API/Entity/Route/Component 清单\n`;
+                prompt += `> 如需了解具体实现，直接 Read 对应源码文件\n\n`;
+            }
+            // 3. 语义定位：如果指定了功能名，自动关联上下文
+            if (options?.featureName) {
+                const { buildFeatureContext, buildFeatureContextPrompt } = await Promise.resolve().then(() => __importStar(require('../core/semantic-locator')));
+                const iterDir = await (0, context_1.getIterationDir)(ctx.iteration);
+                const featureCtx = await buildFeatureContext(process.cwd(), iterDir, options.featureName, options.docName);
+                prompt += buildFeatureContextPrompt(featureCtx);
+            }
+        }
+        catch (e) {
+            logger_1.logger.warn(`   ⚠️ 代码关联注入失败: ${e.message}`);
+        }
+    }
     // v6.80.0+: 注入需求质量上下文（迭代级分析时）
     if (!isGlobal && !isTask && ctx.iteration && ctx.iteration !== 'GLOBAL') {
         try {
@@ -2518,7 +3069,7 @@ sequenceDiagram
     prompt += `## 🚨 最高优先级警告（违反将导致分析失败）\n\n`;
     prompt += `### ⛔ 绝对禁止创建任何额外目录\n`;
     prompt += `- ❌ **错误行为**：创建 020-specs/1001/、020-specs/1002/、020-specs/错误码/、020-specs/工程标识/ 等垃圾目录\n`;
-    prompt += `- ✅ **正确行为**：只使用 CLI 预创建的 global/ 和 {端名}/ 目录，不要手动 mkdir 或 Write 到不存在的目录\n`;
+    prompt += `- ✅ **正确行为**：只使用 CLI 预创建的 overview/ 和 {端名}/ 目录，不要手动 mkdir 或 Write 到不存在的目录\n`;
     prompt += `- ⚠️ **后果**：如果创建额外目录，会导致后续 split/execute 命令找不到文件，整个工作流失败\n\n`;
     prompt += `###  绝对禁止直接用 Write 工具写文件\n`;
     prompt += `- ❌ **错误行为**：Write("020-specs/overview/ANALYSIS.md", content) 或直接 Write 到任何路径\n`;
@@ -2528,7 +3079,7 @@ sequenceDiagram
     prompt += `### ✅ 正确的目录结构\n`;
     prompt += `\`\`\`\n`;
     prompt += `020-specs/\n`;
-    prompt += `├── global/          ← REQUIREMENT.md, ANALYSIS.md, DEPS.md（跨端通用）\n`;
+    prompt += `├── overview/        ← REQUIREMENT.md, ANALYSIS.md, DEPS.md（跨端通用）\n`;
     prompt += `├── admin-web/       ← TECH.md, TEST.md, UI_SPEC.md（Admin 端专属）\n`;
     prompt += `├── booking-service/ ← TECH.md, TEST.md（后端服务专属）\n`;
     prompt += `├── h5-mobile/       ← TECH.md, TEST.md, UI_SPEC.md（H5 端专属）\n`;
@@ -2640,9 +3191,9 @@ sequenceDiagram
             prompt += `2. 读取全局层产物（建立全局视角，重要）\n`;
             prompt += `   在读取迭代需求之前，先 Read 全局层已有产物，了解系统当前状态：\n`;
             prompt += `   a. Read .speccore/GLOBAL/requirements/REQUIREMENT.md → 系统已有功能清单\n`;
-            prompt += `   b. Read .speccore/GLOBAL/global/FUNCTION_MAP.md → 已有功能单元和涉及端\n`;
-            prompt += `   c. Read .speccore/GLOBAL/global/API_CONTRACT.yaml → 已有接口契约\n`;
-            prompt += `   d. Read .speccore/GLOBAL/global/ARCHITECTURE.md → 全局架构（如有）\n`;
+            prompt += `   b. Read .speccore/GLOBAL/overview/FUNCTION_MAP.md → 已有功能单元和涉及端\n`;
+            prompt += `   c. Read .speccore/GLOBAL/overview/API_CONTRACT.yaml → 已有接口契约\n`;
+            prompt += `   d. Read .speccore/GLOBAL/overview/ARCHITECTURE.md → 全局架构（如有）\n`;
             prompt += `   e. Read .speccore/GLOBAL/platforms/{相关端}/_INDEX.md → 各端已有页面和接口索引\n`;
             prompt += `   f. Read .speccore/GLOBAL/platforms/_shared/_ASSOCIATION.md → 前后端关联矩阵（如有）\n`;
             prompt += `   g. Read .speccore/GLOBAL/platforms/_shared/_MODULES.md → 功能模块候选（如有）\n`;
@@ -2711,7 +3262,7 @@ sequenceDiagram
             // v6.70.0+: 跨端功能映射表（FUNCTION_MAP.md）
             // v6.71.3+: 增加与全局层关联分析
             prompt += `7a. **迭代需求与全局层关联分析（重要）**：在生成功能模块清单时，必须对比全局层产物\n`;
-            prompt += `   - 对比迭代需求中的功能模块 vs .speccore/GLOBAL/global/FUNCTION_MAP.md 中的功能单元\n`;
+            prompt += `   - 对比迭代需求中的功能模块 vs .speccore/GLOBAL/overview/FUNCTION_MAP.md 中的功能单元\n`;
             prompt += `   - 标注每个功能模块的「全局对比」类型（新增/扩展/重构/复用）\n`;
             prompt += `   - 识别冲突：如迭代需求修改了全局层已有接口的字段/路径 → 在 RISK.md 中标注\n`;
             prompt += `   - 识别依赖：如迭代的新功能依赖全局层的某个功能 → 在 FUNCTION_MAP.md「依赖任务」中标注\n\n`;
@@ -2773,7 +3324,7 @@ sequenceDiagram
             prompt += `     - MONITOR.md（监控指标）\n`;
             prompt += `   - **禁止**：不要创建 020-specs/ 下的任何额外子目录（如数字编号、中文名称等）\n`;
             prompt += `   - **禁止直接用 Write 工具写文件到 020-specs/**：必须通过 \`speccore analyze --apply '{"文件名":"内容"}' -I ${iter}\` 写入\n`;
-            prompt += `   - ⚠️ 直接 Write 会导致目录结构错误（所有文件扁平在根目录），必须走 --apply 让 CLI 自动路由到 global/ 或 {端名}/ 子目录\n`;
+            prompt += `   - ⚠️ 直接 Write 会导致目录结构错误（所有文件扁平在根目录），必须走 --apply 让 CLI 自动路由到 overview/ 或 {端名}/ 子目录\n`;
             if (ctx.phase !== '1') {
                 // 端专业性约束只在默认模式（全量）中输出
                 prompt += `\n## ⚠️ 端专业性约束\n`;
@@ -2864,7 +3415,7 @@ sequenceDiagram
         prompt += `\n## ⚠️ 重要：Phase 1 完成后的下一步\n\n`;
         prompt += `当你通过 --apply 写入所有综合文档后，CLI 会检测到项目有多个端（≥2 个端）。\n`;
         prompt += `**此时你需要主动询问用户**：\n\n`;
-        prompt += `"✅ Phase 1 已完成，生成了 global/ 的综合文档。\n`;
+        prompt += `"✅ Phase 1 已完成，生成了 overview/ 的综合文档。\n`;
         prompt += `检测到项目有 ${'{'}端列表{'}'} 个端，需要继续执行 Phase 2 生成各端专属文档吗？\n`;
         prompt += `请确认：输入 '继续' 或 'yes' 以执行 Phase 2"\n\n`;
         prompt += `**如果用户确认继续**，你需要执行：\n`;