speccore 6.98.0 → 7.2.0

package/dist/core/doc-quality-gate.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkDocumentQuality = checkDocumentQuality;
+exports.runGlobalQualityGate = runGlobalQualityGate;
+exports.printQualityReport = printQualityReport;
+/**
+ * doc-quality-gate — 文档质量门禁
+ * v7.2.0+
+ *
+ * 全局分析文档生成后的自动质量检查：
+ *   - 检测占位符（"待导入"、"待补充"、"示例"、"_待填写_"）
+ *   - 检测空表格（只有表头没有数据行）
+ *   - 检测字数过浅（少于阈值）
+ *   - 检测缺少 Mermaid 图表（如 ARCHITECTURE.md 要求有图表）
+ *   - 检测缺少关键章节
+ *
+ * 输出: 质量报告，标记问题章节，建议修复命令
+ */
+const fs_extra_1 = require("fs-extra");
+const path_1 = require("path");
+const logger_1 = require("../utils/logger");
+// 占位符关键词
+const PLACEHOLDER_PATTERNS = [
+    /待导入|待补充|待填写|待完善|待确认|待审核/,
+    /_待\w+_/,
+    /示例[：:]\s*$/m,
+    /TODO|FIXME|XXX|HACK/,
+    /\|[\s-]*\|[\s-]*\|[\s-]*\|/, // 空表格行
+];
+// 需要 Mermaid 图表的文档
+const CHART_REQUIRED_DOCS = [
+    'ARCHITECTURE.md', 'INTERACTION_MAP.md', 'DATA_FLOW.md',
+    'DEPLOYMENT.md', 'UI_FLOW.md', '_ASSOCIATION.md', '_MODULES.md',
+];
+// 关键章节要求
+const REQUIRED_SECTIONS = {
+    'ARCHITECTURE.md': ['服务拓扑', '数据流', '部署关系', '容错设计'],
+    'API_CONTRACT.yaml': ['接口定义', '鉴权', '限流', '版本策略'],
+    'REQUIREMENT.md': ['产品愿景', '用户故事', '验收标准'],
+};
+/**
+ * 检查单个文档质量
+ */
+async function checkDocumentQuality(filePath) {
+    if (!(await (0, fs_extra_1.pathExists)(filePath)))
+        return null;
+    const content = await (0, fs_extra_1.readFile)(filePath, 'utf-8');
+    const lines = content.split('\n');
+    const basename_ = filePath.split('/').pop() || '';
+    const issues = [];
+    // 1. 检测占位符
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const pattern of PLACEHOLDER_PATTERNS) {
+            if (pattern.test(line)) {
+                issues.push({
+                    file: filePath,
+                    line: i + 1,
+                    type: 'placeholder',
+                    severity: 'error',
+                    message: `发现占位符: "${line.trim().slice(0, 40)}"`,
+                    suggestion: `补充具体内容，删除占位符`,
+                });
+                break;
+            }
+        }
+    }
+    // 2. 检测字数
+    const wordCount = content.replace(/\s+/g, '').length;
+    if (wordCount < 200) {
+        issues.push({
+            file: filePath,
+            type: 'too-short',
+            severity: 'error',
+            message: `文档过短: ${wordCount} 字（建议 > 500 字）`,
+            suggestion: `补充详细内容，增加分析深度`,
+        });
+    }
+    else if (wordCount < 500) {
+        issues.push({
+            file: filePath,
+            type: 'too-short',
+            severity: 'warning',
+            message: `文档偏短: ${wordCount} 字（建议 > 1000 字）`,
+            suggestion: `补充更多细节和案例`,
+        });
+    }
+    // 3. 检测 Mermaid 图表
+    const hasMermaid = /```mermaid|:::mermaid/.test(content);
+    if (CHART_REQUIRED_DOCS.includes(basename_) && !hasMermaid) {
+        issues.push({
+            file: filePath,
+            type: 'missing-chart',
+            severity: 'error',
+            message: `缺少 Mermaid 图表（${basename_} 必须包含图表）`,
+            suggestion: `添加 Mermaid 图表（graph/sequenceDiagram/stateDiagram 等）`,
+        });
+    }
+    // 4. 检测关键章节
+    const required = REQUIRED_SECTIONS[basename_];
+    if (required) {
+        for (const section of required) {
+            if (!content.includes(section)) {
+                issues.push({
+                    file: filePath,
+                    type: 'missing-section',
+                    severity: 'warning',
+                    message: `缺少关键章节: "${section}"`,
+                    suggestion: `添加 "${section}" 章节`,
+                });
+            }
+        }
+    }
+    // 5. 计算质量分
+    const errorCount = issues.filter(i => i.severity === 'error').length;
+    const warningCount = issues.filter(i => i.severity === 'warning').length;
+    const score = Math.max(0, 100 - errorCount * 20 - warningCount * 5);
+    return { file: filePath, issues, wordCount, hasMermaid, score };
+}
+/**
+ * 扫描全局分析目录，检查所有文档质量
+ */
+async function runGlobalQualityGate(globalDir) {
+    const dir = globalDir || (0, path_1.join)(process.cwd(), '.speccore', 'GLOBAL');
+    const reports = [];
+    // 扫描 overview/ 和 requirements/ 和 platforms/
+    const subdirs = ['overview', 'requirements', 'platforms'];
+    for (const sub of subdirs) {
+        const subDir = (0, path_1.join)(dir, sub);
+        if (!(await (0, fs_extra_1.pathExists)(subDir)))
+            continue;
+        if (sub === 'platforms') {
+            // platforms/ 下有子目录
+            const entries = await (0, fs_extra_1.readdir)(subDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const platformDir = (0, path_1.join)(subDir, entry.name);
+                    const files = await (0, fs_extra_1.readdir)(platformDir);
+                    for (const f of files.filter(f => f.endsWith('.md') || f.endsWith('.yaml') || f.endsWith('.yml'))) {
+                        const report = await checkDocumentQuality((0, path_1.join)(platformDir, f));
+                        if (report)
+                            reports.push(report);
+                    }
+                }
+            }
+        }
+        else {
+            const files = await (0, fs_extra_1.readdir)(subDir);
+            for (const f of files.filter(f => f.endsWith('.md') || f.endsWith('.yaml') || f.endsWith('.yml'))) {
+                const report = await checkDocumentQuality((0, path_1.join)(subDir, f));
+                if (report)
+                    reports.push(report);
+            }
+        }
+    }
+    // 扫描 platforms/_shared/
+    const sharedDir = (0, path_1.join)(dir, 'platforms', '_shared');
+    if (await (0, fs_extra_1.pathExists)(sharedDir)) {
+        const files = await (0, fs_extra_1.readdir)(sharedDir);
+        for (const f of files.filter(f => f.endsWith('.md'))) {
+            const report = await checkDocumentQuality((0, path_1.join)(sharedDir, f));
+            if (report)
+                reports.push(report);
+        }
+    }
+    return reports;
+}
+/**
+ * 打印质量报告
+ */
+function printQualityReport(reports) {
+    if (reports.length === 0) {
+        logger_1.logger.info('📋 未找到全局分析文档');
+        return;
+    }
+    const totalErrors = reports.reduce((sum, r) => sum + r.issues.filter(i => i.severity === 'error').length, 0);
+    const totalWarnings = reports.reduce((sum, r) => sum + r.issues.filter(i => i.severity === 'warning').length, 0);
+    const avgScore = Math.round(reports.reduce((sum, r) => sum + r.score, 0) / reports.length);
+    logger_1.logger.info('');
+    logger_1.logger.info('🔍 全局分析文档质量报告');
+    logger_1.logger.info(`   文档数: ${reports.length} | 平均分: ${avgScore}/100 | ❌ ${totalErrors} | ⚠️ ${totalWarnings}`);
+    logger_1.logger.info('');
+    for (const report of reports) {
+        const fileName = report.file.split('/').slice(-2).join('/');
+        const errors = report.issues.filter(i => i.severity === 'error');
+        const warnings = report.issues.filter(i => i.severity === 'warning');
+        if (errors.length === 0 && warnings.length === 0) {
+            logger_1.logger.info(`   ✅ ${fileName} (${report.wordCount}字, ${report.score}分)`);
+            continue;
+        }
+        const icon = errors.length > 0 ? '❌' : '⚠️';
+        logger_1.logger.info(`   ${icon} ${fileName} (${report.wordCount}字, ${report.score}分) — ${errors.length} 错误, ${warnings.length} 警告`);
+        for (const issue of report.issues.slice(0, 3)) {
+            const lineInfo = issue.line ? `L${issue.line}` : '';
+            const icon2 = issue.severity === 'error' ? '❌' : '⚠️';
+            logger_1.logger.info(`      ${icon2} ${lineInfo} ${issue.message}`);
+        }
+        if (report.issues.length > 3) {
+            logger_1.logger.info(`      ... 还有 ${report.issues.length - 3} 个问题`);
+        }
+    }
+    if (totalErrors > 0) {
+        logger_1.logger.info('');
+        logger_1.logger.info('💡 修复建议:');
+        logger_1.logger.info('   speccore analyze --scope global --layer 4 --deep <文档名>');
+        logger_1.logger.info('   或使用 --iterative 逐节补全');
+    }
+}
+//# sourceMappingURL=doc-quality-gate.js.map

package/dist/core/doc-quality-gate.js.map

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

package/dist/core/graph-semantic.d.ts

@@ -0,0 +1,51 @@
+/**
+ * graph-semantic — LLM 增强的图谱语义查询
+ * v7.0.0+: 让图谱查询从"关键词匹配"升级为"语义理解"
+ *
+ * 核心能力：
+ * 1. 查询词语义扩展 —— "订单相关" → 扩展为 ["order", "booking", "purchase", "交易", "下单", "订单号"]
+ * 2. 候选结果语义排序 —— LLM 理解查询意图后，对匹配结果重新排序
+ * 3. 零 Token 回退 —— LLM 不可用时，降级到本地规则扩展
+ */
+import type { GraphEntity } from './knowledge-graph';
+export interface SemanticExpansion {
+    /** 原始查询词 */
+    original: string;
+    /** LLM 理解的查询意图 */
+    intent: string;
+    /** 扩展后的关键词列表（含同义词、相关概念） */
+    keywords: string[];
+    /** 业务域推断 */
+    domain?: string;
+    /** 查询类型推断 */
+    queryType: 'code' | 'requirement' | 'task' | 'architecture' | 'mixed';
+}
+export interface RankedCandidate {
+    entity: GraphEntity;
+    /** 本地匹配得分 */
+    localScore: number;
+    /** LLM 语义得分 (0-100) */
+    semanticScore: number;
+    /** 综合得分 */
+    finalScore: number;
+    /** LLM 给出的匹配理由 */
+    reason?: string;
+}
+/**
+ * 语义扩展查询词
+ * 优先使用 LLM，降级到本地规则
+ */
+export declare function expandQuerySemantically(question: string, options?: {
+    useLlm?: boolean;
+}): Promise<SemanticExpansion>;
+/**
+ * 使用 LLM 对候选结果做语义排序
+ */
+export declare function semanticRank(question: string, candidates: {
+    entity: GraphEntity;
+    localScore: number;
+}[], options?: {
+    topK?: number;
+    useLlm?: boolean;
+}): Promise<RankedCandidate[]>;
+//# sourceMappingURL=graph-semantic.d.ts.map

package/dist/core/graph-semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-semantic.d.ts","sourceRoot":"","sources":["../../src/core/graph-semantic.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMrD,MAAM,WAAW,iBAAiB;IAChC,YAAY;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa;IACb,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,MAAM,GAAG,cAAc,GAAG,OAAO,CAAC;CACvE;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,WAAW,CAAC;IACpB,aAAa;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAe5B;AAoJD;;GAEG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAAE,EACzD,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5C,OAAO,CAAC,eAAe,EAAE,CAAC,CA4B5B"}

package/dist/core/graph-semantic.js

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * graph-semantic — LLM 增强的图谱语义查询
+ * v7.0.0+: 让图谱查询从"关键词匹配"升级为"语义理解"
+ *
+ * 核心能力：
+ * 1. 查询词语义扩展 —— "订单相关" → 扩展为 ["order", "booking", "purchase", "交易", "下单", "订单号"]
+ * 2. 候选结果语义排序 —— LLM 理解查询意图后，对匹配结果重新排序
+ * 3. 零 Token 回退 —— LLM 不可用时，降级到本地规则扩展
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandQuerySemantically = expandQuerySemantically;
+exports.semanticRank = semanticRank;
+const logger_1 = require("../utils/logger");
+// ═══════════════════════════════════════════════════════════
+// 查询语义扩展
+// ═══════════════════════════════════════════════════════════
+/**
+ * 语义扩展查询词
+ * 优先使用 LLM，降级到本地规则
+ */
+async function expandQuerySemantically(question, options) {
+    const useLlm = options?.useLlm !== false;
+    // 尝试 LLM 扩展
+    if (useLlm) {
+        try {
+            const llmResult = await expandWithLLM(question);
+            if (llmResult)
+                return llmResult;
+        }
+        catch (e) {
+            logger_1.logger.debug('LLM 语义扩展失败，降级到本地规则:', e);
+        }
+    }
+    // 降级到本地规则扩展
+    return expandWithRules(question);
+}
+/**
+ * 使用 LLM 进行语义扩展
+ */
+async function expandWithLLM(question) {
+    const prompt = buildExpansionPrompt(question);
+    const response = await callLLM(prompt);
+    if (!response)
+        return null;
+    try {
+        const parsed = parseLlmJson(response);
+        if (!parsed || !Array.isArray(parsed.keywords))
+            return null;
+        return {
+            original: question,
+            intent: parsed.intent || '通用查询',
+            keywords: parsed.keywords,
+            domain: parsed.domain,
+            queryType: parsed.queryType || 'mixed',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 使用本地规则进行语义扩展（零 Token）
+ */
+function expandWithRules(question) {
+    const lower = question.toLowerCase();
+    const keywords = [];
+    // 1. 提取原始词
+    const rawWords = lower
+        .replace(/[^\u4e00-\u9fa5a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter(w => w.length >= 2);
+    keywords.push(...rawWords);
+    // 2. 业务域同义词扩展
+    const DOMAIN_SYNONYMS = {
+        // 订单/交易域
+        '订单': ['order', 'booking', 'purchase', 'trade', 'transaction', '下单', '订单号', '订单状态', '订单管理'],
+        'order': ['订单', 'booking', 'purchase', 'trade', 'transaction', '下单'],
+        '交易': ['transaction', 'trade', 'order', '支付', 'purchase'],
+        '支付': ['payment', 'pay', 'checkout', 'transaction', '订单付款'],
+        // 用户域
+        '用户': ['user', 'account', 'member', 'customer', 'profile', '用户管理', '用户信息'],
+        'user': ['用户', 'account', 'member', 'customer', 'profile'],
+        '认证': ['auth', 'authentication', 'login', 'oauth', 'jwt', 'token', '登录', '鉴权'],
+        'auth': ['认证', 'authentication', 'login', 'oauth', 'jwt', 'token', '鉴权'],
+        '登录': ['login', 'signin', 'auth', 'authenticate', '认证', '登入'],
+        // 内容域
+        '内容': ['content', 'article', 'post', 'document', 'media', '素材'],
+        'content': ['内容', 'article', 'post', 'document', 'media'],
+        // 消息/通知域
+        '消息': ['message', 'notification', 'notice', 'push', 'sms', 'email', '通知'],
+        'notification': ['消息', 'notification', 'notice', 'push', '通知'],
+        // 数据域
+        '数据': ['data', 'database', 'model', 'entity', 'schema', '表', '字段'],
+        'data': ['数据', 'database', 'model', 'entity', 'schema'],
+        // 搜索域
+        '搜索': ['search', 'query', 'filter', 'find', 'lookup', '检索', '查询'],
+        'search': ['搜索', 'query', 'filter', 'find', 'lookup', '检索'],
+        // 配置域
+        '配置': ['config', 'configuration', 'settings', 'options', 'env', '环境变量'],
+        'config': ['配置', 'configuration', 'settings', 'options', 'env'],
+        // 监控域
+        '监控': ['monitor', 'observability', 'metrics', 'alert', 'log', '监控', '告警'],
+        'monitor': ['监控', 'observability', 'metrics', 'alert', 'log', '告警'],
+        // 安全域
+        '安全': ['security', 'safe', 'protect', 'encrypt', 'permission', '安全', '权限'],
+        'security': ['安全', 'safe', 'protect', 'encrypt', 'permission', '权限'],
+        // 性能域
+        '性能': ['performance', 'optimize', 'cache', 'speed', 'latency', '性能', '优化'],
+        'performance': ['性能', 'optimize', 'cache', 'speed', 'latency', '优化'],
+        // 测试域
+        '测试': ['test', 'testing', 'spec', 'e2e', 'unit', 'integration', '测试', '用例'],
+        'test': ['测试', 'testing', 'spec', 'e2e', 'unit', 'integration'],
+        // 部署域
+        '部署': ['deploy', 'deployment', 'release', 'ci/cd', 'pipeline', '部署', '发布'],
+        'deploy': ['部署', 'deployment', 'release', 'ci/cd', 'pipeline', '发布'],
+    };
+    for (const [key, syns] of Object.entries(DOMAIN_SYNONYMS)) {
+        if (lower.includes(key)) {
+            for (const syn of syns) {
+                if (!keywords.includes(syn))
+                    keywords.push(syn);
+            }
+        }
+    }
+    // 3. 推断查询类型
+    let queryType = 'mixed';
+    if (/\b(code|代码|文件|类|函数|方法|源码|实现)\b/.test(lower))
+        queryType = 'code';
+    else if (/\b(需求|requirement|feature|功能|用户故事|story)\b/.test(lower))
+        queryType = 'requirement';
+    else if (/\b(任务|task|todo|计划|拆分)\b/.test(lower))
+        queryType = 'task';
+    else if (/\b(架构|architecture|设计|结构|拓扑|服务|模块关系)\b/.test(lower))
+        queryType = 'architecture';
+    // 4. 推断业务域
+    let domain;
+    for (const [key] of Object.entries(DOMAIN_SYNONYMS)) {
+        if (lower.includes(key)) {
+            domain = key;
+            break;
+        }
+    }
+    return {
+        original: question,
+        intent: `查询与 "${question}" 相关的实体`,
+        keywords: [...new Set(keywords)],
+        domain,
+        queryType,
+    };
+}
+/**
+ * 构建语义扩展 Prompt
+ */
+function buildExpansionPrompt(question) {
+    return `你是代码知识图谱的语义查询助手。用户的查询可能包含口语化表达、模糊概念或业务术语。
+
+任务：分析用户查询，输出结构化的语义扩展结果。
+
+用户查询: "${question}"
+
+要求：
+1. 理解用户的真实意图（他们在找什么？）
+2. 提取查询中的核心概念
+3. 为每个核心概念生成同义词和相关术语（中英文都要）
+4. 推断查询类型（code/requirement/task/architecture/mixed）
+5. 推断业务域（如订单、用户、支付、内容等）
+
+输出 JSON 格式（不要解释，只返回 JSON）：
+{
+  "intent": "用户的真实意图描述",
+  "keywords": ["原始词", "同义词1", "同义词2", "相关术语1", "英文术语1", "英文术语2"],
+  "domain": "业务域名称",
+  "queryType": "code|requirement|task|architecture|mixed"
+}`;
+}
+// ═══════════════════════════════════════════════════════════
+// 候选结果语义排序
+// ═══════════════════════════════════════════════════════════
+/**
+ * 使用 LLM 对候选结果做语义排序
+ */
+async function semanticRank(question, candidates, options) {
+    const topK = options?.topK || 20;
+    const useLlm = options?.useLlm !== false;
+    // 取本地得分最高的候选
+    const topCandidates = candidates
+        .sort((a, b) => b.localScore - a.localScore)
+        .slice(0, topK);
+    if (topCandidates.length === 0)
+        return [];
+    // 尝试 LLM 排序
+    if (useLlm && topCandidates.length > 1) {
+        try {
+            const ranked = await rankWithLLM(question, topCandidates);
+            if (ranked)
+                return ranked;
+        }
+        catch (e) {
+            logger_1.logger.debug('LLM 语义排序失败，使用本地得分:', e);
+        }
+    }
+    // 降级：使用本地得分作为最终得分
+    return topCandidates.map(c => ({
+        entity: c.entity,
+        localScore: c.localScore,
+        semanticScore: 0,
+        finalScore: c.localScore,
+    }));
+}
+/**
+ * LLM 语义排序
+ */
+async function rankWithLLM(question, candidates) {
+    const prompt = buildRankingPrompt(question, candidates);
+    const response = await callLLM(prompt);
+    if (!response)
+        return null;
+    try {
+        const parsed = parseLlmJson(response);
+        if (!parsed || !Array.isArray(parsed.ranking))
+            return null;
+        const rankingMap = new Map();
+        for (const item of parsed.ranking) {
+            if (item.id && typeof item.score === 'number') {
+                rankingMap.set(item.id, { score: item.score, reason: item.reason || '' });
+            }
+        }
+        return candidates.map(c => {
+            const llmResult = rankingMap.get(c.entity.id);
+            const semanticScore = llmResult?.score || 0;
+            // 综合得分 = 本地得分 * 0.4 + LLM 语义得分 * 0.6
+            const finalScore = c.localScore * 0.4 + semanticScore * 0.6;
+            return {
+                entity: c.entity,
+                localScore: c.localScore,
+                semanticScore,
+                finalScore,
+                reason: llmResult?.reason,
+            };
+        }).sort((a, b) => b.finalScore - a.finalScore);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 构建排序 Prompt
+ */
+function buildRankingPrompt(question, candidates) {
+    const candidateList = candidates.map((c, i) => {
+        const e = c.entity;
+        const info = [
+            `ID: ${e.id}`,
+            `类型: ${e.type}`,
+            `标题: ${e.title}`,
+            e.description ? `描述: ${e.description.slice(0, 100)}` : '',
+            e.semanticTags?.length ? `语义标签: ${e.semanticTags.join(', ')}` : '',
+            e.businessRole ? `业务角色: ${e.businessRole}` : '',
+            e.file ? `文件: ${e.file}` : '',
+        ].filter(Boolean).join('\n   ');
+        return `${i + 1}. ${info}`;
+    }).join('\n\n');
+    return `你是代码知识图谱的语义匹配助手。
+
+用户查询: "${question}"
+
+以下是从知识图谱中初步匹配的候选实体（按本地关键词匹配得分排序）：
+
+${candidateList}
+
+任务：判断每个候选实体与用户查询的语义相关性。
+
+评分标准（0-100）：
+- 90-100: 完全匹配，直接回答用户问题
+- 70-89: 高度相关，包含用户需要的核心信息
+- 50-69: 部分相关，需要进一步探索
+- 30-49: 弱相关，可能有关联但不直接
+- 0-29: 不相关
+
+输出 JSON 格式（不要解释，只返回 JSON）：
+{
+  "reasoning": "简短的整体分析",
+  "ranking": [
+    { "id": "实体ID", "score": 85, "reason": "为什么相关/不相关" },
+    ...
+  ]
+}`;
+}
+// ═══════════════════════════════════════════════════════════
+// LLM 调用（复用 ask-llm 逻辑）
+// ═══════════════════════════════════════════════════════════
+async function callLLM(prompt) {
+    // 优先使用环境变量配置的 LLM
+    const endpoint = process.env.SPECCORE_LLM_ENDPOINT;
+    const apiKey = process.env.SPECCORE_LLM_KEY || process.env.OPENAI_API_KEY;
+    if (endpoint && apiKey) {
+        try {
+            const res = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${apiKey}` },
+                body: JSON.stringify({
+                    model: process.env.SPECCORE_LLM_MODEL || 'gpt-4o-mini',
+                    messages: [
+                        { role: 'system', content: 'You are a helpful assistant. Always respond with valid JSON only.' },
+                        { role: 'user', content: prompt },
+                    ],
+                    temperature: 0.1,
+                    max_tokens: 2000,
+                }),
+                signal: AbortSignal.timeout(15000), // 15s 超时
+            });
+            if (!res.ok) {
+                logger_1.logger.debug(`LLM API 错误: ${res.status} ${res.statusText}`);
+                return null;
+            }
+            const data = await res.json();
+            return data?.choices?.[0]?.message?.content || null;
+        }
+        catch (e) {
+            if (e.name === 'AbortError') {
+                logger_1.logger.debug('LLM 请求超时(15s)，降级到本地规则');
+            }
+            else {
+                logger_1.logger.debug(`LLM 请求失败: ${e.message}`);
+            }
+            // fallthrough
+        }
+    }
+    // 尝试本地 Ollama
+    try {
+        const res = await fetch('http://localhost:11434/api/generate', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                model: 'qwen2.5:7b',
+                prompt,
+                stream: false,
+                format: 'json',
+                options: { temperature: 0.1, num_predict: 2000 },
+            }),
+            signal: AbortSignal.timeout(8000),
+        });
+        if (res.ok) {
+            const data = await res.json();
+            return data?.response || null;
+        }
+    }
+    catch { }
+    return null;
+}
+/**
+ * 解析 LLM 返回的 JSON
+ */
+function parseLlmJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // 尝试提取 JSON 块
+        const match = text.match(/\{[\s\S]*\}/);
+        if (match) {
+            try {
+                return JSON.parse(match[0]);
+            }
+            catch { }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=graph-semantic.js.map