speccore 8.3.121 → 8.3.126

package/dist/commands/analyze.js

@@ -83,9 +83,101 @@ const agents_1 = require("../core/agents");
 const code_graph_1 = require("../core/code-graph");
 // v7.2.0+: 结构化代码数据提取
 const structured_extractor_1 = require("../core/structured-extractor");
+/**
+ * 按 Markdown 标题合并文档内容
+ * v8.3.122+: 新内容中存在的章节替换旧章节，新章节追加，旧文档中未变动的章节保留
+ */
+function mergeDocumentContent(existing, newContent) {
+    if (!existing.trim())
+        return newContent;
+    // 解析文档为标题块
+    function parseSections(text) {
+        const sections = new Map();
+        const lines = text.split('\n');
+        let currentHeading = '';
+        let currentLevel = 0;
+        let currentBody = [];
+        let headerLines = []; // 文档开头无标题的内容
+        for (const line of lines) {
+            const hm = line.match(/^(#{1,3})\s+(.+)/);
+            if (hm) {
+                if (currentHeading) {
+                    sections.set(currentHeading, {
+                        heading: currentHeading,
+                        level: currentLevel,
+                        body: currentBody.join('\n'),
+                    });
+                }
+                else if (currentBody.length > 0) {
+                    headerLines = [...currentBody];
+                }
+                currentHeading = hm[2].trim();
+                currentLevel = hm[1].length;
+                currentBody = [line];
+            }
+            else {
+                currentBody.push(line);
+            }
+        }
+        if (currentHeading) {
+            sections.set(currentHeading, {
+                heading: currentHeading,
+                level: currentLevel,
+                body: currentBody.join('\n'),
+            });
+        }
+        // 保存文档头部内容（如 frontmatter、标题等）
+        if (headerLines.length > 0) {
+            sections.set('__HEADER__', { heading: '__HEADER__', level: 0, body: headerLines.join('\n') });
+        }
+        return sections;
+    }
+    const oldSections = parseSections(existing);
+    const newSections = parseSections(newContent);
+    // 构建合并结果：保留旧文档的头部，按旧文档顺序输出
+    // 对于每个旧章节：如果新文档有同名章节，用新内容替换；否则保留旧内容
+    // 新文档中有但旧文档中没有的章节，追加到最后
+    const result = [];
+    // 先输出头部
+    const header = oldSections.get('__HEADER__');
+    if (header) {
+        result.push(header.body);
+        oldSections.delete('__HEADER__');
+    }
+    newSections.delete('__HEADER__');
+    // 收集旧文档中存在的章节标题顺序
+    const oldOrder = [...oldSections.keys()];
+    const addedNew = new Set();
+    for (const heading of oldOrder) {
+        if (newSections.has(heading)) {
+            result.push(newSections.get(heading).body);
+            addedNew.add(heading);
+        }
+        else {
+            result.push(oldSections.get(heading).body);
+        }
+    }
+    // 追加新文档中旧文档没有的章节
+    for (const [heading, section] of newSections) {
+        if (!addedNew.has(heading)) {
+            result.push(section.body);
+        }
+    }
+    return result.join('\n\n');
+}
+/** 写入文件，支持 --merge 模式（与现有内容按标题合并） */
+async function writeFileMerged(fp, content, merge) {
+    if (merge && await (0, fs_extra_1.pathExists)(fp)) {
+        const existing = await (0, fs_extra_2.readFile)(fp, 'utf-8');
+        content = mergeDocumentContent(existing, content);
+    }
+    await (0, fs_extra_1.writeFile)(fp, content);
+}
 async function analyzeCommand(options) {
     // v6.97.0+ 修复：全局分析时统一设置 iteration 为 'GLOBAL'，避免任何 fallback 到 getDefaultIteration()
     // 这是根治方案：后面所有 "options.iteration || await getDefaultIteration()" 都会命中 options.iteration
+    // v8.3.102+: 向上查找项目根目录（支持在子目录执行）
+    const _projectRoot = (0, task_utils_1.findProjectRoot)() || process.cwd();
     if (options.scope === 'global' && !options.iteration) {
         options.iteration = 'GLOBAL';
     }
@@ -321,7 +413,7 @@ async function analyzeCommand(options) {
         // 自动刷新知识图谱
         try {
             const { refreshKnowledgeGraph } = await Promise.resolve().then(() => __importStar(require('../core/knowledge-graph')));
-            await refreshKnowledgeGraph(process.cwd(), iter);
+            await refreshKnowledgeGraph(_projectRoot, iter);
             logger_1.logger.info('🧠 知识图谱已刷新');
         }
         catch { }
@@ -355,7 +447,7 @@ async function analyzeCommand(options) {
         // 自动刷新知识图谱
         try {
             const { refreshKnowledgeGraph } = await Promise.resolve().then(() => __importStar(require('../core/knowledge-graph')));
-            await refreshKnowledgeGraph(process.cwd(), iter);
+            await refreshKnowledgeGraph(_projectRoot, iter);
             logger_1.logger.info('🧠 知识图谱已刷新');
         }
         catch { }
@@ -375,7 +467,7 @@ async function analyzeCommand(options) {
         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');
+        const unitsCachePath = (0, path_1.join)(_projectRoot, 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'));
@@ -495,7 +587,7 @@ async function analyzeCommand(options) {
     // 命令前索引新鲜度检查（非阻塞）
     // v6.97.0+ 修复：全局分析时不检查迭代级索引，避免误导用户
     if (options.scope !== 'global') {
-        await (0, index_guard_1.warnIfIndexStale)(process.cwd(), 'analyze', options.iteration);
+        await (0, index_guard_1.warnIfIndexStale)(_projectRoot, 'analyze', options.iteration);
     }
     // v8.3.0+: 需求澄清检测状态（跨代码块共享）
     let needsClarify = false;
@@ -658,7 +750,7 @@ async function analyzeCommand(options) {
             // 全局分析：预创建 .speccore/GLOBAL/ 目录结构，不写迭代目录
             // v6.81.0+: 需求文档单独放在 requirements/ 下，技术文档放在 platforms/ 下
             // v7.2.0+: 全局技术文档统一放在 overview/ 子目录下，与迭代层 020-specs/overview/ 命名一致
-            const globalDir = (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL');
+            const globalDir = (0, path_1.join)(_projectRoot, '.speccore', 'GLOBAL');
             await (0, fs_extra_1.ensureDir)(globalDir);
             await (0, fs_extra_1.ensureDir)((0, path_1.join)(globalDir, 'overview'));
             await (0, fs_extra_1.ensureDir)((0, path_1.join)(globalDir, 'platforms'));
@@ -736,7 +828,7 @@ async function analyzeCommand(options) {
         let platformOrder;
         if (!isGlobalScope && iter) {
             // 变更感知：检测 Git 变更影响的端
-            affectedPlatforms = await (0, change_detection_1.detectAffectedPlatforms)(process.cwd());
+            affectedPlatforms = await (0, change_detection_1.detectAffectedPlatforms)(_projectRoot);
             // 关键路径优先：按任务优先级排序端
             platformOrder = await (0, change_detection_1.detectPlatformPriorityOrder)(iter);
         }
@@ -750,7 +842,7 @@ async function analyzeCommand(options) {
         }
         else {
             // 迭代层：使用 createAnalyzePipeline（支持契约先行 + 逐端推进 + 变更感知 + 关键路径优先 + 需求澄清）
-            const result = await (0, pipeline_engine_1.createAnalyzePipeline)(iter, process.cwd(), {
+            const result = await (0, pipeline_engine_1.createAnalyzePipeline)(iter, _projectRoot, {
                 affectedPlatforms: affectedPlatforms && affectedPlatforms.length > 0 ? affectedPlatforms : undefined,
                 platformOrder: platformOrder && platformOrder.length > 0 ? platformOrder : undefined,
                 skipClarify: options.skipClarify,
@@ -762,10 +854,10 @@ async function analyzeCommand(options) {
             initStep = options.skipClarify ? 'phase1-prompt' : 'clarify-prompt';
         }
         // 检查是否有活跃的 Pipeline（恢复模式）
-        const hasActive = await pipeline_engine_1.PipelineEngine.hasActivePipeline(process.cwd(), pipelineKey);
+        const hasActive = await pipeline_engine_1.PipelineEngine.hasActivePipeline(_projectRoot, pipelineKey);
         let currentStep;
         if (hasActive) {
-            const existingState = await pipeline_engine_1.PipelineEngine.loadExistingState(process.cwd(), pipelineKey);
+            const existingState = await pipeline_engine_1.PipelineEngine.loadExistingState(_projectRoot, pipelineKey);
             currentStep = existingState?.currentStep || initStep;
             logger_1.logger.info(`🔄 恢复 Pipeline: ${currentStep}`);
         }
@@ -967,7 +1059,7 @@ ${singlePrompt}`);
                 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(`   ✅ 澄清文档已写入: ${(0, path_1.relative)(process.cwd(), fp)}`);
+                logger_1.logger.info(`   ✅ 澄清文档已写入: ${(0, path_1.relative)(_projectRoot, fp)}`);
             }
             logger_1.logger.info('');
         }
@@ -1039,13 +1131,13 @@ ${singlePrompt}`);
                 }
                 else if (isGlobalScope) {
                     // 全局级：写入 .speccore/GLOBAL/（与 platforms/ 同级，非迭代目录）
-                    const globalBaseDir = (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL');
+                    const globalBaseDir = (0, path_1.join)(_projectRoot, '.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)) {
                         // PATTERNS/ 文件特殊处理 → 写入 .speccore/PATTERNS/
                         if (filename.startsWith('PATTERNS/')) {
-                            const patternsDir = (0, path_1.join)(process.cwd(), '.speccore', 'PATTERNS');
+                            const patternsDir = (0, path_1.join)(_projectRoot, '.speccore', 'PATTERNS');
                             await (0, fs_extra_1.ensureDir)(patternsDir);
                             const patternFile = filename.slice('PATTERNS/'.length);
                             const fp = (0, path_1.join)(patternsDir, patternFile);
@@ -1186,7 +1278,7 @@ ${singlePrompt}`);
                         }
                         // v6.72.0+: PATTERNS/ 文件特殊处理 → 写入 .speccore/PATTERNS/
                         if (filename.startsWith('PATTERNS/')) {
-                            const patternsDir = (0, path_1.join)(process.cwd(), '.speccore', 'PATTERNS');
+                            const patternsDir = (0, path_1.join)(_projectRoot, '.speccore', 'PATTERNS');
                             await (0, fs_extra_1.ensureDir)(patternsDir);
                             const patternFile = filename.slice('PATTERNS/'.length);
                             const fp = (0, path_1.join)(patternsDir, patternFile);
@@ -1215,7 +1307,7 @@ ${singlePrompt}`);
                                 const targetDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
                                 await (0, fs_extra_1.ensureDir)(targetDir);
                                 const fp = (0, path_1.join)(targetDir, parts.slice(1).join('/'));
-                                if (!(await (0, task_utils_1.shouldOverwrite)(fp, !!options.interactive))) {
+                                if (!options.merge && !(await (0, task_utils_1.shouldOverwrite)(fp, !!options.interactive))) {
                                     logger_1.logger.info(`   ⏭️  跳过: ${filename}`);
                                     continue;
                                 }
@@ -1224,7 +1316,9 @@ ${singlePrompt}`);
                                     backups.push(bk);
                                     logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
                                 }
-                                await (0, fs_extra_1.writeFile)(fp, content);
+                                await writeFileMerged(fp, content, !!options.merge);
+                                if (options.merge)
+                                    logger_1.logger.info(`   🔀 ${filename} 已合并`);
                                 count++;
                                 continue;
                             }
@@ -1235,7 +1329,7 @@ ${singlePrompt}`);
                                     const targetDir = (0, path_1.join)(specDir, ...parts.slice(0, -1));
                                     await (0, fs_extra_1.ensureDir)(targetDir);
                                     const fp = (0, path_1.join)(targetDir, parts[parts.length - 1]);
-                                    if (!(await (0, task_utils_1.shouldOverwrite)(fp, !!options.interactive))) {
+                                    if (!options.merge && !(await (0, task_utils_1.shouldOverwrite)(fp, !!options.interactive))) {
                                         logger_1.logger.info(`   ⏭️  跳过: ${filename}`);
                                         continue;
                                     }
@@ -1244,7 +1338,9 @@ ${singlePrompt}`);
                                         backups.push(bk);
                                         logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
                                     }
-                                    await (0, fs_extra_1.writeFile)(fp, content);
+                                    await writeFileMerged(fp, content, !!options.merge);
+                                    if (options.merge)
+                                        logger_1.logger.info(`   🔀 ${filename} 已合并`);
                                     count++;
                                     continue;
                                 }
@@ -1282,7 +1378,7 @@ ${singlePrompt}`);
                         }
                         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))) {
+                        if (!options.merge && !(await (0, task_utils_1.shouldOverwrite)(fp, !!options.interactive))) {
                             logger_1.logger.info(`   ⏭️  跳过: ${filename}`);
                             continue;
                         }
@@ -1291,7 +1387,9 @@ ${singlePrompt}`);
                             backups.push(bk);
                             logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
                         }
-                        await (0, fs_extra_1.writeFile)(fp, content);
+                        await writeFileMerged(fp, content, !!options.merge);
+                        if (options.merge)
+                            logger_1.logger.info(`   🔀 ${filename} 已合并`);
                         count++;
                     }
                     if (skippedCount > 0) {
@@ -1356,7 +1454,7 @@ ${singlePrompt}`);
                     await sanitizeSpecDirectories(iterDir);
                     // v8.3.14+: analyze --apply 后自动清理归档文件和临时文件
                     await (0, cleanup_1.cleanupByType)({
-                        cwd: process.cwd(),
+                        cwd: _projectRoot,
                         types: ['archiveFiles', 'archiveDirs', 'tempFiles'],
                         days: 0, // 不限天数，清理所有归档和临时文件
                         silent: true,
@@ -1476,12 +1574,12 @@ ${singlePrompt}`);
                     logger_1.logger.success(`✅ ${count} 个 Spec 文档已写入 ${options.task}${platformLabel}/（任务级，迭代基线不变）`);
                 }
                 else if (isGlobalScope) {
-                    const globalBaseDir = (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL');
+                    const globalBaseDir = (0, path_1.join)(_projectRoot, '.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');
+                            const patternsDir = (0, path_1.join)(_projectRoot, '.speccore', 'PATTERNS');
                             await (0, fs_extra_1.ensureDir)(patternsDir);
                             const patternFile = filename.slice('PATTERNS/'.length);
                             const fp = (0, path_1.join)(patternsDir, patternFile);
@@ -1576,7 +1674,7 @@ ${singlePrompt}`);
                             continue;
                         }
                         if (filename.startsWith('PATTERNS/')) {
-                            const patternsDir = (0, path_1.join)(process.cwd(), '.speccore', 'PATTERNS');
+                            const patternsDir = (0, path_1.join)(_projectRoot, '.speccore', 'PATTERNS');
                             await (0, fs_extra_1.ensureDir)(patternsDir);
                             const patternFile = filename.slice('PATTERNS/'.length);
                             const fp = (0, path_1.join)(patternsDir, patternFile);
@@ -1639,7 +1737,7 @@ ${singlePrompt}`);
                     await sanitizeSpecDirectories(iterDir);
                     // v8.3.14+: analyze --apply 后自动清理归档文件和临时文件
                     await (0, cleanup_1.cleanupByType)({
-                        cwd: process.cwd(),
+                        cwd: _projectRoot,
                         types: ['archiveFiles', 'archiveDirs', 'tempFiles'],
                         days: 0,
                         silent: true,
@@ -1648,7 +1746,7 @@ ${singlePrompt}`);
                 // 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');
+                        const unitsCachePath = (0, path_1.join)(_projectRoot, 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'));
@@ -1702,7 +1800,7 @@ ${singlePrompt}`);
         }
         else if (isGlobalScope) {
             // 全局级：写 .speccore/GLOBAL/ANALYSIS.md
-            const globalDir = (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL');
+            const globalDir = (0, path_1.join)(_projectRoot, '.speccore', 'GLOBAL');
             await (0, fs_extra_1.ensureDir)(globalDir);
             const globalAnalysisPath = (0, path_1.join)(globalDir, 'ANALYSIS.md');
             if (await (0, task_utils_1.shouldOverwrite)(globalAnalysisPath, !!options.interactive)) {
@@ -1762,7 +1860,7 @@ ${singlePrompt}`);
         if (options.iteration) {
             try {
                 const { refreshKnowledgeGraph } = await Promise.resolve().then(() => __importStar(require('../core/knowledge-graph')));
-                await refreshKnowledgeGraph(process.cwd(), options.iteration);
+                await refreshKnowledgeGraph(_projectRoot, options.iteration);
                 logger_1.logger.info('🧠 知识图谱已刷新');
             }
             catch { }
@@ -1777,7 +1875,7 @@ ${singlePrompt}`);
                 if (await (0, fs_extra_1.pathExists)(reqDir))
                     dirs.push(reqDir);
                 if (dirs.length > 0) {
-                    await indexDirectoryDocuments(process.cwd(), dirs, `${options.iteration}_iteration_all`, `rag-index-${options.iteration}.json`);
+                    await indexDirectoryDocuments(_projectRoot, dirs, `${options.iteration}_iteration_all`, `rag-index-${options.iteration}.json`);
                     logger_1.logger.info('🔍 迭代 RAG 索引已刷新');
                 }
             }
@@ -1790,7 +1888,7 @@ ${singlePrompt}`);
             const pipelineKey = isGlobalScope ? 'GLOBAL' : options.iteration;
             if (!pipelineKey)
                 return;
-            const hasPipeline = await pipeline_engine_1.PipelineEngine.hasActivePipeline(process.cwd(), pipelineKey);
+            const hasPipeline = await pipeline_engine_1.PipelineEngine.hasActivePipeline(_projectRoot, pipelineKey);
             if (hasPipeline) {
                 const { createAnalyzePipeline, createGlobalAnalyzePipeline } = await Promise.resolve().then(() => __importStar(require('../core/pipeline-engine')));
                 // v6.69.0+: 推进时保持与初始化时相同的过滤和排序条件
@@ -1800,9 +1898,9 @@ ${singlePrompt}`);
                 }
                 else {
                     const { detectAffectedPlatforms, detectPlatformPriorityOrder } = await Promise.resolve().then(() => __importStar(require('../core/change-detection')));
-                    const affectedPlatforms = await detectAffectedPlatforms(process.cwd());
+                    const affectedPlatforms = await detectAffectedPlatforms(_projectRoot);
                     const platformOrder = await detectPlatformPriorityOrder(options.iteration);
-                    engine = (await createAnalyzePipeline(options.iteration, process.cwd(), {
+                    engine = (await createAnalyzePipeline(options.iteration, _projectRoot, {
                         affectedPlatforms: affectedPlatforms.length > 0 ? affectedPlatforms : undefined,
                         platformOrder: platformOrder.length > 0 ? platformOrder : undefined,
                     })).engine;
@@ -2444,7 +2542,7 @@ async function injectGraphSummary(prompt) {
         if (_graphSummaryCache && Date.now() - _graphSummaryCacheTime < GRAPH_SUMMARY_TTL) {
             return prompt + _graphSummaryCache;
         }
-        const cg = await (0, code_graph_1.loadCodeGraph)(process.cwd());
+        const cg = await (0, code_graph_1.loadCodeGraph)(((0, task_utils_1.findProjectRoot)() || process.cwd()));
         if (!cg)
             return prompt;
         const lines = [];
@@ -2495,7 +2593,7 @@ async function injectGraphSummary(prompt) {
 // ── v7.2.0+: 检测全局分析当前进度 ──
 // Layer 4 拆分为子层: 4a=产品文档, 4b=全局技术核心, 4c=全局技术扩展, 4d=各端技术
 async function detectGlobalLayerProgress() {
-    const globalDir = (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL');
+    const globalDir = (0, path_1.join)(((0, task_utils_1.findProjectRoot)() || process.cwd()), '.speccore', 'GLOBAL');
     let completedLayer = 0;
     const missing = [];
     // Layer 1: 检查各端 _INDEX.md
@@ -2695,7 +2793,7 @@ async function buildGlobalAnalysisGuide(options) {
     // 下一步命令
     guide += '\n➡️  下一步:\n';
     if (deepDoc && options?.iterative) {
-        const outlinePath = (0, path_1.join)(process.cwd(), '.speccore', 'cache', `deep-outline-${deepDoc.replace(/\//g, '-')}.md`);
+        const outlinePath = (0, path_1.join)(((0, task_utils_1.findProjectRoot)() || 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`;
@@ -2858,11 +2956,13 @@ async function buildMultiDocPrompt(command, ctx, options, clarifyCtx) {
         const targetLayer = options?.layer || progress.nextLayer;
         const isLayered = !!options?.layer || progress.completedLayer < 4;
         // v7.2.0+: 结构化代码数据提取 — Layer 1 之前自动执行
+        // v8.3.125+: 按迭代涉及的端筛选源码路径（避免全量扫描无关端）
         let structuredDataHint = '';
         if (targetLayer === 1 && ctx.withCode) {
             try {
+                const projectRoot = (0, task_utils_1.findProjectRoot)() || process.cwd();
                 // 读取 CONSTITUTION.md 获取源码路径
-                const constitutionPath = (0, path_1.join)(process.cwd(), '.speccore', 'CONSTITUTION.md');
+                const constitutionPath = (0, path_1.join)(projectRoot, '.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');
@@ -2871,7 +2971,54 @@ async function buildMultiDocPrompt(command, ctx, options, clarifyCtx) {
                         sourcePaths = match.map(m => m.replace(/.*-\s*`?/, '').replace(/`?$/, '').trim()).filter(Boolean);
                     }
                 }
-                await (0, structured_extractor_1.extractStructuredData)(process.cwd(), sourcePaths);
+                // v8.3.125+: 按迭代端名筛选源码路径（宁可多扫不要漏扫）
+                const iterDir = ctx.iteration ? await (0, context_1.getIterationDir)(ctx.iteration) : null;
+                let filteredPaths = sourcePaths;
+                if (iterDir && sourcePaths.length > 1) {
+                    try {
+                        // 1. 尝试从 PLATFORMS.md 读取端列表
+                        let platformNames = [];
+                        const platformsPath = (0, path_1.join)(iterDir, '020-specs', 'PLATFORMS.md');
+                        if (await (0, fs_extra_1.pathExists)(platformsPath)) {
+                            const pContent = await (0, fs_extra_2.readFile)(platformsPath, 'utf-8');
+                            const pMatch = pContent.match(/-\s*(\w+)/g);
+                            if (pMatch)
+                                platformNames = pMatch.map(m => m.replace(/^-\s*/, '').trim().toLowerCase());
+                        }
+                        // 2.  fallback：从 020-specs/ 子目录推断端名
+                        if (platformNames.length === 0) {
+                            const specsDir = (0, path_1.join)(iterDir, '020-specs');
+                            if (await (0, fs_extra_1.pathExists)(specsDir)) {
+                                const entries = await (0, fs_extra_2.readdir)(specsDir, { withFileTypes: true });
+                                platformNames = entries
+                                    .filter(e => e.isDirectory() && e.name !== 'overview' && e.name !== 'requirements')
+                                    .map(e => e.name.toLowerCase());
+                            }
+                        }
+                        // 3. 筛选 sourcePaths（路径包含端名则保留）
+                        if (platformNames.length > 0) {
+                            const matched = sourcePaths.filter(sp => {
+                                const lower = sp.toLowerCase();
+                                return platformNames.some(pn => lower.includes(pn));
+                            });
+                            // 同时保留 shared/common/lib 等公共路径
+                            const sharedPaths = sourcePaths.filter(sp => /shared|common|lib|utils|pkg/.test(sp.toLowerCase()));
+                            const combined = [...new Set([...matched, ...sharedPaths])];
+                            // 宁可多扫不要漏扫：如果筛选后为空，回退全量
+                            if (combined.length > 0) {
+                                filteredPaths = combined;
+                                logger_1.logger.info(`   📂 结构化数据扫描已按端筛选: ${filteredPaths.join(', ')}（涉及端: ${platformNames.join(', ')}）`);
+                            }
+                            else {
+                                logger_1.logger.info(`   📂 无法按端筛选，回退全量扫描: ${sourcePaths.join(', ')}`);
+                            }
+                        }
+                    }
+                    catch {
+                        // 筛选失败不阻断，回退全量
+                    }
+                }
+                await (0, structured_extractor_1.extractStructuredData)(projectRoot, filteredPaths);
                 structuredDataHint = '\n> 📊 **结构化数据**: 已提取到 `.speccore/cache/structured-data.json`，包含 API/Entity/Route/Component 清单\n';
             }
             catch (e) {
@@ -2909,7 +3056,7 @@ async function buildMultiDocPrompt(command, ctx, options, clarifyCtx) {
         prompt += `- **核心任务**: ${layerMeta.focus}\n`;
         prompt += `- **预期产出**: ${layerMeta.output}\n\n`;
         prompt += `## 要求\n`;
-        prompt += `1. **先读宪法**: Read .speccore/CONSTITUTION.md，获取工程名、源码路径、端列表。\n`;
+        prompt += `1. **先读宪法**: Read .speccore/CONSTITUTION.md，获取工程标识、源码路径、端列表。\n`;
         prompt += `2. Read .speccore/GLOBAL/ 下已有文档（特别是前一层的产物）作为输入。\n`;
         prompt += `3. **禁止行为**: 不要打开浏览器、不要模拟用户操作、不要访问 URL。所有分析基于直接 Read 源码。\n`;
         if (ctx.withCode) {
@@ -3044,7 +3191,7 @@ async function buildMultiDocPrompt(command, ctx, options, clarifyCtx) {
             prompt += `**每个功能模块涉及哪些端，就读取那些端的详细源码**：\n\n`;
             // v7.4.5+: CLI 预提取每个功能模块的代码上下文
             try {
-                const modulesCtx = await buildLayer3ModuleContext(process.cwd());
+                const modulesCtx = await buildLayer3ModuleContext(((0, task_utils_1.findProjectRoot)() || process.cwd()));
                 if (modulesCtx) {
                     prompt += `## 📎 CLI 预提取的功能模块代码上下文（v7.4.5+）\n\n`;
                     prompt += `> 以下内容由 CLI 从 structured-data.json 和 _MODULES.md 自动提取，你不需要自己搜索。\n`;
@@ -3468,7 +3615,7 @@ async function buildMultiDocPrompt(command, ctx, options, clarifyCtx) {
             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 outlinePath = (0, path_1.join)(((0, task_utils_1.findProjectRoot)() || process.cwd()), '.speccore', 'cache', `deep-outline-${deepDoc.replace(/\//g, '-')}.md`);
                 const hasOutline = await (0, fs_extra_1.pathExists)(outlinePath);
                 if (options?.iterative && !hasOutline) {
                     // 迭代模式第一步：输出大纲
@@ -3534,7 +3681,7 @@ async function buildMultiDocPrompt(command, ctx, options, clarifyCtx) {
             }
             else {
                 // v7.5.0+: 子层内逐文档生成 — 检测当前子层中哪些文档已存在，每次只生成下一个缺失的
-                const globalDir = (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL');
+                const globalDir = (0, path_1.join)(((0, task_utils_1.findProjectRoot)() || process.cwd()), '.speccore', 'GLOBAL');
                 const overviewDir = (0, path_1.join)(globalDir, 'overview');
                 const requirementsDir = (0, path_1.join)(globalDir, 'requirements');
                 const platformsDir = (0, path_1.join)(globalDir, 'platforms');
@@ -3588,7 +3735,7 @@ async function buildMultiDocPrompt(command, ctx, options, clarifyCtx) {
                 const existingDocs = [];
                 const missingDocs = [];
                 for (const doc of expectedDocs) {
-                    const fullPath = (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL', doc);
+                    const fullPath = (0, path_1.join)(((0, task_utils_1.findProjectRoot)() || process.cwd()), '.speccore', 'GLOBAL', doc);
                     if (await (0, fs_extra_1.pathExists)(fullPath)) {
                         existingDocs.push(doc);
                     }
@@ -4309,9 +4456,9 @@ status: "clarified"
     if (!isGlobal && ctx.withCode && ctx.iteration && ctx.iteration !== 'GLOBAL') {
         try {
             // 1. 提取结构化数据（如果还没有）
-            const structuredDataPath = (0, path_1.join)(process.cwd(), '.speccore', 'cache', 'structured-data.json');
+            const structuredDataPath = (0, path_1.join)(((0, task_utils_1.findProjectRoot)() || 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');
+                const constitutionPath = (0, path_1.join)(((0, task_utils_1.findProjectRoot)() || 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');
@@ -4321,7 +4468,7 @@ status: "clarified"
                     }
                 }
                 const { extractStructuredData } = await Promise.resolve().then(() => __importStar(require('../core/structured-extractor')));
-                await extractStructuredData(process.cwd(), sourcePaths);
+                await extractStructuredData(((0, task_utils_1.findProjectRoot)() || process.cwd()), sourcePaths);
             }
             // 2. 注入结构化数据摘要到 Prompt
             if (await (0, fs_extra_1.pathExists)(structuredDataPath)) {
@@ -4342,7 +4489,7 @@ status: "clarified"
             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);
+                const featureCtx = await buildFeatureContext(((0, task_utils_1.findProjectRoot)() || process.cwd()), iterDir, options.featureName, options.docName);
                 prompt += buildFeatureContextPrompt(featureCtx);
             }
         }
@@ -4663,7 +4810,7 @@ status: "clarified"
             prompt += `8. **端发现（重要）**：先确定项目有哪些端，再按端组织文档\n`;
             prompt += `   - 第 1 步：Read .speccore/CONSTITUTION.md\n`;
             prompt += `   - 第 2 步：从「## 端列表」章节提取端名（这是全局权威来源）\n`;
-            prompt += `   - 第 3 步：如果没有「端列表」章节，从「对应端」列提取\n`;
+            prompt += `   - 第 3 步：如果没有「端列表」章节，从「对应需求端」列提取\n`;
             prompt += `   - 第 4 步：如果以上都无法确定，根据需求文档内容判断\n`;
             prompt += `   - 第 5 步：将发现的端列表写入 020-specs/PLATFORMS.md\n`;
             // v6.70.0+: REQUIREMENT.md 以产品视角撰写（不按端分章节）
@@ -4908,7 +5055,7 @@ status: "clarified"
     // ── v6.52.0+: 图谱 RAG 上下文注入（analyze 阶段也检索项目关联内容）──
     if (!isTask && ctx.phase !== '2') {
         try {
-            const ragResult = await (0, unified_retrieval_1.unifiedSearch)(process.cwd(), {
+            const ragResult = await (0, unified_retrieval_1.unifiedSearch)(((0, task_utils_1.findProjectRoot)() || process.cwd()), {
                 query: ctx.iteration || '',
                 iteration: ctx.iteration,
                 platform: ctx.platform,
@@ -5169,26 +5316,7 @@ async function getSubtaskDirs(taskDir) {
         }
         catch { /* ignore */ }
     }
-    // 回退: 旧结构 10-backend/ 和 20-frontend/
-    if (result.length === 0) {
-        for (const catDir of ['10-backend', '20-frontend']) {
-            const catPath = (0, path_1.join)(taskDir, catDir);
-            if (!(await (0, fs_extra_1.pathExists)(catPath)))
-                continue;
-            try {
-                for (const svc of await (0, fs_extra_2.readdir)(catPath, { withFileTypes: true })) {
-                    if (!svc.isDirectory())
-                        continue;
-                    for (const sub of await (0, fs_extra_2.readdir)((0, path_1.join)(catPath, svc.name), { withFileTypes: true })) {
-                        if (sub.isDirectory() && !sub.name.startsWith('.')) {
-                            result.push((0, path_1.join)(catPath, svc.name, sub.name));
-                        }
-                    }
-                }
-            }
-            catch { /* ignore */ }
-        }
-    }
+    // v8.3.121+: 已移除 10-backend/20-frontend 旧结构回退
     return result;
 }
 // ═══════════════════════════════════════════════════════════
@@ -5245,7 +5373,7 @@ async function buildClarifyPhasePrompt(iteration) {
     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();
+    const projectRoot = (0, task_utils_1.findProjectRoot)() || ((0, task_utils_1.findProjectRoot)() || process.cwd());
     const agentContext = {
         iteration,
         iterationDir: iterDir,
@@ -5578,14 +5706,14 @@ async function extractIterationUnits(iterDir) {
 }
 /** 保存单元分析结果到缓存 */
 async function saveUnitAnalysis(iteration, analysis) {
-    const cacheDir = (0, path_1.join)(process.cwd(), exports.UNITS_CACHE_DIR, iteration);
+    const cacheDir = (0, path_1.join)(((0, task_utils_1.findProjectRoot)() || 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);
+    const cacheDir = (0, path_1.join)(((0, task_utils_1.findProjectRoot)() || 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'));