spectra-cli 4.1.1

package/dist/panoramic/qa/prompt-builder.d.ts

@@ -0,0 +1,36 @@
+/**
+ * qa/prompt-builder.ts
+ * Step 6：LLM prompt 组装
+ *
+ * 职责：
+ * - 将 GraphContext + Citation 列表 + 问题文本组装为 LLM 可用的 prompt
+ * - 在 system prompt 中要求 LLM 100% 引用 citation（FR-012）
+ * - 在 user prompt 中显式列出 hyperedge.label 候选（R3 缓解：让 LLM 挑选而非发散）
+ * - citation 内联格式：[来源：path:startLine-endLine]
+ *
+ * 输出：{ systemPrompt, userPrompt }（分离 system/user 便于 Anthropic SDK messages 格式）
+ */
+import type { GraphContext, Citation } from './types.js';
+/** prompt-builder 的输入选项 */
+export interface PromptBuildOptions {
+    /** 是否在 prompt 中包含债务上下文（默认 true） */
+    includeDebtContext?: boolean;
+}
+/** prompt-builder 的输出 */
+export interface QnAPrompt {
+    /** 系统 prompt（Anthropic SDK 的 system 参数） */
+    systemPrompt: string;
+    /** 用户 prompt（messages 数组中 user 角色的 content） */
+    userPrompt: string;
+}
+/**
+ * 组装问答 LLM prompt
+ *
+ * @param graphCtx - graph-retriever 的输出（含 bfsNodes + hyperedges）
+ * @param citations - 所有来源的 Citation 列表（RAG + Graph + Debt + Hyperedge）
+ * @param questionText - 用户原始问题文本
+ * @param options - 选项
+ * @returns QnAPrompt（systemPrompt + userPrompt）
+ */
+export declare function buildQnAPrompt(graphCtx: GraphContext, citations: Citation[], questionText: string, options?: PromptBuildOptions): QnAPrompt;
+//# sourceMappingURL=prompt-builder.d.ts.map

package/dist/panoramic/qa/prompt-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-builder.d.ts","sourceRoot":"","sources":["../../../src/panoramic/qa/prompt-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAMzD,2BAA2B;AAC3B,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,yBAAyB;AACzB,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;CACpB;AAsED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,QAAQ,EAAE,EACrB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,SAAS,CAkFX"}

package/dist/panoramic/qa/prompt-builder.js

@@ -0,0 +1,143 @@
+// ============================================================
+// 辅助函数
+// ============================================================
+/**
+ * 将 Citation 格式化为内联引用文本
+ * 格式：[来源：path:startLine-endLine]
+ */
+function formatCitationInline(citation) {
+    const { specPath, lineRange } = citation;
+    if (specPath === '[graph hyperedge]') {
+        return '[来源：graph-hyperedge]';
+    }
+    return `[来源：${specPath}:${lineRange.startLine}-${lineRange.endLine}]`;
+}
+/**
+ * 格式化单条 Citation 为提示上下文块
+ */
+function formatCitationBlock(citation, index) {
+    const inline = formatCitationInline(citation);
+    const lines = [];
+    lines.push(`### 引用 ${index + 1} ${inline}`);
+    if (citation.excerpt) {
+        lines.push('');
+        lines.push('```');
+        lines.push(citation.excerpt.slice(0, 500));
+        lines.push('```');
+    }
+    return lines.join('\n');
+}
+/**
+ * 格式化 BFS 节点元数据为摘要列表
+ */
+function formatBfsNodesSummary(bfsNodes) {
+    if (bfsNodes.length === 0)
+        return '（无相关节点）';
+    return bfsNodes
+        .slice(0, 15)
+        .map((n) => `- ${n.label}（kind: ${n.kind}, id: ${n.id}）`)
+        .join('\n');
+}
+/**
+ * 格式化 hyperedge 候选列表（R3 缓解：让 LLM 从列表中选而非自由发散）
+ */
+function formatHyperedgeCandidates(hyperedges) {
+    if (hyperedges.length === 0)
+        return '（无超边数据）';
+    return hyperedges
+        .slice(0, 10)
+        .map((he) => {
+        const nodesPreview = he.nodes.slice(0, 3).join(', ');
+        const moreHint = he.nodes.length > 3 ? ` ...（共 ${he.nodes.length} 个节点）` : '';
+        return `- [${he.label}]：${he.rationale.slice(0, 100)}。涉及节点：${nodesPreview}${moreHint}`;
+    })
+        .join('\n');
+}
+// ============================================================
+// 主函数
+// ============================================================
+/**
+ * 组装问答 LLM prompt
+ *
+ * @param graphCtx - graph-retriever 的输出（含 bfsNodes + hyperedges）
+ * @param citations - 所有来源的 Citation 列表（RAG + Graph + Debt + Hyperedge）
+ * @param questionText - 用户原始问题文本
+ * @param options - 选项
+ * @returns QnAPrompt（systemPrompt + userPrompt）
+ */
+export function buildQnAPrompt(graphCtx, citations, questionText, options) {
+    // ── System prompt ──────────────────────────────────────────
+    const systemPrompt = `你是一个专业的代码库知识问答助手，基于知识图谱和文档内容回答问题。
+
+## 回答规则（严格遵守）
+
+1. **100% citation 覆盖要求（FR-012）**：回答中的每一个关键论断都必须附上溯源引用。
+   - 引用格式：[来源：path:startLine-endLine]
+   - 每个关键论断之后必须立即跟随至少一个 [来源：...] 引用
+   - 禁止出现没有引用支撑的推测性论断
+
+2. **仅基于提供的上下文回答**：不得凭借通用知识推断未在上下文中出现的内容。
+
+3. **如果上下文不足以回答问题**：明确说明"根据当前图谱数据无法回答该问题"，不要编造答案。
+
+4. **hyperedge 超边候选列表**：若问题涉及跨模块流程，请从下方的超边候选列表中选择最相关的项目，
+   不要自行创造不在列表中的流程名称（R3 缓解）。
+
+## 输出格式
+
+请以 JSON 格式返回结果：
+\`\`\`json
+{
+  "answer": "回答文本（含内联 [来源：...] 引用）",
+  "citations": [
+    {
+      "specPath": "引用的文件路径（或 [graph hyperedge]）",
+      "startLine": 行号数字,
+      "endLine": 行号数字,
+      "excerpt": "原文摘要（最多 200 字符）"
+    }
+  ]
+}
+\`\`\``;
+    // ── User prompt ────────────────────────────────────────────
+    const parts = [];
+    // 1. 用户问题
+    parts.push('## 用户问题');
+    parts.push('');
+    parts.push(questionText);
+    parts.push('');
+    // 2. 相关节点摘要
+    parts.push('## 相关代码节点（BFS 检索结果）');
+    parts.push('');
+    parts.push(formatBfsNodesSummary(graphCtx.bfsNodes));
+    parts.push('');
+    // 3. hyperedge 超边候选列表（R3 缓解：显式列出，让 LLM 挑选）
+    parts.push('## 超边候选列表（跨模块流程）');
+    parts.push('');
+    parts.push(formatHyperedgeCandidates(graphCtx.hyperedges));
+    parts.push('');
+    // 4. 参考文档摘要（Citation 列表）
+    if (citations.length > 0) {
+        parts.push('## 参考文档摘要（用于回答和 citation）');
+        parts.push('');
+        citations.forEach((citation, idx) => {
+            parts.push(formatCitationBlock(citation, idx));
+            parts.push('');
+        });
+    }
+    else {
+        parts.push('## 参考文档摘要');
+        parts.push('');
+        parts.push('（无可用文档摘要，请根据节点元数据回答，并注明数据来源有限）');
+        parts.push('');
+    }
+    // 5. 降级提示（当 fallbackMode 存在时）
+    if (graphCtx.fallbackMode) {
+        parts.push(`> 注意：当前处于 ${graphCtx.fallbackMode} 降级模式，图谱检索结果有限，回答可能不完整。`);
+        parts.push('');
+    }
+    parts.push('请基于以上上下文，按 JSON 格式回答用户问题。回答中每个关键论断后面必须附上对应的 [来源：...] 引用。');
+    const userPrompt = parts.join('\n');
+    return { systemPrompt, userPrompt };
+}
+//# sourceMappingURL=prompt-builder.js.map

package/dist/panoramic/qa/prompt-builder.js.map

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

package/dist/panoramic/qa/rag-reranker.d.ts

@@ -0,0 +1,43 @@
+import type { EmbeddingProvider } from '../anchoring/embedding-provider.js';
+import type { DocChunk } from '../anchoring/chunker.js';
+import type { GraphContext } from './types.js';
+/** Top-K 精排结果单元 */
+export interface RankedChunk {
+    /** 对应的 DocChunk 对象（含 filePath, startLine, endLine, text） */
+    chunk: DocChunk;
+    /** 余弦相似度得分 */
+    similarity: number;
+    /** 对应节点 ID（来自 filterByThreshold 的 nodeId 字段） */
+    nodeId: string;
+}
+/** rag-reranker 的输入选项 */
+export interface RerankOptions {
+    /** embedding 精排相似度阈值（默认 0.70） */
+    similarityThreshold?: number;
+    /** Top-K 截断数量（默认 10） */
+    topK?: number;
+}
+/** rag-reranker 的输出结果 */
+export interface RerankResult {
+    /** Top-K 精排后的 chunk 列表（按 similarity 降序） */
+    rankedChunks: RankedChunk[];
+    /** 降级模式：embedding 加载失败时设为 bfs-only */
+    fallbackMode?: 'bfs-only';
+}
+/**
+ * 测试专用：注入 mock embedding provider（覆盖模块级缓存）
+ * @param provider - mock 实现；传 null 时重置缓存
+ */
+export declare function setEmbeddingProviderForTesting(provider: EmbeddingProvider | null): void;
+/**
+ * 对候选节点对应的 spec 文件做 chunk 切分 + embedding 精排
+ *
+ * @param graphCtx - graph-retriever 输出的图谱上下文（含 bfsNodes）
+ * @param specPaths - 候选节点对应的 spec 文件绝对路径列表
+ * @param questionText - 用户问题文本（用于 query embedding）
+ * @param projectRoot - 项目根目录（用于计算 repo-relative 路径）
+ * @param options - 精排选项（threshold、topK）
+ * @returns RerankResult（含精排 chunks 和可选 fallbackMode）
+ */
+export declare function rerankWithEmbedding(graphCtx: GraphContext, specPaths: string[], questionText: string, projectRoot: string, options?: RerankOptions): Promise<RerankResult>;
+//# sourceMappingURL=rag-reranker.d.ts.map

package/dist/panoramic/qa/rag-reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-reranker.d.ts","sourceRoot":"","sources":["../../../src/panoramic/qa/rag-reranker.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM/C,mBAAmB;AACnB,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,KAAK,EAAE,QAAQ,CAAC;IAChB,cAAc;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yBAAyB;AACzB,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,yBAAyB;AACzB,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,sCAAsC;IACtC,YAAY,CAAC,EAAE,UAAU,CAAC;CAC3B;AAqBD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAEvF;AAMD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,MAAM,EAAE,EACnB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAyFvB"}

package/dist/panoramic/qa/rag-reranker.js

@@ -0,0 +1,129 @@
+/**
+ * qa/rag-reranker.ts
+ * Step 3：chunk 切分 + embedding 精排
+ *
+ * 职责：
+ * - 对候选节点对应的 spec 文件做 Markdown chunk 切分
+ * - 用 embedding provider 对 chunks 和问题做向量化
+ * - 通过 filterByThreshold 筛选 Top-K 最相关 chunks
+ * - embedding 加载失败时降级为 bfs-only（R2 缓解）
+ *
+ * 设计决策：
+ * - embedding provider 采用模块级 singleton（R2 缓解）：按环境配置复用同一实例，
+ *   避免每次问答重复初始化 @huggingface/transformers 模型（首次加载 5-15 秒）
+ */
+import { chunkMarkdownFiles } from '../anchoring/chunker.js';
+import { createEmbeddingProvider } from '../anchoring/providers/factory.js';
+import { filterByThreshold } from '../anchoring/similarity.js';
+// ============================================================
+// 模块级 singleton：按 providerName 缓存 embedding provider
+// ============================================================
+/** 模块级 embedding provider 缓存（R2 缓解：避免重复初始化） */
+let _cachedProvider = null;
+/**
+ * 获取 embedding provider（模块级 singleton 策略）
+ * 首次调用时初始化，后续复用同一实例
+ * 测试中可通过 setEmbeddingProviderForTesting() 注入 mock
+ */
+function getEmbeddingProvider() {
+    if (!_cachedProvider) {
+        _cachedProvider = createEmbeddingProvider();
+    }
+    return _cachedProvider;
+}
+/**
+ * 测试专用：注入 mock embedding provider（覆盖模块级缓存）
+ * @param provider - mock 实现；传 null 时重置缓存
+ */
+export function setEmbeddingProviderForTesting(provider) {
+    _cachedProvider = provider;
+}
+// ============================================================
+// 主函数
+// ============================================================
+/**
+ * 对候选节点对应的 spec 文件做 chunk 切分 + embedding 精排
+ *
+ * @param graphCtx - graph-retriever 输出的图谱上下文（含 bfsNodes）
+ * @param specPaths - 候选节点对应的 spec 文件绝对路径列表
+ * @param questionText - 用户问题文本（用于 query embedding）
+ * @param projectRoot - 项目根目录（用于计算 repo-relative 路径）
+ * @param options - 精排选项（threshold、topK）
+ * @returns RerankResult（含精排 chunks 和可选 fallbackMode）
+ */
+export async function rerankWithEmbedding(graphCtx, specPaths, questionText, projectRoot, options) {
+    const threshold = options?.similarityThreshold ?? 0.70;
+    const topK = options?.topK ?? 10;
+    // specPaths 为空时直接降级（无 spec 文件可精排）
+    if (specPaths.length === 0) {
+        return { rankedChunks: [] };
+    }
+    // Step 3a：Markdown chunk 切分
+    const chunks = chunkMarkdownFiles(specPaths, projectRoot);
+    if (chunks.length === 0) {
+        return { rankedChunks: [] };
+    }
+    // Step 3b：获取 embedding provider（singleton）
+    let provider;
+    try {
+        provider = getEmbeddingProvider();
+    }
+    catch (err) {
+        // embedding provider 初始化失败：降级为 bfs-only（R2）
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[warn] qa/rag-reranker: embedding provider 加载失败，降级为 bfs-only。原因：${message}`);
+        return { rankedChunks: [], fallbackMode: 'bfs-only' };
+    }
+    // Step 3c：批量 embed chunks + 问题
+    const chunkTexts = chunks.map((c) => c.text);
+    const allTexts = [...chunkTexts, questionText];
+    let allVectors;
+    try {
+        const embedResult = await provider.embed(allTexts);
+        allVectors = embedResult.vectors;
+    }
+    catch (err) {
+        // embed() 调用失败：降级为 bfs-only（R2）
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[warn] qa/rag-reranker: embedding 计算失败，降级为 bfs-only。原因：${message}`);
+        return { rankedChunks: [], fallbackMode: 'bfs-only' };
+    }
+    // 分离 chunk 向量和 query 向量（最后一个为 query）
+    const chunkVectors = allVectors.slice(0, chunks.length);
+    const queryVector = allVectors[chunks.length];
+    if (!queryVector) {
+        console.warn('[warn] qa/rag-reranker: 未能获取 query embedding 向量，降级为 bfs-only');
+        return { rankedChunks: [], fallbackMode: 'bfs-only' };
+    }
+    // Step 3d：以 query 为唯一代理节点，计算 chunk-query 相似度（单一排序维度）
+    // 使用 __query__ 作为虚拟节点 ID，避免 chunk × bfsNode 笛卡尔积的语义伪装
+    const nodeVectors = new Map();
+    nodeVectors.set('__query__', queryVector);
+    // Step 3e：filterByThreshold 筛选相似度达标的 pairs（按 chunk-query 相似度排序）
+    const pairs = filterByThreshold(chunkVectors, nodeVectors, threshold);
+    // Step 3f：将 pairs 映射到 RankedChunk，按 similarity 降序取 Top-K
+    // nodeId 来自 chunk.filePath 对应的 BFS 节点（通过 specPath 匹配）
+    // 匹配失败时保底使用第一个 bfsNode 的 id
+    const fallbackNodeId = graphCtx.bfsNodes[0]?.id ?? '__unknown__';
+    const topPairs = pairs.slice(0, topK);
+    const rankedChunks = topPairs
+        .map((pair) => {
+        const chunk = chunks[pair.chunkIndex];
+        if (!chunk)
+            return null;
+        // 按 specPath 匹配 chunk.filePath 来源所属的 BFS 节点
+        const matchedNode = graphCtx.bfsNodes.find((n) => n.specPath !== undefined && (
+        // 支持绝对路径和 repo-relative 路径两种情况
+        n.specPath === chunk.filePath ||
+            chunk.filePath.endsWith(n.specPath) ||
+            n.specPath.endsWith(chunk.filePath)));
+        return {
+            chunk,
+            similarity: pair.similarity,
+            nodeId: matchedNode?.id ?? fallbackNodeId,
+        };
+    })
+        .filter((item) => item !== null);
+    return { rankedChunks };
+}
+//# sourceMappingURL=rag-reranker.js.map

package/dist/panoramic/qa/rag-reranker.js.map

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

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

@@ -0,0 +1,126 @@
+/**
+ * F5 Reading UX 核心类型定义
+ * 包含 BatchMode、QnAQuery、QnAAnswer、Citation、GraphContext 等所有 F5 公开类型
+ */
+/**
+ * 批处理运行模式
+ * - full：完整文档（默认，行为与旧版等价）
+ * - reading：轻量模式，跳过产品文档层生成器
+ * - code-only：纯 AST 模式，跳过所有 LLM 推断步骤
+ */
+export type BatchMode = 'full' | 'reading' | 'code-only';
+/**
+ * 用户提交的自然语言问题（单轮无状态）
+ */
+export interface QnAQuery {
+    /** 问题文本（不允许空字符串，> 2000 字符时截断） */
+    text: string;
+    /** 可选：提示查询聚焦的模块名或节点 ID */
+    focusNodeId?: string;
+}
+/**
+ * 溯源引用单元
+ */
+export interface Citation {
+    /** repo-relative spec 文件路径 */
+    specPath: string;
+    /** 行区间（1-based，含边界） */
+    lineRange: {
+        startLine: number;
+        endLine: number;
+    };
+    /** 原文摘要（buildEvidenceText 截断到 200 字符） */
+    excerpt: string;
+    /** 对应 graph 节点 ID（可选，hyperedge citation 可能无对应节点） */
+    nodeId?: string;
+    /** 余弦相似度得分（RAG 精排路径下填充） */
+    similarity?: number;
+}
+/**
+ * 问答 B+C 混合架构中间态
+ */
+export interface GraphContext {
+    /** BFS 命中的候选节点列表 */
+    bfsNodes: Array<{
+        id: string;
+        label: string;
+        kind: string;
+        specPath?: string;
+    }>;
+    /** embedding 精排后的 Top-K chunk 列表 */
+    topChunks: Array<{
+        chunk: import('../anchoring/chunker.js').DocChunk;
+        similarity: number;
+    }>;
+    /** F4 hyperedge 关联信息 */
+    hyperedges: Array<import('../graph/graph-types.js').Hyperedge>;
+    /** BFS 降级模式标识 */
+    fallbackMode?: 'rag-only' | 'bfs-only' | 'graph-insufficient';
+}
+/**
+ * 问答预算配置（record-only 模式，不阻断）
+ */
+export interface QnABudgetConfig {
+    /** hardcode 单次上限：约 $0.05/query（估算 5k input + 1k output tokens） */
+    readonly hardcodeLimitUsd: 0.05;
+    /** 超额时行为：仅记账不阻断 */
+    readonly onOverLimit: 'record-only';
+}
+/**
+ * 问答选项
+ */
+export interface QnAOptions {
+    /** 项目根目录 */
+    projectRoot: string;
+    /** 图谱数据路径（默认从 projectRoot 推断） */
+    graphJsonPath?: string;
+    /** BFS 节点预算（默认 20） */
+    bfsBudget?: number;
+    /** BFS 遍历深度（默认 2） */
+    bfsDepth?: number;
+    /** embedding 精排相似度阈值（默认 0.70） */
+    similarityThreshold?: number;
+    /** budget 配置（使用 QnABudgetConfig 默认值） */
+    budgetConfig?: Partial<QnABudgetConfig>;
+}
+/**
+ * 问答结果
+ */
+export interface QnAAnswer {
+    /** 回答文本 */
+    text: string;
+    /** 溯源引用列表（100% 覆盖率要求） */
+    citations: Citation[];
+    /** LLM token 使用记录 */
+    tokenUsage: {
+        input: number;
+        output: number;
+        /** 超额时标记为 true，不阻断调用 */
+        overBudget: boolean;
+    };
+    /** 处理耗时（ms） */
+    durationMs: number;
+    /** 降级模式（如有） */
+    fallbackMode?: GraphContext['fallbackMode'];
+}
+/**
+ * graph.html 生成配置
+ */
+export interface GraphHtmlOptions {
+    /** force layout 启停阈值（< 2000 启用，≥ 2000 切静态） */
+    readonly forceLayoutThreshold: 2000;
+    /** 是否渲染 hyperedge 凸包层（默认 true） */
+    showHyperedges?: boolean;
+    /** 是否启用搜索框（默认 true） */
+    enableSearch?: boolean;
+    /** 是否启用节点点击跳转 spec 文件（默认 true） */
+    enableJumpToSpec?: boolean;
+    /** 文件体积警告阈值（字节，默认 5 MB = 5 * 1024 * 1024） */
+    fileSizeWarnThreshold?: number;
+    /**
+     * 节点总数（含 enrichedNodes 注入后的最终值）。Feature 140 T19 用于决定是否注入
+     * "极小图"banner（节点数 < 3 时）。未传时不显示 banner，与旧版兼容。
+     */
+    nodeCount?: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/panoramic/qa/types.js

@@ -0,0 +1,6 @@
+/**
+ * F5 Reading UX 核心类型定义
+ * 包含 BatchMode、QnAQuery、QnAAnswer、Citation、GraphContext 等所有 F5 公开类型
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/panoramic/qa/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/panoramic/query.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Panoramic Query Helper
+ * 封装 cross-package / architecture-ir / overview / natural-language 四种操作的业务逻辑。
+ * CLI handler 和 MCP tool 均通过此模块完成调用（FR-005）。
+ */
+export type PanoramicOperation = 'cross-package' | 'architecture-ir' | 'overview' | 'natural-language';
+export interface PanoramicQueryOptions {
+    projectRoot: string;
+    operation: PanoramicOperation;
+    /** 问题文本（operation=natural-language 时必填） */
+    question?: string;
+}
+export type PanoramicQueryResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 执行 panoramic 架构分析查询
+ *
+ * @param options.operation 操作类型
+ * @param options.projectRoot 项目根目录绝对路径
+ * @param options.question 问题文本（natural-language 时必填）
+ * @returns 成功时返回对应 Generator 的输出，失败时返回友好错误信息
+ */
+export declare function queryPanoramic(options: PanoramicQueryOptions): Promise<PanoramicQueryResult>;
+//# sourceMappingURL=query.d.ts.map

package/dist/panoramic/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/panoramic/query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,MAAM,MAAM,kBAAkB,GAAG,eAAe,GAAG,iBAAiB,GAAG,UAAU,GAAG,kBAAkB,CAAC;AAEvG,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAqE/B"}

package/dist/panoramic/query.js

@@ -0,0 +1,80 @@
+/**
+ * Panoramic Query Helper
+ * 封装 cross-package / architecture-ir / overview / natural-language 四种操作的业务逻辑。
+ * CLI handler 和 MCP tool 均通过此模块完成调用（FR-005）。
+ */
+import { buildProjectContext } from './project-context.js';
+import { CrossPackageAnalyzer } from './generators/cross-package-analyzer.js';
+import { ArchitectureIRGenerator } from './generators/architecture-ir-generator.js';
+import { ArchitectureOverviewGenerator } from './generators/architecture-overview-generator.js';
+import { answerQuestion } from './qa/index.js';
+/**
+ * 执行 panoramic 架构分析查询
+ *
+ * @param options.operation 操作类型
+ * @param options.projectRoot 项目根目录绝对路径
+ * @param options.question 问题文本（natural-language 时必填）
+ * @returns 成功时返回对应 Generator 的输出，失败时返回友好错误信息
+ */
+export async function queryPanoramic(options) {
+    try {
+        // natural-language 分支不需要 buildProjectContext，直接路由到 qa
+        if (options.operation === 'natural-language') {
+            const { projectRoot, question } = options;
+            // handler 层校验：natural-language 时 question 必填
+            if (!question || question.trim().length === 0) {
+                return {
+                    ok: false,
+                    error: 'operation=natural-language 时 question 参数必填，且不能为空字符串',
+                };
+            }
+            const answer = await answerQuestion({ text: question }, { projectRoot });
+            // 将 QnAAnswer 序列化为 MCP 响应格式（JSON serializable）
+            return {
+                ok: true,
+                data: {
+                    answer: answer.text,
+                    citations: answer.citations,
+                    tokenUsage: answer.tokenUsage,
+                    durationMs: answer.durationMs,
+                    fallbackMode: answer.fallbackMode,
+                },
+            };
+        }
+        const context = await buildProjectContext(options.projectRoot);
+        switch (options.operation) {
+            case 'cross-package': {
+                const analyzer = new CrossPackageAnalyzer();
+                if (!analyzer.isApplicable(context)) {
+                    return {
+                        ok: false,
+                        error: '当前项目不是 monorepo，cross-package 分析不可用',
+                    };
+                }
+                const input = await analyzer.extract(context);
+                const output = await analyzer.generate(input);
+                return { ok: true, data: output };
+            }
+            case 'architecture-ir': {
+                const generator = new ArchitectureIRGenerator();
+                const input = await generator.extract(context);
+                const output = await generator.generate(input);
+                // 返回 output.ir（ArchitectureIR），而非整个 ArchitectureIROutput
+                return { ok: true, data: output.ir };
+            }
+            case 'overview': {
+                const generator = new ArchitectureOverviewGenerator();
+                const input = await generator.extract(context);
+                const output = await generator.generate(input);
+                return { ok: true, data: output };
+            }
+        }
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=query.js.map

package/dist/panoramic/query.js.map

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