spectra-cli 4.1.1

package/dist/panoramic/graph/graph-query.d.ts

@@ -0,0 +1,226 @@
+/**
+ * GraphQueryEngine — 知识图谱查询引擎
+ * 负责从 _meta/graph.json 加载图谱，构建内存索引，提供查询接口
+ * 参照 graphify 极简设计，不引入任何新运行时依赖
+ */
+import type { GraphJSON, GraphNode, GraphEdge, Hyperedge, SemanticEdgeRelation } from './graph-types.js';
+/**
+ * 关键词子图查询结果
+ */
+export interface QueryResult {
+    /** 匹配到的节点列表（已按 budget 裁剪） */
+    nodes: GraphNode[];
+    /** 节点间的边列表 */
+    edges: GraphEdge[];
+    /** 查询摘要文本（节点数量 + 截断提示） */
+    summary: string;
+    /** 是否因超出 budget 而截断 */
+    truncated: boolean;
+    /** 原始匹配节点总数（截断前） */
+    totalMatches: number;
+}
+/**
+ * 单节点详情查询结果
+ */
+export interface NodeResult {
+    /** 查找到的节点，不存在时为 null */
+    node: GraphNode | null;
+    /** 邻居节点及连接边列表 */
+    neighbors: Array<{
+        node: GraphNode;
+        edge: GraphEdge;
+    }>;
+    /** 节点所属社区 ID，无社区信息时为 null */
+    community: string | null;
+    /** 附加消息（如"节点不存在"） */
+    message?: string;
+}
+/**
+ * 最短路径查询结果
+ */
+export interface PathResult {
+    /** 路径节点序列（按源到目标顺序），不存在路径时为 null */
+    path: GraphNode[] | null;
+    /** 路径上的边列表 */
+    edges: GraphEdge[];
+    /** 结果描述信息 */
+    message: string;
+}
+/**
+ * 社区节点列表查询结果
+ */
+export interface CommunityResult {
+    /** 社区 ID */
+    communityId: string;
+    /** 该社区的所有节点 */
+    nodes: GraphNode[];
+    /**
+     * 社区内聚度（来自 _meta/graph-report.md）
+     * 文件不存在时 graceful degrade，值为 null
+     */
+    cohesion: number | null;
+    /** 附加消息（如"社区不存在"或"内聚度不可用"） */
+    message?: string;
+}
+/**
+ * 枢纽节点（God Nodes）查询结果
+ */
+export interface GodNodesResult {
+    /** 按度数降序排列的枢纽节点列表（含 degree 字段） */
+    nodes: Array<GraphNode & {
+        degree: number;
+    }>;
+}
+/**
+ * schema v2.0：语义边信息（供 graph_node 工具 semanticEdges 字段使用）
+ * 表示与某节点关联的一条语义边，含方向、对端节点和证据字段
+ */
+export interface SemanticEdgeInfo {
+    /** 语义边类型（三种之一） */
+    type: SemanticEdgeRelation;
+    /** 相对于查询节点的方向（outgoing: 以该节点为 source；incoming: 以该节点为 target） */
+    direction: 'incoming' | 'outgoing';
+    /** 对端节点 ID */
+    peer: string;
+    /** 证据文本（来自 GraphEdge.evidenceText） */
+    evidenceText?: string;
+    /** 证据来源（来自 GraphEdge.evidenceSource） */
+    evidenceSource?: string;
+    /** 置信度 */
+    confidence?: 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
+}
+/**
+ * 将查询字符串拆分为小写词项集合。
+ *
+ * 支持以下拆分规则：
+ * - PascalCase：'PQueue' → ['p', 'queue']（'p' 长度=1 被过滤，最终保留 ['queue']）
+ * - 连续大写：'XMLParser' → ['xml', 'parser']
+ * - 分隔符：空格 / `-` / `_` / `.` 全部视作分隔
+ *
+ * 处理规则：
+ * - 全部转小写
+ * - 长度 ≤ 1 的 token 被过滤（避免 'p' / 'i' 等单字符噪声匹配）
+ * - 去重后返回稳定顺序（基于 Set 插入顺序）
+ *
+ * 注意：中文字符不会被 PascalCase 正则改动，按原样进入分隔符拆分；
+ * 因此中文查询如「优先队列」不会被错误拆分（无空格时整段保留为一个 token）。
+ *
+ * @param q - 原始查询字符串
+ * @returns 去重、过滤后的小写 token 数组
+ */
+export declare function tokenize(q: string): string[];
+/**
+ * 知识图谱查询引擎
+ * 从 GraphJSON 构建内存索引，提供高效查询接口
+ */
+export declare class GraphQueryEngine {
+    /** 原始图数据 */
+    private graph;
+    /** 节点 ID → 节点对象的索引映射 */
+    private nodeMap;
+    /** 邻接表：节点 ID → 相邻节点及连接边的数组 */
+    private adjacency;
+    /**
+     * 从 GraphJSON 构建查询引擎，同时建立内存索引
+     * @param graph - 符合 NetworkX node-link 格式的图谱 JSON
+     */
+    constructor(graph: GraphJSON);
+    /**
+     * 从磁盘文件加载图谱，返回初始化完成的查询引擎
+     * @param graphPath - graph.json 文件的绝对路径
+     * @throws 文件不存在或 JSON 格式不合法时抛出含明确原因的 Error
+     */
+    static loadFromFile(graphPath: string): GraphQueryEngine;
+    /**
+     * 对所有节点计算关键词匹配分（参照 graphify _score_nodes 逻辑）
+     * - label 包含词项：+1 分
+     * - metadata.sourcePath 或 metadata.path 包含词项：+0.5 分
+     * @param terms - 查询词项数组（已小写）
+     * @returns 按分数降序排列的节点 ID + 分数列表
+     */
+    private scoreNodes;
+    /**
+     * BFS 广度优先遍历（参照 graphify _bfs 逻辑）
+     * 从起始节点集合出发，按层遍历邻接表，防止循环访问
+     * @param startIds - 起始节点 ID 集合
+     * @param depth - 最大遍历深度
+     * @returns 访问到的节点 ID 集合和遍历到的边列表
+     */
+    private bfs;
+    /**
+     * 按 budget 裁剪节点列表
+     * 优先级：pinnedIds 固定保留 > 度数降序（hub 节点优先）
+     * @param nodes - 待裁剪的节点列表
+     * @param budget - 节点数上限（≤ 0 时使用默认值 50）
+     * @param pinnedIds - 必须保留的节点 ID 集合（如查询起点）
+     * @returns 裁剪后的节点列表及截断标志
+     */
+    private truncateByBudget;
+    /**
+     * 关键词子图查询（对应 graph_query MCP tool）
+     * 拆分查询词 → 关键词评分 → BFS 扩展子图 → budget 裁剪
+     * @param question - 自然语言查询词
+     * @param options - 查询选项（budget、mode、depth）
+     * @returns QueryResult
+     */
+    query(question: string, options?: {
+        budget?: number;
+        mode?: 'bfs' | 'dfs';
+        depth?: number;
+    }): QueryResult;
+    /**
+     * 单节点详情查询（对应 graph_node MCP tool）
+     * id 优先精确查找，回退到 keyword 模糊匹配
+     * @param params - 查询参数（id 优先，keyword 作为 fallback）
+     * @returns NodeResult
+     */
+    getNode(params: {
+        id?: string;
+        keyword?: string;
+        budget?: number;
+    }): NodeResult;
+    /**
+     * 最短路径查询（对应 graph_path MCP tool）
+     * 无权图 BFS 最短路径算法
+     * @param source - 源节点 ID
+     * @param target - 目标节点 ID
+     * @returns PathResult
+     */
+    findPath(source: string, target: string): PathResult;
+    /**
+     * 社区节点查询（对应 graph_community MCP tool）
+     * 按节点 metadata.community 字段分组，返回指定社区所有节点
+     * cohesion 从 _meta/graph-report.md 读取，文件不存在时 graceful degrade
+     * @param communityId - 社区 ID
+     * @param budget - 节点数上限（可选）
+     * @returns CommunityResult
+     */
+    getCommunity(communityId: string, budget?: number): CommunityResult;
+    /**
+     * 超边查询（对应 graph_hyperedges MCP tool）
+     * 返回图谱中所有超边，支持按 label 子串模糊过滤和按 node_id 精确过滤
+     * @param options - 过滤选项（均可选；两项均不传时返回全部）
+     * @returns Hyperedge 数组（graph.json 无 hyperedges 字段时返回空数组）
+     */
+    getHyperedges(options?: {
+        label?: string;
+        nodeId?: string;
+        limit?: number;
+    }): Hyperedge[];
+    /**
+     * 语义边查询（对应 graph_node MCP tool 的 semanticEdges 字段）
+     * 返回与指定节点关联的所有语义边（relation 为三种语义类型之一）
+     * 节点不存在或无语义边时返回空数组（不报错）
+     * @param nodeId - 目标节点 ID；undefined 或 null 时直接返回空数组
+     * @returns SemanticEdgeInfo 数组
+     */
+    getSemanticEdges(nodeId: string | null | undefined): SemanticEdgeInfo[];
+    /**
+     * 枢纽节点查询（对应 graph_god_nodes MCP tool）
+     * 计算每个节点的度数，按降序返回前 limit 个
+     * @param limit - 返回节点数量上限（默认 10）
+     * @returns GodNodesResult
+     */
+    getGodNodes(limit?: number): GodNodesResult;
+}
+//# sourceMappingURL=graph-query.d.ts.map

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

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