spectra-cli 4.1.1

package/dist/panoramic/qa/debt-context.js

@@ -0,0 +1,82 @@
+/**
+ * qa/debt-context.ts
+ * Step 4：F3 debt-scanner 集成 + 债务上下文注入
+ *
+ * 职责：
+ * - 检测问题是否含债务关键词（TODO/FIXME/HACK/技术债/最老等）
+ * - 匹配时调用 scanProjectDebt()，返回按 ageDays 倒序 Top-5 CodeDebtEntry
+ * - 将 CodeDebtEntry 转换为 Citation 格式
+ * - 不匹配时返回空结果（不触发 scanProjectDebt，节省 I/O）
+ *
+ * 说明：
+ * - plan §7 F3 集成决策：scanProjectDebt 每次问答都调用，不缓存
+ *   （主要是 AST 扫描 + git blame，无 LLM，单次耗时约 0.5-3 秒，可接受）
+ */
+import { scanProjectDebt } from '../../debt-scanner/index.js';
+// ============================================================
+// 债务关键词正则（大小写不敏感）
+// ============================================================
+/**
+ * 触发 debt-scanner 的关键词集合
+ * 包含：英文 TODO/FIXME/HACK/XXX/technical debt + 中文等价词
+ */
+const DEBT_KEYWORD_PATTERN = /TODO|FIXME|HACK|XXX|technical\s*debt|技术债|最老|最旧|最长时间|债务/i;
+// ============================================================
+// 工具函数
+// ============================================================
+/**
+ * 检测问题文本是否包含债务关键词
+ */
+export function isDebtQuestion(questionText) {
+    return DEBT_KEYWORD_PATTERN.test(questionText);
+}
+// ============================================================
+// 主函数
+// ============================================================
+/**
+ * 按需注入债务上下文
+ * 问题含债务关键词时：调用 scanProjectDebt，返回 Top-5 ageDays 倒序的 Citation
+ * 否则：返回 triggered=false + 空 citations
+ *
+ * @param questionText - 用户问题文本
+ * @param projectRoot - 项目根目录
+ * @param registry - LanguageAdapterRegistry（来自 batch-orchestrator 或 MCP 上下文）
+ * @param options - 选项（topN、scanOptions）
+ * @returns DebtContextResult
+ */
+export async function injectDebtContext(questionText, projectRoot, registry, options) {
+    // 关键词路由：不匹配时提前返回
+    if (!isDebtQuestion(questionText)) {
+        return { triggered: false, citations: [] };
+    }
+    const topN = options?.topN ?? 5;
+    // 调用 scanProjectDebt（每次都调用，不缓存）
+    let report;
+    try {
+        report = await scanProjectDebt({
+            projectRoot,
+            registry,
+            dryRun: true, // F5 问答仅需 AST 扫描，不需要 LLM 主题推断
+            ...options?.scanOptions,
+        });
+    }
+    catch (err) {
+        // scanProjectDebt 失败时不阻断问答，返回空债务上下文并记录 warn
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[warn] qa/debt-context: scanProjectDebt 失败，跳过债务上下文注入。原因：${message}`);
+        return { triggered: true, citations: [] };
+    }
+    // 按 ageDays 倒序排列，取 Top-N
+    const sorted = report.codeEntries
+        .filter((e) => e.ageDays >= 0)
+        .sort((a, b) => b.ageDays - a.ageDays)
+        .slice(0, topN);
+    // 转换为 Citation 格式
+    const citations = sorted.map((entry) => ({
+        specPath: entry.filePath,
+        lineRange: { startLine: entry.line, endLine: entry.line },
+        excerpt: entry.text.slice(0, 200),
+    }));
+    return { triggered: true, citations };
+}
+//# sourceMappingURL=debt-context.js.map

package/dist/panoramic/qa/debt-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debt-context.js","sourceRoot":"","sources":["../../../src/panoramic/qa/debt-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAwB9D,+DAA+D;AAC/D,kBAAkB;AAClB,+DAA+D;AAE/D;;;GAGG;AACH,MAAM,oBAAoB,GAAG,yDAAyD,CAAC;AAEvF,+DAA+D;AAC/D,OAAO;AACP,+DAA+D;AAE/D;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,YAAoB;IACjD,OAAO,oBAAoB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AACjD,CAAC;AAED,+DAA+D;AAC/D,MAAM;AACN,+DAA+D;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,YAAoB,EACpB,WAAmB,EACnB,QAA4C,EAC5C,OAA4B;IAE5B,iBAAiB;IACjB,IAAI,CAAC,cAAc,CAAC,YAAY,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAC7C,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC;IAEhC,gCAAgC;IAChC,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,eAAe,CAAC;YAC7B,WAAW;YACX,QAAQ;YACR,MAAM,EAAE,IAAI,EAAE,8BAA8B;YAC5C,GAAG,OAAO,EAAE,WAAW;SACxB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,4CAA4C;QAC5C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,CAAC,IAAI,CAAC,2DAA2D,OAAO,EAAE,CAAC,CAAC;QACnF,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAC5C,CAAC;IAED,yBAAyB;IACzB,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW;SAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;SAC7B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;SACrC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAElB,kBAAkB;IAClB,MAAM,SAAS,GAAe,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACnD,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE;QACzD,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;KAClC,CAAC,CAAC,CAAC;IAEJ,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AACxC,CAAC"}

package/dist/panoramic/qa/graph-retriever.d.ts

@@ -0,0 +1,29 @@
+/**
+ * qa/graph-retriever.ts
+ * Step 1-2：Graph BFS 检索 + hyperedge 扩展
+ *
+ * 职责：
+ * - 通过 GraphQueryEngine.query() 做 BFS 候选节点检索
+ * - 通过 engine.getHyperedges() 做 label + nodeId 两种命中方式扩展
+ * - 合并去重，构建 GraphContext
+ * - BFS 命中 < 3 节点时设 fallbackMode = 'rag-only'（R1 / FR-014）
+ */
+import type { GraphQueryEngine } from '../graph/graph-query.js';
+import type { GraphContext } from './types.js';
+/** graph-retriever 的输入选项 */
+export interface GraphRetrieverOptions {
+    /** BFS 节点预算（默认 20） */
+    budget?: number;
+    /** BFS 遍历深度（默认 2） */
+    depth?: number;
+}
+/**
+ * 通过 BFS + hyperedge 扩展检索与问题相关的图谱上下文
+ *
+ * @param questionText - 用户问题文本
+ * @param engine - GraphQueryEngine 实例
+ * @param options - 检索选项（budget、depth）
+ * @returns GraphContext（含 bfsNodes、hyperedges、fallbackMode）
+ */
+export declare function retrieveGraphContext(questionText: string, engine: GraphQueryEngine, options?: GraphRetrieverOptions): GraphContext;
+//# sourceMappingURL=graph-retriever.d.ts.map

package/dist/panoramic/qa/graph-retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-retriever.d.ts","sourceRoot":"","sources":["../../../src/panoramic/qa/graph-retriever.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM/C,4BAA4B;AAC5B,MAAM,WAAW,qBAAqB;IACpC,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA0BD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,YAAY,CA0Cd"}

package/dist/panoramic/qa/graph-retriever.js

@@ -0,0 +1,65 @@
+// ============================================================
+// 工具函数
+// ============================================================
+/**
+ * 对数组元素按 key 函数去重，保留首次出现的元素
+ */
+function dedup(arr, keyFn) {
+    const seen = new Set();
+    const result = [];
+    for (const item of arr) {
+        const key = keyFn(item);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(item);
+        }
+    }
+    return result;
+}
+// ============================================================
+// 主函数
+// ============================================================
+/**
+ * 通过 BFS + hyperedge 扩展检索与问题相关的图谱上下文
+ *
+ * @param questionText - 用户问题文本
+ * @param engine - GraphQueryEngine 实例
+ * @param options - 检索选项（budget、depth）
+ * @returns GraphContext（含 bfsNodes、hyperedges、fallbackMode）
+ */
+export function retrieveGraphContext(questionText, engine, options) {
+    const budget = options?.budget ?? 20;
+    const depth = options?.depth ?? 2;
+    // Step 1：BFS 关键词子图检索
+    const queryResult = engine.query(questionText, { budget, mode: 'bfs', depth });
+    const bfsNodes = queryResult.nodes.map((n) => ({
+        id: n.id,
+        label: n.label,
+        kind: n.kind,
+        specPath: n.metadata['specPath'],
+    }));
+    // Step 2：hyperedge 扩展（两种命中方式）
+    // 方式 1：按 label 子串模糊匹配（问题含流程名时适用）
+    // 截取问题前 30 字符作为 label 搜索词
+    const labelQuery = questionText.slice(0, 30).trim();
+    const heByLabel = labelQuery.length > 0
+        ? engine.getHyperedges({ label: labelQuery })
+        : [];
+    // 方式 2：按已命中的 BFS 节点 ID 精确匹配（最多取前 5 个种子节点）
+    const heByNode = [];
+    for (const bfsNode of bfsNodes.slice(0, 5)) {
+        const hes = engine.getHyperedges({ nodeId: bfsNode.id });
+        heByNode.push(...hes);
+    }
+    // 合并去重（按 hyperedge.id 去重）
+    const allHyperedges = dedup([...heByLabel, ...heByNode], (he) => he.id);
+    // fallback 判断：BFS 命中 < 3 节点时降级为纯 RAG（R1 / FR-014）
+    const fallbackMode = bfsNodes.length < 3 ? 'rag-only' : undefined;
+    return {
+        bfsNodes,
+        topChunks: [], // 由 rag-reranker 填充
+        hyperedges: allHyperedges,
+        fallbackMode,
+    };
+}
+//# sourceMappingURL=graph-retriever.js.map

package/dist/panoramic/qa/graph-retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-retriever.js","sourceRoot":"","sources":["../../../src/panoramic/qa/graph-retriever.ts"],"names":[],"mappings":"AA0BA,+DAA+D;AAC/D,OAAO;AACP,+DAA+D;AAE/D;;GAEG;AACH,SAAS,KAAK,CAAI,GAAQ,EAAE,KAA0B;IACpD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAQ,EAAE,CAAC;IACvB,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+DAA+D;AAC/D,MAAM;AACN,+DAA+D;AAE/D;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,YAAoB,EACpB,MAAwB,EACxB,OAA+B;IAE/B,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;IAElC,qBAAqB;IACrB,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/E,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7C,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,QAAQ,EAAG,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAwB;KACzD,CAAC,CAAC,CAAC;IAEJ,8BAA8B;IAE9B,iCAAiC;IACjC,0BAA0B;IAC1B,MAAM,UAAU,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,MAAM,SAAS,GAAgB,UAAU,CAAC,MAAM,GAAG,CAAC;QAClD,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAC7C,CAAC,CAAC,EAAE,CAAC;IAEP,0CAA0C;IAC1C,MAAM,QAAQ,GAAgB,EAAE,CAAC;IACjC,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,MAAM,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QACzD,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,0BAA0B;IAC1B,MAAM,aAAa,GAAG,KAAK,CAAC,CAAC,GAAG,SAAS,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAExE,kDAAkD;IAClD,MAAM,YAAY,GAChB,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IAE/C,OAAO;QACL,QAAQ;QACR,SAAS,EAAE,EAAE,EAAE,oBAAoB;QACnC,UAAU,EAAE,aAAa;QACzB,YAAY;KACb,CAAC;AACJ,CAAC"}

package/dist/panoramic/qa/index.d.ts

@@ -0,0 +1,23 @@
+import type { QnAQuery, QnAAnswer, QnAOptions } from './types.js';
+/**
+ * 测试专用：清除引擎缓存
+ */
+export declare function clearEngineCache(): void;
+/**
+ * 自然语言问答 — 公开 API
+ *
+ * 7 步 pipeline：
+ * 1-2. GraphRetriever：BFS 候选节点 + hyperedge 扩展
+ * 3.   RAGReranker：chunk 切分 + embedding 精排
+ * 4.   DebtContext：债务上下文注入（按关键词路由）
+ * 5.   Citation：构建溯源引用列表
+ * 6.   PromptBuilder：组装 LLM prompt
+ * 7.   LLMCaller：budget-gate + Anthropic SDK 调用
+ *
+ * @param query - 用户问题（含 text + 可选 focusNodeId）
+ * @param options - 问答选项（projectRoot 等）
+ * @returns QnAAnswer（含 text、citations、tokenUsage、durationMs）
+ * @throws InvalidQueryError 当 query.text 为空字符串时
+ */
+export declare function answerQuestion(query: QnAQuery, options: QnAOptions): Promise<QnAAnswer>;
+//# sourceMappingURL=index.d.ts.map

package/dist/panoramic/qa/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/panoramic/qa/index.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA+BlE;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,SAAS,CAAC,CA8KpB"}

package/dist/panoramic/qa/index.js

@@ -0,0 +1,201 @@
+/**
+ * qa/index.ts
+ * 公开 API 汇聚点：answerQuestion()
+ *
+ * 职责：
+ * - 入参校验（空字符串拒绝、> 2000 字符截断）
+ * - 空图谱检查（nodes.length === 0 时返回友好提示）
+ * - 串联 7 步 pipeline：
+ *   Step 1-2：graph-retriever（BFS + hyperedge 扩展）
+ *   Step 3：rag-reranker（chunk 切分 + embedding 精排）
+ *   Step 4：debt-context（债务上下文注入）
+ *   Step 5：citation（Citation 构建 + lineRange 验证）
+ *   Step 6：prompt-builder（LLM prompt 组装）
+ *   Step 7：llm-caller（budget-gate + Anthropic SDK 调用）
+ * - 结构化日志（F-015 LOW）：BFS 命中数、fallbackMode、各步耗时、总 durationMs
+ */
+import { GraphQueryEngine } from '../graph/graph-query.js';
+import { resolveGraphJsonPath } from '../graph/graph-paths.js';
+import { retrieveGraphContext } from './graph-retriever.js';
+import { rerankWithEmbedding } from './rag-reranker.js';
+import { injectDebtContext } from './debt-context.js';
+import { buildCitations } from './citation.js';
+import { buildQnAPrompt } from './prompt-builder.js';
+import { callQnALlm } from './llm-caller.js';
+// ============================================================
+// 常量
+// ============================================================
+/** 问题最大字符数，超出时截断 */
+const MAX_QUERY_LENGTH = 2000;
+// ============================================================
+// 引擎缓存（模块级，按 projectRoot 缓存，避免重复加载 graph.json）
+// ============================================================
+const engineCache = new Map();
+/**
+ * 获取 GraphQueryEngine 实例（按 projectRoot 缓存）
+ * 图谱文件不存在时抛出 Error（明确告知用户需要先生成图谱）
+ */
+function getEngine(projectRoot, graphJsonPath) {
+    const graphPath = graphJsonPath ?? resolveGraphJsonPath(projectRoot);
+    const cacheKey = graphPath;
+    let engine = engineCache.get(cacheKey);
+    if (!engine) {
+        engine = GraphQueryEngine.loadFromFile(graphPath);
+        engineCache.set(cacheKey, engine);
+    }
+    return engine;
+}
+/**
+ * 测试专用：清除引擎缓存
+ */
+export function clearEngineCache() {
+    engineCache.clear();
+}
+// ============================================================
+// 主函数
+// ============================================================
+/**
+ * 自然语言问答 — 公开 API
+ *
+ * 7 步 pipeline：
+ * 1-2. GraphRetriever：BFS 候选节点 + hyperedge 扩展
+ * 3.   RAGReranker：chunk 切分 + embedding 精排
+ * 4.   DebtContext：债务上下文注入（按关键词路由）
+ * 5.   Citation：构建溯源引用列表
+ * 6.   PromptBuilder：组装 LLM prompt
+ * 7.   LLMCaller：budget-gate + Anthropic SDK 调用
+ *
+ * @param query - 用户问题（含 text + 可选 focusNodeId）
+ * @param options - 问答选项（projectRoot 等）
+ * @returns QnAAnswer（含 text、citations、tokenUsage、durationMs）
+ * @throws InvalidQueryError 当 query.text 为空字符串时
+ */
+export async function answerQuestion(query, options) {
+    const t0 = Date.now();
+    // ── 入参校验 ──────────────────────────────────────────────
+    // Edge Case 3：空字符串查询直接拒绝
+    if (!query.text || query.text.trim().length === 0) {
+        throw new Error('问题不能为空，请提供有效的查询文本');
+    }
+    // Edge Case 4：> 2000 字符截断并 warn
+    let questionText = query.text;
+    if (questionText.length > MAX_QUERY_LENGTH) {
+        console.warn(`[warn] qa/index: 问题文本超过 ${MAX_QUERY_LENGTH} 字符，已截断为前 ${MAX_QUERY_LENGTH} 字符。` +
+            `原始长度：${questionText.length}`);
+        questionText = questionText.slice(0, MAX_QUERY_LENGTH);
+    }
+    const { projectRoot, graphJsonPath, bfsBudget, bfsDepth, similarityThreshold } = options;
+    // ── 加载图谱引擎 ──────────────────────────────────────────
+    let engine;
+    try {
+        engine = getEngine(projectRoot, graphJsonPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[warn] qa/index: 图谱加载失败，返回空图谱提示。原因：${message}`);
+        return {
+            text: '图谱为空或无法加载，无法回答该问题。请先运行 `spectra graph` 生成图谱。',
+            citations: [],
+            tokenUsage: { input: 0, output: 0, overBudget: false },
+            durationMs: Date.now() - t0,
+            fallbackMode: 'graph-insufficient',
+        };
+    }
+    // ── Step 1-2：Graph BFS + hyperedge 扩展 ─────────────────
+    const t1 = Date.now();
+    const graphCtx = retrieveGraphContext(questionText, engine, {
+        budget: bfsBudget,
+        depth: bfsDepth,
+    });
+    const retrieverMs = Date.now() - t1;
+    // Edge Case 1：空图谱（BFS 命中 0 节点）
+    if (graphCtx.bfsNodes.length === 0) {
+        console.info(`[info] qa: 图谱为空，bfs_hits=0, duration_retriever=${retrieverMs}ms, total=${Date.now() - t0}ms`);
+        return {
+            text: '图谱为空，无法回答该问题。图谱可能尚未生成或不包含任何节点。',
+            citations: [],
+            tokenUsage: { input: 0, output: 0, overBudget: false },
+            durationMs: Date.now() - t0,
+            fallbackMode: graphCtx.fallbackMode,
+        };
+    }
+    // 结构化日志：BFS 命中数和 fallbackMode
+    console.info(`[info] qa: bfs_hits=${graphCtx.bfsNodes.length}, ` +
+        `hyperedges=${graphCtx.hyperedges.length}, ` +
+        `fallback=${graphCtx.fallbackMode ?? 'none'}, ` +
+        `retriever_ms=${retrieverMs}`);
+    // ── Step 3：RAG embedding 精排 ────────────────────────────
+    const t2 = Date.now();
+    // 收集 BFS 节点对应的 spec 文件路径（过滤无 specPath 的节点）
+    const specPaths = graphCtx.bfsNodes
+        .filter((n) => !!n.specPath)
+        .map((n) => n.specPath)
+        // 去重
+        .filter((p, i, arr) => arr.indexOf(p) === i);
+    const rerankResult = await rerankWithEmbedding(graphCtx, specPaths, questionText, projectRoot, { similarityThreshold });
+    const embeddingMs = Date.now() - t2;
+    // 将精排结果合并到 graphCtx.topChunks（供下游使用）
+    graphCtx.topChunks = rerankResult.rankedChunks.map((r) => ({
+        chunk: r.chunk,
+        similarity: r.similarity,
+    }));
+    // 若 rag-reranker 降级为 bfs-only，更新 fallbackMode
+    if (rerankResult.fallbackMode === 'bfs-only') {
+        graphCtx.fallbackMode = 'bfs-only';
+    }
+    console.info(`[info] qa: embedding_chunks=${rerankResult.rankedChunks.length}, embedding_ms=${embeddingMs}`);
+    // W-002：BFS 候选节点不足 3 个（rag-only 降级）且 RAG 精排 0 个 chunk 时，二级降级
+    if (graphCtx.fallbackMode === 'rag-only' && rerankResult.rankedChunks.length === 0) {
+        return {
+            text: '图谱数据不足以回答此问题：BFS 命中候选节点不足 3 个，且 RAG 精排未命中任何相关 spec 片段。请尝试更具体的问题或运行 `spectra batch` 补充图谱数据。',
+            citations: [],
+            tokenUsage: { input: 0, output: 0, overBudget: false },
+            durationMs: Date.now() - t0,
+            fallbackMode: 'rag-only',
+        };
+    }
+    // ── Step 4：debt 上下文注入 ───────────────────────────────
+    // 注意：scanProjectDebt 需要 registry，但 QnAOptions 未提供
+    // 此处传入 null registry，injectDebtContext 中有 try/catch 保护
+    // plan §7 说明：F5 问答仅需 AST 扫描，registry 不参与债务扫描的核心逻辑
+    const debtResult = await injectDebtContext(questionText, projectRoot, 
+    // registry 设为 undefined cast，scanProjectDebt 内部 dryRun=true 时不依赖 registry
+    undefined);
+    // ── Step 5：Citation 构建 ─────────────────────────────────
+    const citations = buildCitations(rerankResult, graphCtx, debtResult.citations, projectRoot);
+    // ── Step 6：LLM prompt 组装 ───────────────────────────────
+    const prompt = buildQnAPrompt(graphCtx, citations, questionText);
+    // ── Step 7：LLM 调用 ──────────────────────────────────────
+    const t3 = Date.now();
+    let llmResult;
+    try {
+        llmResult = await callQnALlm(prompt);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[error] qa/index: LLM 调用失败。原因：${message}`);
+        throw new Error(`问答 LLM 调用失败：${message}`);
+    }
+    const llmMs = Date.now() - t3;
+    const totalMs = Date.now() - t0;
+    console.info(`[info] qa: llm_ms=${llmMs}, total_ms=${totalMs}, ` +
+        `input_tokens=${llmResult.tokenUsage.input}, output_tokens=${llmResult.tokenUsage.output}, ` +
+        `over_budget=${llmResult.tokenUsage.overBudget}`);
+    // ── 合并 citations：优先使用 LLM 解析的 citations，若为空则用构建的 citations ──
+    const finalCitations = llmResult.parsedCitations.length > 0
+        ? llmResult.parsedCitations
+        : citations;
+    // W-004：finalCitations 为空且 answer 中未包含"图谱数据不足"时，加注无引用警告
+    let answerText = llmResult.answer;
+    if (finalCitations.length === 0 && !answerText.includes('图谱数据不足')) {
+        answerText = '[注意：本答案无引用，图谱数据可能不足]\n\n' + answerText;
+    }
+    return {
+        text: answerText,
+        citations: finalCitations,
+        tokenUsage: llmResult.tokenUsage,
+        durationMs: totalMs,
+        fallbackMode: graphCtx.fallbackMode,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/panoramic/qa/index.js.map

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

package/dist/panoramic/qa/llm-caller.d.ts

@@ -0,0 +1,35 @@
+import type { Citation } from './types.js';
+import type { QnAPrompt } from './prompt-builder.js';
+/** LLM 调用选项 */
+export interface QnALlmOptions {
+    /** 最大输出 token 数（默认 2048） */
+    maxTokens?: number;
+    /** 采样温度（默认 0.3） */
+    temperature?: number;
+    /** 超时毫秒（默认 60_000） */
+    timeoutMs?: number;
+}
+/** LLM 调用结果 */
+export interface QnALlmResult {
+    /** 回答文本（来自 LLM 响应的 answer 字段） */
+    answer: string;
+    /** 从 LLM 响应解析出的 citations */
+    parsedCitations: Citation[];
+    /** token 使用记录 */
+    tokenUsage: {
+        input: number;
+        output: number;
+        /** true = 超过 hardcode 上限（record-only，不阻断） */
+        overBudget: boolean;
+    };
+}
+/**
+ * 调用 LLM 完成问答
+ *
+ * @param prompt - buildQnAPrompt 输出的 { systemPrompt, userPrompt }
+ * @param options - 调用选项（maxTokens、temperature、timeoutMs）
+ * @returns QnALlmResult（含 answer、parsedCitations、tokenUsage）
+ * @throws LLM 调用失败时抛出 Error（不吞掉异常，由 index.ts 处理）
+ */
+export declare function callQnALlm(prompt: QnAPrompt, options?: QnALlmOptions): Promise<QnALlmResult>;
+//# sourceMappingURL=llm-caller.d.ts.map

package/dist/panoramic/qa/llm-caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-caller.d.ts","sourceRoot":"","sources":["../../../src/panoramic/qa/llm-caller.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAiBrD,eAAe;AACf,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAe;AACf,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,eAAe,EAAE,QAAQ,EAAE,CAAC;IAC5B,iBAAiB;IACjB,UAAU,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,6CAA6C;QAC7C,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;CACH;AAsDD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAoEvB"}

package/dist/panoramic/qa/llm-caller.js

@@ -0,0 +1,138 @@
+/**
+ * qa/llm-caller.ts
+ * Step 7：Budget-gate 注入 + Anthropic SDK 调用
+ *
+ * 职责：
+ * - 用 estimateFast() 预估 token 消耗
+ * - 调用 runBudgetGate({ budget: Infinity, preset: 'continue' }) 实现 record-only 模式（Q2 / FR-017）
+ *   - budget = Infinity 保证永不触发阻断
+ *   - 超额判断：若 totalEstimate > HARDCODE_LIMIT_TOKENS，标记 overBudget=true 并记录 warn
+ * - 调用 Anthropic SDK messages.create()（模型 ID 从项目配置读取，不硬编码）
+ * - 解析响应：提取 answer + citations + tokenUsage
+ *
+ * 注意：HARDCODE_LIMIT_TOKENS 约为 $0.05/query：
+ *   claude-sonnet 输入约 $3/1M tokens → $0.05 / $0.000003 ≈ 16,666 input tokens
+ *   加上 ~3,333 output tokens（~$10/1M × $0.05 / $0.00001）
+ *   这里保守取 5k input + 1k output = ~6000 tokens 作为提示性 hardcode 上限
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import { estimateFast } from '../../core/token-counter.js';
+import { runBudgetGate } from '../../batch/budget-gate.js';
+import { resolveReverseSpecModel } from '../../core/model-selection.js';
+// ============================================================
+// 常量
+// ============================================================
+/**
+ * 单次问答 token 消耗的 hardcode 上限（约 $0.05/query）
+ * 以 claude-sonnet input $3/1M 计算：$0.05 / $0.000003 ≈ 16,666 input tokens
+ * 此处保守取较小值（5000 + 1000 = 6000 tokens）触发 warn 提示
+ */
+const HARDCODE_LIMIT_TOKENS = 6000;
+// ============================================================
+// 响应解析
+// ============================================================
+/**
+ * 从 LLM 返回的文本中解析 QnA JSON 结果
+ * 容错：JSON 解析失败时返回 answer=rawText, citations=[]
+ */
+function parseLlmResponse(rawText) {
+    // 尝试从 markdown 代码块中提取 JSON
+    const jsonMatch = rawText.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    const jsonStr = jsonMatch ? jsonMatch[1] : rawText.trim();
+    try {
+        const parsed = JSON.parse(jsonStr ?? rawText.trim());
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            'answer' in parsed &&
+            typeof parsed['answer'] === 'string') {
+            const obj = parsed;
+            const answer = String(obj['answer']);
+            const rawCitations = Array.isArray(obj['citations']) ? obj['citations'] : [];
+            // 解析 citations 数组
+            const citations = rawCitations
+                .filter((c) => typeof c === 'object' && c !== null)
+                .map((c) => ({
+                specPath: String(c['specPath'] ?? ''),
+                lineRange: {
+                    startLine: typeof c['startLine'] === 'number' ? c['startLine'] : 0,
+                    endLine: typeof c['endLine'] === 'number' ? c['endLine'] : 0,
+                },
+                excerpt: String(c['excerpt'] ?? ''),
+            }));
+            return { answer, citations };
+        }
+    }
+    catch {
+        // JSON 解析失败：将原始文本作为 answer 返回
+    }
+    return { answer: rawText.trim(), citations: [] };
+}
+// ============================================================
+// 主函数
+// ============================================================
+/**
+ * 调用 LLM 完成问答
+ *
+ * @param prompt - buildQnAPrompt 输出的 { systemPrompt, userPrompt }
+ * @param options - 调用选项（maxTokens、temperature、timeoutMs）
+ * @returns QnALlmResult（含 answer、parsedCitations、tokenUsage）
+ * @throws LLM 调用失败时抛出 Error（不吞掉异常，由 index.ts 处理）
+ */
+export async function callQnALlm(prompt, options) {
+    const maxTokens = options?.maxTokens ?? 2048;
+    const temperature = options?.temperature ?? 0.3;
+    const timeoutMs = options?.timeoutMs ?? 60_000;
+    // ── Step 7a：budget gate（record-only 模式）────────────────
+    const inputEstimate = estimateFast(prompt.userPrompt + prompt.systemPrompt);
+    const outputEstimate = Math.round(inputEstimate * 0.3);
+    const totalEstimate = inputEstimate + outputEstimate;
+    // budget = Infinity 保证永不触发阻断（record-only 语义）
+    await runBudgetGate({
+        baseEstimate: totalEstimate,
+        budget: Infinity,
+        preset: 'continue',
+        isTTY: false,
+    });
+    // 超额判断：超过 hardcode 上限时记录 warn（不阻断）
+    const overBudget = totalEstimate > HARDCODE_LIMIT_TOKENS;
+    if (overBudget) {
+        console.warn(`[warn] qna token cost over hardcode limit, recorded only. ` +
+            `estimate=${totalEstimate} tokens, limit=${HARDCODE_LIMIT_TOKENS} tokens`);
+    }
+    // ── Step 7b：从项目配置读取模型 ID（不硬编码）─────────────
+    const modelId = resolveReverseSpecModel().model;
+    // ── Step 7c：Anthropic SDK 调用──────────────────────────
+    const client = new Anthropic({
+        apiKey: process.env['ANTHROPIC_API_KEY'],
+        timeout: timeoutMs,
+    });
+    const response = await client.messages.create({
+        model: modelId,
+        max_tokens: maxTokens,
+        temperature,
+        system: prompt.systemPrompt,
+        messages: [{ role: 'user', content: prompt.userPrompt }],
+    });
+    // ── Step 7d：提取文本内容 ──────────────────────────────
+    const rawText = response.content
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('\n');
+    // 实际 token 使用量（来自 API 响应）
+    const actualInput = response.usage?.input_tokens ?? inputEstimate;
+    const actualOutput = response.usage?.output_tokens ?? outputEstimate;
+    const actualTotal = actualInput + actualOutput;
+    const actualOverBudget = overBudget || actualTotal > HARDCODE_LIMIT_TOKENS;
+    // ── Step 7e：解析响应结构 ─────────────────────────────
+    const { answer, citations } = parseLlmResponse(rawText);
+    return {
+        answer,
+        parsedCitations: citations,
+        tokenUsage: {
+            input: actualInput,
+            output: actualOutput,
+            overBudget: actualOverBudget,
+        },
+    };
+}
+//# sourceMappingURL=llm-caller.js.map

package/dist/panoramic/qa/llm-caller.js.map

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