aurak/docs/3.0/employee_evaluation_agent_analysis.md

基于知识库的人员评价智能体（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 对象：

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 接口并直接写死伪造的题目数据，通过控制台来模拟跑通最基础的认知与条件规划流！