speccore 8.3.166 → 8.3.168

package/README.md

@@ -337,7 +337,7 @@ speccore status                                       # 查看分析进度和过
 
 ```bash
 npm install -g speccore
-speccore --version   # v8.3.95
+speccore --version   # v8.3.167
 ```
 
 ## 命令列表
@@ -380,15 +380,18 @@ speccore --version   # v8.3.95
 - **终端**：Unicode 框线美化输出
 - **AI 调用**：自动生成 Ocean 主题 HTML 页面（四边脉冲扫描线）
 
-## 🤖 三层 AI 架构
+## 🤖 多层 AI 架构（v8.3.167+）
 
 ```
 @spec-ask "..."  (AI IDE 入口)
   ├─ 🧠 自有 LLM   → OpenAI / Ollama（SPECCORE_LLM_KEY 环境变量）
   ├─ 🤖 宿主 AI    → WorkBuddy / TRAE / Qoder（自动检测）
-  └─ 📐 规则引擎   → 18 条命令 KB + 4 预定义工作流（永远可用）
+  ├─ 📐 规则引擎   → 18 条命令 KB + 4 预定义工作流（永远可用）
+  └─ 🎭 多 Subagent → 按阶段/端/模块分配专属角色（步骤隔离）
 ```
 
+**多 Subagent 协作**：大项目自动启用功能模块级分批，每个模块由独立 Agent 深入分析，避免上下文溢出。
+
 零配置：没配 Key 自动降级，功能不受影响。
 
 ## 📖 文档

package/dist/commands/analyze.d.ts

@@ -56,6 +56,7 @@ export declare function buildMultiDocPrompt(command: string, ctx: {
     platform?: string;
     phase?: string;
     autoMode?: boolean;
+    feature?: string;
 }, options?: AnalyzeOptions, clarifyCtx?: {
     needsClarify: boolean;
     clarifyTargets: {

package/dist/commands/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/commands/analyze.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/commands/analyze.ts"],"names":[],"mappings":"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"}

package/dist/commands/analyze.js

@@ -844,11 +844,26 @@ async function analyzeCommand(options) {
             initStep = 'init';
         }
         else {
-            // 迭代层：使用 createAnalyzePipeline（支持契约先行 + 逐端推进 + 变更感知 + 关键路径优先 + 需求澄清）
+            // 迭代层：使用 createAnalyzePipeline（支持契约先行 + 逐端推进 + 变更感知 + 关键路径优先 + 需求澄清 + 功能模块分批）
+            // v8.3.167+: 大项目自动启用功能模块分批
+            let features;
+            try {
+                const iterDirForFeatures = await (0, context_1.getIterationDir)(iter);
+                if (iterDirForFeatures) {
+                    const { parseFeatureList } = await Promise.resolve().then(() => __importStar(require('../core/spec-paths')));
+                    const featureList = await parseFeatureList(iterDirForFeatures);
+                    if (featureList.length > 2) {
+                        features = featureList;
+                        logger_1.logger.info(`📦 检测到 ${featureList.length} 个功能模块，启用分批分析模式`);
+                    }
+                }
+            }
+            catch { /* 忽略功能模块检测失败 */ }
             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,
+                features,
             });
             engine = result.engine;
             steps = result.steps;
@@ -871,6 +886,8 @@ async function analyzeCommand(options) {
         // 根据当前步骤生成对应的 prompt
         let prompt;
         const platformMatch = currentStep.match(/^platform-(.+)-prompt$/);
+        // v8.3.167+: 检测功能模块步骤
+        const featureMatch = currentStep.match(/^feature-(.+)-prompt$/);
         if (isGlobalScope) {
             // 全局层 Pipeline 步骤映射
             if (currentStep === 'init' || currentStep === 'discovery') {
@@ -913,6 +930,14 @@ async function analyzeCommand(options) {
                 analyzeOptions: options,
             }));
         }
+        else if (featureMatch) {
+            // v8.3.167+: 功能模块级分析步骤
+            const featureName = featureMatch[1];
+            prompt = (0, prompt_builder_1.buildPromptText)(await (0, prompt_builder_1.buildPrompt)('analyze', {
+                iteration: iter,
+                analyzeOptions: { ...options, feature: featureName, phase: '1' },
+            }));
+        }
         else if (currentStep === 'contract-prompt') {
             // 契约先行阶段：基于 Phase 1 文档生成跨端契约
             prompt = await buildContractFirstPrompt(iter);
@@ -955,11 +980,13 @@ async function analyzeCommand(options) {
                             ? 'Phase 0/3: 需求确认'
                             : currentStep === 'phase1-prompt'
                                 ? 'Phase 1/3: 迭代综合文档'
-                                : currentStep === 'contract-prompt'
-                                    ? 'Phase 2/3: 契约定义'
-                                    : platformMatch
-                                        ? `Phase 2/3: ${platformMatch[1]} 端专属文档`
-                                        : 'Pipeline';
+                                : featureMatch
+                                    ? `Phase 1b/3: ${featureMatch[1]} 功能模块分析`
+                                    : currentStep === 'contract-prompt'
+                                        ? 'Phase 2/3: 契约定义'
+                                        : platformMatch
+                                            ? `Phase 2/3: ${platformMatch[1]} 端专属文档`
+                                            : 'Pipeline';
         }
         // v8.3.160+: 步骤隔离模式，每步完成后需新会话继续
         const finalPrompt = prompt + `\n\n## ⚠️ Pipeline 模式：步骤隔离 (${progressLabel})\n\n` +
@@ -967,8 +994,15 @@ async function analyzeCommand(options) {
             `当你通过 --apply 写入文档后，CLI 会自动输出 [SPECCORE_STEP_DONE] 标记和下一步命令。\n\n` +
             `**看到 [SPECCORE_STEP_DONE] 后，请在新会话中执行提示的命令**，继续下一步。\n`;
         // v8.3.166+: Phase 2 端级步骤输出端级 subagent 标记
+        // v8.3.167+: 功能模块步骤输出功能模块级 subagent 标记
         const platformSubagent = platformMatch ? `spec-analyzer-${platformMatch[1]}` : undefined;
-        if (platformSubagent) {
+        const featureSubagent = featureMatch ? `spec-analyzer-feature` : undefined;
+        if (featureSubagent) {
+            process.stdout.write(`[SPECCORE_SUBAGENT: ${featureSubagent}]\n`);
+            process.stdout.write(`[SPECCORE_CONTEXT_BUDGET: 10000]\n`);
+            process.stdout.write(`[SPECCORE_CONTEXT_TYPE: full]\n\n`);
+        }
+        else if (platformSubagent) {
             process.stdout.write(`[SPECCORE_SUBAGENT: ${platformSubagent}]\n`);
             process.stdout.write(`[SPECCORE_CONTEXT_BUDGET: 8000]\n`);
             process.stdout.write(`[SPECCORE_CONTEXT_TYPE: platform-only]\n\n`);
@@ -4475,7 +4509,13 @@ sequenceDiagram
     const GLOBAL_DOCS = [...GLOBAL_INDEX_DOCS, ...FEATURE_OVERVIEW_DOCS_LIST];
     let taskDocs = docs.filter(([n]) => includeDocs.includes(n));
     if (ctx.phase === '1') {
-        taskDocs = taskDocs.filter(([n]) => GLOBAL_DOCS.includes(n));
+        if (ctx.feature) {
+            // v8.3.167+: 功能模块级分析，只生成该模块的 overview 文档（不含全局索引）
+            taskDocs = taskDocs.filter(([n]) => FEATURE_OVERVIEW_DOCS_LIST.includes(n));
+        }
+        else {
+            taskDocs = taskDocs.filter(([n]) => GLOBAL_DOCS.includes(n));
+        }
     }
     else if (ctx.phase === '2') {
         taskDocs = taskDocs.filter(([n]) => PLATFORM_DOCS.includes(n));
@@ -4664,7 +4704,8 @@ sequenceDiagram
         // overview/TECH.md: 整体架构
         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`;
+    const featureLabel = ctx.feature ? ` · 功能模块:${ctx.feature}` : '';
+    let prompt = `\n# 任务: ${command}${task} (${taskDocs.length}个文档 · ${isTask ? `类型:${taskType}` : '迭代全量'}${ctx.phase ? ` · Phase ${ctx.phase}` : ''}${featureLabel})\n\n`;
     // v8.3.160+: 注入子 Agent 角色定义
     if (agentContextText) {
         prompt = agentContextText + '\n\n' + prompt;
@@ -4898,6 +4939,15 @@ status: "clarified"
     prompt += `- 如果文档内容不完整，标注"文档未提及"，不要自行脑补\n`;
     prompt += `- 分析过程中，始终把迭代名称当作透明信息处理，不做任何功能推断\n\n`;
     prompt += `## 分析范围说明\n`;
+    // v8.3.167+: 功能模块级分析专属指令
+    if (ctx.feature && !isTask) {
+        prompt += `- 当前是**功能模块级分析**，只分析「**${ctx.feature}**」功能模块\n`;
+        prompt += `- **只生成该功能模块的 overview/ 文档**，不要分析其他功能模块\n`;
+        prompt += `- 文档写入路径格式：\`${ctx.feature}/overview/{文件名}\`（如 \`${ctx.feature}/overview/REQUIREMENT.md\`）\n`;
+        prompt += `- **全局索引文档（FUNCTION_MAP.md / INTERACTION_MAP.md / PLATFORMS.md）已在 Phase 1 主步骤生成，不要重复生成**\n`;
+        prompt += `- 分析前请先 Read 全局索引文档，确保本模块内容与全局文档一致\n`;
+        prompt += `- 如果需求文档中该模块的描述不完整，标注"文档未充分描述"，不要自行脑补\n\n`;
+    }
     if (isTask) {
         prompt += `- 当前是**任务级分析**，类型为 \`${taskType}\`，只需产出 ${taskDocs.length} 个文档：${taskDocs.map(([n]) => n).join('、')}\n`;
         prompt += `- bugfix: 聚焦根因分析和修复验证；research: 聚焦技术调研；review: 聚焦代码审查\n`;