企业级 AI Agent 知识库“图谱检索增强”（GraphRAG）架构实战：实体关系抽取、社区聚类发现与向量图谱混合检索治理

/**
 * @file EnterpriseGraphRagEngine.ts
 * @description 企业级 GraphRAG 混合检索执行引擎核心实现
 * 涵盖：意图路由（Local/Global）、多跳子图遍历（Graph Traversal）与全局社区摘要聚合
 */

import { EventEmitter } from 'node:events';

/** 知识图谱实体节点定义 */
export interface GraphEntityNode {
  id: string; // 唯一实体编号
  name: string; // 实体规范名称
  type: string; // 实体类别（如系统、组织、法规、设备）
  description: string; // 实体摘要定义
  communityId: string; // 所属核心社区编号
}

/** 实体间有向关系三元组定义 */
export interface GraphRelationshipEdge {
  sourceId: string; // 头实体编号
  targetId: string; // 尾实体编号
  predicate: string; // 关系谓词（如依赖、调用、管辖、故障引发）
  weight: number; // 关系权重（1-10）
  evidenceChunkId: string; // 来源原始文本切片编号
}

/** 分层社区摘要报告定义 */
export interface CommunitySummaryReport {
  communityId: string; // 社区编号
  level: number; // 社区分层等级（0:全局, 1:业务域, 2:工序级）
  title: string; // 社区核心主题标题
  summary: string; // 结构化主题全景摘要
  findings: string[]; // 核心洞察事实清单
  embedding?: number[]; // 报告向量嵌入
}

/** 混合检索配置选项 */
export interface GraphRagSearchOptions {
  intentOverride?: 'local' | 'global'; // 强制指定意图模式
  maxHops?: number; // 局部检索最大遍历跳数（默认 2）
  topCommunities?: number; // 全局检索召回社区数量（默认 3）
}

/** 混合检索统一输出结果契约 */
export interface GraphRagSearchResult {
  searchMode: 'local' | 'global'; // 实际执行的检索模式
  contextMarkdown: string; // 注入大模型推理上下文的 Markdown 证据块
  citedEntities: string[]; // 引用涉及的实体名称清单
  citedCommunityIds: string[]; // 引用涉及的社区编号清单
}

/**
 * 企业级 GraphRAG 混合检索执行引擎类
 */
export class EnterpriseGraphRagEngine extends EventEmitter {
  // 模拟图数据库与向量数据库客户端接入点
  private graphNodes: Map<string, GraphEntityNode> = new Map();
  private graphEdges: GraphRelationshipEdge[] = [];
  private communityReports: CommunitySummaryReport[] = [];

  constructor() {
    super();
    // 初始化模拟业务图谱数据
    this.seedMockEnterpriseKnowledgeGraph();
  }

  /**
   * 混合检索入口：智能研判用户意图并分发至局部图遍历或全局社区汇总
   * @param query 用户提问
   * @param options 检索配置参数
   */
  public async search(
    query: string,
    options: GraphRagSearchOptions = {}
  ): Promise<GraphRagSearchResult> {
    // 1. 意图判别：通过关键词启发式规则或语义分类器识别 Local 还是 Global
    const mode = options.intentOverride || this.classifyQueryIntent(query);

    if (mode === 'global') {
      return this.executeGlobalSearch(query, options.topCommunities ?? 3);
    } else {
      return this.executeLocalSearch(query, options.maxHops ?? 2);
    }
  }

  /**
   * 意图分类器：区分宏观全局概括（Global）与具体实体深挖（Local）
   * @param query 提问文本
   */
  private classifyQueryIntent(query: string): 'local' | 'global' {
    const globalKeywords = ['全景', '总结', '梳理全部', '整体趋势', '整体架构', '有哪些主要类别', '风险分布'];
    const hasGlobalIntent = globalKeywords.some(keyword => query.includes(keyword));
    return hasGlobalIntent ? 'global' : 'local';
  }

  /**
   * 局部检索管道（Local Search）：基于实体种子与多跳子图展开
   * @param query 用户提问
   * @param maxHops 最大拓扑遍历深度
   */
  private async executeLocalSearch(
    query: string,
    maxHops: number
  ): Promise<GraphRagSearchResult> {
    // 步骤一：通过字符串包含与命名实体识别匹配种子实体（生产环境结合向量初筛）
    const matchedSeeds: GraphEntityNode[] = [];
    for (const node of this.graphNodes.values()) {
      if (query.toLowerCase().includes(node.name.toLowerCase())) {
        matchedSeeds.push(node);
      }
    }

    // 若未直接命中实体，默认退化为全节点初筛（取前 2 个节点作为回退种子）
    const effectiveSeeds = matchedSeeds.length > 0
      ? matchedSeeds
      : Array.from(this.graphNodes.values()).slice(0, 2);

    // 步骤二：以种子实体为中心向外展开 K 跳子图（Graph Traversal）
    const visitedNodeIds = new Set<string>();
    const traversedEdges: GraphRelationshipEdge[] = [];
    let currentFrontier = effectiveSeeds.map(node => node.id);

    currentFrontier.forEach(id => visitedNodeIds.add(id));

    for (let hop = 0; hop < maxHops; hop++) {
      const nextFrontier: string[] = [];
      for (const edge of this.graphEdges) {
        if (currentFrontier.includes(edge.sourceId) && !visitedNodeIds.has(edge.targetId)) {
          visitedNodeIds.add(edge.targetId);
          nextFrontier.push(edge.targetId);
          traversedEdges.push(edge);
        } else if (currentFrontier.includes(edge.targetId) && !visitedNodeIds.has(edge.sourceId)) {
          visitedNodeIds.add(edge.sourceId);
          nextFrontier.push(edge.sourceId);
          traversedEdges.push(edge);
        }
      }
      currentFrontier = nextFrontier;
      if (currentFrontier.length === 0) break;
    }

    // 步骤三：格式化为大模型可读的上下文 Markdown 知识块
    const contextLines: string[] = ['### 【局部知识图谱拓扑事实证据链】'];
    const citedEntityNames: string[] = [];

    contextLines.push('#### 核心关联实体清单：');
    visitedNodeIds.forEach(id => {
      const node = this.graphNodes.get(id);
      if (node) {
        citedEntityNames.push(node.name);
        contextLines.push(`- **${node.name}** [类型: ${node.type}]: ${node.description}`);
      }
    });

    contextLines.push('\n#### 关联关系与依赖链条：');
    traversedEdges.forEach(edge => {
      const source = this.graphNodes.get(edge.sourceId)?.name || edge.sourceId;
      const target = this.graphNodes.get(edge.targetId)?.name || edge.targetId;
      contextLines.push(`- [${source}] --(${edge.predicate}, 权重: ${edge.weight})--> [${target}] (来源切片: ${edge.evidenceChunkId})`);
    });

    return {
      searchMode: 'local',
      contextMarkdown: contextLines.join('\n'),
      citedEntities: citedEntityNames,
      citedCommunityIds: []
    };
  }

  /**
   * 全局检索管道（Global Search）：基于分层社区发现报告聚合宏观视角
   * @param query 用户提问
   * @param topCount 召回社区数量
   */
  private async executeGlobalSearch(
    query: string,
    topCount: number
  ): Promise<GraphRagSearchResult> {
    // 生产环境中通过 Vector ANN 召回与 query 语义最匹配的社区报告
    // 本演示代码通过层级与匹配度快速筛选
    const relevantReports = this.communityReports
      .sort((a, b) => a.level - b.level) // 优先考量顶层概览
      .slice(0, topCount);

    const contextLines: string[] = ['### 【GraphRAG 全局分层社区报告摘要】'];
    const citedCommunities: string[] = [];

    relevantReports.forEach(report => {
      citedCommunities.push(report.communityId);
      contextLines.push(`#### 社区报告: ${report.title} (层级: Level-${report.level})`);
      contextLines.push(`**主题概述：** ${report.summary}`);
      contextLines.push('**核心业务洞察：**');
      report.findings.forEach(finding => {
        contextLines.push(`  * ${finding}`);
      });
      contextLines.push('');
    });

    return {
      searchMode: 'global',
      contextMarkdown: contextLines.join('\n'),
      citedEntities: [],
      citedCommunityIds: citedCommunities
    };
  }

  /**
   * 初始化模拟测试数据（涵盖制造车间、ERP 系统与质检流程）
   */
  private seedMockEnterpriseKnowledgeGraph(): void {
    // 实体入库
    this.graphNodes.set('ent_mes', {
      id: 'ent_mes',
      name: 'MES生产执行系统',
      type: '软件系统',
      description: '负责制造现场车间工单调度、工序工步流转及设备实时数据采集',
      communityId: 'comm_smart_mfg'
    });
    this.graphNodes.set('ent_erp', {
      id: 'ent_erp',
      name: 'ERP核心业务系统',
      type: '软件系统',
      description: '集团财务管理、销售订单、原材料采购入库及BOM清单管理中枢',
      communityId: 'comm_erp_finance'
    });
    this.graphNodes.set('ent_cnc', {
      id: 'ent_cnc',
      name: '5轴数控加工中心CNC-08',
      type: '生产设备',
      description: '精密铝合金叶轮加工核心关键设备，配备主轴振动与温度传感器',
      communityId: 'comm_smart_mfg'
    });
    this.graphNodes.set('ent_qa', {
      id: 'ent_qa',
      name: '三坐标质检站QA-Station',
      type: '检测站点',
      description: '对机加工成品进行微米级公差抽样检测，生成质检合规放行报告',
      communityId: 'comm_smart_mfg'
    });

    // 关系边入库
    this.graphEdges.push({
      sourceId: 'ent_erp',
      targetId: 'ent_mes',
      predicate: '下发生产批次工单',
      weight: 9,
      evidenceChunkId: 'doc_sop_erp_integration_p12'
    });
    this.graphEdges.push({
      sourceId: 'ent_mes',
      targetId: 'ent_cnc',
      predicate: '调度装载加工程序与派工',
      weight: 8,
      evidenceChunkId: 'doc_mes_machining_flow_p05'
    });
    this.graphEdges.push({
      sourceId: 'ent_cnc',
      targetId: 'ent_qa',
      predicate: '自动推送成品批次报检请求',
      weight: 7,
      evidenceChunkId: 'doc_qa_inspection_rule_p08'
    });

    // 社区分层摘要入库
    this.communityReports.push({
      communityId: 'comm_smart_mfg',
      level: 1,
      title: '数字化车间智能制造与加工质检协同闭环',
      summary: '本社区由 MES 生产执行系统、5轴数控加工中心及三坐标质检站构成，实现了工单下发、排产加工与质检放行的全链路数字化直通。',
      findings: [
        '设备预警响应：数控加工中心主轴振动超标将通过 MES 毫秒级触发生产暂停，阻断不良品批次扩大。',
        '闭环反馈机制：质检站检测出的公差偏移会自动反哺至机床刀补系统进行微米级动态补偿。'
      ]
    });
    this.communityReports.push({
      communityId: 'comm_erp_finance',
      level: 0,
      title: '集团核心业务与产供销一体化架构',
      summary: '涵盖财务应付、BOM 物料管理与跨厂区工单协同，为制造前端提供权威主数据基线。',
      findings: [
        '订单状态同步：MES 加工进度每 5 分钟向 ERP 对账并更新物料消耗台账。'
      ]
    });
  }
}