speccore 6.92.0 → 6.98.0

package/dist/core/code-graph/requirement-linker.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.linkRequirementsToCode = linkRequirementsToCode;
+/**
+ * Requirement ↔ Code Graph Linker
+ * v6.94.0: 建立需求文档与代码节点之间的关联映射
+ */
+const path_1 = require("path");
+const fs_extra_1 = require("fs-extra");
+const logger_1 = require("../../utils/logger");
+const index_1 = require("./index");
+const GRAPH_DIR = '.speccore/code-graph';
+/**
+ * 从迭代目录提取需求关键词
+ */
+async function extractRequirements(projectRoot, iteration) {
+    const results = [];
+    // 确定迭代目录
+    let iterDir;
+    if (iteration) {
+        iterDir = (0, path_1.join)(projectRoot, iteration);
+    }
+    else {
+        // 尝试从 context.json 读取当前迭代
+        try {
+            const ctxPath = (0, path_1.join)(projectRoot, '.speccore', 'local', 'context.json');
+            if (await (0, fs_extra_1.pathExists)(ctxPath)) {
+                const ctx = JSON.parse(await (0, fs_extra_1.readFile)(ctxPath, 'utf-8'));
+                if (ctx.currentIteration) {
+                    iterDir = (0, path_1.join)(projectRoot, ctx.currentIteration);
+                }
+            }
+        }
+        catch { /* 忽略 */ }
+    }
+    if (!iterDir || !(await (0, fs_extra_1.pathExists)(iterDir))) {
+        return results;
+    }
+    // 扫描需求文档目录
+    const reqDirs = [
+        (0, path_1.join)(iterDir, '010-requirements', 'features'),
+        (0, path_1.join)(iterDir, '010-requirements', 'converted'),
+        (0, path_1.join)(iterDir, '020-specs'),
+    ];
+    for (const dir of reqDirs) {
+        if (!(await (0, fs_extra_1.pathExists)(dir)))
+            continue;
+        const files = await (0, fs_extra_1.readdir)(dir).catch(() => []);
+        for (const f of files) {
+            if (!f.endsWith('.md'))
+                continue;
+            const filePath = (0, path_1.join)(dir, f);
+            try {
+                const content = await (0, fs_extra_1.readFile)(filePath, 'utf-8');
+                const { title, keywords } = parseRequirementDoc(content, f);
+                if (keywords.length > 0) {
+                    results.push({ file: filePath, title, keywords });
+                }
+            }
+            catch { /* 忽略读取失败 */ }
+        }
+    }
+    return results;
+}
+/**
+ * 解析单个需求文档，提取标题和关键词
+ */
+function parseRequirementDoc(content, filename) {
+    const lines = content.split('\n');
+    let title = filename.replace('.md', '');
+    const keywords = new Set();
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // H1/H2 标题作为需求标题
+        if (trimmed.startsWith('# ')) {
+            title = trimmed.replace(/^#\s+/, '');
+        }
+        // 提取英文标识符（camelCase / PascalCase / snake_case）
+        const identifiers = trimmed.match(/[A-Za-z][A-Za-z0-9_]*[A-Za-z0-9]/g) || [];
+        for (const id of identifiers) {
+            // 过滤常见停用词
+            if (id.length <= 2)
+                continue;
+            if (/^(the|and|or|for|with|from|into|this|that|when|then|than|them|they|their|there|where|what|which|while|will|would|should|could|can|may|might|must|shall|use|using|used|get|set|add|new|delete|update|create|remove|list|find|search|filter|sort|order|page|size|limit|offset|count|total|sum|avg|min|max|true|false|null|undefined|const|let|var|function|class|interface|type|enum|return|if|else|switch|case|break|continue|for|while|do|try|catch|finally|throw|async|await|import|export|default|from|as|of|in|instanceof|typeof|void|yield|debugger)$/i.test(id)) {
+                continue;
+            }
+            keywords.add(id);
+        }
+    }
+    return { title, keywords: [...keywords] };
+}
+function computeMatchScore(reqKeywords, node) {
+    const nodeNameLower = node.name.toLowerCase();
+    const nodeFileLower = node.filePath.toLowerCase();
+    let matches = 0;
+    const matched = [];
+    for (const kw of reqKeywords) {
+        const kwLower = kw.toLowerCase();
+        // 节点名包含关键词
+        if (nodeNameLower.includes(kwLower)) {
+            matches += 2;
+            matched.push(kw);
+            continue;
+        }
+        // 文件名包含关键词
+        if (nodeFileLower.includes(kwLower)) {
+            matches += 1;
+            matched.push(kw);
+            continue;
+        }
+        // snippet 包含关键词
+        if (node.snippet && node.snippet.toLowerCase().includes(kwLower)) {
+            matches += 0.5;
+            matched.push(kw);
+        }
+    }
+    if (matches === 0)
+        return { score: 0, matched: [] };
+    // 归一化：匹配分 / (关键词数 * 2)
+    const score = Math.min(1, matches / (reqKeywords.length * 2));
+    return { score, matched };
+}
+/**
+ * 建立需求与代码的关联映射
+ */
+async function linkRequirementsToCode(projectRoot, iteration) {
+    const root = projectRoot || process.cwd();
+    const graph = await (0, index_1.loadCodeGraph)(root);
+    if (!graph) {
+        logger_1.logger.warn('代码图谱不存在，请先运行 speccore code-index --graph');
+        return {
+            generatedAt: new Date().toISOString(),
+            iteration,
+            totalRequirements: 0,
+            totalLinkedNodes: 0,
+            coverageRatio: 0,
+            links: [],
+        };
+    }
+    const requirements = await extractRequirements(root, iteration);
+    logger_1.logger.info(`📋 发现 ${requirements.length} 个需求文档`);
+    const links = [];
+    const allLinkedNodeIds = new Set();
+    for (const req of requirements) {
+        const nodeScores = new Map();
+        for (const node of graph.nodes) {
+            const result = computeMatchScore(req.keywords, node);
+            if (result.score > 0.3) {
+                nodeScores.set(node.id, { node, score: result.score, matched: result.matched });
+            }
+        }
+        // 取 top 10
+        const topMatches = Array.from(nodeScores.values())
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 10);
+        if (topMatches.length > 0) {
+            const linkedNodeIds = topMatches.map(m => m.node.id);
+            const avgScore = topMatches.reduce((s, m) => s + m.score, 0) / topMatches.length;
+            const allMatched = [...new Set(topMatches.flatMap(m => m.matched))];
+            for (const id of linkedNodeIds) {
+                allLinkedNodeIds.add(id);
+            }
+            links.push({
+                sourceFile: req.file,
+                requirement: req.title,
+                linkedNodeIds,
+                confidence: Math.round(avgScore * 100) / 100,
+                matchedKeywords: allMatched.slice(0, 10),
+            });
+        }
+    }
+    // 计算覆盖率：有链接的代码节点 / 总代码节点
+    const coverageRatio = graph.nodes.length > 0
+        ? Math.round((allLinkedNodeIds.size / graph.nodes.length) * 100) / 100
+        : 0;
+    const report = {
+        generatedAt: new Date().toISOString(),
+        iteration: iteration || requirements[0]?.file.split('/').find(s => s.startsWith('Iteration-')),
+        totalRequirements: requirements.length,
+        totalLinkedNodes: allLinkedNodeIds.size,
+        coverageRatio,
+        links,
+    };
+    // 输出 JSON
+    const outPath = (0, path_1.join)(root, GRAPH_DIR, 'REQ_CODE_LINK.json');
+    await (0, fs_extra_1.writeFile)(outPath, JSON.stringify(report, null, 2));
+    logger_1.logger.info(`🔗 需求↔代码关联已生成:`);
+    logger_1.logger.info(`   ${links.length} 个需求 ↔ ${allLinkedNodeIds.size} 个代码节点 (覆盖率 ${(coverageRatio * 100).toFixed(0)}%)`);
+    logger_1.logger.info(`   输出: ${outPath}`);
+    return report;
+}
+//# sourceMappingURL=requirement-linker.js.map

package/dist/core/code-graph/requirement-linker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-linker.js","sourceRoot":"","sources":["../../../src/core/code-graph/requirement-linker.ts"],"names":[],"mappings":"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"}

package/dist/core/error-diagnosis.d.ts

@@ -0,0 +1,20 @@
+export interface DiagnosisResult {
+    matched: boolean;
+    category: string;
+    severity: 'info' | 'warn' | 'error';
+    message: string;
+    suggestions: string[];
+}
+/**
+ * 诊断错误信息，返回匹配结果和建议
+ */
+export declare function diagnoseError(error: unknown): DiagnosisResult;
+/**
+ * 打印诊断结果
+ */
+export declare function printDiagnosis(result: DiagnosisResult): void;
+/**
+ * 包装函数：自动诊断并打印
+ */
+export declare function diagnoseAndPrint(error: unknown): DiagnosisResult;
+//# sourceMappingURL=error-diagnosis.d.ts.map

package/dist/core/error-diagnosis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-diagnosis.d.ts","sourceRoot":"","sources":["../../src/core/error-diagnosis.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAqGD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CA6B7D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAW5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAIhE"}

package/dist/core/error-diagnosis.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diagnoseError = diagnoseError;
+exports.printDiagnosis = printDiagnosis;
+exports.diagnoseAndPrint = diagnoseAndPrint;
+/**
+ * Error Diagnosis — 错误自动诊断
+ * v6.96.0: 分析常见错误模式，给出针对性修复建议
+ */
+const logger_1 = require("../utils/logger");
+const ERROR_PATTERNS = [
+    {
+        category: '迭代不存在',
+        severity: 'error',
+        patterns: [/No active iteration found/i, /迭代.*不存在/i, /Iteration.*not found/i],
+        message: '当前没有活跃的迭代，或指定的迭代不存在',
+        suggestions: [
+            '运行 speccore iteration create <名称> 创建新迭代',
+            '运行 speccore init 初始化项目',
+            '使用 --iteration <名称> 指定已有迭代',
+        ],
+    },
+    {
+        category: '任务未找到',
+        severity: 'warn',
+        patterns: [/Task.*not found/i, /任务.*未找到/i, /没有找到.*任务/i],
+        message: '指定的任务不存在或名称不匹配',
+        suggestions: [
+            '运行 speccore status 查看当前迭代的任务列表',
+            '使用任务 ID 的完整形式（如 Task-001）',
+            '检查是否已运行 speccore split 拆分任务',
+        ],
+    },
+    {
+        category: '锁冲突',
+        severity: 'warn',
+        patterns: [/锁已被.*持有/i, /lock.*held by/i, /acquireLock/i],
+        message: '另一个进程或用户正在操作此迭代',
+        suggestions: [
+            '等待其他操作完成后重试',
+            '使用 --force 强制获取锁（谨慎使用）',
+            '运行 speccore status 查看当前锁持有者',
+        ],
+    },
+    {
+        category: '图谱缺失',
+        severity: 'info',
+        patterns: [/图谱不存在/i, /graph.*not found/i, /graph\.json.*不存在/i],
+        message: '代码知识图谱尚未构建',
+        suggestions: [
+            '运行 speccore code-index --graph 构建代码知识图谱',
+            '运行 speccore code-index --graph --incremental 增量更新',
+        ],
+    },
+    {
+        category: 'Git 错误',
+        severity: 'warn',
+        patterns: [/not a git repository/i, /git.*error/i, /protected branch/i, /冲突/i],
+        message: 'Git 操作遇到问题',
+        suggestions: [
+            '确认当前目录是 Git 仓库',
+            '检查是否在受保护分支上，切换到 feature 分支',
+            '运行 git status 查看未提交的变更',
+            '如果有冲突，先解决冲突再执行',
+        ],
+    },
+    {
+        category: '依赖缺失',
+        severity: 'error',
+        patterns: [/Cannot find module/i, /MODULE_NOT_FOUND/i, /ENOENT/i],
+        message: '缺少必要的依赖或文件',
+        suggestions: [
+            '运行 npm install 安装依赖',
+            '检查文件路径是否正确',
+            '确认 .speccore/ 目录结构完整',
+        ],
+    },
+    {
+        category: 'Prompt 构建失败',
+        severity: 'error',
+        patterns: [/prompt-builder/i, /buildPrompt/i, /PromptContext/i],
+        message: 'Prompt 构建过程中出现错误',
+        suggestions: [
+            '检查插件系统是否正常加载：speccore doctor',
+            '查看 .speccore/local/ 目录权限',
+            '尝试重启命令',
+        ],
+    },
+    {
+        category: '网络/超时',
+        severity: 'warn',
+        patterns: [/timeout/i, /ETIMEDOUT/i, /ECONNREFUSED/i, /网络/i],
+        message: '网络连接超时或失败',
+        suggestions: [
+            '检查网络连接',
+            '如果是 LLM API 调用，检查 API key 是否有效',
+            '稍后重试',
+        ],
+    },
+];
+/**
+ * 诊断错误信息，返回匹配结果和建议
+ */
+function diagnoseError(error) {
+    const errorStr = String(error);
+    const errorMsg = error instanceof Error ? error.message : errorStr;
+    for (const pattern of ERROR_PATTERNS) {
+        for (const regex of pattern.patterns) {
+            if (regex.test(errorMsg) || regex.test(errorStr)) {
+                return {
+                    matched: true,
+                    category: pattern.category,
+                    severity: pattern.severity,
+                    message: pattern.message,
+                    suggestions: pattern.suggestions,
+                };
+            }
+        }
+    }
+    return {
+        matched: false,
+        category: '未知错误',
+        severity: 'error',
+        message: errorMsg,
+        suggestions: [
+            '查看详细错误堆栈：添加 --verbose 或 DEBUG=* 环境变量',
+            '运行 speccore doctor 检查项目健康度',
+            '查阅文档: https://github.com/your-org/speccore#troubleshooting',
+        ],
+    };
+}
+/**
+ * 打印诊断结果
+ */
+function printDiagnosis(result) {
+    const icon = result.severity === 'error' ? '❌' : result.severity === 'warn' ? '⚠️' : 'ℹ️';
+    logger_1.logger.info('');
+    logger_1.logger.info(`${icon} 错误诊断: ${result.category}`);
+    logger_1.logger.info(`   ${result.message}`);
+    logger_1.logger.info('');
+    logger_1.logger.info('💡 建议修复步骤:');
+    for (let i = 0; i < result.suggestions.length; i++) {
+        logger_1.logger.info(`   ${i + 1}. ${result.suggestions[i]}`);
+    }
+    logger_1.logger.info('');
+}
+/**
+ * 包装函数：自动诊断并打印
+ */
+function diagnoseAndPrint(error) {
+    const result = diagnoseError(error);
+    printDiagnosis(result);
+    return result;
+}
+//# sourceMappingURL=error-diagnosis.js.map

package/dist/core/error-diagnosis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-diagnosis.js","sourceRoot":"","sources":["../../src/core/error-diagnosis.ts"],"names":[],"mappings":"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"}

package/dist/core/intent-recognition.d.ts

@@ -45,4 +45,11 @@ export declare function getCommandMapping(commandId: string): CommandMapping | u
  * 根据意图类型获取相关命令
  */
 export declare function getCommandsByIntent(intent: IntentType): CommandMapping[];
+/** 容易与"普通 AI 对话"混淆的意图 */
+export declare const AMBIGUOUS_INTENTS: Set<IntentType>;
+/**
+ * 判断用户输入是否明确与 speccore CLI 操作相关
+ * v6.97.0+ 新增：避免"分析代码""讨论需求"等普通聊天被误判为 speccore 操作
+ */
+export declare function isSpeccoreOperation(input: string): boolean;
 //# sourceMappingURL=intent-recognition.d.ts.map

package/dist/core/intent-recognition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-recognition.d.ts","sourceRoot":"","sources":["../../src/core/intent-recognition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,WAAW;AACX,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,kBAAkB,GAClB,SAAS,GACT,OAAO,GACP,IAAI,GACJ,MAAM,GACN,QAAQ,GACR,MAAM,GACN,WAAW,GACX,SAAS,GACT,gBAAgB,GAChB,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,SAAS,GACT,MAAM,GACN,QAAQ,GACR,UAAU,GACV,MAAM,GACN,OAAO,GACP,cAAc,GACd,kBAAkB,GAClB,uBAAuB,GACvB,gBAAgB,GAChB,eAAe,GACf,SAAS,GACT,QAAQ,GACR,UAAU,GACV,WAAW,GACX,OAAO,GACP,QAAQ,GACR,UAAU,GACV,cAAc,GACd,cAAc,GACd,SAAS,GACT,UAAU,GACV,YAAY,CAAC;AAEjB,aAAa;AACb,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,aAAa;AACb,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAgcD;;GAEG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAsG5E;AA6FD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAIhF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,EAAE,CAExD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE/E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,EAAE,CAExE"}
+{"version":3,"file":"intent-recognition.d.ts","sourceRoot":"","sources":["../../src/core/intent-recognition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,WAAW;AACX,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,kBAAkB,GAClB,SAAS,GACT,OAAO,GACP,IAAI,GACJ,MAAM,GACN,QAAQ,GACR,MAAM,GACN,WAAW,GACX,SAAS,GACT,gBAAgB,GAChB,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,SAAS,GACT,MAAM,GACN,QAAQ,GACR,UAAU,GACV,MAAM,GACN,OAAO,GACP,cAAc,GACd,kBAAkB,GAClB,uBAAuB,GACvB,gBAAgB,GAChB,eAAe,GACf,SAAS,GACT,QAAQ,GACR,UAAU,GACV,WAAW,GACX,OAAO,GACP,QAAQ,GACR,UAAU,GACV,cAAc,GACd,cAAc,GACd,SAAS,GACT,UAAU,GACV,YAAY,CAAC;AAEjB,aAAa;AACb,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,aAAa;AACb,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA+dD;;GAEG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA2G5E;AAmID;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAIhF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,EAAE,CAExD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE/E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,EAAE,CAExE;AA0BD,yBAAyB;AACzB,eAAO,MAAM,iBAAiB,iBAE5B,CAAC;AAEH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAG1D"}

package/dist/core/intent-recognition.js

@@ -5,11 +5,13 @@
  * 支持 31 种意图类型、200+ 关键词匹配、置信度计算、上下文感知增强
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AMBIGUOUS_INTENTS = void 0;
 exports.recognizeIntent = recognizeIntent;
 exports.getConfidenceLevel = getConfidenceLevel;
 exports.getAllCommandMappings = getAllCommandMappings;
 exports.getCommandMapping = getCommandMapping;
 exports.getCommandsByIntent = getCommandsByIntent;
+exports.isSpeccoreOperation = isSpeccoreOperation;
 const context_1 = require("./context");
 // ============================================================
 // 命令映射表（12 种意图，按优先级排序）
@@ -54,15 +56,46 @@ const COMMAND_MAPPINGS = [
         description: '创建新迭代 — 生成 STAFFING + 产品需求 + 需求文档目录',
         args: '--name=<name> --owner=<owner>',
     },
-    // 需求分析
+    // 需求分析（全局级 + 迭代级 + 任务级 + 重新/补充分析）
     {
         id: 'analyze',
         intent: 'analyze',
         priority: 90,
-        triggers: ['分析需求', '需求分析', 'AI分析', '代码分析', '分析代码', '迭代分析', '分析迭代', '本迭代分析', '当前迭代分析'],
-        patterns: ['分析(.+)需求', '分析(.+)代码', '迭代(.+)分析', '本迭代(.+)分析'],
-        description: 'AI 分析 — 需求完整性 + 改动范围 + 风险矩阵',
-        args: '-I <iteration> 或 --scope global --src <dirs>',
+        triggers: [
+            // 迭代级
+            '分析需求', '需求分析', 'AI分析', '代码分析', '分析代码',
+            '迭代分析', '分析迭代', '本迭代分析', '当前迭代分析',
+            // 全局级（v6.97.0+ 修复：避免全局分析 fallback 到迭代层）
+            '全局分析', '全局层分析', '分析全局层', '分析全局',
+            '全量分析', '全量层分析', '分析全量层', '分析全量',
+            '项目分析', '分析项目', '分析整体架构',
+            '分析所有端', '分析所有工程', '跨端分析', '全局架构分析',
+            '整体分析', '全项目分析', '项目架构分析',
+            '分析整个系统', '分析整个项目', '分析所有源码',
+            // 任务级（v6.97.0+ 新增：子任务/单任务分析）
+            '任务分析', '分析任务', '子任务分析', '分析子任务',
+            'Task分析', '分析Task', '当前任务分析', '单任务分析',
+            // 重新/补充分析（v6.97.0+ 新增：覆盖 --supplement / --sync）
+            '重新分析', '再分析', '重新生成分析', '重新跑分析',
+            '补充分析', '追加分析', '更新分析', '修正分析',
+            '完善分析', '刷新分析', '重新评估', '重新审查',
+        ],
+        patterns: [
+            '分析(.+)需求', '分析(.+)代码',
+            '迭代(.+)分析', '本迭代(.+)分析',
+            // 全局级匹配模式
+            '全局分析(.+)', '全量分析(.+)', '分析所有(.+)',
+            '分析项目(.+)', '项目(.+)分析', '整体(.+)分析',
+            '跨端(.+)分析', '架构(.+)分析',
+            // 任务级匹配模式
+            '任务(.+)分析', '分析任务(.+)', '子任务(.+)分析',
+            'Task(.+)分析', '分析Task(.+)',
+            // 重新/补充分析匹配模式
+            '重新(.+)分析', '再(.+)分析', '补充(.+)分析',
+            '更新(.+)分析', '修正(.+)分析', '完善(.+)分析',
+        ],
+        description: 'AI 分析 — 需求完整性 + 改动范围 + 风险矩阵（支持全局级/迭代级/任务级/重新分析）',
+        args: '-I <iteration> 或 --scope global|task --with-code --supplement --sync',
     },
     // 任务拆分
     {
@@ -481,11 +514,17 @@ async function recognizeIntent(input) {
             let contextAware = false;
             const contextRule = CONTEXT_RULES[mapping.id];
             if (contextRule) {
-                if (activeIteration) {
+                // v6.97.0+ 修复：用户明确说全局分析时，不因活跃迭代给迭代级意图加分
+                const hasGlobalScope = /全局|全量|所有项目|所有工程|整体架构|跨端|整个系统/.test(input);
+                if (activeIteration && !hasGlobalScope) {
                     totalScore += 15;
                     contextAware = true;
                     matched.push('上下文感知: 有活跃迭代');
                 }
+                else if (activeIteration && hasGlobalScope && mapping.intent === 'analyze') {
+                    // 全局分析时，analyze 意图不因活跃迭代加分（避免全局被迭代上下文拉高）
+                    matched.push('上下文感知: 有活跃迭代，但用户明确全局分析，不加分');
+                }
                 else if (mapping.intent === 'execute' ||
                     mapping.intent === 'query_progress') {
                     totalScore -= 20; // 无上下文降权
@@ -571,11 +610,21 @@ function extractParams(input, mapping) {
     if (iterMatch) {
         params.iteration = iterMatch[1];
     }
-    // 检测 scope 参数（全局分析 vs 迭代分析）
+    // 检测 scope 参数（全局分析 vs 迭代分析 vs 任务分析）
+    // v6.97.0+ 新增：任务级 scope 映射，优先级高于全局（先匹配先命中）
     const scopeKeywords = {
-        '全局': 'global', '所有工程': 'global', '全部工程': 'global',
-        '所有项目': 'global', '全部项目': 'global', '整个项目': 'global',
-        '全量': 'global', '整体': 'global', '全部': 'global',
+        // 任务级（优先匹配，避免"任务"被误判为迭代级）
+        '子任务': 'task', '单任务': 'task',
+        '任务级': 'task', '任务层': 'task',
+        // 全局级
+        '全局': 'global', '全局层': 'global', '全局范围': 'global',
+        '全量': 'global', '全量层': 'global', '全量范围': 'global',
+        '所有工程': 'global', '全部工程': 'global',
+        '所有项目': 'global', '全部项目': 'global', '全项目': 'global',
+        '整个项目': 'global', '整个系统': 'global',
+        '所有端': 'global', '全部端': 'global',
+        '所有源码': 'global', '全部源码': 'global',
+        '整体': 'global', '全部': 'global',
     };
     for (const [keyword, scopeValue] of Object.entries(scopeKeywords)) {
         if (input.includes(keyword)) {
@@ -583,6 +632,31 @@ function extractParams(input, mapping) {
             break;
         }
     }
+    // 检测任务名（--task 参数）
+    // v6.97.0+ 新增：从输入中提取 Task-XXX 或子任务名
+    const taskIdMatch = input.match(/Task[\-\s]*(\w+)/i);
+    if (taskIdMatch) {
+        params.task = `Task-${taskIdMatch[1]}`;
+    }
+    const taskNameMatch = input.match(/(?:子任务|任务)[：:\s]*([^，,。\s]+)/);
+    if (taskNameMatch && !params.task) {
+        params.task = taskNameMatch[1];
+    }
+    // 检测 --with-code 参数（源码扫描）
+    const codeKeywords = ['源码', '代码', '结合源码', '扫描代码', '读代码', '看代码', 'with-code', 'with code'];
+    if (codeKeywords.some(k => input.includes(k))) {
+        params.withCode = 'true';
+    }
+    // 检测重新/补充分析参数（--supplement / --sync）
+    // v6.97.0+ 新增：覆盖"重新分析""补充分析""更新分析"等场景
+    const supplementKeywords = ['重新', '再', '补充', '追加', '更新', '修正', '完善', '刷新'];
+    if (supplementKeywords.some(k => input.includes(k)) && input.includes('分析')) {
+        params.supplement = 'true';
+    }
+    const syncKeywords = ['回写', '同步到', '写回', '局部更新'];
+    if (syncKeywords.some(k => input.includes(k))) {
+        params.sync = 'true';
+    }
     // 检测工具/平台名称（--tool 参数）
     const toolKeywords = {
         'trae': 'trae', 'tree': 'trae',
@@ -643,4 +717,38 @@ function getCommandMapping(commandId) {
 function getCommandsByIntent(intent) {
     return COMMAND_MAPPINGS.filter((m) => m.intent === intent);
 }
+// ═══════════════════════════════════════════════════════════
+// 意图域检测 — 区分 speccore CLI 操作 vs 普通 AI 对话
+// ═══════════════════════════════════════════════════════════
+/** 明确表明用户在使用 speccore 的上下文关键词 */
+const SPECCORE_CONTEXT_KEYWORDS = [
+    // 工具名
+    'speccore', 'spec-core', 'spec_ask', 'spec-ask',
+    // 迭代/项目管理
+    '迭代', 'iteration', 'sprint', 'STAFFING',
+    // 全局分析（speccore 专有概念）
+    '全局', '全局层', '全量', '全量层', '跨端',
+    // 任务/拆分
+    '拆分', 'split', '子任务', 'Task-', 'task-',
+    // 文档/规格
+    'PRD', 'doc2spec', 'spec2doc', 'ANALYSIS', '020-specs', '030-tasks',
+    // 执行相关（明确 speccore 语境）
+    'execute', 'dev --', 'done', 'reindex',
+    // 端（speccore 专有概念）
+    'backend', 'frontend', 'h5', 'admin', 'with-code', 'with code',
+    // 变更
+    '变更', 'change --',
+];
+/** 容易与"普通 AI 对话"混淆的意图 */
+exports.AMBIGUOUS_INTENTS = new Set([
+    'analyze', 'split', 'execute', 'plan', 'review',
+]);
+/**
+ * 判断用户输入是否明确与 speccore CLI 操作相关
+ * v6.97.0+ 新增：避免"分析代码""讨论需求"等普通聊天被误判为 speccore 操作
+ */
+function isSpeccoreOperation(input) {
+    const lower = input.toLowerCase();
+    return SPECCORE_CONTEXT_KEYWORDS.some(kw => lower.includes(kw.toLowerCase()));
+}
 //# sourceMappingURL=intent-recognition.js.map