智能体与知识图谱设计

.antigravityrules

@@ -11,3 +11,16 @@
 3. **UI Notifications**:
    - All popup messages, error alerts, and system notifications **MUST** uniformly use the toast component (e.g., via `useToast().showError()`, `showSuccess()`). 
    - Never use native browser `window.alert()`.
+
+4. **Agent Architecture & Orchestration (v3.0)**:
+   - High-complexity, multi-turn AI workflows (e.g., AI Tutor, Evaluation Agents) **MUST** use `LangGraph` for state machine orchestration. Do not rely on hardcoded linear `if-else` blocks or flat chains for multi-step agent interactions.
+   - Separate distinct AI responsibilities (e.g., `QuestionGenerator`, `Grader`, `ReportAnalyzer`) into independent **Graph Nodes**.
+   - Use **Conditional Edges (Routing)** to dynamically control the flow based on the graph state (e.g., triggering follow-up questions vs. proceeding to the next question).
+   - The graph must maintain a central `State` object (e.g., `EvaluationState`) to track session data, current progress, multi-turn dialogue history, and interruption/recovery points (Thread IDs).
+
+5. **Agent Evaluation & Anti-Hallucination**:
+   - When using an LLM to grade or evaluate user input against a knowledge base, the Agent's System Prompt **MUST** always include the original reference documents (Ground Truth Chunks) to strictly prevent AI hallucination during scoring.
+
+6. **Knowledge Graph Integration**:
+   - When extracting complex relationships from documents for GraphRAG, ensure the LLM output conforms strictly to predefined schemas (Ontology) to prevent graph pollution.
+   - Heavy extraction tasks (like Full Document Entity/Relation Extraction) must be handled asynchronously as background tasks, rather than blocking synchronous API calls.

docs/3.0/employee_evaluation_agent_analysis.md

@@ -0,0 +1,127 @@
+# 基于知识库的人员评价智能体（Employee Evaluation Agent）架构设计（基于 LangGraph）
+
+基于现有的系统架构（React + NestJS + Langchain + Elasticsearch），要构建一个能够“基于知识库提问、根据回答打分、最终评估知识掌握程度”的智能体，这在 AI 领域属于出典型的 **AI Tutor / AI Examiner（AI 导师/考官）** 场景。
+
+为了实现高度可控、可干预且支持复杂多轮状态流转的对话互动（如追问、动态调整问题难度等），**采用 LangGraph 作为整个后端 Agent 的编排核心是目前的最佳实践**。
+
+以下是详细的需求分析、架构设计与实施建议：
+
+## 一、 核心业务流程
+一个完整的评估闭环应该包含以下四个阶段：
+1. **考纲拟定与生题 (Question Generation)**：选定知识库或特定文档集，AI 自动提取核心知识点，生成不同难度（事实记忆类、场景应用类、分析判断类）的考题及标准答案基准。
+2. **交互答题 (Interactive Exam)**：员工在前端查看问题并作答。系统通过一问一答的方式进行渐进式交互。
+3. **智能阅卷与评分 (Automated Grading)**：每轮回答后，AI 立即比对员工答案、参考答案及原始文献（Context），给出基础分数与点评反馈，并决定是否继续追问。
+4. **综合学情报告 (Mastery Assessment)**：图流转结束后，结合所有轮次的答题记录，总结该员工在特定领域/知识簇的掌握情况，输出雷达图与能力定级。
+
+---
+
+## 二、 基于 LangGraph 的核心智能体设计与编排
+
+LangGraph 的核心思想是将 LLM 的推理流程转化为**状态机（State Machine）**和**有向无环/有环图（Graph）**。在这里，我们将各个细分任务的 Agent 定义为图中的**节点（Nodes）**，通过**边（Edges）**和**条件边（Conditional Edges）**来完成整个复杂流程的**智能编排（Orchestration）**。
+
+### 1. 状态定义 (State Definition)
+所有 Agent Node 共享并修改一个全局作用域的 State 对象：
+```typescript
+interface EvaluationState {
+  sessionId: string;                 // 会话 ID
+  knowledgeBaseId: string;           // 关联的知识库 ID
+  documentContexts: string[];        // 检索出的前置知识点/文档块
+  questions: ExamQuestion[];         // 生成的问题列表（含标准答案采分点）
+  currentQuestionIndex: number;      // 当前进行到的题目索引
+  isCurrentQuestionPass: boolean;    // 针对当前题的评估状态（是否通过）
+  shouldFollowUp: boolean;           // 是否需要追问
+  dialogueHistory: ChatMessage[];    // 人机对话历史
+  scores: Record<number, number>;    // 每道题的得分 { questionIndex: score }
+  feedbacks: Record<number, string>; // 每道题的点评
+  finalReport?: string;              // 最终评估报告
+}
+```
+
+### 2. 多智能体协作与节点 (Multi-Agent Nodes)
+我们将不同职责的 Agent 封装成独立的图节点。
+
+* **`Agent A: QuestionGenerator` (出题节点)**：
+  * **编排角色**：图的初始化引擎。负责冷启动，与 Elasticsearch 交互拉取 Context。
+  * **操作**：把生成的问题列表写入 `State.questions`，初始化 `currentQuestionIndex = 0`。
+* **`Agent B: Interviewer` (提问/引导节点)**：
+  * **编排角色**：前端界面的发言人。它不会直接做判断，只负责从 `State.questions` 或追问历史中组织话术，并挂起图流程，等待人类回答。
+* **`Agent C: Grader` (评分与判决节点)**：
+  * **编排角色**：“大脑”裁判。在人类输入后唤醒。负责调用大模型比对标准答案，打出本轮 Score。
+  * **关键逻辑**：更新 `State.scores`。并负责修改状态流转标志位 `shouldFollowUp` 和 `isCurrentQuestionPass`。
+* **`Agent D: ReportAnalyzer` (学情报告生成节点)**：
+  * **编排角色**：总结法官。当图流转判定无需再问时进入，通读整个 State，产出带格式的 Markdown 雷达分析结论。
+
+### 3. 智能体之间的图流转编排 (Conditional Routing Orchestration)
+LangGraph 通过代码级声明连线逻辑（Routing），极大降低了复杂对话分支的维护成本。**这也是弃用传统线性代码，改用 LangGraph 的核心价值所在**。
+
+* **初始化流**：`Start` -> `AgentA (出题)` -> `AgentB (提问)` -> `中断挂起等待人类输入`。
+* **阅卷流**：前端推送答案（人类恢复运行）-> 图被唤醒进入 `AgentC (判卷)`。
+* **动态编排与条件分支 (核心亮点)**：
+  `AgentC` 执行完毕后，LangGraph 不会写死下一步去哪，而是进入一个路由判决函数（Router Logic）：
+  * **分支 1（追问）**：`If (shouldFollowUp == true)` -> 图重新倒流回 `AgentB`（但带上了让它引导追问的 Prompt） -> `再次等待输入`。
+  * **分支 2（下一题）**：`If (shouldFollowUp == false && currentQuestionIndex < questions.length - 1)` -> 修改 `currentQuestionIndex++` -> 走向 `AgentB (抛出新题)`。
+  * **分支 3（结束出报告）**：`If (所有题目已答完)` -> 流向 `AgentD (总结报告)` -> `End` 结束图。
+
+### 4. 数据库持久化层 (TypeORM)
+使用 LangGraph 后，可以结合它的 **Checkpointer** 机制在 SQLite/Postgres 中自动保存图状态（State）。这让你具备了**断点续看/续考**的天然能力。
+您也可以同步将核心指标存储至业务表：
+* `AssessmentSession` (评估总表)：存分数和图的线程ID (thread_id) 用于恢复会话。
+* `AssessmentQuestion & Record` (明细表)：便于生成 BI 报表。
+
+---
+
+## 三、 LangGraph 架构下的前端交互设计
+
+* **对话式答题台 (Chat-based Exam Interface)**：
+  * 放弃传统的“一份大卷子”式样。采用类似 ChatView 的交互。
+  * **流式响应**：LangGraph 原生支持 Streaming。当进入 `AgentC (判卷)` 时，前端马上能以打字机效果看到 AI 思考的反馈：“✅ 概念理解正确，得 8 分。但漏掉了另一个核心条件 XXX...”
+  * **断点续考**：由于 LangGraph 使用 thread_id 记录状态，员工关闭浏览器后再次进入，图能够从中断的具体节点恢复并继续推送上一题的反手追问。
+
+---
+
+## 四、 实施路径与关键难点避坑
+
+### 阶段一：实现单题循环验证 (MVP)
+先跑通最简单的 Pipeline，只包含一题。
+1. 在后端的 Langchain 模块引入 `@langchain/langgraph`。
+2. 构建一个非常简化的图（提问 -> 人类回答 -> 评分反馈 -> 结束）。
+3. 前端复用当前的聊天组件向该 Graph 推送消息。
+
+### 阶段二：打通完善的多智能体编排 (Orchestration Loop)
+* 引入 `QuestionGenerator` 负责从 Elasticsearch 拉取知识库 Chunks 进行组卷。
+* 编写复杂的 `Router` 路由逻辑，完成完整的 5-10 题多轮轮询与追问编排。
+* **避坑提示**：防止大模型在评分时“放水”或出现幻觉，在 `Grader` 节点中务必将出题时检索到的文档 Chunk 放在 System Prompt 中作为 Ground Truth（事实基准）。
+
+### 阶段三：长时间线跟踪与知识图谱融合
+* 结合之前提到的“知识图谱”，可以将每次考试员工做错的节点（如“产品A的定价策略”）在特定图谱中标记为红灯。下次再生成试卷（图启动时），`QuestionGenerator` 优先去图谱中寻找那些红灯节点进行错题重练。
+
+---
+
+## 五、 智能体设计四要素维度评估
+
+在构建完善的智能体体系时，通常需要综合考量以下四个核心要素。本设计针对这四个维度的完成度如下：
+
+### 1. 认知推理 (Cognitive Reasoning)
+* **设计体现**：系统主要依赖于 `QuestionGenerator`（出题引擎）和 `Grader`（判卷大脑）这两个计算节点进行认知推理。能够从大量检索文本中提取采分点（归纳提取），并能够比对标准答案与员工口语化、非结构化回答之间的语义契合度（演绎判断）。
+* **完善度**：较高。这部分的上限完全取决于选用的底层大模型的能力（如逻辑推理和指令遵循），系统自身架构能够通过注入 Ground Truth 文档来限制模型幻觉。
+
+### 2. 任务规划 (Task Planning)
+* **设计体现**：通过 **LangGraph 的状态机与条件路由（Conditional Edges）** 实现了强大的动态任务规划能力。传统弱智能体只能采用线性流，而本系统通过路由节点（Router Logic）根据人类前置回答情况，能实时决策下一步规划（追问、切入下一题、还是直接结束出报告）。
+* **完善度**：极高。基于有向图流转的声明式编排完美契合了复杂评估场景（特别是多轮考官对话）规划流转的需要。
+
+### 3. 工具调用 (Tool Calling / Action)
+* **设计体现**：目前的 MVP 架构在 `QuestionGenerator` 节点中隐式具有 RAG 工具（调用 Elasticsearch 获取文本）。
+* **可进阶增强点**：为了提升考试交互的真实性，可以赋予图中的 `Interviewer` (提问/引导节点) 额外的 Tool Calling 能力。例如，如果员工在答题中途反向提问求助（如：“考官，能给我提示一下安全规范的第三大类吗？”），Agent 可以被授权临时调用专门的 `RetrievalTool` 再去查一次资料，而不是只能死板地等待答案。
+
+### 4. 持续学习 (Continuous Learning / Memory)
+* **设计体现**：**短时记忆（Short-term Memory）**通过 LangGraph 的 `EvaluationState.dialogueHistory` 和 `EvaluationState.scores` 原生闭环实现；**长时记忆（Long-term Memory）**则通过 TypeORM 写入业务关系库。
+* **可进阶增强点**：目前的架构在“自主进化”上略显不足，可通过之前讨论的**知识图谱（Knowledge Graph）**形成学习反馈闭环。把系统中员工普遍答错的高频知识点，作为带有权重的“薄弱红灯节点”沉淀入图谱；下一次生成总考卷时，出题 Agent 会通过调用图查询接口，专找这种薄弱节点强化出题。这构成了系统级对员工群体的持续学习刻画。
+
+---
+
+## 六、 总结与建议选择
+
+将架构改为 LangGraph 后，**状态管理的复杂性和不同职责小模型（或小Agent）之间的协作编排（Orchestration），从自己苦写大量 if-else 或微服务 RPC 退化为了直观的、声明式的图流转**。这能够完美匹配“因材施教”、“多角色评委苏格拉底式追问”的高级 AI 导师形态。并且在这个架构底座上，认知、规划、工具和记忆这四大能力组件都可以被模块化地插拔与增强。
+
+**推荐第一步**：
+从新建 `server/src/assessment` 模块开始，编写一个基于 `@langchain/langgraph` 的测试脚本，定义 `State` 接口并直接写死伪造的题目数据，通过控制台来模拟跑通最基础的认知与条件规划流！

docs/3.0/knowledge_graph_analysis.md

@@ -0,0 +1,66 @@
+# 知识库引入知识图谱（Knowledge Graph）分析与实施建议
+
+基于项目当前技术栈（前端 React/Vite，后端 NestJS，使用 Elasticsearch、TypeORM 和 Langchain），如果要在现有的知识库（Knowledge Base）中引入知识图谱（Knowledge Graph）功能，通常是为了向 GraphRAG（图检索增强生成）演进。这能极大地提升系统处理复杂查询（如跨文档、多跳推理关联）的能力。
+
+以下是针对现有项目的架构分析与实施建议：
+
+## 一、 核心价值与应用场景
+将知识图谱引入知识库后，您可以实现：
+1. **更精准的 RAG (GraphRAG)**：传统的向量检索（如 Elasticsearch 密集向量）擅长捕捉语义相似性，但在“找出A与C之间的所有中间联系”等多跳逻辑推理上表现不佳。图谱可以弥补这一短板。
+2. **可视化探索**：允许用户在前端以节点和边的形式，直观地浏览知识库中概念之间的关系。
+3. **知识融合**：将分布在多篇独立文档（PDF/Word等）中的碎片化信息，通过实体（Entity）统一串联成网状结构。
+
+## 二、 技术选型建议
+考虑到后端已经深度集成了 `@langchain/core` 和 `@langchain/openai`，强烈建议最大限度复用 Langchain 的生态体系。
+
+1. **图数据库 (Graph Database) 选型**：
+   * **优选：Neo4j**。它是目前与大模型和 Langchain 集成最成熟的图数据库。Langchain 原生支持 Neo4j（通过相关的扩展包），并且可以直接用 Cypher 语言进行图查询。
+   * **备选：Memgraph** 或 **NebulaGraph**。
+   * **当前栈复用**：如果不希望引入新的数据库组件，您也可以先用关系型数据库（当前用的 TypeORM 控制的底层数据库）建立三元组表 `(head, relation, tail)` 作为简化版的图存储，但查询效率和图算法能力远不及原生图引擎。
+
+2. **实体/关系提取 (Knowledge Extraction)**：
+   * **方案**：利用 LLM（目前已接入的大语言模型）。使用 Langchain 构建信息抽取链（Extraction Chain），通过 Prompt 指导模型从文本分块（Chunks）中提取 `[实体1] -> [关系] -> [实体2]` 的三元组。
+   * **工具**：可以使用 Langchain 提供的 `LLMGraphTransformer` 工具。
+
+3. **前端可视化组件**：
+   * **推荐**：`react-force-graph` （轻量、支持 2D/3D、适合 React）。
+   * **备选**：`vis-network` 或 ECharts 的关系图组件。
+
+## 三、 架构演进与实施步骤
+建议分几个阶段进行，逐步迭代：
+
+### 第一阶段：数据管道升级（建图）
+在当前的文件上传、解析和切分（Text Splitters）流程中，**在存入 Elasticsearch 向量库的同时，增加一条图谱构建分支**：
+1. **文本分块 (Chunking)**：复用现有的切分逻辑。
+2. **实体抽取 (Extraction)**：将 Chunk 发送给 LLM，提示词例如：“从以下文本中提取关键实体（如人名、机构、技术、概念）及它们之间的关系，以 JSON 格式输出。”
+3. **实体消歧与对齐 (Entity Resolution)**：比如“Apple”和“苹果公司”应指向同一个节点。可以结合向量空间中相似度，将意思相近的实体进行合并。
+4. **存入图数据库**：将提取出的 Node（实体）和 Edge（关系）写入 Neo4j。并将源文档的 Chunk ID 作为属性附加在 Node 或 Edge 上，以此实现“图谱与原文档内容的双向链接”。
+
+### 第二阶段：检索融合 (Hybrid RAG)
+改造当前的问答（Chat/Search）接口，引入**混合检索（Hybrid Retrieval）**：
+1. 用户输入问题后，首先利用 LLM 解析问题中的核心**实体**。
+2. **图检索**：从图库中查询这些实体，获取相关的连通子图（例如周围 2 度的节点和边）。
+3. **向量检索**：同时在 Elasticsearch 中进行传统的语义相似度检索。
+4. **上下文组装**：将图谱中查到的关系路径（如：`A -> 属于 -> B -> 包含 -> C`）转化为自然语言，与向量检索拿到的文本片段拼在一起，作为 prompt 提供给 LLM 回答。
+
+### 第三阶段：前端图谱可视化
+1. 提供一个单独的“知识图谱”视图页面。
+2. 后端提供 `/api/knowledge-graph/nodes` 接口，根据当前知识图（或特定过滤条件下的子图）返回节点和链接数据。
+3. 前端使用 `react-force-graph` 渲染：
+   * 点击某个节点，可以展开查询关联节点。
+   * 关联节点可以溯源，显示出“该关系是由哪份知识库文档的哪一句话提取出来的”。
+
+## 四、 项目需要做出的具体改动评估
+1. **依赖层 (`server/package.json`)**：
+   * 需要新增类似 `neo4j-driver`、`@langchain/community` 等依赖。
+   * Docker 环境：`docker-compose.yml` 中需要引入 Neo4j 容器。
+2. **知识处理流 (`server/src/knowledge-base/` 等目录)**：
+   * 需要新增一个专门处理图操作的服务（如 `graph.service.ts`）。
+   * 需要修改当前的导入任务（`import-task`），让其支持异步地调用大模型进行耗时的实体抽取操作（这部分成本较高且较慢，建议通过事件驱动或消息队列异步处理）。
+3. **前端展示 (`web/components/`)**：
+   * 设计新的 UI 组件（如 `GraphViewer.tsx`）。
+
+## 五、 核心建议与避坑指南
+1. **Token 成本与耗时控制**：从全文中提取高质量图谱极耗费 Token，且速度慢。建议初期只对**高价值核心文档**开启图谱提取，并且采用批处理异步任务。
+2. **模型能力要求**：信息抽取高度依赖模型的指令遵循（Instruction Following）能力。如果使用的是私有部署的小模型，可能会出现实体抽取格式混乱的问题；建议使用如 GPT-4o, Claude 3.5 Sonnet 等强模型进行图谱提取。
+3. **本体论 (Ontology) 建设**：完全开放域的“自由抽取”会导致图谱非常混乱（如“今天”也成了一个无意义节点）。建议在业务初期，预定义好希望提取的实体类型（如：只提取 `[产品]`, `[故障]`, `[解决方案]`, `[组件]` 四类），在 Prompt 中强制 LLM 遵守这一 Schema。