speccore 8.1.2 → 8.3.2

package/dist/commands/analyze.js

@@ -33,7 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNITS_CACHE_DIR = void 0;
 exports.analyzeCommand = analyzeCommand;
+exports.extractIterationUnits = extractIterationUnits;
+exports.saveUnitAnalysis = saveUnitAnalysis;
+exports.loadUnitAnalyses = loadUnitAnalyses;
+exports.detectPendingUnits = detectPendingUnits;
+exports.consolidateUnitAnalyses = consolidateUnitAnalyses;
+exports.buildUnitAnalysisPrompt = buildUnitAnalysisPrompt;
 /**
  * analyze — 统一分析命令
  *
@@ -61,6 +68,7 @@ const index_guard_1 = require("../core/index-guard");
 const spec_paths_1 = require("../core/spec-paths");
 const spec_skeleton_1 = require("../core/spec-skeleton");
 const unified_retrieval_1 = require("../core/unified-retrieval");
+const unit_context_assembler_1 = require("../core/unit-context-assembler");
 const pipeline_engine_1 = require("../core/pipeline-engine");
 const change_detection_1 = require("../core/change-detection");
 const streaming_analyzer_1 = require("../core/streaming-analyzer");
@@ -79,8 +87,12 @@ async function analyzeCommand(options) {
     if (options.scope === 'global' && !options.iteration) {
         options.iteration = 'GLOBAL';
     }
-    // ── --full / --phase 模式: 委托给 synthesizeCommand（原 synthesize 命令） ──
-    if (options.full || options.phase) {
+    // ── --full 模式: 委托给 synthesizeCommand（原 synthesize 命令） ──
+    // v8.3.1+ 修复：--phase 不再委托给 synthesize，analyze 的 Phase 1/2 由 analyze 自己处理
+    // 原因：analyze --phase 2 应该生成端级文档（{端}/TECH.md/DEV_GUIDE.md），
+    //       而 synthesize --phase 2 是跨端关系提取（CROSS_PLATFORM.md/ARCHITECTURE.md），
+    //       两者完全不同，委托会导致用户永远无法执行 analyze 的 Phase 2
+    if (options.full) {
         const { synthesizeCommand } = await Promise.resolve().then(() => __importStar(require('./synthesize')));
         return synthesizeCommand({
             iteration: options.iteration,
@@ -351,6 +363,103 @@ async function analyzeCommand(options) {
         logger_1.logger.info(`   speccore reindex                    # 完整重建索引`);
         return;
     }
+    // ── v8.2.0+: 功能单元聚焦分析模式（--extract-units / --unit / --consolidate / --resume-units）──
+    if (options.extractUnits || options.unit || options.consolidate || options.resumeUnits) {
+        const iter = options.iteration || await (0, context_1.getDefaultIteration)();
+        if (!iter) {
+            logger_1.logger.error('请指定迭代: -I <iteration>');
+            return;
+        }
+        const iterDir = await (0, context_1.getIterationDir)(iter);
+        // Step 1: 提取功能单元清单
+        let units = [];
+        const unitsCachePath = (0, path_1.join)(process.cwd(), exports.UNITS_CACHE_DIR, iter, 'units.json');
+        if (await (0, fs_extra_1.pathExists)(unitsCachePath)) {
+            try {
+                units = JSON.parse(await (0, fs_extra_2.readFile)(unitsCachePath, 'utf-8'));
+                logger_1.logger.info(`📋 已加载功能单元清单: ${units.length} 个`);
+            }
+            catch { /* fall through to re-extract */ }
+        }
+        if (units.length === 0 || options.extractUnits) {
+            units = await extractIterationUnits(iterDir);
+            await (0, fs_extra_1.ensureDir)((0, path_1.dirname)(unitsCachePath));
+            await (0, fs_extra_1.writeFile)(unitsCachePath, JSON.stringify(units, null, 2));
+            logger_1.logger.info(`📋 功能单元清单已提取: ${units.length} 个`);
+            for (const u of units) {
+                logger_1.logger.info(`   ${u.id}: ${u.name} (${u.source}#L${u.sourceRange.startLine})`);
+            }
+            if (options.extractUnits) {
+                logger_1.logger.info('');
+                logger_1.logger.info('📋 下一步: 逐个分析功能单元');
+                logger_1.logger.info(`   speccore analyze --prompt -I ${iter} --unit M-01`);
+                return;
+            }
+        }
+        // Step 2: 汇总模式（--consolidate）
+        if (options.consolidate) {
+            const analyses = await loadUnitAnalyses(iter);
+            if (analyses.length === 0) {
+                logger_1.logger.warn('⚠️ 尚未完成任何单元分析，请先运行 --unit 模式');
+                logger_1.logger.info(`   speccore analyze --prompt -I ${iter} --unit M-01`);
+                return;
+            }
+            const report = await consolidateUnitAnalyses(iter, units, analyses);
+            if (options.prompt) {
+                process.stdout.write(`[SPECCORE_PROMPT]\n${report}\n\n## 操作选项\n\n**选项 A：确认通过，写入所有文档**\n\`\`\`bash\nspeccore analyze --apply '[DOC:...]' -I ${iter}\n\`\`\`\n`);
+                process.exitCode = 10;
+                return;
+            }
+            if (options.apply) {
+                // 直接通过 --apply 的 [DOC:xxx] 处理逻辑写入
+                logger_1.logger.info(`📋 汇总报告已生成，共 ${analyses.length}/${units.length} 个单元`);
+                return;
+            }
+            logger_1.logger.info(`📋 汇总报告（${analyses.length}/${units.length} 个单元）`);
+            logger_1.logger.info('   使用 --prompt 查看完整报告，或 --apply 直接写入');
+            return;
+        }
+        // Step 3: 断点续跑（--resume-units）
+        let targetUnit;
+        if (options.resumeUnits) {
+            const pending = await detectPendingUnits(iter, units);
+            if (pending.length === 0) {
+                logger_1.logger.success('🎉 所有功能单元分析已完成！');
+                logger_1.logger.info('   运行 --consolidate 汇总为统一报告');
+                logger_1.logger.info(`   speccore analyze --prompt -I ${iter} --consolidate`);
+                return;
+            }
+            targetUnit = pending[0];
+            logger_1.logger.info(`🔄 断点续跑: ${targetUnit.id} ${targetUnit.name}（剩余 ${pending.length} 个）`);
+        }
+        // Step 4: 分析单个单元（--unit M-01）
+        if (options.unit) {
+            targetUnit = units.find(u => u.id === options.unit);
+            if (!targetUnit) {
+                logger_1.logger.error(`未找到功能单元: ${options.unit}`);
+                logger_1.logger.info(`   可用单元: ${units.map(u => u.id).join(', ')}`);
+                return;
+            }
+        }
+        if (targetUnit && options.prompt) {
+            const prompt = await buildUnitAnalysisPrompt(iterDir, iter, targetUnit, units);
+            process.stdout.write(`[SPECCORE_PROMPT]\n${prompt}`);
+            process.exitCode = 10;
+            return;
+        }
+        if (targetUnit && options.apply) {
+            // AI 输出的是 [DOC:xxx] 格式，由 --apply 的 parseDocMarkers 处理
+            logger_1.logger.info(`✅ 功能单元 ${targetUnit.id} 分析结果已接收`);
+            logger_1.logger.info('   结果已通过 --apply 的 [DOC:xxx] 解析写入');
+            return;
+        }
+        if (targetUnit) {
+            logger_1.logger.info(`📋 功能单元: ${targetUnit.id} ${targetUnit.name}`);
+            logger_1.logger.info(`   来源: ${targetUnit.source}#L${targetUnit.sourceRange.startLine}`);
+            logger_1.logger.info('   使用 --prompt 生成分析 Prompt，或 --apply 写入分析结果');
+            return;
+        }
+    }
     // 模糊匹配端名
     if (options.platform) {
         const resolved = await (0, platform_registry_1.resolvePlatform)(options.platform);
@@ -368,6 +477,9 @@ async function analyzeCommand(options) {
     if (options.scope !== 'global') {
         await (0, index_guard_1.warnIfIndexStale)(process.cwd(), 'analyze', options.iteration);
     }
+    // v8.3.0+: 需求澄清检测状态（跨代码块共享）
+    let needsClarify = false;
+    const clarifyTargets = [];
     // 备份追踪
     const backups = [];
     const printBackupSummary = () => {
@@ -417,86 +529,102 @@ async function analyzeCommand(options) {
         const reqDir = (0, path_1.join)(iterDir, '010-requirements');
         const specDir = (0, path_1.join)(iterDir, '020-specs');
         await (0, fs_extra_1.ensureDir)(specDir);
-        // 收集需求文档
+        // v8.2.0+: 需求收集优先从黄金需求目录 020-specs/requirements/ 读取
+        // 该目录存放经过 clarify 后的专业需求，作为分析和后续步骤的唯一依据
         const requirements = [];
-        const reqIndex = (0, path_1.join)(reqDir, 'INDEX.md');
-        if (await (0, fs_extra_1.pathExists)(reqIndex))
-            requirements.push(reqIndex);
-        const convDir = (0, path_1.join)(reqDir, 'converted');
-        if (await (0, fs_extra_1.pathExists)(convDir)) {
+        const goldenReqDir = (0, path_1.join)(specDir, 'requirements');
+        const hasGoldenDocs = await (0, fs_extra_1.pathExists)(goldenReqDir);
+        if (hasGoldenDocs) {
             try {
-                const files = await (0, fs_extra_2.readdir)(convDir);
-                for (const f of files.filter((f) => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f)))
-                    requirements.push((0, path_1.join)(convDir, f));
+                const goldenFiles = await (0, fs_extra_2.readdir)(goldenReqDir);
+                for (const f of goldenFiles.filter((f) => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))) {
+                    requirements.push((0, path_1.join)(goldenReqDir, f));
+                }
             }
             catch { }
         }
-        const reqRoot = (0, path_1.join)(reqDir, 'REQUIREMENT.md');
-        if (await (0, fs_extra_1.pathExists)(reqRoot))
-            requirements.push(reqRoot);
-        // 收集 features/*/README.md
-        const featuresDir = (0, path_1.join)(reqDir, 'features');
-        if (await (0, fs_extra_1.pathExists)(featuresDir)) {
-            try {
-                const featureEntries = await (0, fs_extra_2.readdir)(featuresDir, { withFileTypes: true });
-                for (const fe of featureEntries) {
-                    if (fe.isDirectory() && !fe.name.startsWith('.')) {
-                        const readmePath = (0, path_1.join)(featuresDir, fe.name, 'README.md');
-                        if (await (0, fs_extra_1.pathExists)(readmePath))
-                            requirements.push(readmePath);
+        // 如果黄金需求目录为空，回退到原始需求目录 010-requirements/
+        if (requirements.length === 0) {
+            const reqIndex = (0, path_1.join)(reqDir, 'INDEX.md');
+            if (await (0, fs_extra_1.pathExists)(reqIndex))
+                requirements.push(reqIndex);
+            const convDir = (0, path_1.join)(reqDir, 'converted');
+            if (await (0, fs_extra_1.pathExists)(convDir)) {
+                try {
+                    const files = await (0, fs_extra_2.readdir)(convDir);
+                    for (const f of files.filter((f) => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f)))
+                        requirements.push((0, path_1.join)(convDir, f));
+                }
+                catch { }
+            }
+            const reqRoot = (0, path_1.join)(reqDir, 'REQUIREMENT.md');
+            if (await (0, fs_extra_1.pathExists)(reqRoot))
+                requirements.push(reqRoot);
+            // 收集 features/*/README.md
+            const featuresDir = (0, path_1.join)(reqDir, 'features');
+            if (await (0, fs_extra_1.pathExists)(featuresDir)) {
+                try {
+                    const featureEntries = await (0, fs_extra_2.readdir)(featuresDir, { withFileTypes: true });
+                    for (const fe of featureEntries) {
+                        if (fe.isDirectory() && !fe.name.startsWith('.')) {
+                            const readmePath = (0, path_1.join)(featuresDir, fe.name, 'README.md');
+                            if (await (0, fs_extra_1.pathExists)(readmePath))
+                                requirements.push(readmePath);
+                        }
                     }
                 }
+                catch { }
             }
-            catch { }
-        }
-        // 收集 staging/ 下的分类文档（doc2spec --classify 产物，带 type frontmatter）
-        const stagingDir = (0, path_1.join)(reqDir, 'staging');
-        if (await (0, fs_extra_1.pathExists)(stagingDir)) {
-            try {
-                const stagingFiles = await (0, fs_extra_2.readdir)(stagingDir);
-                for (const f of stagingFiles.filter((f) => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))) {
-                    requirements.push((0, path_1.join)(stagingDir, f));
+            // 收集 staging/ 下的分类文档
+            const stagingDir = (0, path_1.join)(reqDir, 'staging');
+            if (await (0, fs_extra_1.pathExists)(stagingDir)) {
+                try {
+                    const stagingFiles = await (0, fs_extra_2.readdir)(stagingDir);
+                    for (const f of stagingFiles.filter((f) => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))) {
+                        requirements.push((0, path_1.join)(stagingDir, f));
+                    }
                 }
+                catch { }
             }
-            catch { }
-        }
-        // 收集类型目录下的文档（bugs/, refactors/, research/ — 扁平 .md 文件）
-        for (const typeDir of ['bugs', 'refactors', 'research']) {
-            const typeDirPath = (0, path_1.join)(reqDir, typeDir);
-            if (!(await (0, fs_extra_1.pathExists)(typeDirPath)))
-                continue;
-            try {
-                const typeFiles = await (0, fs_extra_2.readdir)(typeDirPath);
-                for (const f of typeFiles.filter((f) => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))) {
-                    requirements.push((0, path_1.join)(typeDirPath, f));
+            // 收集类型目录下的文档
+            for (const typeDir of ['bugs', 'refactors', 'research']) {
+                const typeDirPath = (0, path_1.join)(reqDir, typeDir);
+                if (!(await (0, fs_extra_1.pathExists)(typeDirPath)))
+                    continue;
+                try {
+                    const typeFiles = await (0, fs_extra_2.readdir)(typeDirPath);
+                    for (const f of typeFiles.filter((f) => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))) {
+                        requirements.push((0, path_1.join)(typeDirPath, f));
+                    }
                 }
+                catch { }
             }
-            catch { }
+        }
+        else {
+            logger_1.logger.info(`   📋 使用黄金需求目录: 020-specs/requirements/ (${requirements.length} 个文档)`);
         }
         if (requirements.length === 0) {
             logger_1.logger.warn('未找到需求文档，请先导入: speccore doc2spec');
             return;
         }
-        // v6.76.0+: --clarify 模式下检测需求文档专业度
-        if (options.clarify) {
+        // v8.3.0+: 需求澄清作为必须过程（除非 --skip-clarify）
+        if (!options.skipClarify) {
             const { detectProfessionalLevel } = await Promise.resolve().then(() => __importStar(require('../core/requirement-clarifier')));
-            let lowQualityCount = 0;
             for (const reqPath of requirements) {
                 const reqContent = await (0, fs_extra_2.readFile)(reqPath, 'utf-8');
                 const level = detectProfessionalLevel(reqContent);
                 if (level !== 'high') {
-                    lowQualityCount++;
+                    needsClarify = true;
+                    clarifyTargets.push({ path: reqPath, level });
                     logger_1.logger.warn(`   ⚠️  需求文档质量${level.toUpperCase()}: ${reqPath.replace(iterDir + '/', '')}`);
-                    logger_1.logger.info(`      💡 建议: speccore clarify --from "${reqPath}" --to ${iter}`);
                 }
             }
-            if (lowQualityCount > 0) {
+            if (needsClarify) {
                 logger_1.logger.info('');
-                logger_1.logger.info(`📋 ${lowQualityCount}/${requirements.length} 个需求文档需要澄清整理`);
-                logger_1.logger.info('   选项 1: 先执行 clarify 整理需求，再重新 analyze');
-                logger_1.logger.info('   选项 2: 继续使用当前文档分析（加 --force 跳过检测）');
+                logger_1.logger.info(`📋 ${clarifyTargets.length}/${requirements.length} 个需求文档需要澄清整理`);
+                logger_1.logger.info('   将在分析流程中自动注入需求澄清阶段（Phase 0）');
+                logger_1.logger.info('   如需跳过: speccore analyze -I ${iter} --skip-clarify');
                 logger_1.logger.info('');
-                // 不阻断，但在 prompt 中注入澄清指令
             }
         }
         // 【v6.40.2 修复】--auto 不再跳过 AI，而是自动生成 prompt 让宿主 AI 执行专业分析
@@ -752,6 +880,63 @@ async function analyzeCommand(options) {
                 return;
             }
         }
+        // v8.3.0+: 解析 [CLARIFY:xxx] 标记 — 需求澄清是强制前置步骤
+        const clarifyBlocks = parseClarifyMarkers(options.apply);
+        if (clarifyBlocks.size > 0 && !isGlobalScope) {
+            logger_1.logger.info(`📋 检测到 ${clarifyBlocks.size} 个澄清文档，先写入黄金需求目录...`);
+            const goldenDir = (0, path_1.join)(iterDir, '020-specs', 'requirements');
+            await (0, fs_extra_1.ensureDir)(goldenDir);
+            for (const [filename, content] of clarifyBlocks) {
+                const { parseClarifiedRequirement, buildClarifiedHeader } = await Promise.resolve().then(() => __importStar(require('../core/requirement-clarifier')));
+                const { content: cleaned } = parseClarifiedRequirement(content);
+                const header = buildClarifiedHeader(filename);
+                const finalContent = header + cleaned;
+                const fp = (0, path_1.join)(goldenDir, (0, path_1.basename)(filename));
+                await (0, fs_extra_1.ensureDir)((0, path_1.dirname)(fp));
+                await (0, fs_extra_1.writeFile)(fp, finalContent);
+                logger_1.logger.info(`   ✅ 澄清文档已写入: ${fp.replace(process.cwd() + '/', '')}`);
+            }
+            logger_1.logger.info('');
+        }
+        // v8.3.0+: 需求澄清验证 — 如果需求质量不足但未澄清，拒绝写入
+        if (!isGlobalScope && !isTaskLevel && !options.skipClarify) {
+            const goldenDir = (0, path_1.join)(iterDir, '020-specs', 'requirements');
+            const hasClarifiedDocs = await (0, fs_extra_1.pathExists)(goldenDir) && (await (0, fs_extra_2.readdir)(goldenDir)).some((f) => f.endsWith('.md'));
+            if (!hasClarifiedDocs && clarifyBlocks.size === 0) {
+                // 重新检测需求质量
+                const { detectProfessionalLevel } = await Promise.resolve().then(() => __importStar(require('../core/requirement-clarifier')));
+                const reqDir = (0, path_1.join)(iterDir, '010-requirements');
+                const requirements = [];
+                const reqIndex = (0, path_1.join)(reqDir, 'INDEX.md');
+                if (await (0, fs_extra_1.pathExists)(reqIndex))
+                    requirements.push(reqIndex);
+                const convDir = (0, path_1.join)(reqDir, 'converted');
+                if (await (0, fs_extra_1.pathExists)(convDir)) {
+                    const files = await (0, fs_extra_2.readdir)(convDir);
+                    for (const f of files.filter((f) => f.endsWith('.md')))
+                        requirements.push((0, path_1.join)(convDir, f));
+                }
+                let lowQualityCount = 0;
+                for (const reqPath of requirements) {
+                    const reqContent = await (0, fs_extra_2.readFile)(reqPath, 'utf-8');
+                    const level = detectProfessionalLevel(reqContent);
+                    if (level !== 'high')
+                        lowQualityCount++;
+                }
+                if (lowQualityCount > 0) {
+                    logger_1.logger.error('❌ 需求澄清未完成，拒绝写入分析结果');
+                    logger_1.logger.error(`   ${lowQualityCount} 个需求文档质量不足，必须先澄清为 PRD`);
+                    logger_1.logger.info('');
+                    logger_1.logger.info('解决方式：');
+                    logger_1.logger.info('   1. 在 AI 输出中先包含 [CLARIFY:requirements/xxx.md] 标记的澄清文档');
+                    logger_1.logger.info('   2. 或先手动运行: speccore clarify --from "<需求文件>" --to ' + options.iteration + ' --prompt');
+                    logger_1.logger.info('');
+                    logger_1.logger.info('   如需跳过澄清（不推荐）:');
+                    logger_1.logger.info(`   speccore analyze --apply ... -I ${options.iteration} --skip-clarify`);
+                    return;
+                }
+            }
+        }
         // 支持 JSON 多文档写入
         if (options.apply.startsWith('{')) {
             try {
@@ -865,19 +1050,35 @@ async function analyzeCommand(options) {
                     const validPlatforms = new Set([spec_paths_1.GLOBAL_SPECS_DIR, ...(await (0, spec_paths_1.parsePlatformList)())]);
                     let skippedCount = 0;
                     for (const [filename, content] of Object.entries(docs)) {
-                        // v6.80.0+: 010-requirements/ 路径处理（clarify 结果写入）
+                        // v8.2.0+: 需求文档写入黄金需求目录 020-specs/requirements/
+                        // 支持 010-requirements/ 路径（向后兼容，自动重定向）
+                        if (filename.startsWith('020-specs/requirements/')) {
+                            const reqFilePath = filename.slice('020-specs/requirements/'.length);
+                            const goldenDir = (0, path_1.join)(iterDir, '020-specs', 'requirements');
+                            const fp = (0, path_1.join)(goldenDir, reqFilePath);
+                            await (0, fs_extra_1.ensureDir)((0, path_1.dirname)(fp));
+                            let finalContent = content;
+                            if (reqFilePath.startsWith('clarified-') && !content.startsWith('---')) {
+                                finalContent = (0, requirement_clarifier_1.buildClarifiedHeader)(reqFilePath) + content;
+                            }
+                            await (0, fs_extra_1.writeFile)(fp, finalContent);
+                            logger_1.logger.info(`   📝 黄金需求已写入: 020-specs/requirements/${reqFilePath}`);
+                            count++;
+                            continue;
+                        }
+                        // v6.80.0+: 向后兼容 — 010-requirements/ 路径自动重定向到黄金需求目录
                         if (filename.startsWith('010-requirements/')) {
                             const reqFilePath = filename.slice('010-requirements/'.length);
-                            const reqDir = (0, path_1.join)(iterDir, '010-requirements');
-                            const fp = (0, path_1.join)(reqDir, reqFilePath);
+                            // v8.2.0+: clarify 结果写入 020-specs/requirements/ 而非 010-requirements/converted/
+                            const goldenDir = (0, path_1.join)(iterDir, '020-specs', 'requirements');
+                            const fp = (0, path_1.join)(goldenDir, reqFilePath.replace(/^converted\//, ''));
                             await (0, fs_extra_1.ensureDir)((0, path_1.dirname)(fp));
-                            // 为 clarified 文件添加头部元信息
                             let finalContent = content;
                             if (reqFilePath.startsWith('converted/clarified-') && !content.startsWith('---')) {
                                 finalContent = (0, requirement_clarifier_1.buildClarifiedHeader)(reqFilePath) + content;
                             }
                             await (0, fs_extra_1.writeFile)(fp, finalContent);
-                            logger_1.logger.info(`   📝 需求文档已写入: ${reqFilePath}`);
+                            logger_1.logger.info(`   📝 黄金需求已写入: 020-specs/requirements/${reqFilePath.replace(/^converted\//, '')}`);
                             count++;
                             continue;
                         }
@@ -942,6 +1143,60 @@ async function analyzeCommand(options) {
                         logger_1.logger.warn(`⚠️ 共跳过 ${skippedCount} 个非法目录的文档，请检查 AI 输出是否包含非端名目录`);
                     }
                     logger_1.logger.success(`✅ ${count} 个 Spec 文档已写入 020-specs/`);
+                    // v8.3.1+: 空模板检测 — 写入后立即检查是否有文档仍为骨架状态
+                    const emptySkeletonDocs = [];
+                    const emptyTableDocs = [];
+                    try {
+                        const { readdir, readFile } = await Promise.resolve().then(() => __importStar(require('fs-extra')));
+                        const specDir = (0, path_1.join)(iterDir, '020-specs');
+                        const checkDir = async (dir, prefix = '') => {
+                            const entries = await readdir(dir, { withFileTypes: true });
+                            for (const entry of entries) {
+                                const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+                                const fullPath = (0, path_1.join)(dir, entry.name);
+                                if (entry.isDirectory()) {
+                                    await checkDir(fullPath, relPath);
+                                }
+                                else if (entry.name.endsWith('.md')) {
+                                    const content = await readFile(fullPath, 'utf-8');
+                                    if (content.includes('<!-- SPEC-SKELETON -->')) {
+                                        emptySkeletonDocs.push(relPath);
+                                    }
+                                    // 检测空表格：| 表头 | 表头 | 后没有数据行
+                                    const tableMatches = content.match(/\|[^\n]+\|\n\|[-:\s|]+\|/g);
+                                    if (tableMatches) {
+                                        for (const table of tableMatches) {
+                                            const tableEnd = content.indexOf(table) + table.length;
+                                            const afterTable = content.slice(tableEnd, tableEnd + 200);
+                                            // 如果表格后面紧跟空行或另一个表格/标题，说明没有数据行
+                                            if (!afterTable.trim().startsWith('|')) {
+                                                emptyTableDocs.push(relPath);
+                                                break;
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        };
+                        await checkDir(specDir);
+                        if (emptySkeletonDocs.length > 0) {
+                            logger_1.logger.warn('');
+                            logger_1.logger.warn(`⚠️ 检测到 ${emptySkeletonDocs.length} 个文档仍为骨架状态（含 <!-- SPEC-SKELETON -->）:`);
+                            for (const d of emptySkeletonDocs)
+                                logger_1.logger.warn(`   ❌ ${d}`);
+                            logger_1.logger.info('   💡 建议重新执行 analyze 补充这些文档');
+                        }
+                        if (emptyTableDocs.length > 0) {
+                            logger_1.logger.warn('');
+                            logger_1.logger.warn(`⚠️ 检测到 ${emptyTableDocs.length} 个文档含空表格（只有表头无数据）:`);
+                            for (const d of emptyTableDocs)
+                                logger_1.logger.warn(`   ❌ ${d}`);
+                            logger_1.logger.info('   💡 建议重新执行 analyze 补充表格数据');
+                        }
+                    }
+                    catch (e) {
+                        logger_1.logger.debug(`空模板检测失败（非关键）: ${e.message}`);
+                    }
                     // v6.90.0+: 事后校验——检测并清理 AI 绕过 --apply 创建的非法目录/文件
                     await sanitizeSpecDirectories(iterDir);
                     // v7.4.0+: 从 AI 输出中提取疑问并持久化
@@ -1022,6 +1277,227 @@ async function analyzeCommand(options) {
                 // fallback to single-file mode
             }
         }
+        // v8.2.0+: [DOC:xxx] 标记解析 —— 统一报告自动拆分
+        // AI 输出格式: [DOC:REQUIREMENT.md]...内容...[DOC:TECH.md]...内容...
+        const docBlocks = parseDocMarkers(options.apply);
+        if (docBlocks.size > 1) {
+            // 将 [DOC:xxx] 格式转换为 JSON 格式复用现有写入逻辑
+            const docs = {};
+            for (const [docName, content] of docBlocks) {
+                docs[docName] = content;
+            }
+            // 构造一个 faux JSON 字符串让后面的 JSON 解析逻辑处理
+            options.apply = JSON.stringify(docs);
+            // 重新进入 JSON 处理分支（递归一次）
+            try {
+                const docs = JSON.parse(options.apply);
+                let count = 0;
+                if (isTaskLevel && taskDir) {
+                    const targetSubDir = options.platform && !isTaskLevel ? options.platform : '00-specs';
+                    const taskSpecDir = (0, path_1.join)(taskDir, targetSubDir);
+                    await (0, fs_extra_1.ensureDir)(taskSpecDir);
+                    for (const [filename, content] of Object.entries(docs)) {
+                        const fp = (0, path_1.join)(taskSpecDir, filename);
+                        if (!(await (0, task_utils_1.shouldOverwrite)(fp, !!options.interactive))) {
+                            logger_1.logger.info(`   ⏭️  跳过: ${filename}`);
+                            continue;
+                        }
+                        const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
+                        if (bk) {
+                            backups.push(bk);
+                            logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${bk.split('/').pop()}`);
+                        }
+                        await (0, fs_extra_1.writeFile)(fp, content);
+                        count++;
+                    }
+                    const platformLabel = options.platform ? `/${options.platform}` : '';
+                    logger_1.logger.success(`✅ ${count} 个 Spec 文档已写入 ${options.task}${platformLabel}/（任务级，迭代基线不变）`);
+                }
+                else if (isGlobalScope) {
+                    const globalBaseDir = (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL');
+                    await (0, fs_extra_1.ensureDir)(globalBaseDir);
+                    const globalSet = new Set(spec_paths_1.GLOBAL_SPEC_FILES);
+                    for (const [filename, content] of Object.entries(docs)) {
+                        if (filename.startsWith('PATTERNS/')) {
+                            const patternsDir = (0, path_1.join)(process.cwd(), '.speccore', 'PATTERNS');
+                            await (0, fs_extra_1.ensureDir)(patternsDir);
+                            const patternFile = filename.slice('PATTERNS/'.length);
+                            const fp = (0, path_1.join)(patternsDir, patternFile);
+                            let existing = '';
+                            if (await (0, fs_extra_1.pathExists)(fp))
+                                existing = await (0, fs_extra_2.readFile)(fp, 'utf-8');
+                            const merged = existing ? `${existing}\n\n---\n\n${content}` : content;
+                            await (0, fs_extra_1.writeFile)(fp, merged);
+                            logger_1.logger.info(`   🧩 PATTERN 已追加: ${patternFile}`);
+                            count++;
+                            continue;
+                        }
+                        let targetDir;
+                        let targetFilename;
+                        if (filename.includes('/')) {
+                            const parts = filename.split('/');
+                            if (parts[0] === 'platforms' || parts[0] === 'requirements') {
+                                targetDir = (0, path_1.join)(globalBaseDir, ...parts.slice(0, -1));
+                                targetFilename = parts[parts.length - 1];
+                            }
+                            else {
+                                targetDir = (0, path_1.join)(globalBaseDir, 'platforms', parts[0]);
+                                targetFilename = parts[parts.length - 1];
+                            }
+                        }
+                        else if (filename === 'REQUIREMENT.md') {
+                            targetDir = (0, path_1.join)(globalBaseDir, 'requirements');
+                            targetFilename = filename;
+                        }
+                        else if (globalSet.has(filename)) {
+                            targetDir = (0, path_1.join)(globalBaseDir, 'overview');
+                            targetFilename = filename;
+                        }
+                        else {
+                            targetDir = (0, path_1.join)(globalBaseDir, 'overview');
+                            targetFilename = filename;
+                        }
+                        await (0, fs_extra_1.ensureDir)(targetDir);
+                        const fp = (0, path_1.join)(targetDir, targetFilename);
+                        if (!(await (0, task_utils_1.shouldOverwrite)(fp, !!options.interactive))) {
+                            logger_1.logger.info(`   ⏭️  跳过: ${filename}`);
+                            continue;
+                        }
+                        const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
+                        if (bk) {
+                            backups.push(bk);
+                            logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${bk.split('/').pop()}`);
+                        }
+                        await (0, fs_extra_1.writeFile)(fp, content);
+                        count++;
+                    }
+                    logger_1.logger.success(`✅ ${count} 个全局文档已写入 .speccore/GLOBAL/`);
+                }
+                else {
+                    const specDir = (0, path_1.join)(iterDir, '020-specs');
+                    await (0, fs_extra_1.ensureDir)(specDir);
+                    const globalSet = new Set(spec_paths_1.GLOBAL_SPEC_FILES);
+                    const validPlatforms = new Set([spec_paths_1.GLOBAL_SPECS_DIR, ...(await (0, spec_paths_1.parsePlatformList)())]);
+                    let skippedCount = 0;
+                    for (const [filename, content] of Object.entries(docs)) {
+                        // v8.2.0+: 黄金需求目录支持
+                        if (filename.startsWith('020-specs/requirements/')) {
+                            const reqFilePath = filename.slice('020-specs/requirements/'.length);
+                            const goldenDir = (0, path_1.join)(iterDir, '020-specs', 'requirements');
+                            const fp = (0, path_1.join)(goldenDir, reqFilePath);
+                            await (0, fs_extra_1.ensureDir)((0, path_1.dirname)(fp));
+                            let finalContent = content;
+                            if (reqFilePath.startsWith('clarified-') && !content.startsWith('---')) {
+                                finalContent = (0, requirement_clarifier_1.buildClarifiedHeader)(reqFilePath) + content;
+                            }
+                            await (0, fs_extra_1.writeFile)(fp, finalContent);
+                            logger_1.logger.info(`   📝 黄金需求已写入: 020-specs/requirements/${reqFilePath}`);
+                            count++;
+                            continue;
+                        }
+                        // 向后兼容：010-requirements/ 自动重定向到黄金需求目录
+                        if (filename.startsWith('010-requirements/')) {
+                            const reqFilePath = filename.slice('010-requirements/'.length);
+                            const goldenDir = (0, path_1.join)(iterDir, '020-specs', 'requirements');
+                            const fp = (0, path_1.join)(goldenDir, reqFilePath.replace(/^converted\//, ''));
+                            await (0, fs_extra_1.ensureDir)((0, path_1.dirname)(fp));
+                            let finalContent = content;
+                            if (reqFilePath.startsWith('converted/clarified-') && !content.startsWith('---')) {
+                                finalContent = (0, requirement_clarifier_1.buildClarifiedHeader)(reqFilePath) + content;
+                            }
+                            await (0, fs_extra_1.writeFile)(fp, finalContent);
+                            logger_1.logger.info(`   📝 黄金需求已写入: 020-specs/requirements/${reqFilePath.replace(/^converted\//, '')}`);
+                            count++;
+                            continue;
+                        }
+                        if (filename.startsWith('PATTERNS/')) {
+                            const patternsDir = (0, path_1.join)(process.cwd(), '.speccore', 'PATTERNS');
+                            await (0, fs_extra_1.ensureDir)(patternsDir);
+                            const patternFile = filename.slice('PATTERNS/'.length);
+                            const fp = (0, path_1.join)(patternsDir, patternFile);
+                            let existing = '';
+                            if (await (0, fs_extra_1.pathExists)(fp))
+                                existing = await (0, fs_extra_2.readFile)(fp, 'utf-8');
+                            const merged = existing ? `${existing}\n\n---\n\n${content}` : content;
+                            await (0, fs_extra_1.writeFile)(fp, merged);
+                            logger_1.logger.info(`   🧩 PATTERN 已追加: ${patternFile}`);
+                            count++;
+                            continue;
+                        }
+                        let cleanFilename = filename;
+                        if (cleanFilename.startsWith(`${spec_paths_1.GLOBAL_SPECS_DIR}/`)) {
+                            cleanFilename = cleanFilename.slice(`${spec_paths_1.GLOBAL_SPECS_DIR}/`.length);
+                        }
+                        if (cleanFilename.includes('/')) {
+                            const prefix = cleanFilename.split('/')[0];
+                            if (!validPlatforms.has(prefix)) {
+                                logger_1.logger.warn(`   ⚠️ 文件名含未知目录前缀 "${prefix}/"，已自动剥离: ${cleanFilename}`);
+                                cleanFilename = cleanFilename.split('/').pop();
+                            }
+                        }
+                        const platformDir = cleanFilename.includes('/') ? cleanFilename.split('/')[0] : null;
+                        if (platformDir && !validPlatforms.has(platformDir)) {
+                            logger_1.logger.warn(`   ⚠️ 跳过非法端目录: ${platformDir}（文件: ${cleanFilename}）`);
+                            skippedCount++;
+                            continue;
+                        }
+                        const targetDir = globalSet.has(cleanFilename)
+                            ? (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR)
+                            : options.platform ? (0, path_1.join)(specDir, options.platform) : specDir;
+                        await (0, fs_extra_1.ensureDir)(targetDir);
+                        const fp = (0, path_1.join)(targetDir, cleanFilename);
+                        if (!(await (0, task_utils_1.shouldOverwrite)(fp, !!options.interactive))) {
+                            logger_1.logger.info(`   ⏭️  跳过: ${filename}`);
+                            continue;
+                        }
+                        const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
+                        if (bk) {
+                            backups.push(bk);
+                            logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${bk.split('/').pop()}`);
+                        }
+                        await (0, fs_extra_1.writeFile)(fp, content);
+                        count++;
+                    }
+                    if (skippedCount > 0) {
+                        logger_1.logger.warn(`⚠️ 共跳过 ${skippedCount} 个非法目录的文档，请检查 AI 输出是否包含非端名目录`);
+                    }
+                    logger_1.logger.success(`✅ ${count} 个 Spec 文档已写入 020-specs/`);
+                    await sanitizeSpecDirectories(iterDir);
+                }
+                // v8.2.0+: 单元分析结果保存到缓存（供 --consolidate 汇总使用）
+                if (options.unit && options.iteration) {
+                    try {
+                        const unitsCachePath = (0, path_1.join)(process.cwd(), exports.UNITS_CACHE_DIR, options.iteration, 'units.json');
+                        let unitName = options.unit;
+                        if (await (0, fs_extra_1.pathExists)(unitsCachePath)) {
+                            const allUnits = JSON.parse(await (0, fs_extra_2.readFile)(unitsCachePath, 'utf-8'));
+                            const matched = allUnits.find(u => u.id === options.unit);
+                            if (matched)
+                                unitName = matched.name;
+                        }
+                        const unitAnalysis = {
+                            id: options.unit,
+                            name: unitName,
+                            req: docs['REQ.md'] || docs['REQUIREMENT.md'] || '',
+                            tech: docs['TECH.md'] || docs['ANALYSIS.md'] || '',
+                            test: docs['TEST.md'] || '',
+                            risk: docs['RISK.md'] || '',
+                            timestamp: new Date().toISOString(),
+                        };
+                        await saveUnitAnalysis(options.iteration, unitAnalysis);
+                        logger_1.logger.info(`💾 单元分析 ${options.unit} 已缓存（供 --consolidate 使用）`);
+                    }
+                    catch (e) {
+                        logger_1.logger.debug('单元分析缓存失败（非关键）:', e);
+                    }
+                }
+                printBackupSummary();
+                return;
+            }
+            catch (e) {
+                logger_1.logger.warn('⚠️ [DOC:xxx] 解析后写入失败，回退到单文件模式');
+            }
+        }
         // 单文件模式
         if (isTaskLevel && taskDir) {
             // 任务级：写 Task/00-specs/（v6.44.0+）
@@ -1265,7 +1741,7 @@ async function analyzeCommand(options) {
             }
             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);
+        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, needsClarify ? { needsClarify, clarifyTargets } : undefined);
         process.stdout.write(`[SPECCORE_PROMPT]\n${prompt}`);
         // v7.2.0+: 全局分析完成后输出下一步引导
         if (options.scope === 'global') {
@@ -1895,13 +2371,37 @@ async function detectGlobalLayerProgress() {
             missing.push('Layer 2: platforms/_shared/_ASSOCIATION.md + _MODULES.md');
         }
     }
-    // Layer 3: 检查 _MODULES.md
+    // Layer 3: 检查各端功能模块深入文档（v8.3.0+ 修复：不再把 _MODULES.md 当 Layer 3 产物）
     if (completedLayer >= 2) {
-        if (await (0, fs_extra_1.pathExists)((0, path_1.join)(globalDir, 'platforms', '_shared', '_MODULES.md'))) {
-            completedLayer = 3;
+        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);
+            if (platformDirs.length === 0) {
+                missing.push('Layer 3: platforms/{端}/modules/*.md（功能模块深入文档）');
+            }
+            else {
+                const moduleDocChecks = await Promise.all(platformDirs.map(async (d) => {
+                    const modulesDir = (0, path_1.join)(platformsDir, d, 'modules');
+                    if (!await (0, fs_extra_1.pathExists)(modulesDir))
+                        return false;
+                    const files = await (0, fs_extra_2.readdir)(modulesDir).catch(() => []);
+                    return files.some(f => f.endsWith('.md'));
+                }));
+                if (moduleDocChecks.every(Boolean)) {
+                    completedLayer = 3;
+                }
+                else {
+                    for (const [i, d] of platformDirs.entries()) {
+                        if (!moduleDocChecks[i]) {
+                            missing.push(`Layer 3: platforms/${d}/modules/*.md（功能模块深入文档）`);
+                        }
+                    }
+                }
+            }
         }
-        else {
-            missing.push('Layer 3: platforms/_shared/_MODULES.md（功能模块候选清单）');
+        catch {
+            missing.push('Layer 3: platforms/{端}/modules/*.md（功能模块深入文档）');
         }
     }
     // Layer 4 子层检测
@@ -1910,10 +2410,28 @@ async function detectGlobalLayerProgress() {
         const overviewDir = (0, path_1.join)(globalDir, 'overview');
         const requirementsDir = (0, path_1.join)(globalDir, 'requirements');
         const completedSubLayers = [];
-        // 4a: 产品文档
+        // 4a: 产品文档（全局 + 各端，v8.3.0+ 修复：检查各端 REQUIREMENT.md）
         const hasReq = await (0, fs_extra_1.pathExists)((0, path_1.join)(requirementsDir, 'REQUIREMENT.md'));
-        if (hasReq)
+        let allPlatformReqsExist = true;
+        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 platformReqChecks = await Promise.all(platformDirs.map(p => (0, fs_extra_1.pathExists)((0, path_1.join)(requirementsDir, p, 'REQUIREMENT.md'))));
+            allPlatformReqsExist = platformReqChecks.every(Boolean);
+            for (const [i, p] of platformDirs.entries()) {
+                if (!platformReqChecks[i]) {
+                    missing.push(`Layer 4a: requirements/${p}/REQUIREMENT.md（${p} 产品视角需求）`);
+                }
+            }
+        }
+        catch { /* ignore */ }
+        if (hasReq && allPlatformReqsExist) {
             completedSubLayers.push('4a');
+        }
+        else if (!hasReq) {
+            missing.push('Layer 4a: requirements/REQUIREMENT.md（全局需求总纲）');
+        }
         // 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'));
@@ -1924,15 +2442,42 @@ async function detectGlobalLayerProgress() {
             || await (0, fs_extra_1.pathExists)((0, path_1.join)(overviewDir, 'DATA_FLOW.md'));
         if (hasExtTech)
             completedSubLayers.push('4c');
-        // 4d: 各端技术文档
+        // 4d: 各端技术文档（v8.3.0+ 修复：每个端都要有，不再用 some(Boolean)）
         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)
+            const missingPlatformDocs = [];
+            for (const d of platformDirs) {
+                const isBackend = /service|server|api|backend/i.test(d);
+                if (isBackend) {
+                    const hasApi = await (0, fs_extra_1.pathExists)((0, path_1.join)(platformsDir, d, 'API_INVENTORY.md'));
+                    const hasData = await (0, fs_extra_1.pathExists)((0, path_1.join)(platformsDir, d, 'DATA_MODEL.md'));
+                    if (!hasApi)
+                        missingPlatformDocs.push(`platforms/${d}/API_INVENTORY.md`);
+                    if (!hasData)
+                        missingPlatformDocs.push(`platforms/${d}/DATA_MODEL.md`);
+                }
+                else {
+                    const hasUi = await (0, fs_extra_1.pathExists)((0, path_1.join)(platformsDir, d, 'UI_FLOW.md'));
+                    const hasApiMap = await (0, fs_extra_1.pathExists)((0, path_1.join)(platformsDir, d, 'API_CALL_MAP.md'));
+                    const hasState = await (0, fs_extra_1.pathExists)((0, path_1.join)(platformsDir, d, 'STATE_MANAGEMENT.md'));
+                    if (!hasUi)
+                        missingPlatformDocs.push(`platforms/${d}/UI_FLOW.md`);
+                    if (!hasApiMap)
+                        missingPlatformDocs.push(`platforms/${d}/API_CALL_MAP.md`);
+                    if (!hasState)
+                        missingPlatformDocs.push(`platforms/${d}/STATE_MANAGEMENT.md`);
+                }
+            }
+            if (missingPlatformDocs.length === 0 && platformDirs.length > 0) {
                 completedSubLayers.push('4d');
+            }
+            else {
+                for (const doc of missingPlatformDocs) {
+                    missing.push(`Layer 4d: ${doc}`);
+                }
+            }
         }
         catch { /* ignore */ }
         if (completedSubLayers.length === 4) {
@@ -2111,7 +2656,7 @@ async function buildLayer3ModuleContext(projectRoot) {
     return ctx.join('\n\n---\n\n');
 }
 // ── buildMultiDocPrompt: 多文档协议 ──
-async function buildMultiDocPrompt(command, ctx, options) {
+async function buildMultiDocPrompt(command, ctx, options, clarifyCtx) {
     const iter = ctx.iteration || '当前迭代';
     const task = ctx.task ? ` — ${ctx.task}` : '';
     const taskType = ctx.type || 'feature';
@@ -2119,6 +2664,9 @@ async function buildMultiDocPrompt(command, ctx, options) {
     const isTask = ctx.scope === 'task' || !!ctx.task;
     const isGlobal = ctx.scope === 'global';
     const autoMode = ctx.autoMode || false;
+    // v8.3.0+: 从 clarifyCtx 提取需求澄清状态
+    const needsClarify = clarifyCtx?.needsClarify ?? false;
+    const clarifyTargets = clarifyCtx?.clarifyTargets ?? [];
     // global 范围: 从源码反推需求 + 生成技术栈配置
     if (isGlobal) {
         // v6.74.0+: 流式全局分析模式
@@ -3167,38 +3715,46 @@ sequenceDiagram
             `# 开发者实现指南
 
 > ${iter} | ${now}
-> 本文档面向开发者，提供具体实现步骤、代码模式和最佳实践。
+> 本文档面向开发者，提供**可执行的实现指导**——开发者读完知道改哪些文件、先改什么后改什么、具体怎么改、改完怎么验证。
 
 ## 写作要求
 
 ### 迭代级 DEV_GUIDE.md（020-specs/overview/）
-- **技术栈与选型决策**：每个技术点的选型理由、替代方案对比
-- **代码分层规范**：目录结构、各层职责、代码组织方式
-- **通用设计模式**：Repository 模式、Service 模式、策略模式等具体实现
-- **跨端数据流**：请求从入口到数据库的完整链路、数据转换规则
-- **错误处理策略**：全局错误码、异常分类、降级策略
-- **性能优化基线**：缓存策略、数据库优化、并发控制
-- **安全基线**：鉴权流程、数据校验、敏感信息处理
+面向全迭代，提供全局实施指导：
+- **分支策略**：从哪个分支切 feature 分支，合并到哪里，分支命名规范
+- **改造范围清单**：本迭代所有需要修改的文件（新增/修改/删除），按类型分类
+- **改造顺序与依赖**：按依赖关系排列的实施步骤，说明每步为什么先做
+- **关键实现步骤（代码级）**：具体到文件/函数级的改造方式，包含改造前后对比
+- **接口契约（前后端对照）**：所有接口的路径、后端实现位置、前端调用位置、状态
+- **每步验证方式**：每步改完用什么命令/操作验证，通过标准是什么
+- **回滚方案**：数据库变更的 DOWN migration、代码回滚方式、配置回滚方式
+- **常见坑点**：已知陷阱及解决方式
 
 ### 端级 DEV_GUIDE.md（020-specs/{端}/）
-- **端技术栈**：框架、库、工具链及选型理由
-- **目录结构规范**：该端的代码组织方式
-- **核心流程实现**：关键业务流程的伪代码/示例代码
-- **API 调用模式**：请求封装、错误处理、重试策略
-- **状态管理**：全局状态设计、与后端同步策略
-- **端特定最佳实践**：该端特有的性能优化、安全策略
+面向本端开发者：
+- **本端改造范围**：本端需要修改的文件清单
+- **本端实施步骤（按依赖排序）**：具体到文件/函数的开发顺序
+- **代码级指引**：改哪几行、改什么、改造后的代码片段
+- **与后端联调**：接口状态、联调顺序、Mock 方案
+- **验证方式**：本端特有的验证命令/操作和通过标准
+- **本端坑点**：该端特有的陷阱
 
 ### 任务级 DEV_GUIDE.md（Task/00-specs/）
-- **任务概述**：该任务在整体功能中的位置和职责
-- **实现步骤**：Step-by-step 的开发步骤
-- **关键代码示例**：核心逻辑的伪代码或代码片段
-- **与存量功能的集成**：如何与已有代码交互、复用哪些模块
-- **测试策略**：单元测试、集成测试的具体写法
-- **注意事项**：常见坑点、边界条件、调试技巧
+面向具体任务开发者，最细粒度：
+- **本任务改造范围**：该任务涉及的具体文件（新增/修改/删除）
+- **实施步骤（按依赖排序）**：Step-by-step，具体到文件/函数级
+- **关键代码指引**：核心改造点的文件位置、改造方式、改造后代码示例
+- **接口契约**：本任务涉及的前后接口对照表
+- **每步验证**：每步改完怎么验证（命令/操作 + 通过标准）
+- **回滚方案**：本任务改坏了怎么回退
+- **已知坑点**：常见坑点及解决方式
 
 ## 质量要求
 - 必须是**可执行的实现指导**，不是抽象概念
-- 包含具体的代码示例（伪代码或关键代码片段）
+- **改造范围**必须列出具体文件路径（相对项目根目录）
+- **改造顺序**必须说明依赖关系（为什么 A 必须在 B 之前）
+- **代码示例**必须具体到文件/函数/行号级别
+- **验证方式**必须是可执行的命令或操作（不是"测试通过"这种空话）
 - 基于 020-specs/ 中已有的分析文档，不做重复分析
 - 补充技术文档中未涉及的实现细节
 - 如果涉及存量功能，说明复用方式和集成点
@@ -3246,15 +3802,19 @@ sequenceDiagram
                 if (perDocStatus.nextUnfilled) {
                     const nextDocName = perDocStatus.nextUnfilled.docName;
                     const nextDocPlatform = perDocStatus.nextUnfilled.platform || null;
-                    // 过滤 taskDocs 只保留下一个未填充的文档
-                    if (nextDocPlatform && perDocStatus.nextUnfilled.category === 'platform') {
-                        // Phase 2 文档（端专属）
-                        taskDocs = taskDocs.filter(([n]) => n === nextDocName);
-                        ctx.platform = nextDocPlatform;
-                    }
-                    else {
-                        // Phase 1 文档（overview）
-                        taskDocs = taskDocs.filter(([n]) => n === nextDocName);
+                    // v8.2.0+: 功能单元聚焦模式不强制单文档过滤，让 AI 一次输出完整单元分析
+                    const isUnitMode = !!(options?.unit || options?.consolidate || options?.extractUnits);
+                    if (!isUnitMode) {
+                        // 过滤 taskDocs 只保留下一个未填充的文档（默认逐文档推进模式）
+                        if (nextDocPlatform && perDocStatus.nextUnfilled.category === 'platform') {
+                            // Phase 2 文档（端专属）
+                            taskDocs = taskDocs.filter(([n]) => n === nextDocName);
+                            ctx.platform = nextDocPlatform;
+                        }
+                        else {
+                            // Phase 1 文档（overview）
+                            taskDocs = taskDocs.filter(([n]) => n === nextDocName);
+                        }
                     }
                     logger_1.logger.info(`🦴 骨架进度: ${perDocStatus.filledCount}/${perDocStatus.totalCount} 已填充，下一个: ${perDocStatus.nextUnfilled.relPath}`);
                     // v8.1.0+: 校验上一个已填充文档的质量
@@ -3412,6 +3972,57 @@ 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`;
+    // v8.3.0+: 如果检测到需求质量不足，在 prompt 开头注入强制澄清阶段
+    if (needsClarify && !isGlobal && !isTask && !ctx.phase) {
+        const now = new Date().toISOString();
+        prompt += `## 🚨 Phase 0: 需求澄清（强制前置 — 未完成则禁止进入 Phase 1）\n\n`;
+        prompt += `检测到以下需求文档质量不足，**必须先完成专业化整理，才能继续技术分析**：\n\n`;
+        for (const t of clarifyTargets) {
+            prompt += `- \`${t.path.split('/').slice(-2).join('/')}\`（质量: ${t.level.toUpperCase()}）\n`;
+        }
+        prompt += `\n### 澄清执行步骤（必须按顺序完成）\n\n`;
+        prompt += `**Step 1**: 读取上述每个需求文档的原始内容\n`;
+        prompt += `**Step 2**: 将口语化/非专业描述整理为 PRD 级专业文档\n`;
+        prompt += `**Step 3**: 补充：验收标准(AC)、功能边界、业务规则、异常处理、数据模型\n`;
+        prompt += `**Step 4**: 输出澄清后的文档，使用以下标记格式：\n`;
+        prompt += `\`\`\`
+[CLARIFY:requirements/clarified-{feature-name}.md]
+---
+source: "原始文档路径"
+clarified-at: "${now}"
+status: "clarified"
+---
+
+# {功能名称}
+
+## 背景与目标
+...
+
+## 用户故事
+...
+
+## 功能规格
+...
+
+## 验收标准（AC）
+- [ ] ...
+
+## 非功能需求
+...
+
+## 依赖与约束
+...
+\`\`\`
+`;
+        prompt += `**Step 5**: 用 Read 工具验证文件已正确写入 \`{迭代}/020-specs/requirements/clarified-{feature-name}.md\`\n`;
+        prompt += `**Step 6**: 基于澄清后的需求继续 Phase 1 分析\n\n`;
+        prompt += `### ⚠️ 重要提醒\n\n`;
+        prompt += `- **如果输出中没有 [CLARIFY:xxx] 标记的澄清文档，--apply 阶段将拒绝写入所有分析结果**\n`;
+        prompt += `- CLI 会在接收 --apply 时先解析 [CLARIFY:xxx] 标记，写入 020-specs/requirements/，然后才处理 [DOC:xxx] 标记\n`;
+        prompt += `- 不要跳过此步骤，不要假设需求已经够清晰\n`;
+        prompt += `- 如果原始描述不完整，在澄清文档中标注「待补充」而不是自行编造\n\n`;
+        prompt += `---\n\n`;
+    }
     // v7.2.0+: 迭代分析代码关联 — 注入结构化数据和语义定位上下文
     if (!isGlobal && ctx.withCode && ctx.iteration && ctx.iteration !== 'GLOBAL') {
         try {
@@ -3529,24 +4140,37 @@ sequenceDiagram
         try {
             const iterDirForCtx = await (0, context_1.getIterationDir)(iter);
             if (iterDirForCtx) {
-                // 1. 注入 PRD 内容（010-requirements/ 下的需求文档）
-                const reqDir = (0, path_1.join)(iterDirForCtx, '010-requirements');
+                // v8.2.0+: 注入 PRD 内容（优先从黄金需求目录 020-specs/requirements/ 读取）
                 let prdContent = '';
-                const prdSources = (0, path_1.join)(reqDir, 'sources');
-                const prdConverted = (0, path_1.join)(reqDir, 'converted');
-                const prdFeatures = (0, path_1.join)(reqDir, 'features');
-                for (const dir of [prdSources, prdConverted, prdFeatures]) {
-                    if (await (0, fs_extra_1.pathExists)(dir)) {
-                        const files = (await Promise.resolve().then(() => __importStar(require('fs-extra')))).readdirSync(dir).filter((f) => f.endsWith('.md')).slice(0, 5);
-                        for (const f of files) {
-                            const content = await (await Promise.resolve().then(() => __importStar(require('fs-extra')))).readFile((0, path_1.join)(dir, f), 'utf-8');
-                            prdContent += `\n### ${f}\n${content.slice(0, 2000)}\n`;
+                const goldenReqDir = (0, path_1.join)(iterDirForCtx, '020-specs', 'requirements');
+                if (await (0, fs_extra_1.pathExists)(goldenReqDir)) {
+                    // 黄金需求目录存在，只读这里（唯一依据）
+                    const files = (await Promise.resolve().then(() => __importStar(require('fs-extra')))).readdirSync(goldenReqDir).filter((f) => f.endsWith('.md')).slice(0, 10);
+                    for (const f of files) {
+                        const content = await (await Promise.resolve().then(() => __importStar(require('fs-extra')))).readFile((0, path_1.join)(goldenReqDir, f), 'utf-8');
+                        prdContent += `\n### ${f}\n${content.slice(0, 2000)}\n`;
+                    }
+                }
+                else {
+                    // 回退：从 010-requirements/ 读取原始需求
+                    const reqDir = (0, path_1.join)(iterDirForCtx, '010-requirements');
+                    const prdSources = (0, path_1.join)(reqDir, 'sources');
+                    const prdConverted = (0, path_1.join)(reqDir, 'converted');
+                    const prdFeatures = (0, path_1.join)(reqDir, 'features');
+                    for (const dir of [prdSources, prdConverted, prdFeatures]) {
+                        if (await (0, fs_extra_1.pathExists)(dir)) {
+                            const files = (await Promise.resolve().then(() => __importStar(require('fs-extra')))).readdirSync(dir).filter((f) => f.endsWith('.md')).slice(0, 5);
+                            for (const f of files) {
+                                const content = await (await Promise.resolve().then(() => __importStar(require('fs-extra')))).readFile((0, path_1.join)(dir, f), 'utf-8');
+                                prdContent += `\n### ${f}\n${content.slice(0, 2000)}\n`;
+                            }
                         }
                     }
                 }
                 if (prdContent.length > 0) {
                     prompt += `\n## 📎 需求文档原文（PRD，写作核心输入）\n\n`;
-                    prompt += `> 以下是 010-requirements/ 下的需求文档，这是你撰写专业分析文档的核心输入。所有分析必须基于这些内容，不要臆造。\n`;
+                    const sourceLabel = await (0, fs_extra_1.pathExists)(goldenReqDir) ? '020-specs/requirements/（黄金需求，已澄清）' : '010-requirements/（原始需求）';
+                    prompt += `> 以下是 ${sourceLabel} 下的需求文档，这是你撰写专业分析文档的核心输入。所有分析必须基于这些内容，不要臆造。\n`;
                     prompt += prdContent.slice(0, 5000);
                     prompt += `\n\n`;
                 }
@@ -3641,24 +4265,55 @@ sequenceDiagram
             prompt += `- Read 020-specs/overview/ANALYSIS.md → 分析报告\n`;
             prompt += `- Read 020-specs/overview/TECH.md → 整体技术架构\n`;
             prompt += `- Read 020-specs/overview/RISK.md、DEPS.md、REVIEW.md、MONITOR.md（如存在）\n\n`;
-            prompt += `### Step 2: 为每个端撰写专属文档\n`;
-            prompt += `根据全局上下文，为 PLATFORMS.md 中的**每个端**分别撰写：\n`;
-            prompt += `- **{端}/TECH.md**：该端专属技术方案（必须对齐 overview/TECH.md 架构）\n`;
+            prompt += `### Step 2: 为每个端撰写专属文档（v8.3.1+ 强制四文档）\n`;
+            prompt += `根据全局上下文，为 PLATFORMS.md 中的**每个端**分别撰写以下 **4 份文档**，缺一不可：\n\n`;
+            prompt += `**1. {端}/TECH.md — 该端专属技术方案（必须对齐 overview/TECH.md 架构）**\n`;
+            prompt += `  - 该端的分层架构、模块划分、核心接口设计（路径/方法/参数/响应/状态码）\n`;
+            prompt += `  - 数据库表结构（字段/类型/索引/约束，如适用）\n`;
+            prompt += `  - 业务规则实现（含边界条件和异常流）\n`;
             prompt += `  - ⚠️ **必须包含「业务-代码映射」章节**：在 TECH.md 末尾添加表格，列出本端涉及的业务模块及其对应的代码实体（文件/表/API/组件等），关系类型由你根据技术栈自主决定（如 api_controller、uses_table、page、component、route、middleware、interceptor、gateway 等）\n`;
             prompt += `  - 表格格式：| 业务模块 | 代码实体 | 关系类型 | 说明 |\n`;
             prompt += `  - 示例：| 会议室档案 | backend/RoomController.java | api_controller | REST 控制器 |\n`;
-            prompt += `  - 示例：| 会议室档案 | admin-web/src/pages/RoomList.vue | page | 列表页 |\n`;
-            prompt += `- **{端}/TEST.md**：该端专属测试计划\n`;
-            prompt += `- **{端}/UI_SPEC.md**：该端专属 UI 规格（仅前端端需要）\n\n`;
+            prompt += `  - 示例：| 会议室档案 | admin-web/src/pages/RoomList.vue | page | 列表页 |\n\n`;
+            prompt += `**2. {端}/TEST.md — 该端专属测试计划**\n`;
+            prompt += `  - 覆盖该端所有功能模块的测试用例（含前置条件、步骤、预期结果）\n`;
+            prompt += `  - 边界值和异常输入测试\n`;
+            prompt += `  - 必须覆盖 REQUIREMENT.md 中该端的验收标准\n\n`;
+            prompt += `**3. {端}/UI_SPEC.md — 该端专属 UI 规格（仅前端端需要）**\n`;
+            prompt += `  - 页面结构与路由（每个页面的路径、入口、权限）\n`;
+            prompt += `  - 组件清单和字段→UI 映射\n`;
+            prompt += `  - 状态枚举和错误处理策略\n\n`;
+            prompt += `**4. {端}/DEV_GUIDE.md — 该端开发者实现指南（v8.3.1+ 新增强制要求）**\n`;
+            prompt += `  - ⛔ **禁止只写框架/占位符** — 必须是可执行的实现指导\n`;
+            prompt += `  - **本端改造范围清单**：列出本端所有需要新增/修改/删除的文件（相对项目根目录的具体路径）\n`;
+            prompt += `  - **本端实施步骤（按依赖排序）**：Step-by-step，具体到文件/函数级，说明每步为什么先做\n`;
+            prompt += `  - **代码级指引**：改哪几行、改什么、改造后的关键代码片段\n`;
+            prompt += `  - **与后端联调**：接口状态、联调顺序、Mock 方案（表格格式）\n`;
+            prompt += `  - **验证方式**：本端特有的验证命令/操作和通过标准（表格格式）\n`;
+            prompt += `  - **本端坑点**：已知陷阱及解决方式\n`;
+            prompt += `  - **回滚方案**：代码回滚方式、配置回滚方式\n\n`;
             prompt += `### Step 3: 一致性检查\n`;
             prompt += `- 各端 TECH.md 的技术选型必须与 overview/TECH.md 一致\n`;
             prompt += `- UI_SPEC.md 的字段映射必须与后端 API 响应字段一一对应\n`;
             prompt += `- TEST.md 必须覆盖 REQUIREMENT.md 中该端的验收标准\n\n`;
+            prompt += `### Step 3: 自检 — 确保所有文档已实质填充\n`;
+            prompt += `生成完成后，逐个检查每个文档：\n`;
+            prompt += `- 如果文档中仍含有 \`<!-- SPEC-SKELETON -->\` 标记或空表格 → **必须重新填充**\n`;
+            prompt += `- 如果「改造范围」表格只有表头没有数据行 → **必须补充具体文件路径**\n`;
+            prompt += `- 如果「验证方式」表格只有表头 → **必须补充可执行的命令/操作**\n`;
+            prompt += `- DEV_GUIDE.md 必须有至少 3 个具体文件路径和 3 个可执行验证步骤\n\n`;
             prompt += `### 写入方式\n`;
             prompt += `**Pipeline 模式**：一次 --apply 写入所有端的文档（推荐）\n`;
-            prompt += `speccore analyze --apply '{"TECH.md":"...","TEST.md":"...","UI_SPEC.md":"..."}' -I ${iter} --platform all\n\n`;
+            prompt += `speccore analyze --apply '{"TECH.md":"...","TEST.md":"...","UI_SPEC.md":"...","DEV_GUIDE.md":"..."}' -I ${iter} --platform all\n\n`;
             prompt += `**或者逐端写入**（每端一次 --apply）：\n`;
-            prompt += `speccore analyze --apply '{"TECH.md":"...","TEST.md":"...","UI_SPEC.md":"..."}' -I ${iter} --platform {端名}\n\n`;
+            prompt += `speccore analyze --apply '{"TECH.md":"...","TEST.md":"...","UI_SPEC.md":"...","DEV_GUIDE.md":"..."}' -I ${iter} --platform {端名}\n\n`;
+            prompt += `### ⛔ 强制约束（违反则分析无效）\n`;
+            prompt += `- **禁止省略任何一份文档** — 4 份文档（TECH.md + TEST.md + UI_SPEC.md + DEV_GUIDE.md）缺一不可\n`;
+            prompt += `- **禁止输出空表格** — 每个 Markdown 表格必须有至少 1 行数据，只有表头的表格视为未完成\n`;
+            prompt += `- **禁止输出占位符** — 不允许写「待填充」、「TODO」、「...」、「xxx」等占位内容\n`;
+            prompt += `- **DEV_GUIDE.md 最低标准**：改造范围表格 ≥3 行、实施步骤 ≥3 步、验证方式表格 ≥3 行、坑点 ≥2 条\n`;
+            prompt += `- **如果 token 不足**：优先保证 DEV_GUIDE.md 完整，其他文档可精简但不可空\n`;
+            prompt += `- **自检必做**：写入前用 Read 工具检查每个文档，确认不含 \`<!-- SPEC-SKELETON -->\` 且所有表格有数据行\n\n`;
         }
         else {
             // v6.61.0+: 一次性生成所有文档（global/ + {端}/）
@@ -3698,7 +4353,14 @@ sequenceDiagram
             prompt += `   - **边界处理**：如果文档对某功能描述不完整，标注"文档未充分描述"，不要自行脑补完整方案\n`;
             prompt += `   - **交叉验证**：每写一个功能点，回头检查需求文档中是否有对应描述，没有则删除\n`;
             prompt += `6. 每个文档都要具体内容（禁止"待填充"）\n`;
-            prompt += `7. **端发现（重要）**：先确定项目有哪些端，再按端组织文档\n`;
+            prompt += `7. **辅助文档强制要求（v8.3.1+ 修复空模板问题）**：以下文档常被 AI 遗漏或敷衍，必须同等重视：\n`;
+            prompt += `   - **FUNCTION_MAP.md**：功能单元 × 端映射表，必须用 Markdown 表格，每行一个功能单元，不允许合并。表头：| # | 功能单元 | 涉及端 | 全局对比 | 共享能力 | 依赖任务 | 说明 |\n`;
+            prompt += `   - **INTERACTION_MAP.md**：每个功能单元一个 Mermaid sequenceDiagram，展示跨端交互时序，箭头标注接口路径\n`;
+            prompt += `   - **DEV_GUIDE.md（迭代级）**：全局实施指导，必须包含：分支策略、改造范围清单（具体到文件路径）、改造顺序与依赖、代码级指引（含改造前后对比）、接口契约对照表、每步验证方式、回滚方案、常见坑点\n`;
+            prompt += `   - **MONITOR.md**：必须按 Fatal/Critical/Warning/Info 四级定义告警规则，不能只列指标名称\n`;
+            prompt += `   - **REVIEW.md**：安全检查必须逐接口列出鉴权需求，不能笼统写"需要鉴权"\n`;
+            prompt += `   ⛔ **自检规则**：生成完成后检查每个文档，如果仍含 \`<!-- SPEC-SKELETON -->\` 或空表格只有表头 → 必须重新填充\n`;
+            prompt += `8. **端发现（重要）**：先确定项目有哪些端，再按端组织文档\n`;
             prompt += `   - 第 1 步：Read .speccore/CONSTITUTION.md\n`;
             prompt += `   - 第 2 步：从「## 端列表」章节提取端名（这是全局权威来源）\n`;
             prompt += `   - 第 3 步：如果没有「端列表」章节，从「对应端」列提取\n`;
@@ -3706,7 +4368,7 @@ sequenceDiagram
             prompt += `   - 第 5 步：将发现的端列表写入 020-specs/PLATFORMS.md\n`;
             // v6.70.0+: REQUIREMENT.md 以产品视角撰写（不按端分章节）
             // v6.99.0+: 丰富需求文档章节要求
-            prompt += `8. **REQUIREMENT.md 写作风格（重要）**：全局需求文档必须以产品/用户视角撰写\n`;
+            prompt += `9. **REQUIREMENT.md 写作风格（重要）**：全局需求文档必须以产品/用户视角撰写\n`;
             prompt += `   - **按业务场景/用户旅程组织章节**，不按端分章节（如"H5端需求"、"后端需求"）\n`;
             prompt += `   - 文档结构必须包含（如需求文档中有相关信息）：\n`;
             prompt += `     - **产品愿景**：本迭代要解决的核心问题和目标价值（1-2段）\n`;
@@ -3724,7 +4386,7 @@ sequenceDiagram
             prompt += `   - 端的信息只在「功能模块清单」表格中标注，正文不区分端\n`;
             // v6.49.14+: 功能模块清单必须含涉及端列 + 来源链接
             // v6.71.3+: 增加「与全局层对比」列
-            prompt += `9. **功能模块清单（重要）**：写入 overview/REQUIREMENT.md 时，功能模块清单表格必须包含以下列\n`;
+            prompt += `10. **功能模块清单（重要）**：写入 overview/REQUIREMENT.md 时，功能模块清单表格必须包含以下列\n`;
             prompt += `   - 表格格式：| # | 功能模块 | 涉及端 | 全局对比 | 来源 | 说明 |\n`;
             prompt += `   - 「涉及端」：每个模块标注需要**新开发工作**的端（标准端名，逗号分隔）\n`;
             prompt += `     - 「涉及」= 该端需要写新接口/新页面/新逻辑\n`;
@@ -4272,6 +4934,16 @@ async function buildClarifyPhasePrompt(iteration) {
     if (qualityReports.length > 0) {
         await (0, requirement_clarifier_1.writeClarifyReport)(iterDir, qualityReports);
     }
+    // v8.2.0+: 提取功能单元，支持单元化澄清（解决注意力漂移）
+    let allDocContent = '';
+    for (const p of docPaths) {
+        try {
+            allDocContent += await (0, fs_extra_2.readFile)(p, 'utf-8') + '\n\n';
+        }
+        catch { /* ignore */ }
+    }
+    const extractedUnits = (0, requirement_clarifier_1.extractUnitsFromText)(allDocContent);
+    const hasMultipleUnits = extractedUnits.length >= 2;
     // v6.84.0+: 从 AGENTS 规范数据库动态加载角色
     let prompt = `\n# 任务: 需求专业化（Phase 0: 需求澄清，v6.84.0+)\n\n`;
     const projectRoot = (0, task_utils_1.findProjectRoot)() || process.cwd();
@@ -4332,6 +5004,33 @@ async function buildClarifyPhasePrompt(iteration) {
     prompt += `3. \`010-requirements/converted/*.md\` — 已转换文档\n`;
     prompt += `4. \`010-requirements/features/*/README.md\` — 功能级补充\n`;
     prompt += `5. \`010-requirements/prototypes/\` — 原型文件\n\n`;
+    // v8.2.0+: 如果检测到多个功能单元，启用单元化澄清模式
+    if (hasMultipleUnits) {
+        prompt += `## ⚠️ 功能单元拆分澄清模式（v8.2.0+）\n\n`;
+        prompt += `检测到需求文档包含 ${extractedUnits.length} 个功能单元。为避免注意力漂移，请**按单元逐个澄清**：\n\n`;
+        prompt += `### 功能单元清单\n\n`;
+        for (const u of extractedUnits) {
+            prompt += `- **${u.id}**: ${u.name}\n`;
+        }
+        prompt += `\n`;
+        prompt += `### 单元化澄清规则\n\n`;
+        prompt += `1. **逐单元处理**：每次只深入分析一个功能单元，不要跨单元混合\n`;
+        prompt += `2. **使用 [UNIT:xxx] 标记**：每个单元的澄清结果用 \`[UNIT:单元ID]\` 开头分隔\n`;
+        prompt += `3. **关联上下文**：分析当前单元时，参考相关单元的摘要（保持逻辑一致性）\n`;
+        prompt += `4. **全局约束共享**：术语表、接口契约在所有单元间统一\n`;
+        prompt += `5. **优先核心单元**：如果单元过多（>5），先处理核心功能单元\n\n`;
+        prompt += `### 输出格式示例\n\n`;
+        prompt += `\`\`\`\n`;
+        for (const u of extractedUnits.slice(0, 2)) {
+            prompt += `[UNIT:${u.id}]\n`;
+            prompt += `## ${u.name}\n`;
+            prompt += `（该单元的专业化澄清内容...）\n\n`;
+        }
+        if (extractedUnits.length > 2) {
+            prompt += `...（其余 ${extractedUnits.length - 2} 个单元依此类推）\n`;
+        }
+        prompt += `\`\`\`\n\n`;
+    }
     prompt += `---\n\n`;
     prompt += `# 📋 五步迭代澄清流程\n\n`;
     prompt += `> 本阶段要求你先以专业角色深度分析，再生成改写版，与用户反复迭代确认，最终写入。\n\n`;
@@ -4420,11 +5119,11 @@ async function buildClarifyPhasePrompt(iteration) {
     prompt += `   - 记录取舍：每轮迭代记录「采纳/拒绝/待确认」的决策\n\n`;
     prompt += `## Step 5: 确认写入\n\n`;
     prompt += `当用户确认 "满意，可以写入" 后：\n\n`;
-    prompt += `1. 将最终版 PRD 写入 \`010-requirements/converted/clarified-{源文件名}-{日期}.md\`\n`;
-    prompt += `2. 同时生成 \`010-requirements/converted/clarified-{源文件名}-{日期}-diff.md\` 保存最终对比报告\n`;
+    prompt += `1. 将最终版 PRD 写入 \`020-specs/requirements/clarified-{源文件名}-{日期}.md\`（黄金需求目录）\n`;
+    prompt += `2. 同时生成 \`020-specs/requirements/clarified-{源文件名}-{日期}-diff.md\` 保存最终对比报告\n`;
     prompt += `3. 使用以下命令写入：\n\n`;
     prompt += `\`\`\`bash\n`;
-    prompt += `speccore analyze --apply '{"010-requirements/converted/clarified-xxx.md":"...","010-requirements/converted/clarified-xxx-diff.md":"..."}' -I ${iteration}\n`;
+    prompt += `speccore analyze --apply '{"020-specs/requirements/clarified-xxx.md":"...","020-specs/requirements/clarified-xxx-diff.md":"..."}' -I ${iteration}\n`;
     prompt += `\`\`\`\n\n`;
     prompt += `> 注意：写入后 CLI 会自动推进到需求确认阶段。\n`;
     return await injectGraphSummary(prompt);
@@ -4432,7 +5131,7 @@ async function buildClarifyPhasePrompt(iteration) {
 async function buildConfirmCheckPrompt(iteration) {
     const iterDir = await (0, context_1.getIterationDir)(iteration);
     const reportPath = (0, path_1.join)(iterDir, '010-requirements', 'CLARIFY_REPORT.md');
-    const convertedDir = (0, path_1.join)(iterDir, '010-requirements', 'converted');
+    const goldenDir = (0, path_1.join)(iterDir, '020-specs', 'requirements');
     let prompt = `\n# 任务: 需求确认（Phase 0: 确认检查，v6.83.0+）\n\n`;
     if (await (0, fs_extra_1.pathExists)(reportPath)) {
         const report = await (0, fs_extra_2.readFile)(reportPath, 'utf-8');
@@ -4442,11 +5141,11 @@ async function buildConfirmCheckPrompt(iteration) {
             prompt += `\n\n... (报告共 ${report.length} 字符，已截断)\n`;
         }
     }
-    // v6.83.0+: 检查是否有 diff 文件
+    // v8.2.0+: 检查黄金需求目录是否有 diff 文件
     let diffFiles = [];
-    if (await (0, fs_extra_1.pathExists)(convertedDir)) {
+    if (await (0, fs_extra_1.pathExists)(goldenDir)) {
         try {
-            const entries = await (0, fs_extra_2.readdir)(convertedDir);
+            const entries = await (0, fs_extra_2.readdir)(goldenDir);
             diffFiles = entries.filter(f => f.includes('-diff.md'));
         }
         catch { /* ignore */ }
@@ -4454,13 +5153,13 @@ async function buildConfirmCheckPrompt(iteration) {
     if (diffFiles.length > 0) {
         prompt += `\n## 已生成的对比报告\n\n`;
         for (const f of diffFiles) {
-            prompt += `- \`converted/${f}\` — 需求澄清对比记录\n`;
+            prompt += `- \`020-specs/requirements/${f}\` — 需求澄清对比记录\n`;
         }
         prompt += '\n';
     }
     prompt += `## 确认检查清单\n\n`;
     prompt += `请逐项确认：\n\n`;
-    prompt += `- [ ] clarified-*.md 已写入 \`010-requirements/converted/\`\n`;
+    prompt += `- [ ] clarified-*.md 已写入 \`020-specs/requirements/\`（黄金需求目录）\n`;
     prompt += `- [ ] 验收标准可测试、可量化\n`;
     prompt += `- [ ] 功能边界明确（不做什么）\n`;
     prompt += `- [ ] 业务流程完整（含异常分支）\n`;
@@ -4484,4 +5183,277 @@ async function buildConfirmCheckPrompt(iteration) {
     prompt += `\`\`\`\n`;
     return await injectGraphSummary(prompt);
 }
+// ================================================================
+// v8.2.0+: 功能单元聚焦分析辅助函数（解决注意力漂移+空模板问题）
+// ================================================================
+/** 解析 [DOC:filename] 标记，将统一报告拆分为多文档 Map */
+function parseDocMarkers(text) {
+    const result = new Map();
+    const markerRegex = /\[DOC:([^\]]+)\]/g;
+    let match;
+    const positions = [];
+    while ((match = markerRegex.exec(text)) !== null) {
+        positions.push({ name: match[1].trim(), index: match.index });
+    }
+    for (let i = 0; i < positions.length; i++) {
+        const start = positions[i].index + `[DOC:${positions[i].name}]`.length;
+        const end = i < positions.length - 1 ? positions[i + 1].index : text.length;
+        const content = text.slice(start, end).trim();
+        result.set(positions[i].name, content);
+    }
+    return result;
+}
+/** 解析 [CLARIFY:filename] 标记，提取需求澄清文档 Map — v8.3.0+ */
+function parseClarifyMarkers(text) {
+    const result = new Map();
+    const markerRegex = /\[CLARIFY:([^\]]+)\]/g;
+    let match;
+    const positions = [];
+    while ((match = markerRegex.exec(text)) !== null) {
+        positions.push({ name: match[1].trim(), index: match.index });
+    }
+    for (let i = 0; i < positions.length; i++) {
+        const start = positions[i].index + `[CLARIFY:${positions[i].name}]`.length;
+        const end = i < positions.length - 1 ? positions[i + 1].index : text.length;
+        const content = text.slice(start, end).trim();
+        result.set(positions[i].name, content);
+    }
+    return result;
+}
+exports.UNITS_CACHE_DIR = '.speccore/cache/unit-analysis';
+/** 从需求文档提取功能单元清单 */
+async function extractIterationUnits(iterDir) {
+    const reqDir = (0, path_1.join)(iterDir, '010-requirements');
+    const units = [];
+    let idCounter = 1;
+    if (!await (0, fs_extra_1.pathExists)(reqDir))
+        return units;
+    const reqFiles = [];
+    async function scanDir(dir) {
+        const entries = await (0, fs_extra_2.readdir)(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = (0, path_1.join)(dir, entry.name);
+            if (entry.isDirectory())
+                await scanDir(fullPath);
+            else if (entry.name.endsWith('.md'))
+                reqFiles.push(fullPath);
+        }
+    }
+    await scanDir(reqDir);
+    for (const file of reqFiles) {
+        const content = await (0, fs_extra_2.readFile)(file, 'utf-8');
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const headingMatch = line.match(/^#{2,3}\s+(.+)$/);
+            if (!headingMatch)
+                continue;
+            const name = headingMatch[1].trim();
+            // 跳过通用标题
+            const skipKeywords = ['需求概述', '术语表', '附录', '测试策略', '参考资料', '目录', '引言', '背景'];
+            if (skipKeywords.some(k => name.includes(k)))
+                continue;
+            // 收集后续 1-15 行作为内容摘要
+            let descLines = [];
+            for (let j = i + 1; j < Math.min(i + 16, lines.length); j++) {
+                const l = lines[j];
+                if (l.match(/^#{1,3}\s+/))
+                    break;
+                if (l.trim())
+                    descLines.push(l.trim());
+            }
+            units.push({
+                id: `M-${String(idCounter++).padStart(2, '0')}`,
+                name,
+                source: (0, path_1.relative)(reqDir, file),
+                sourceRange: { startLine: i + 1, endLine: i + 1 + descLines.length },
+                content: descLines.join('\n').slice(0, 500),
+            });
+            if (idCounter > 30)
+                break; // 最多识别 30 个功能单元
+        }
+        if (idCounter > 30)
+            break;
+    }
+    return units;
+}
+/** 保存单元分析结果到缓存 */
+async function saveUnitAnalysis(iteration, analysis) {
+    const cacheDir = (0, path_1.join)(process.cwd(), exports.UNITS_CACHE_DIR, iteration);
+    await (0, fs_extra_1.ensureDir)(cacheDir);
+    const fp = (0, path_1.join)(cacheDir, `${analysis.id}.json`);
+    await (0, fs_extra_1.writeFile)(fp, JSON.stringify(analysis, null, 2));
+}
+/** 读取已完成的单元分析 */
+async function loadUnitAnalyses(iteration) {
+    const cacheDir = (0, path_1.join)(process.cwd(), exports.UNITS_CACHE_DIR, iteration);
+    if (!await (0, fs_extra_1.pathExists)(cacheDir))
+        return [];
+    const files = (await (0, fs_extra_2.readdir)(cacheDir)).filter(f => f.endsWith('.json'));
+    const results = [];
+    for (const f of files) {
+        try {
+            const content = await (0, fs_extra_2.readFile)((0, path_1.join)(cacheDir, f), 'utf-8');
+            results.push(JSON.parse(content));
+        }
+        catch { /* skip */ }
+    }
+    return results.sort((a, b) => a.id.localeCompare(b.id));
+}
+/** 检测未完成的单元分析 */
+async function detectPendingUnits(iteration, allUnits) {
+    const completed = await loadUnitAnalyses(iteration);
+    const completedIds = new Set(completed.map(a => a.id));
+    return allUnits.filter(u => !completedIds.has(u.id));
+}
+/** 汇总所有单元分析为统一报告（带 [DOC:xxx] 标记） */
+async function consolidateUnitAnalyses(iteration, units, analyses) {
+    const lines = [];
+    lines.push(`# ${iteration} 迭代 Spec 统一报告`);
+    lines.push(`> 生成时间: ${new Date().toISOString()}`);
+    lines.push(`> 共 ${analyses.length}/${units.length} 个功能单元已完成分析`);
+    lines.push('');
+    // 汇总 REQUIREMENT.md
+    lines.push('[DOC:REQUIREMENT.md]');
+    lines.push(`# ${iteration} 需求规格`);
+    lines.push('');
+    lines.push('## 功能模块清单');
+    lines.push('| 单元ID | 模块名称 | 需求来源 |');
+    lines.push('|:---|:---|:---|');
+    for (const u of units) {
+        lines.push(`| ${u.id} | ${u.name} | ${u.source}#L${u.sourceRange.startLine} |`);
+    }
+    lines.push('');
+    for (const a of analyses) {
+        lines.push(`### ${a.id} ${a.name}`);
+        lines.push(a.req.split('\n').slice(0, 5).join('\n'));
+        lines.push('');
+    }
+    lines.push('');
+    // 汇总 ANALYSIS.md
+    lines.push('[DOC:ANALYSIS.md]');
+    lines.push(`# ${iteration} 架构分析`);
+    lines.push('');
+    for (const a of analyses) {
+        lines.push(`## ${a.id} ${a.name}`);
+        lines.push(a.tech);
+        lines.push('');
+    }
+    lines.push('');
+    // 汇总 FUNCTION_MAP.md
+    lines.push('[DOC:FUNCTION_MAP.md]');
+    lines.push(`# ${iteration} 功能映射`);
+    lines.push('');
+    lines.push('| 单元ID | 功能模块 | 涉及端 | 优先级 |');
+    lines.push('|:---|:---|:---|:---|');
+    for (const a of analyses) {
+        lines.push(`| ${a.id} | ${a.name} | ${(a.tech.match(/端[:：]\s*(.+)/)?.[1] || '待定')} | P1 |`);
+    }
+    lines.push('');
+    // 汇总 TECH.md
+    lines.push('[DOC:TECH.md]');
+    lines.push(`# ${iteration} 技术方案`);
+    lines.push('');
+    for (const a of analyses) {
+        lines.push(`## ${a.id} ${a.name}`);
+        lines.push(a.tech);
+        lines.push('');
+    }
+    lines.push('');
+    // 汇总 TEST.md
+    lines.push('[DOC:TEST.md]');
+    lines.push(`# ${iteration} 测试方案`);
+    lines.push('');
+    for (const a of analyses) {
+        lines.push(`## ${a.id} ${a.name}`);
+        lines.push(a.test);
+        lines.push('');
+    }
+    lines.push('');
+    // 汇总 RISK.md
+    lines.push('[DOC:RISK.md]');
+    lines.push(`# ${iteration} 风险评估`);
+    lines.push('');
+    for (const a of analyses) {
+        if (a.risk) {
+            lines.push(`## ${a.id} ${a.name}`);
+            lines.push(a.risk);
+            lines.push('');
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/** 构建单个功能单元的深度分析 Prompt */
+async function buildUnitAnalysisPrompt(iterDir, iteration, unit, allUnits) {
+    // 使用智能上下文组装引擎（三层上下文模型）
+    const unitRef = { id: unit.id, name: unit.name, content: unit.content };
+    const allUnitRefs = allUnits.map(u => ({ id: u.id, name: u.name, content: u.content }));
+    const ctxResult = await (0, unit_context_assembler_1.assembleUnitContext)(iterDir, iteration, unitRef, allUnitRefs, {
+        maxTokens: 6000,
+        maxRelatedUnits: 3,
+        maxCodeFiles: 5,
+        useKnowledgeGraph: true,
+    });
+    const prompt = `
+# 功能单元深度分析: ${unit.id} ${unit.name}
+
+## 迭代信息
+- 迭代: ${iteration}
+- 单元ID: ${unit.id}
+- 来源: ${unit.source}#L${unit.sourceRange.startLine}
+- 全迭代共 ${allUnits.length} 个功能单元
+- 上下文预算: ${ctxResult.stats.estimatedTokens} tokens (核心${ctxResult.stats.coreChars}字符 + 关联${ctxResult.stats.relatedUnitChars + ctxResult.stats.codeChars}字符 + 全局${ctxResult.stats.globalChars}字符)
+
+## 需求上下文
+${ctxResult.context}
+
+## 分析要求
+
+请对「${unit.name}」进行深度分析，输出以下文档（使用 [DOC:xxx] 标记分隔）：
+
+### [DOC:REQ.md] 需求规格
+- 功能描述（用户故事格式）
+- 输入/输出定义
+- 业务规则（R-XX 编号）
+- 异常场景
+
+### [DOC:TECH.md] 技术方案
+- 数据模型/接口设计
+- 核心算法/逻辑
+- 端分工（backend/web/admin 等）
+- 依赖服务
+
+### [DOC:TEST.md] 测试方案
+- 验收标准（Given-When-Then）
+- 边界值
+- 异常路径
+
+### [DOC:RISK.md] 风险评估（如适用）
+- 技术风险
+- 业务风险
+- 缓解方案
+
+## 输出格式
+\`\`\`
+[DOC:REQ.md]
+（内容...）
+
+[DOC:TECH.md]
+（内容...）
+
+[DOC:TEST.md]
+（内容...）
+
+[DOC:RISK.md]
+（内容...）
+\`\`\`
+
+## 重要提示
+- 只分析当前功能单元「${unit.name}」，不要涉及其他模块
+- 每个文档必须有实质内容，不能是空模板
+- 使用具体的技术术语，避免泛泛而谈
+`;
+    return prompt.trim();
+}
 //# sourceMappingURL=analyze.js.map