speccore 8.3.285 → 8.3.295

package/dist/core/prompt-builder.js

@@ -69,6 +69,7 @@ const content_delivery_1 = require("./content-delivery");
 // v8.3.183+: HTML 原型渲染（Playwright 截图 + accessibility tree，替代纯文本）
 const html_prototype_1 = require("./html-prototype");
 // v8.3.122+: execute 时深入读取关联源码
+// v8.3.3xx+: 消费前兜底建索引（ensureCodeIndexFresh）+ 迭代源码 scope 解析
 const code_scanner_1 = require("./code-scanner");
 // v8.3.125+: 同义词扩展，解决中英文/缩写关键词匹配失败
 const synonyms_1 = require("../utils/synonyms");
@@ -1560,12 +1561,13 @@ function getInstruction(command, context) {
                 '## 前端实现要求（Layer 3）',
                 '如果任务涉及前端各端（admin/H5/小程序/App），还需：',
                 '1. 按 UI_SPEC.md 中的字段→UI 映射实现每个页面',
-                '2. 按路由表创建页面组件和路由配置',
-                '3. 实现状态枚举的前端展示（与后端数据模型一致）',
-                '4. 实现表单校验规则（与后端校验规则一致）',
-                '5. 实现页面四态：加载中/正常/空态/错误态',
-                '6. 实现响应式适配（按 UI_SPEC.md 中的断点和布局策略）',
-                '7. 前端组件必须与后端 API 响应字段一一对应，不能硬编码',
+                '2. **按 UI_SPEC.md「元素标识约定」给组件添加 data-testid 属性**（命名遵循约定的 {模块}-{页面}-{元素} 格式，页面容器以 xxx-page 结尾）——冒烟测试的 VERIFY_SPEC 断言依赖这些属性定位元素，缺失会导致冒烟失败',
+                '3. 按路由表创建页面组件和路由配置',
+                '4. 实现状态枚举的前端展示（与后端数据模型一致）',
+                '5. 实现表单校验规则（与后端校验规则一致）',
+                '6. 实现页面四态：加载中/正常/空态/错误态',
+                '7. 实现响应式适配（按 UI_SPEC.md 中的断点和布局策略）',
+                '8. 前端组件必须与后端 API 响应字段一一对应，不能硬编码',
                 '',
                 '## 🤖 自动模式指令',
                 '',
@@ -1682,23 +1684,64 @@ async function buildPrompt(command, options) {
         try {
             const iterDir = await (0, context_1.getIterationDir)(options.iteration);
             if (iterDir) {
-                const reqIndex = (0, path_1.join)(iterDir, '010-requirements', 'INDEX.md');
-                if (await (0, fs_extra_1.pathExists)(reqIndex)) {
-                    const idxContent = await (0, fs_extra_1.readFile)(reqIndex, 'utf-8');
-                    const titleMatch = idxContent.match(/^#\s+(.+)$/m);
-                    if (titleMatch)
-                        searchQuery = titleMatch[1].trim();
+                // 优先级：010-requirements/INDEX.md → features/INDEX.md → 需求文档标题（跳过 README.md 规范说明）
+                // 否则 README.md 的「目录规范」标题会污染查询词，导致源码匹配全空；
+                // 泛化标题（功能单元索引/目录规范等）同样丢弃，回退迭代名（含业务语义）
+                const reqIndexCandidates = [
+                    (0, path_1.join)(iterDir, '010-requirements', 'INDEX.md'),
+                    (0, path_1.join)(iterDir, '010-requirements', 'features', 'INDEX.md'),
+                ];
+                const isGenericTitle = (t) => /(目录|索引|规范|说明|README|指南|总览|报告|审查|清单|质量)/i.test(t);
+                let found = false;
+                for (const idxPath of reqIndexCandidates) {
+                    if (await (0, fs_extra_1.pathExists)(idxPath)) {
+                        const idxContent = await (0, fs_extra_1.readFile)(idxPath, 'utf-8');
+                        const titleMatch = idxContent.match(/^#\s+(.+)$/m);
+                        if (titleMatch) {
+                            const t = titleMatch[1].trim();
+                            if (!isGenericTitle(t)) {
+                                searchQuery = t;
+                                found = true;
+                                break;
+                            }
+                        }
+                    }
                 }
-                else {
-                    // 尝试读取第一个需求文档
+                if (!found) {
+                    // 兜底：features/ 下第一个 SOURCE.md 的标题（业务语义最强，如「预订管理」）
+                    const featuresDir = (0, path_1.join)(iterDir, '010-requirements', 'features');
+                    const featureDirs = (await (0, fs_extra_1.readdir)(featuresDir, { withFileTypes: true }).catch(() => []))
+                        .filter((e) => e.isDirectory())
+                        .map((e) => e.name);
+                    for (const fd of featureDirs) {
+                        const sourcePath = (0, path_1.join)(featuresDir, fd, 'SOURCE.md');
+                        if (!(await (0, fs_extra_1.pathExists)(sourcePath)))
+                            continue;
+                        const sourceContent = await (0, fs_extra_1.readFile)(sourcePath, 'utf-8');
+                        const titleMatch = sourceContent.match(/^#\s+(.+)$/m);
+                        if (titleMatch) {
+                            const t = titleMatch[1].trim();
+                            if (!isGenericTitle(t)) {
+                                searchQuery = t;
+                                found = true;
+                                break;
+                            }
+                        }
+                    }
+                }
+                if (!found) {
+                    // 尝试读取第一个需求文档（跳过 README.md 目录规范说明与报告类文档）
                     const reqDir = (0, path_1.join)(iterDir, '010-requirements');
                     const reqFiles = (await (0, fs_extra_1.readdir)(reqDir).catch(() => []))
-                        .filter(f => f.endsWith('.md') && !f.startsWith('.'));
+                        .filter(f => f.endsWith('.md') && !f.startsWith('.') && !/^(README|QUALITY_REPORT|CLARIFY_REPORT)$/i.test(f.replace(/\.md$/, '')));
                     if (reqFiles.length > 0) {
                         const firstReq = await (0, fs_extra_1.readFile)((0, path_1.join)(reqDir, reqFiles[0]), 'utf-8');
                         const titleMatch = firstReq.match(/^#\s+(.+)$/m);
-                        if (titleMatch)
-                            searchQuery = titleMatch[1].trim();
+                        if (titleMatch) {
+                            const t = titleMatch[1].trim();
+                            if (!isGenericTitle(t))
+                                searchQuery = t;
+                        }
                     }
                 }
             }
@@ -1768,7 +1811,6 @@ async function buildPrompt(command, options) {
             // 这是最高优先级的改进：用结构化卡片替代原始源码，Token 效率提升 10-20 倍
             let structuredDataPath = (0, path_1.join)(cwd, '.speccore', 'cache', 'structured-data.json');
             let structured = null;
-            let structuredCardsInjected = false;
             // 优先尝试平台分段文件
             if (options.platform) {
                 const platformPath = (0, path_1.join)(cwd, '.speccore', 'cache', `structured-data.${options.platform}.json`);
@@ -1980,140 +2022,123 @@ async function buildPrompt(command, options) {
                         });
                         const cardChars = cardLines.join('\n').length;
                         logger_1.logger?.info?.(`   📇 结构化卡片: ${matchedApis.length} API + ${matchedEntities.length} Entity + ${matchedComponents.length} Component + ${matchedRoutes.length} Route + ${matchedDtos.length} DTO + ${matchedServices.length} Service (${Math.round(cardChars / 1000)}K 字符)`);
-                        structuredCardsInjected = true;
                     }
                 }
                 catch { /* 结构化数据解析失败不阻断 */ }
             }
-            const codeMatches = await (0, code_scanner_1.findRelevantCode)(searchQuery, 15, undefined, options.iteration, options.task);
+            // v8.3.3xx+: 消费前兜底——索引缺失/过期时自动重建 + 无索引告警
+            // 按迭代解析源码 scope，与 analyze-engine 消费路径保持一致；
+            // 否则兜底构建会落到 DEFAULT_SCOPE（项目根 src/ 等），索引空壳、查询无结果
+            const codeIndexScope = options.iteration
+                ? (await (0, code_scanner_1.resolveIterationScope)(options.iteration).catch(() => undefined))
+                : undefined;
+            await (0, code_scanner_1.ensureCodeIndexFresh)(codeIndexScope);
+            const codeMatches = await (0, code_scanner_1.findRelevantCode)(searchQuery, 20, codeIndexScope, options.iteration, options.task);
             if (codeMatches.length > 0) {
-                // v8.3.124+: 如果已注入结构化卡片，减少原始源码的文件数和长度
-                const sourceMaxFiles = structuredCardsInjected ? 8 : 15;
-                const sourceMaxBytes = structuredCardsInjected ? 60000 : 100000;
-                const sourceContents = await (0, code_scanner_1.readRelevantSource)(codeMatches, sourceMaxBytes, sourceMaxFiles);
-                const sourceKeys = Object.keys(sourceContents);
-                if (sourceKeys.length > 0) {
-                    // v8.3.122+: execute 时注入知识图谱任务上下文
-                    // v8.3.125+: 自动检查过期并刷新
-                    if (command === 'execute' && options.iteration && options.task) {
-                        try {
-                            const kg = await (0, knowledge_graph_1.loadFreshKnowledgeGraph)(cwd, options.iteration);
-                            if (kg) {
-                                const ctx = (0, knowledge_graph_1.getFullTaskContext)(kg, options.task);
-                                const ctxLines = ['## 🔗 任务关联上下文（知识图谱）', ''];
-                                if (ctx.requirement)
-                                    ctxLines.push(`- **上游需求**: ${ctx.requirement.title} (${ctx.requirement.file})`);
-                                if (ctx.parentTask)
-                                    ctxLines.push(`- **父任务**: ${ctx.parentTask.title}`);
-                                if (ctx.dependsOn.length > 0)
-                                    ctxLines.push(`- **依赖任务**（需先完成）: ${ctx.dependsOn.map(d => d.title).join(', ')}`);
-                                if (ctx.downstreamTasks.length > 0)
-                                    ctxLines.push(`- **下游任务**（依赖本任务）: ${ctx.downstreamTasks.map(d => d.title).join(', ')}`);
-                                if (ctx.relatedSpecs.length > 0) {
-                                    ctxLines.push(`- **关联规格文档**:`);
-                                    for (const spec of ctx.relatedSpecs) {
-                                        ctxLines.push(`  - ${spec.title}: \`${spec.file}\``);
-                                    }
-                                }
-                                if (ctx.dependencyChain.length > 0) {
-                                    ctxLines.push(`- **依赖链路**: ${ctx.dependencyChain.map(c => c.taskName).join(' → ')}`);
+                // v8.3.122+: execute 时注入知识图谱任务上下文
+                // v8.3.125+: 自动检查过期并刷新
+                if (command === 'execute' && options.iteration && options.task) {
+                    try {
+                        const kg = await (0, knowledge_graph_1.loadFreshKnowledgeGraph)(cwd, options.iteration);
+                        if (kg) {
+                            const ctx = (0, knowledge_graph_1.getFullTaskContext)(kg, options.task);
+                            const ctxLines = ['## 🔗 任务关联上下文（知识图谱）', ''];
+                            if (ctx.requirement)
+                                ctxLines.push(`- **上游需求**: ${ctx.requirement.title} (${ctx.requirement.file})`);
+                            if (ctx.parentTask)
+                                ctxLines.push(`- **父任务**: ${ctx.parentTask.title}`);
+                            if (ctx.dependsOn.length > 0)
+                                ctxLines.push(`- **依赖任务**（需先完成）: ${ctx.dependsOn.map(d => d.title).join(', ')}`);
+                            if (ctx.downstreamTasks.length > 0)
+                                ctxLines.push(`- **下游任务**（依赖本任务）: ${ctx.downstreamTasks.map(d => d.title).join(', ')}`);
+                            if (ctx.relatedSpecs.length > 0) {
+                                ctxLines.push(`- **关联规格文档**:`);
+                                for (const spec of ctx.relatedSpecs) {
+                                    ctxLines.push(`  - ${spec.title}: \`${spec.file}\``);
                                 }
-                                extraSpecs.push({
-                                    name: '🔗 任务关联上下文',
-                                    path: 'kg-context.md',
-                                    content: ctxLines.join('\n'),
-                                });
                             }
-                        }
-                        catch { /* 知识图谱加载失败不阻断 */ }
-                    }
-                    // v8.3.123+: analyze 时注入知识图谱迭代级上下文
-                    // v8.3.125+: 自动检查过期并刷新
-                    if (command === 'analyze' && options.iteration) {
-                        try {
-                            const kg = await (0, knowledge_graph_1.loadFreshKnowledgeGraph)(cwd, options.iteration);
-                            if (kg) {
-                                const compactCtx = (0, context_builder_1.buildCompactContext)(kg, {});
-                                if (compactCtx) {
-                                    extraSpecs.push({
-                                        name: '🧠 知识图谱摘要',
-                                        path: 'kg-summary.md',
-                                        content: compactCtx,
-                                    });
-                                }
+                            if (ctx.dependencyChain.length > 0) {
+                                ctxLines.push(`- **依赖链路**: ${ctx.dependencyChain.map(c => c.taskName).join(' → ')}`);
                             }
+                            extraSpecs.push({
+                                name: '🔗 任务关联上下文',
+                                path: 'kg-context.md',
+                                content: ctxLines.join('\n'),
+                            });
                         }
-                        catch { /* 知识图谱加载失败不阻断 */ }
                     }
-                    // 按匹配得分排序注入源码，并附加匹配原因
-                    const sortedMatches = [...codeMatches].sort((a, b) => b.score - a.score);
-                    for (const match of sortedMatches.slice(0, sourceMaxFiles)) {
-                        const content = sourceContents[match.file];
-                        if (!content)
-                            continue;
-                        const reasons = [];
-                        if (match.score >= 50)
-                            reasons.push(`@spec 注释直接关联 (score:${match.score})`);
-                        else if (match.score >= 40)
-                            reasons.push(`知识图谱 source-file 实体关联 (score:${match.score})`);
-                        else if (match.score >= 35)
-                            reasons.push(`业务模块 codeEntities 关联 (score:${match.score})`);
-                        else if (match.score >= 25)
-                            reasons.push(`Spec 技术关键词匹配 (score:${match.score})`);
-                        else
-                            reasons.push(`关键词匹配 (score:${match.score})`);
-                        if (match.exports.length > 0)
-                            reasons.push(`导出: ${match.exports.join(', ')}`);
-                        if (match.apis.length > 0)
-                            reasons.push(`API: ${match.apis.join(', ')}`);
-                        extraSpecs.push({
-                            name: `🔍 ${(0, path_1.basename)(match.file)}`,
-                            path: match.file,
-                            content: `## 关联源码: ${match.file}\n> **匹配原因**: ${reasons.join(' | ')}\n\n\`\`\`${match.file.split('.').pop() || 'ts'}\n${content}\n\`\`\``,
-                        });
-                    }
-                    logger_1.logger?.info?.(`   💻 深入源码: ${sourceKeys.length} 个完整文件已注入 (${Math.round(Object.values(sourceContents).reduce((a, c) => a + c.length, 0) / 1000)}K 字符)`);
-                    // v8.3.125+: 可选阅读清单 — 让宿主 AI 按需深入读取未预加载的关联文件
-                    // 解决 "8文件/60KB 限制导致大型功能读不全" 的问题
-                    const unreadMatches = sortedMatches.slice(sourceMaxFiles);
-                    if (unreadMatches.length > 0) {
-                        const optionalLines = [
-                            '## 📖 可选阅读清单（宿主 AI 按需读取）',
-                            '> 以下文件与当前任务高度相关，但因 Token 预算限制未完整预加载到上下文中。',
-                            '> 如果你的 IDE（Cursor / Claude Code / Windsurf）支持文件读取，可按需打开以下文件深入理解业务逻辑：',
-                            '',
-                        ];
-                        for (const match of unreadMatches.slice(0, 15)) {
-                            const reasons = [];
-                            if (match.score >= 50)
-                                reasons.push('@spec 注释直接关联');
-                            else if (match.score >= 40)
-                                reasons.push('知识图谱关联');
-                            else if (match.score >= 35)
-                                reasons.push('业务模块关联');
-                            else if (match.score >= 25)
-                                reasons.push('技术关键词匹配');
-                            else
-                                reasons.push('关键词匹配');
-                            if (match.exports.length > 0)
-                                reasons.push(`导出 ${match.exports.join(', ')}`);
-                            if (match.apis.length > 0)
-                                reasons.push(`API ${match.apis.join(', ')}`);
-                            optionalLines.push(`- \`${match.file}\` — ${reasons.join(' | ')} (score:${match.score})`);
-                        }
-                        if (unreadMatches.length > 15) {
-                            optionalLines.push(`\n... 还有 ${unreadMatches.length - 15} 个关联文件未列出`);
+                    catch { /* 知识图谱加载失败不阻断 */ }
+                }
+                // v8.3.123+: analyze 时注入知识图谱迭代级上下文
+                // v8.3.125+: 自动检查过期并刷新
+                if (command === 'analyze' && options.iteration) {
+                    try {
+                        const kg = await (0, knowledge_graph_1.loadFreshKnowledgeGraph)(cwd, options.iteration);
+                        if (kg) {
+                            const compactCtx = (0, context_builder_1.buildCompactContext)(kg, {});
+                            if (compactCtx) {
+                                extraSpecs.push({
+                                    name: '🧠 知识图谱摘要',
+                                    path: 'kg-summary.md',
+                                    content: compactCtx,
+                                });
+                            }
                         }
-                        optionalLines.push('\n---');
-                        optionalLines.push('💡 **使用方式**: 如果上述预加载源码不足以理解实现细节，请打开对应文件查看完整代码。');
-                        extraSpecs.push({
-                            name: '📖 可选阅读清单',
-                            path: 'optional-reading.md',
-                            content: optionalLines.join('\n'),
-                        });
-                        logger_1.logger?.info?.(`   📖 可选阅读清单: ${unreadMatches.length} 个关联文件（宿主 AI 可按需读取）`);
                     }
+                    catch { /* 知识图谱加载失败不阻断 */ }
+                }
+                // v8.3.3xx+: 第三层——CLI 只导航不拼全文。
+                // 注入「相关源码阅读清单 + 宿主 AI 按需深读协议」，
+                // 全文阅读交给宿主 AI 的 Read / Grep / LSP 工具按需执行。
+                const sortedMatches = [...codeMatches].sort((a, b) => b.score - a.score);
+                const listLines = [
+                    '## 📖 相关源码阅读清单（CLI 导航 + 宿主 AI 按需深读）',
+                    '',
+                    '> 以下文件由代码索引相关性导航得出，按匹配得分降序排列。',
+                    '> **CLI 不拼入源码全文**——一个端动辄几百个文件，全量拼入会撑爆上下文或截断失真。',
+                    '> 请用你的 Read / Grep / LSP 工具按需打开深读。',
+                    '',
+                    '| 优先级 | 文件 | 匹配原因 | 代码线索 |',
+                    '|:---|:---|:---|:---|',
+                ];
+                for (const match of sortedMatches.slice(0, 15)) {
+                    const reasons = [];
+                    if (match.score >= 50)
+                        reasons.push('@spec 注释直接关联');
+                    else if (match.score >= 40)
+                        reasons.push('知识图谱 source-file 实体关联');
+                    else if (match.score >= 35)
+                        reasons.push('业务模块 codeEntities 关联');
+                    else if (match.score >= 25)
+                        reasons.push('Spec 技术关键词匹配');
+                    else
+                        reasons.push('关键词匹配');
+                    const clues = [];
+                    if (match.exports.length > 0)
+                        clues.push(`导出 \`${match.exports.slice(0, 4).join(' ')}\``);
+                    if (match.apis.length > 0)
+                        clues.push(`API \`${match.apis.slice(0, 3).join(' ')}\``);
+                    const priority = match.score >= 40 ? 'P0' : (match.score >= 25 ? 'P1' : 'P2');
+                    listLines.push(`| ${priority} | \`${match.file}\` | ${reasons.join(' / ')} (score:${match.score}) | ${clues.join('；') || '—'} |`);
+                }
+                if (sortedMatches.length > 15) {
+                    listLines.push(`| … | 其余 ${sortedMatches.length - 15} 个关联文件 | 运行 \`speccore code-index --show\` 查看全量索引 | — |`);
                 }
+                listLines.push('');
+                listLines.push('### 🔍 深读协议（宿主 AI 执行）');
+                listLines.push('');
+                listLines.push('1. **先读 P0**：用 Read 打开优先级最高的 2-3 个文件，理解核心实现与数据结构');
+                listLines.push('2. **符号追踪**：对清单中的导出符号用 LSP（goToDefinition / findReferences）追踪定义与调用点');
+                listLines.push('3. **路径检索**：对 API 路径 / 表名用 Grep 全仓检索关联实现');
+                listLines.push('4. **按需扩展**：从已读文件的 import 出发追踪依赖链；任务涉及哪个文件，就深读哪个文件');
+                listLines.push('5. **禁止要求拼全文**：不要要求 CLI 把源码全文塞进 prompt——CLI 的职责是导航，全文阅读由你按需执行');
+                listLines.push('');
+                extraSpecs.push({
+                    name: '📖 相关源码阅读清单',
+                    path: 'reading-list.md',
+                    content: listLines.join('\n'),
+                });
+                logger_1.logger?.info?.(`   📖 相关源码阅读清单: ${sortedMatches.length} 个关联文件（CLI 导航，宿主 AI 按需深读）`);
             }
         }
         catch (e) {
@@ -2214,6 +2239,9 @@ async function buildPrompt(command, options) {
                 feature: options.analyzeOptions.feature,
             };
             const rawPrompt = await buildMultiDocPrompt('analyze', ctx, options.analyzeOptions);
+            // v8.3.3xx+: rawPrompt 路由会丢弃常规 extraSpecs，阅读清单（CLI 导航 + 宿主 AI 深读）单独追加
+            const readingList = extraSpecs.find(s => s.name === '📖 相关源码阅读清单');
+            const finalRawPrompt = readingList ? `${rawPrompt}\n\n${readingList.content}` : rawPrompt;
             return {
                 marker: '[SPECCORE_PROMPT]',
                 version: '1.0',
@@ -2228,7 +2256,7 @@ async function buildPrompt(command, options) {
                 extraSpecs: [],
                 instruction: '',
                 outputHint: '请返回 Markdown 格式的分析结果',
-                rawPrompt,
+                rawPrompt: finalRawPrompt,
                 subagent: options.subagent || DEFAULT_SUBAGENT_MAP[command],
             };
         }