# 基于知识库的人员评价智能体（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` 接口并直接写死伪造的题目数据，通过控制台来模拟跑通最基础的认知与条件规划流！
