speccore 8.3.174 → 8.3.176

package/dist/commands/analyze.js

@@ -78,10 +78,7 @@ 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");
-// v6.80.0+: 需求澄清模块
 const requirement_clarifier_1 = require("../core/requirement-clarifier");
-// v6.83.0+: 专业 AI 角色定义
-// v6.84.0+: 迁移到规范数据库 (.speccore/AGENTS/)，保留向后兼容
 const agents_1 = require("../core/agents");
 // v6.91.0+: 代码知识图谱摘要注入
 const code_graph_1 = require("../core/code-graph");
@@ -645,7 +642,6 @@ 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 goldenReqDir = (0, path_1.join)(specDir, 'requirements');
@@ -921,7 +917,6 @@ async function analyzeCommand(options) {
             prompt = await buildClarifyPhasePrompt(iter);
         }
         else if (currentStep === 'confirm-check') {
-            // v6.80.0+: 需求确认阶段 — 输出质量报告提示
             prompt = await buildConfirmCheckPrompt(iter);
         }
         else if (currentStep === 'phase1-prompt') {
@@ -1047,7 +1042,6 @@ async function analyzeCommand(options) {
     // ── Prompt 模式 ──
     if (options.prompt) {
         const iter = options.scope === 'global' ? 'GLOBAL' : (options.iteration || await (0, context_1.getDefaultIteration)());
-        // v6.80.0+: 非 Pipeline 模式下也默认检测需求质量
         if (iter !== 'GLOBAL' && !options.skipClarify && !options.pipeline) {
             const iterDir = await (0, context_1.getIterationDir)(iter);
             const hasClarified = await (0, requirement_clarifier_1.hasValidClarifiedDocs)(iterDir);
@@ -1142,13 +1136,12 @@ ${singlePrompt}`);
                 return;
             }
         }
-        // v8.3.161+: AI 上下文中禁止 --skip-clarify（质量门禁不可被 AI 自行绕过）
         if (options.skipClarify && !process.stdout.isTTY) {
             logger_1.logger.warn('⚠️ AI 上下文检测到 --skip-clarify，此行为不推荐');
             logger_1.logger.info('   需求澄清是质量门禁，应由人类用户确认后使用');
             logger_1.logger.info('   如果需求文档已经过 clarify 流程，会自动跳过澄清阶段');
             logger_1.logger.info('   如需强制跳过，请在交互式终端中执行此命令');
-            // 不阻止，但输出强烈警告（保持向后兼容）
+            // 不阻止，但输出强烈警告（输出警告）
         }
         // v8.3.0+: 解析 [CLARIFY:xxx] 标记 — 需求澄清是强制前置步骤
         const clarifyBlocks = parseClarifyMarkers(options.apply);
@@ -1212,7 +1205,6 @@ ${singlePrompt}`);
             try {
                 const docs = JSON.parse(options.apply);
                 const docEntries = Object.entries(docs);
-                // v8.3.161+: 批量 apply 防护 — JSON 模式同样限制文档数量
                 const MAX_DOCS_PER_APPLY = 3;
                 if (docEntries.length > MAX_DOCS_PER_APPLY) {
                     logger_1.logger.error(`❌ 批量 apply 拦截: JSON 包含 ${docEntries.length} 个文档，超过单次上限 ${MAX_DOCS_PER_APPLY}`);
@@ -1226,7 +1218,6 @@ ${singlePrompt}`);
                     logger_1.logger.info('   原因：单会话内批量生成过多文档会导致上下文溢出、质量下降');
                     return;
                 }
-                // v8.3.161+: 迭代级 analyze 禁止直接写入 overview/REQUIREMENT.md
                 if (!isGlobalScope) {
                     for (const filename of Object.keys(docs)) {
                         if (filename === 'overview/REQUIREMENT.md' || filename === 'REQUIREMENT.md') {
@@ -1252,7 +1243,7 @@ ${singlePrompt}`);
                         const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
                         if (bk) {
                             backups.push(bk);
-                            logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
+                            logger_1.logger.info(`   📦 ${filename} 已备份: ${(0, path_1.basename)(bk)}`);
                         }
                         await (0, fs_extra_1.writeFile)(fp, content);
                         count++;
@@ -1325,7 +1316,7 @@ ${singlePrompt}`);
                         const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
                         if (bk) {
                             backups.push(bk);
-                            logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
+                            logger_1.logger.info(`   📦 ${filename} 已备份: ${(0, path_1.basename)(bk)}`);
                         }
                         await (0, fs_extra_1.writeFile)(fp, content);
                         count++;
@@ -1373,8 +1364,7 @@ ${singlePrompt}`);
                     }
                     let skippedCount = 0;
                     for (const [filename, content] of Object.entries(docs)) {
-                        // v8.2.0+: 需求文档写入黄金需求目录 020-specs/requirements/
-                        // 支持 010-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');
@@ -1390,10 +1380,8 @@ ${singlePrompt}`);
                             count++;
                             continue;
                         }
-                        // v6.80.0+: 向后兼容 — 010-requirements/ 路径自动重定向到黄金需求目录
                         if (filename.startsWith('010-requirements/')) {
                             const reqFilePath = filename.slice('010-requirements/'.length);
-                            // 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));
@@ -1445,7 +1433,7 @@ ${singlePrompt}`);
                                 const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
                                 if (bk) {
                                     backups.push(bk);
-                                    logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
+                                    logger_1.logger.info(`   📦 ${filename} 已备份: ${(0, path_1.basename)(bk)}`);
                                 }
                                 await writeFileMerged(fp, content, !!options.merge);
                                 if (options.merge)
@@ -1467,7 +1455,7 @@ ${singlePrompt}`);
                                     const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
                                     if (bk) {
                                         backups.push(bk);
-                                        logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
+                                        logger_1.logger.info(`   📦 ${filename} 已备份: ${(0, path_1.basename)(bk)}`);
                                     }
                                     await writeFileMerged(fp, content, !!options.merge);
                                     if (options.merge)
@@ -1496,7 +1484,7 @@ ${singlePrompt}`);
                         }
                         // 综合文档写入 overview/ 子目录，端专属文档写入 {功能模块}/{端}/ 子目录
                         // v8.3.24+: 按文件名前缀路由，支持多段指定
-                        // v8.3.25+: 如果 AI 输出旧格式 {端}/{文件}，尝试回退到功能模块路由
+                        // 如果 AI 输出 {端}/{文件}，尝试回退到功能模块路由
                         let targetDir;
                         if (globalSet.has(cleanFilename)) {
                             targetDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
@@ -1537,7 +1525,7 @@ ${singlePrompt}`);
                         const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
                         if (bk) {
                             backups.push(bk);
-                            logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
+                            logger_1.logger.info(`   📦 ${filename} 已备份: ${(0, path_1.basename)(bk)}`);
                         }
                         await writeFileMerged(fp, content, !!options.merge);
                         if (options.merge)
@@ -1689,10 +1677,8 @@ ${singlePrompt}`);
                 // fallback to single-file mode
             }
         }
-        // v8.2.0+: [DOC:xxx] 标记解析 —— 统一报告自动拆分
         // AI 输出格式: [DOC:REQUIREMENT.md]...内容...[DOC:TECH.md]...内容...
         const docBlocks = parseDocMarkers(options.apply);
-        // v8.3.161+: 批量 apply 防护 — 禁止单会话内批量写入过多文档
         const MAX_DOCS_PER_APPLY = 3;
         if (docBlocks.size > MAX_DOCS_PER_APPLY) {
             logger_1.logger.error(`❌ 批量 apply 拦截: 检测到 ${docBlocks.size} 个 [DOC:xxx] 文档，超过单次上限 ${MAX_DOCS_PER_APPLY}`);
@@ -1707,7 +1693,6 @@ ${singlePrompt}`);
             logger_1.logger.info('   请在新会话中逐个批次执行，确保每个文档的质量深入');
             return;
         }
-        // v8.3.161+: 迭代级 analyze 禁止直接写入 overview/REQUIREMENT.md
         if (!isGlobalScope) {
             for (const docName of docBlocks.keys()) {
                 if (docName === 'overview/REQUIREMENT.md' || docName === 'REQUIREMENT.md') {
@@ -1744,7 +1729,7 @@ ${singlePrompt}`);
                         const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
                         if (bk) {
                             backups.push(bk);
-                            logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
+                            logger_1.logger.info(`   📦 ${filename} 已备份: ${(0, path_1.basename)(bk)}`);
                         }
                         await (0, fs_extra_1.writeFile)(fp, content);
                         count++;
@@ -1806,7 +1791,7 @@ ${singlePrompt}`);
                         const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
                         if (bk) {
                             backups.push(bk);
-                            logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
+                            logger_1.logger.info(`   📦 ${filename} 已备份: ${(0, path_1.basename)(bk)}`);
                         }
                         await (0, fs_extra_1.writeFile)(fp, content);
                         count++;
@@ -1820,7 +1805,6 @@ ${singlePrompt}`);
                     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');
@@ -1836,7 +1820,7 @@ ${singlePrompt}`);
                             count++;
                             continue;
                         }
-                        // 向后兼容：010-requirements/ 自动重定向到黄金需求目录
+                        // 010-requirements/ 自动重定向到黄金需求目录
                         if (filename.startsWith('010-requirements/')) {
                             const reqFilePath = filename.slice('010-requirements/'.length);
                             const goldenDir = (0, path_1.join)(iterDir, '020-specs', 'requirements');
@@ -1904,7 +1888,7 @@ ${singlePrompt}`);
                         const bk = await (0, task_utils_1.backupWithTimestamp)(fp);
                         if (bk) {
                             backups.push(bk);
-                            logger_1.logger.info(`   📦 ${filename} 旧版已备份: ${(0, path_1.basename)(bk)}`);
+                            logger_1.logger.info(`   📦 ${filename} 已备份: ${(0, path_1.basename)(bk)}`);
                         }
                         await (0, fs_extra_1.writeFile)(fp, content);
                         count++;
@@ -1922,7 +1906,6 @@ ${singlePrompt}`);
                         silent: true,
                     });
                 }
-                // v8.2.0+: 单元分析结果保存到缓存（供 --consolidate 汇总使用）
                 if (options.unit && options.iteration) {
                     try {
                         const unitsCachePath = (0, path_1.join)(_projectRoot, exports.UNITS_CACHE_DIR, options.iteration, 'units.json');
@@ -1967,7 +1950,7 @@ ${singlePrompt}`);
                 const taskBackup = await (0, task_utils_1.backupWithTimestamp)(taskAnalysisPath);
                 if (taskBackup) {
                     backups.push(taskBackup);
-                    logger_1.logger.info(`   📦 旧版已备份: ${taskBackup.split('/').pop()}`);
+                    logger_1.logger.info(`   📦 已备份: ${taskBackup.split('/').pop()}`);
                 }
                 await (0, fs_extra_1.writeFile)(taskAnalysisPath, options.apply);
                 const platformLabel = options.platform ? `/${options.platform}` : '';
@@ -1986,7 +1969,7 @@ ${singlePrompt}`);
                 const globalBackup = await (0, task_utils_1.backupWithTimestamp)(globalAnalysisPath);
                 if (globalBackup) {
                     backups.push(globalBackup);
-                    logger_1.logger.info(`   📦 旧版已备份: ${globalBackup.split('/').pop()}`);
+                    logger_1.logger.info(`   📦 已备份: ${globalBackup.split('/').pop()}`);
                 }
                 await (0, fs_extra_1.writeFile)(globalAnalysisPath, options.apply);
                 logger_1.logger.success(`✅ ANALYSIS.md 已写入 .speccore/GLOBAL/`);
@@ -2005,7 +1988,7 @@ ${singlePrompt}`);
                 const iterBackup = await (0, task_utils_1.backupWithTimestamp)(iterAnalysisPath);
                 if (iterBackup) {
                     backups.push(iterBackup);
-                    logger_1.logger.info(`   📦 旧版已备份: ${iterBackup.split('/').pop()}`);
+                    logger_1.logger.info(`   📦 已备份: ${iterBackup.split('/').pop()}`);
                 }
                 await (0, fs_extra_1.writeFile)(iterAnalysisPath, options.apply);
                 logger_1.logger.success(`✅ ANALYSIS.md 已写入 020-specs/overview/`);
@@ -2141,7 +2124,7 @@ ${singlePrompt}`);
                         }));
                     }
                     else if (state.currentStep === 'phase2-prompt') {
-                        // 兼容旧 Pipeline 步骤名
+                        // Pipeline 步骤名映射
                         nextPrompt = (0, prompt_builder_1.buildPromptText)(await (0, prompt_builder_1.buildPrompt)('analyze', {
                             iteration: options.iteration,
                             analyzeOptions: { ...options, phase: '2' },
@@ -2457,7 +2440,7 @@ async function enrichTaskDocs(iteration, taskId, reqFiles) {
         return;
     }
     const fullTaskDir = (0, path_1.join)(iterDir, taskEntry.name);
-    // 向后兼容: _shared/ → 00-specs/
+    // _shared/ → 00-specs/
     const specsDir = (await (0, fs_extra_1.pathExists)((0, path_1.join)(fullTaskDir, '_shared')))
         ? (0, path_1.join)(fullTaskDir, '_shared')
         : (0, path_1.join)(fullTaskDir, '00-specs');
@@ -2564,7 +2547,7 @@ async function enrichTaskDocs(iteration, taskId, reqFiles) {
     }
     // 创建缺失文件（v6.49.9+: 扫描平铺的端目录）
     const subtaskDirs = subtaskPaths;
-    // 旧结构回退
+    // 结构回退
     if (subtaskDirs.length === 0) {
         const legacyArtifacts = (0, path_1.join)(fullTaskDir, '99-artifacts');
         if (await (0, fs_extra_1.pathExists)(legacyArtifacts))
@@ -2862,7 +2845,7 @@ async function detectGlobalLayerProgress() {
                 }
             }
             else {
-                // 回退：检查各端 modules/ 目录是否有文档（旧逻辑）
+                // 回退：检查各端 modules/ 目录是否有文档（兜底）
                 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) {
@@ -3839,7 +3822,7 @@ async function buildMultiDocPrompt(command, ctx, options, clarifyCtx) {
         prompt += `3. **PATTERNS/*.md 特殊处理**: 不覆盖，只追加。Read 旧文件 → 合并新内容 → Write 回原文件（不生成备份）\n`;
         prompt += `4. 所有文件写完后，输出冲突汇总:\n`;
         prompt += `   \`\`\`\n`;
-        prompt += `   ⚠️  N 个文件有冲突，旧版已重命名为时间戳格式：\n`;
+        prompt += `   ⚠️  N 个文件有冲突，已重命名为时间戳格式：\n`;
         prompt += `      📄 .speccore/GLOBAL/platforms/xxx/API_INVENTORY.md\n`;
         prompt += `         对比: diff API_INVENTORY.md API_INVENTORY-20260813143025.md\n`;
         prompt += `      💡 请对比时间戳文件，合并自定义内容后删除\n`;
@@ -4538,7 +4521,7 @@ sequenceDiagram
     const GLOBAL_INDEX_DOCS = ['FUNCTION_MAP.md', 'INTERACTION_MAP.md', 'PLATFORMS.md'];
     const FEATURE_OVERVIEW_DOCS_LIST = ['REQUIREMENT.md', 'ANALYSIS.md', 'TECH.md', 'RISK.md', 'DEPS.md', 'REVIEW.md', 'MONITOR.md', 'DEV_GUIDE.md'];
     const PLATFORM_DOCS = ['TECH.md', 'TEST.md', 'UI_SPEC.md', 'DEV_GUIDE.md'];
-    // 向后兼容：保留 GLOBAL_DOCS 引用
+    // GLOBAL_DOCS 引用
     const GLOBAL_DOCS = [...GLOBAL_INDEX_DOCS, ...FEATURE_OVERVIEW_DOCS_LIST];
     let taskDocs = docs.filter(([n]) => includeDocs.includes(n));
     if (ctx.phase === '1') {
@@ -4568,7 +4551,6 @@ sequenceDiagram
                 if (perDocStatus.nextUnfilled) {
                     const nextDocName = perDocStatus.nextUnfilled.docName;
                     const nextDocPlatform = perDocStatus.nextUnfilled.platform || null;
-                    // v8.2.0+: 功能单元聚焦模式不强制单文档过滤，让 AI 一次输出完整单元分析
                     const isUnitMode = !!(options?.unit || options?.consolidate || options?.extractUnits);
                     if (!isUnitMode) {
                         // 过滤 taskDocs 只保留下一个未填充的文档（默认逐文档推进模式）
@@ -4839,7 +4821,6 @@ status: "clarified"
             logger_1.logger.warn(`   ⚠️ 代码关联注入失败: ${e.message}`);
         }
     }
-    // v6.80.0+: 注入需求质量上下文（迭代级分析时）
     if (!isGlobal && !isTask && ctx.iteration && ctx.iteration !== 'GLOBAL') {
         try {
             const iterDir = await (0, context_1.getIterationDir)(ctx.iteration);
@@ -5655,11 +5636,9 @@ async function getSubtaskDirs(taskDir) {
         }
         catch { /* ignore */ }
     }
-    // v8.3.121+: 已移除 10-backend/20-frontend 旧结构回退
     return result;
 }
 // ═══════════════════════════════════════════════════════════
-// v6.80.0+: 需求澄清 Phase Prompt 构建
 // ═══════════════════════════════════════════════════════════
 async function buildClarifyPhasePrompt(iteration) {
     const iterDir = await (0, context_1.getIterationDir)(iteration);
@@ -5700,7 +5679,6 @@ 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 {
@@ -5710,7 +5688,6 @@ async function buildClarifyPhasePrompt(iteration) {
     }
     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)() || ((0, task_utils_1.findProjectRoot)() || process.cwd());
     const agentContext = {
@@ -5727,7 +5704,7 @@ async function buildClarifyPhasePrompt(iteration) {
             }
         }
         else {
-            // 回退到硬编码角色（向后兼容）
+            // 回退到硬编码角色（兜底）
             prompt += agents_1.PRODUCT_ANALYST_ROLE;
             prompt += '\n\n';
             prompt += agents_1.INTERACTION_DESIGNER_ROLE;
@@ -5735,7 +5712,7 @@ async function buildClarifyPhasePrompt(iteration) {
         }
     }
     catch {
-        // 回退到硬编码角色（向后兼容）
+        // 回退到硬编码角色（兜底）
         prompt += agents_1.PRODUCT_ANALYST_ROLE;
         prompt += '\n\n';
         prompt += agents_1.INTERACTION_DESIGNER_ROLE;
@@ -5781,7 +5758,6 @@ async function buildClarifyPhasePrompt(iteration) {
         }
         prompt += `\n> ⚠️ **重要**：每份源文档对应一份独立的澄清文档，禁止将多份源文档合并为一份。\n\n`;
     }
-    // v8.2.0+: 如果检测到多个功能单元，启用单元化澄清模式
     if (hasMultipleUnits) {
         prompt += `## ⚠️ 功能单元拆分澄清模式（v8.2.0+）\n\n`;
         prompt += `检测到需求文档包含 ${extractedUnits.length} 个功能单元。为避免注意力漂移，请**按单元逐个澄清**：\n\n`;
@@ -5949,7 +5925,6 @@ async function buildConfirmCheckPrompt(iteration) {
             prompt += `\n\n... (报告共 ${report.length} 字符，已截断)\n`;
         }
     }
-    // v8.2.0+: 检查黄金需求目录是否有 diff 文件
     let diffFiles = [];
     if (await (0, fs_extra_1.pathExists)(goldenDir)) {
         try {
@@ -5992,7 +5967,6 @@ async function buildConfirmCheckPrompt(iteration) {
     return await injectGraphSummary(prompt);
 }
 // ================================================================
-// v8.2.0+: 功能单元聚焦分析辅助函数（解决注意力漂移+空模板问题）
 // ================================================================
 /** 解析 [DOC:filename] 标记，将统一报告拆分为多文档 Map */
 function parseDocMarkers(text) {