RoleCoach AI 互动学习系统

1. 项目总体架构

RoleCoach AI 互动学习系统是一款能与 AI 互动的知识学习系统。学员可以基于 RAG 知识库生产出个性化课程、在 AI 课堂中与 AI 教练智能体通过主动回忆学习法、费曼学习法等学习法强化学习效果。

1.1 总体分层架构图

1.2 系统架构层级说明

1.3 数据和运行状态的核心架构

flowchart TB
  KB["知识库<br/>domains"] --> SD["来源文档<br/>source_documents"]
  SD --> SDV["文档版本<br/>source_document_versions"]
  SDV --> EC["证据切片<br/>evidence_chunks<br/>全文 + 向量"]
  EC --> LOE["知识点证据绑定<br/>learning_object_evidence"]
  LOE --> LO["知识点<br/>learning_objects"]
  LO --> KG["知识图谱关系<br/>knowledge_edges"]
  EC --> KH["课堂知识文稿<br/>knowledge_htmls / blocks"]
  KH --> LES["课时<br/>lessons"]
  LES --> CRS["课程<br/>courses"]
  CRS --> CLS["课堂会话<br/>classroom_sessions"]
  CLS --> MSG["课堂消息<br/>classroom_messages"]
  MSG --> MEM["学习记忆<br/>learner_object_mastery / review_tasks / learner_reflections"]
  CLS --> LOG["运行追踪<br/>operation_runs / spans / events / prompt_traces"]
  JOB["课程生产任务<br/>course_generation_jobs"] --> PKG["课程生产包<br/>course_production_packages"]
  PKG --> CRS
  JOB --> LOG

2. AI 课堂 Agent

AI 课堂 Agent 像一位教练，学员每次阅读、提问、回答等现场信号，教练都会判断下一步应该讲解、追问、评估、更新学习记录，还是保持安静等待。

2.1 实现机制

2.1.1 课堂启动机制

课堂开始时，系统会锁定当前课时对应的教材版本、知识点和证据范围。这个锁定动作能够保证学员在一节课中的讲解、追问和评估都基于同一份材料，避免同一节课中途引用范围变化。

sequenceDiagram
  participant Learner as 学员
  participant Web as Web 前端
  participant API as API
  participant Runtime as AI 课堂运行时
  participant DB as 学习数据中心

  Learner->>Web: 从课程入口进入 AI 课堂
  Web->>API: 提交进入课堂请求
  API->>Runtime: 创建或恢复课堂
  Runtime->>DB: 读取课时、教材、知识点和证据范围
  Runtime->>DB: 记录本次课堂启动过程
  Runtime-->>API: 返回课堂当前状态
  API-->>Web: 返回目录、正文、教练开场和阅读状态
  Web-->>Learner: 展示左侧目录、中间教材、右侧教练区

2.1.2 每一轮互动的处理机制

flowchart TB
  A["学员发送消息或点击快捷动作"] --> B["系统记录本轮输入"]
  B --> C["整理课堂上下文<br/>课堂状态、教材、证据、规则、记忆"]
  C --> D{"这是否是正式回答<br/>且已经读完正文"}
  D -- 是 --> E["进入回答评估"]
  D -- 否 --> F["由 Planner 判断下一步教学动作"]
  F --> G["工具安全边界检查是否符合课堂规则"]
  G --> H{"动作是否允许执行"}
  H -- 不允许 --> I["把原因反馈给 Planner 重新规划"]
  I --> F
  H -- 允许 --> J{"本轮要做什么"}
  J -- 讲解或追问 --> K["生成教练回复"]
  J -- 正式回答 --> L["评估回答质量"]
  L --> M["判断本节课是否允许结束"]
  M --> N{"是否允许更新学习记忆"}
  N -- 允许 --> O["更新掌握情况、复习安排和学习反思"]
  N -- 暂不允许 --> P["只保存本轮反馈"]
  K --> Q["返回新的课堂状态"]
  O --> Q
  P --> Q

2.1.3 阅读门禁机制

课堂不会在学员刚打开正文时立刻要求回答。前端会先展示知识正文和内容块，学员点击“读完”后，系统才会进入追问、练习和评估环节。阅读完成前，系统主要允许讲解、提示和历史回忆，阅读完成后才会允许正式评分和学习记忆更新。

2.1.4 回答评估和课堂结束机制

当学员提交正式回答后，系统会从理解是否正确、表达是否清楚、能否放进真实场景三个角度评估回答。随后课堂运行时会结合学习法、回答次数、连续错误情况和证据状态判断本节课是否结束。达到要求时，课堂会进入完成状态；还有明显缺漏时，AI 教练会继续追问或安排补充练习。

2.2 记忆系统

AI 课堂里的记忆系统会把聊天记录、课堂状态、学员资料、知识点掌握情况和复习安排一起纳入管理。它既服务当前课堂的连续性，也服务后续学习的延续性。系统在每一轮互动前读取相关记忆，在正式评估结束后有条件地更新学习档案，在对话足够长或课堂暂停时整理课堂摘要，在发现有价值的教学信号时形成学习反思。

2.2.1 记忆系统机制图

flowchart TB
  A["课堂动作<br/>进入课堂、读完、提问、回答、暂停"] --> B["AI 课堂运行时"]
  B --> C["读取当前课堂状态<br/>正在学哪节课、读到哪里、刚刚聊了什么"]
  B --> D["读取学员资料<br/>学习偏好、历史表现、当前目标"]
  B --> E["读取短期课堂记忆<br/>最近对话、课堂摘要、上一轮反馈"]
  B --> F["读取长期学习记忆<br/>掌握情况、复习安排、学习反思"]
  C --> G["整理成本轮课堂上下文"]
  D --> G
  E --> G
  F --> G
  G --> H["Planner、回复生成和回答评估"]
  H --> I["生成课堂回复或评估结果"]
  I --> J{"是否满足写入学习档案的条件"}
  J -- 否 --> K["只保存课堂消息和本轮反馈"]
  J -- 是 --> L["更新掌握情况、复习安排和学习反思"]
  K --> M["必要时生成课堂摘要"]
  L --> M
  M --> N["下一轮课堂继续使用这些记忆"]

2.2.2 记忆从哪里来

课堂记忆主要来自四类信息。第一类是当前课堂现场，比如学员正在学哪节课、有没有读完正文、上一轮反馈是什么。第二类是最近对话和课堂摘要。第三类是学员的长期学习记录，系统会知道这个学员过去在哪些知识点上掌握较好，哪些内容需要复习。第四类是学习反思，它更像教师观察，记录学员常见的表达问题、理解习惯和后续引导方向。

2.2.3 短期记忆如何工作

短期记忆面向当前课堂，重点解决“这一节课刚刚发生了什么”。系统会把最近几轮对话带入上下文，如果课堂暂停、课堂结束，或者对话已经积累到需要整理的程度，系统会生成一份课堂摘要。摘要不会替代完整聊天记录，它的作用是把本节课的重要问题、关键回答、明显误解和下一步建议压缩成更容易调用的内容。

比如学员刚问过一个概念，下一轮再回答时，AI 教练能知道他刚刚纠结在哪里；如果学员暂停后回来，系统也能从摘要里恢复这一节课的学习脉络。短期记忆不会直接改变学员的长期掌握状态，它主要让课堂不割裂。

2.2.4 长期记忆如何写入

长期记忆只在正式回答完成评估、课堂结束判断允许、证据规则满足时写入。系统会根据本次回答表现更新学员对相关知识点的掌握情况，并安排合适的复习节奏。如果学员已经掌握，复习会被安排得更远；如果学员仍需要复习或重学，复习会更快出现。这个策略让课堂结果能够回到学习档案和后续复习安排里，避免只停留在一条聊天反馈中。

2.2.5 学习反思如何形成

学习反思是更高一层的教学观察。系统会在评估结束后观察学员是否有值得沉淀的学习信号，例如总能说出结论但解释不清原因，或者能背出定义却不会放进业务场景。反思内容会用于后续课堂的引导方式，让 AI 教练更像一个逐渐了解学员的老师。

2.2.6 记忆系统的安全边界

记忆系统有三条关键边界。第一，学员没有读完正文时，系统不会把本轮表现写成长期掌握结论，因为此时无法判断学员是否真正学习过当前内容。第二，资料证据不足或冲突时，系统不会进行正式评价和长期记忆更新，以免污染后续学习档案。第三，系统会识别重复点击和网络重试，避免同一轮回答被重复评分、重复写入或重复创建复习安排。

2.3 课堂交互

2.3.1 学习法切换

课堂支持掌握学习法、主动回忆法和费曼学习法。学员切换学习法后，系统会更新本节课的教学节奏，重新安排开场提示、追问方式、评价重点和主动介入方式。同样一份教材，在不同学习法下会产生不同的课堂体验。

2.3.2 掌握学习法如何实现

掌握学习法的核心是“先理解，再练习，再确认是否达标”。学员进入课堂或切换到掌握学习法后，系统会提示他先阅读正文，读完后用自己的场景回答问题。阅读完成前，AI 教练主要做解释和阅读引导；读完后，AI 教练会围绕定义、判断条件、关键步骤和业务例子安排练习。

评估时，系统会同时看理解、表达和应用。理解主要看概念是否准确，表达主要看回答是否清楚，应用主要看学员是否能把知识放进真实场景。回答达标后，系统允许课堂结束并更新学习档案；回答不达标时，AI 教练会根据缺漏点给提示，必要时安排再练一轮。

2.3.3 主动回忆法如何实现

主动回忆法的核心是“先从脑子里取出来，再对照资料补漏”。系统会先让学员带着记忆线索阅读，读完后尽量不看原文，凭记忆写下关键点。AI 教练会更像回忆陪练，先鼓励学员自己说，再用关键词、顺序提示或二次确认帮助他把遗漏内容补回来。

评估时，系统更重视学员能否主动提取关键点。反馈阶段会推动学员把遗漏点用自己的话补一句，必要时做第二次确认。长期记忆写入时，系统会记录本次学习中暴露出的薄弱点，后续复习也会优先采用回忆式提问，帮助学员把知识真正记住。

2.3.4 费曼学习法如何实现

费曼学习法的核心是“讲给新人听”。学员切换到费曼学习法后，系统会提醒他读完后用大白话解释当前概念。AI 教练会检查概念是否准确、逻辑是否连贯、表达是否足够让新人听懂。如果回答里有跳步、含混或缺少例子，系统会让学员按建议重新讲一版。

评估时，系统会把表达清晰度放在更重要的位置。一个回答即使概念大致正确，如果讲得绕、缺少例子，或者让没有背景的人听不懂，AI 教练也会继续引导学员重讲。长期记忆写入时，系统会记录表达薄弱点、常见误解和下一步建议，后续课堂能够继续针对“讲清楚”这个问题调整引导方式。

2.3.5 三种学习法共用的底层控制

三种学习法共享同一套阅读门禁、证据规则、任务规划、工具安全边界、结构化评估和记忆写入。差异主要体现在开场提示、追问方式、评分重点和主动介入方式上。这样既能保持课堂安全边界一致，又能让学员感受到不同学习法带来的节奏差异。

2.3.6 主动介入

前端会在学员空闲、草稿停留、阅读位置变化等场景向课堂运行时发送现场信号。系统会先判断是否真的需要打扰学员，如果学员正在阅读或刚刚收到提示，系统会选择不打扰；如果学员明显卡住，AI 教练会给一句短提示，帮助学员继续推进。

flowchart LR
  S["现场信号<br/>空闲、草稿卡住、阅读位置变化"] --> R["记录现场状态"]
  R --> C["整理课堂上下文"]
  C --> P["判断是否需要介入"]
  P --> G["检查冷却时间、次数和阅读状态"]
  G -->|暂不打扰| SK["只记录判断结果"]
  G -->|需要介入| MSG["生成一句短提示并展示给学员"]

2.4 Agent 相关技术知识点的实现策略

2.4.1 Agent Runtime

课堂 Agent Runtime 是课堂的总控中心。它负责保存会话状态、读取课堂规则、调用模型、执行工具、写入消息、记录学习事件并返回最新课堂状态。这样设计的价值是把课堂规则集中管理，前端专注展示和交互，API 专注接收请求，课堂决策集中在运行时中完成。

2.4.2 Task Planning / 任务规划

任务规划负责判断本轮互动应该做什么。它会根据学员消息、课堂状态、学习法、教材内容、证据情况和历史记忆，决定这一轮更适合讲解、追问、提示、评估，还是回忆过去内容。对于明显属于正式回答的场景，系统会直接进入评估流程，减少不必要的规划调用。

2.4.3 ReAct Loop / 推理与行动循环

ReAct 规划循环让 AI 在“提出动作”和“收到规则反馈”之间自我修正。比如任务规划器想在学员还没有读完正文时评分，工具安全边界会拒绝这个动作，并把拒绝原因反馈给任务规划器，让它重新选择讲解或阅读提示。系统会限制重新规划次数，避免循环过长。

2.4.4 Tool Registry / 工具注册表

课堂工具会被集中登记和管理，主要分为上下文整理、教学规划、回复生成、回答评估、课堂结束判断、记忆更新、主动介入、对话摘要和安全检查等类型。每类工具都有明确的使用场景和边界，模型只能在课堂运行时允许的范围内调用。

2.4.5 Tool Guardrails / 工具安全边界

工具安全边界会根据阅读状态、证据状态、消息类型、课堂阶段和候选工具决定是否允许执行。正式评估、课堂结束和长期记忆写入都要求学员已经读完正文，并且当前资料证据能够支撑评价。普通解释在证据不足时只能做通用说明，不能被包装成企业资料结论。

2.4.6 RAG Grounding / 检索增强与证据约束

课堂会优先使用本节课已经锁定的知识文稿和证据切片作为回答依据。学员进入课堂时，系统已经确定当前课时、当前知识点、教材版本和可引用资料范围，因此课堂里的 RAG 每一轮都以本节课允许使用的证据为边界，先整理上下文，再让 AI 教练讲解、追问或评估。

当学员只是提问概念时，AI 教练会把教材正文、当前内容块、相关证据和最近对话一起放入上下文，生成自然语言讲解。当学员提交正式回答时，系统会把回答和评估标准一起交给评估器，评估器只能根据当前教材、证据和课堂规则判断掌握情况。如果证据不足或资料存在冲突，课堂会继续做一般解释和阅读引导，但不会给出确定性掌握结论，也不会把结果写入长期学习记忆。

2.4.7 Structured Output / 结构化输出

Planner、评估器、主动介入、摘要和反思都要求模型按结构化格式返回结果。系统会检查模型输出是否完整、是否能被解析、是否符合课堂规则。这个策略能够减少模型自由发挥对课堂状态的影响，让评估、记忆和课堂结束判断更稳定。

2.4.8 Context Engineering / 上下文工程

课堂运行时会把课程、课时、教材、证据状态、阅读状态、学习法、最近消息、课堂摘要、学员画像和学习记忆整理成一份上下文包。模型看到的内容带有边界、来源和可用动作说明，避免直接面对零散数据。这样能够让 Planner 和回复生成更加稳定，也让系统在模型请求工具前完成权限校验。

2.4.9 Tracing / 调用链路追踪

每一轮课堂都会留下运行记录和模型调用记录。团队能够追查某一轮为什么追问、为什么没有评估、为什么没有更新长期学习记录、模型输入输出是什么、哪一步发生降级或失败。对非技术读者来说，这就是课堂后台的“过程留痕”。

2.4.10 Idempotency / 幂等控制

学员消息、快捷动作、阅读完成和记忆写入都会做幂等控制。网络抖动、重复点击或页面重试不会导致同一条消息被重复评估，也不会重复更新学习档案。

3. 课程生产 Agent

课程生产 Agent 的价值在于把一句自然语言课程目标变成可预览、可质检、可发布、可追溯证据的课程包。管理员只需要说明想做什么课程、给谁学、希望使用哪些资料，系统会在后台完成目标理解、资料检索、证据筛选、课程结构生成、课时正文生成、质量检查和预览发布。

3.1 实现机制

3.1.1 从管理员输入到任务入队

sequenceDiagram
  participant Admin as 管理员
  participant Web as 知识库页面
  participant API as API
  participant Service as 课程生产服务
  participant DB as 任务与课程数据

  Admin->>Web: 输入课程目标并选择资料来源
  Web->>API: 提交课程生产意图
  API->>Service: 判断目标是否适合生成课程
  Service->>Service: 识别课程目标、受众和资料范围
  Service-->>API: 返回判断结果和规范化目标
  Web->>API: 确认创建课程生成任务
  API->>Service: 创建后台任务
  Service->>DB: 保存任务和初始状态
  DB-->>Web: 返回任务进度

3.1.2 后台课程生产流程

flowchart TB
  A["Worker 领取课程生成任务"] --> B["目标规划<br/>把课程目标转成检索线索"]
  B --> C["关键词召回<br/>寻找明确命中的资料"]
  C --> D["向量召回<br/>寻找语义相近的资料"]
  D --> E["融合排序<br/>合并多路结果并控制数量"]
  E --> F["主题过滤<br/>剔除偏离课程目标的资料"]
  F --> G["知识点选择<br/>确定课程要覆盖的重点"]
  G --> H["课程骨架生成<br/>生成标题、简介和课时结构"]
  H --> I["逐课时内容生成<br/>生成主教材正文和知识卡片"]
  I --> J["正文质量修复<br/>内容不足时补充和扩写"]
  J --> K["质量门禁<br/>检查证据、课时、正文和引用"]
  K --> L["创建预览包<br/>等待管理员确认"]

课程生成是一个耗时任务，所以由 Worker 在后台推进。每一步都会更新任务状态和运行记录，管理员能在页面上看到进度。如果任务执行过程中服务重启，系统也会尽量通过任务状态继续恢复处理。

3.1.3 召回与排序机制

课程生产会同时使用关键词召回、向量召回、范围兜底召回和联网搜索召回。关键词召回更适合命中明确名称，向量召回更适合理解语义相近内容，范围兜底用于资料范围明确但关键词没有命中的情况，联网搜索用于管理员明确选择公开网络资料的场景。

实际执行时，系统会先把管理员的一句话课程目标拆成关键词、语义查询、预期知识点和资料范围。然后按资料来源策略决定先查个人资料、企业资料、混合资料，还是公开网络资料。企业课程只使用企业知识库；个人课程默认优先使用个人资料；如果管理员允许混合检索，个人资料不足时会补充企业资料；如果管理员明确选择联网搜索，系统会只使用网页结果，并且要求每条资料都有可追溯的网址。

flowchart LR
  A["课程目标"] --> B["提炼关键词、语义查询和预期知识点"]
  B --> C["关键词召回"]
  B --> D["向量召回"]
  B --> E["知识点证据召回"]
  C --> F["候选资料池"]
  D --> F
  E --> F
  F --> G{"命中是否足够"}
  G -->|不足| H["指定范围兜底"]
  G -->|足够| I["合并去重"]
  H --> I
  I --> J["综合重排"]
  J --> K["主题过滤和数量控制"]
  K --> L["送入课程生成"]

重排会把多种信号合在一起判断。系统会重点看这条资料被多少种召回方式命中、语义距离是否接近、关键词是否直接命中、是否落在管理员指定的资料范围内、资料质量是否可靠，以及它是否已经和某个知识点建立了清晰连接。整体权重上，检索命中强度占比最高，其次是语义接近度，再往后是关键词、资料范围、资料质量和知识点连接。混合检索时，如果任务目标强调个人学习资料，个人资料会获得额外优先级。

为了避免某一份长文档占据全部上下文，系统会做数量控制。送入模型前，候选资料会先合并去重，同一文档版本和同一来源文档都会有上限，最终只保留最靠前的一批证据片段。随后系统还会做主题过滤，把明显不包含课程核心词、预期知识点或相近表达的资料剔除。这样做的目的，是让模型看到的资料少而准，生成课程时更容易围绕目标展开。

如果关键词和向量都没有命中，系统会进入范围兜底，只在管理员指定的资料范围内挑选证据，并在质量检查里标记这次生成使用了降级策略。如果个人资料命中太少，而管理员允许补充企业资料，系统会再次检索企业知识库，并记录为什么触发补充。这个过程会进入运行日志，方便后续判断是资料不足、向量服务异常，还是课程目标写得过于宽泛。

3.1.4 课程内容生成机制

课程生产采用“先搭课程骨架，再逐课时生成内容”的方式。系统会先生成课程标题、简介、目标水平和课时结构，再为每一节课选择对应证据，生成主教材正文、知识卡片和来源关系。这样每节课使用的资料更精准，也更容易定位哪一节课质量不足。

系统会要求模型把来源关系放在结构化结果里，正文里不直接写一串难懂的证据标记。前端展示时再用更自然的方式说明资料来源，避免学员或管理员在正文中看到内部引用痕迹。

3.1.5 质量门禁和发布机制

质量门禁会检查预览包是否具备发布条件，包括是否有课时、课时是否绑定证据、正文是否完整、知识卡片是否有来源、引用资料是否属于本次候选范围、向量检索是否降级、证据是否贴合课程主题。未通过质量门禁的课程仍然能预览，但不能进入正式发布。

发布时，系统会再次检查质量报告，然后把课程预览包转成正式课程、课时、知识文稿和证据关系。发布操作会记录处理过程，重复点击不会重复创建课程。

3.2 Agent 相关技术知识点的实现策略

3.2.1 Intent Recognition / 意图识别

课程生产入口会先判断管理员输入是否适合生成课程，并抽取规范化课程目标、目标受众和资料来源偏好。这个 Agent 会把闲聊、查资料、系统排查、目标过于模糊等请求挡在任务创建前，让后台生成资源用在真正的课程生产上。

3.2.2 Query Planning / 查询规划

Query Planner 会把自然语言课程目标转换为关键词、语义查询、预期知识点和约束。它负责为检索准备更好的线索，不直接生成课程正文。即使模型规划失败，系统也会使用规则兜底提取关键词，保证后续检索还有基础输入。

3.2.3 Hybrid Retrieval / 混合检索

课程生产会融合关键词召回、向量召回、知识点证据召回和范围兜底召回。这个策略既能处理明确术语，也能处理自然语言表达，还能在指定资料范围内兜底。对于个人资料不足的情况，系统会按配置决定是否补充企业知识库资料，并记录补充原因。

3.2.4 Evidence Grounding / 证据约束

课程生产生成的课程骨架、课时正文、知识卡片和来源引用都必须绑定资料证据。质量门禁会拒绝没有证据支撑的关键内容。这样发布后的课程会成为有资料依据的课程资产，避免变成一篇孤立的 AI 文案。

3.2.5 Structured Output / 结构化输出

课程生产使用结构化输出控制课程骨架、课时正文、知识卡片和正文修复结果。后端会对模型输出做规范化处理，缺失内容会使用可控规则补齐，不合法引用会被过滤，正文质量不足会触发修复。

3.2.6 Durable Execution / 持久化任务执行

课程生成是长任务，所以系统使用后台 Worker、任务状态、步骤状态、心跳和租约来保障执行过程。Worker 领取任务后需要持续证明自己还在处理，如果处理进程异常退出，系统能够通过任务状态继续追踪问题。

3.2.7 Quality Gate / 质量门禁

质量门禁是课程生产 Agent 的最后一道控制。它不会只看模型有没有返回内容，还会检查证据数量、正文质量、课时结构和引用合法性。质量报告会进入预览包，让管理员知道课程为什么能发布，或者为什么只能预览。

3.2.8 Tracing / 调用链路追踪

课程生产每个阶段都会留下运行记录，包括目标规划、检索策略、关键词召回、向量召回、排序、课程生成、修复、质量检查和预览包创建。管理员页面能够展示任务进度，运营和技术团队能够追查失败原因。

3.2.9 Human-in-the-loop / 人工确认

课程生产不会自动发布。Worker 只生成预览包，管理员需要查看预览、确认质量，再点击发布。废弃、重新生成、发布都会记录操作过程，让 AI 生产内容进入正式课程前保留人工确认。

4. 知识库

知识库是 AI 课堂和课程生产的基础。它负责把原始资料变成可检索、可引用、可评估、可生成课程的知识资产。系统同时支持学员知识库和企业知识库，资料来源会被清楚区分，方便后续做权限、范围和引用控制。

4.1 实现机制

4.1.1 知识库导入全流程

flowchart TB
  A["管理员选择知识库并上传文件"] --> B["系统保存文件并记录基础信息"]
  B --> C["创建来源文档和解析任务"]
  C --> D["Worker 领取解析任务"]
  D --> E["提交到 RAGFlow<br/>按知识库配置解析"]
  E --> F["同步解析进度"]
  F --> G["拉取解析后的文本切片"]
  G --> H["规整为平台证据切片"]
  H --> I["保存为可引用资料证据"]
  I --> J["知识后处理 Worker"]
  J --> K["生成 Embedding 向量"]
  K --> L["大模型抽取知识点和关系"]
  L --> M["形成知识点、证据绑定和知识关系"]

这个流程把“上传文件”拆成两个后台步骤。第一步是解析文件并形成证据切片，第二步是向量化和知识图谱抽取。解析依赖 RAGFlow，后处理依赖 Embedding 和大模型。管理员在前端看到的是资料从上传、解析、处理到可用的状态变化。

4.1.2 来源文档和版本

系统会把资料分成来源文档和文档版本。来源文档表示“这份资料是什么”，文档版本表示“这份资料的某一次文件内容和处理状态”。这样的结构支持重新上传、重新解析、对比版本和保留历史处理记录。

4.1.3 RAGFlow 解析机制

知识导入流程会领取待解析任务，确认解析服务可用后，把文件提交到对应的数据集。提交后，Worker 会持续同步解析进度，解析完成后再把文本切片拉回本系统，整理成统一的资料证据。管理员暂停或终止任务时，Worker 会在关键步骤前重新检查状态，发现任务已经暂停或终止就停止处理并记录原因。

4.1.4 向量化机制

向量化会把证据切片转换成适合语义检索的向量。完成后，课程生产和知识库查询就能根据“意思相近”找到资料，而不只依赖完全一样的关键词。系统会检查向量结果是否完整、维度是否符合配置，只有通过检查后才会把资料标记为可用于语义检索。

4.1.5 知识图谱抽取机制

知识后处理会从资料证据中抽取知识点和知识点之间的关系。系统会先把证据切片分批交给模型，每一批只处理有限数量的片段，并要求模型只输出资料里能支撑的知识点和关系。模型返回后，系统会继续做校验，检查名称是否完整、类型是否在规范内、置信度是否达标、证据是否真的来自输入资料、关系方向是否合理。只有通过这些检查的内容才会进入正式知识库。

flowchart TB
  A["证据切片"] --> B["分批抽取知识点"]
  B --> C["抽取关系"]
  C --> D["类型和方向校验"]
  D --> E["证据绑定校验"]
  E --> F{"是否通过"}
  F -->|通过| G["写入知识点、证据绑定和图谱关系"]
  F -->|未通过| H["记录拒绝原因，等待复查"]

系统默认把资料里的知识对象分成六类。这样的分类比“所有东西都叫知识点”更清晰，因为课程生产需要知道哪些内容适合当教学目标，哪些内容是业务场景，哪些内容是方法步骤，哪些内容只是工具或模板。

关系类型也有明确边界。系统不会接受模型随意创造的关系名，也不会接受方向明显不合理的关系。例如“方法包含步骤”成立，但“场景包含步骤”就不符合这套图谱规则；“一般相关”这类宽泛关系必须写清楚原因，否则会被拒绝。

图谱写入时，系统还会保留被拒绝的候选内容和拒绝原因。常见拒绝原因包括没有名称、类型不在规范里、置信度太低、缺少有效证据、关系两端找不到对应知识对象、关系方向不符合规则，以及“一般相关”没有解释。这样做能让后续运营和教学设计人员知道模型尝试抽取了什么，也能判断资料本身是否需要补充。

4.1.6 知识库服务前端

知识库页面把资料管理和课程生成放在同一个工作台中。资料管理侧关注知识库、来源文档、解析任务、证据切片和知识图谱；课程生成侧关注生成任务、预览包、质量报告、发布和废弃。前端通过统一服务入口调用后端，页面不直接处理数据库细节。

4.2 Agent 相关技术知识点的实现策略

4.2.1 RAG / 检索增强生成

知识库的 RAG 基础是证据切片。RAGFlow 负责把文档切成文本片段，本系统再把这些片段整理成可引用、可检索、可追溯的资料证据。AI 课堂和课程生产都会基于这些证据片段进行引用。

4.2.2 Chunking / 文档切片

Chunk 是文档被拆成的小片段。不同资料适合不同拆法，例如手册、问答、表格、论文、书籍和图片资料的解析方式并不相同。系统会清洗和控制传给解析服务的配置，避免内部字段污染外部解析服务。

4.2.3 Embedding and Vector Search / 向量化与向量检索

Embedding 用于把资料片段变成向量，Vector Search 用于寻找语义相近的内容。课程生产会把课程目标转换成语义查询，再用向量检索找相近证据。运行守卫也会检查系统中是否有可用的向量资料，避免用户发起无法完成的 AI 搜索或课程生成。

4.2.4 Knowledge Graph / 知识图谱

知识图谱由知识对象、关系和证据三部分组成。知识对象解决“资料里有哪些可教学内容”，关系解决“这些内容之间怎么连接”，证据解决“为什么说这条连接成立”。系统会把图谱关系和原始证据绑定在一起，因此后续课程生产使用图谱时，仍然能够回到资料来源。

图谱的实现策略有三层约束。第一层是类型约束，只有概念、目标、场景、规则约束、方法和工具产物这六类对象会被写入图谱。第二层是关系约束，系统只接受预先定义的关系类型，并检查关系两端的对象类型是否匹配。第三层是证据约束，每个知识对象至少要有一段资料证据，每条关系也必须有资料片段支撑。三层都通过后，这条知识才会进入后续检索、课程组织和课堂引导。

4.2.5 Evidence Binding / 证据绑定

证据绑定贯穿知识库、课程生产和课堂。知识点绑定证据，课程课时绑定证据，知识文稿内容块绑定证据，课堂回复保留证据引用，评估和长期记忆也受到证据规则限制。这个设计让 AI 输出能够回到原始资料。

4.2.6 Metadata Filtering / 元数据过滤

课程生产和知识库查询会按照个人知识库、企业知识库、来源文档、文档版本、知识点和状态进行过滤。这个策略让同一个系统能够服务个人资料学习、企业资料学习和混合检索，并且保持资料来源边界清晰。

4.2.7 Hybrid Retrieval / 图谱与向量混合检索

项目采用图谱与向量混合检索。向量检索负责找到“意思接近”的资料，关键词检索负责找到“字面明确命中”的资料，知识图谱负责把资料从单个片段扩展到相关知识点、前后关系和适用场景。课程生产会先收集这些候选资料，再统一去重、重排、过滤和限量。

举例来说，管理员输入“生成一门面向销售新人的 RAG 课程”时，关键词检索会命中包含 RAG 的片段，向量检索会命中“检索增强生成”“基于资料回答”这类表达相近的内容，知识图谱会帮助系统找到相关的目标、方法、规则和场景，例如“证据绑定”“回答可追溯”“销售话术训练”。这些结果合并后，系统会优先选择主题贴合、来源可靠、证据充足并且能支撑课时结构的资料。

4.2.8 Background Job / 后台任务执行

知识导入和知识后处理都由 Worker 执行。解析 Worker 会处理暂停、终止、等待外部服务和失败恢复；知识后处理 Worker 会批量处理待向量化和待抽取的资料。运行记录让这些后台动作对管理员和团队可见。

4.2.9 Tracing / 调用链路追踪

知识导入会记录上传、解析配置、RAGFlow 提交、解析进度、切片同步、证据发布、向量索引和知识图谱提升等事件。出现失败时，系统会记录失败阶段、错误信息和对应任务，让问题排查有据可依。