多Agent协同重构教学资料：数据库课程教案自动化实践-平芜编程栈

1. 项目概述：当一门课的“散装资料”撞上 WorkBuddy 的多 Agent 协同引擎

我带数据库原理与应用这门课已经七年了，每年开学前最头疼的不是备课内容，而是整理资料——学生用的 PDF 讲义、自己写的 Word 笔记、从 MOOC 下载的视频字幕、零散的 SQL 练习题截图、往届学生的错题汇总 Excel 表、甚至还有几页手写板书拍照……全堆在一个叫“数据库_2024秋”的文件夹里，命名五花八门：“ch3-索引优化_v2_final(改).pdf”、“索引那块儿的几个例子.docx”、“视频05-查询执行计划-字幕.txt”、“学生问的B+树分裂问题.png”。去年我试过用传统 PPT 软件硬拖硬贴，结果做出来的教案逻辑断层，PPT 页面堆满文字，动画全是“淡入”，讲到 B+ 树分裂时学生眼神放空——不是内容不行，是信息没被真正“消化”过。

直到我用 WorkBuddy 搭建了一套教学资料自动重组流水线。它不是个“AI 一键生成 PPT”的玩具，而是一套可配置、可追踪、可复用的多 Agent 协同工作流。我把原始散装资料扔进去，系统自动拆解、归类、校验、重构：一个 Agent 负责识别并提取 PDF 中的定义与定理（比如“事务的 ACID 特性”），另一个 Agent 对比教材目录结构，把零散内容锚定到“第6章并发控制”下；第三个 Agent 把 SQL 练习题按难度和知识点打标，生成带解析的卡片；最后一个 Agent 把所有结构化输出喂给 PPT 引擎，自动生成带分步动画的 B+ 树分裂示意图页面，连配色都按教学场景做了区分——概念页用蓝灰冷色调，案例页用橙黄暖色强调，错误陷阱页加红色警示边框。整个过程不依赖提示词反复调试，也不需要手动复制粘贴，更不会把“对偶问题”和“凸优化”混进数据库章节。核心在于：WorkBuddy 把教师脑中的知识图谱，变成了可执行、可验证、可迭代的工程化流程。

这个项目解决的不是“怎么快速做 PPT”，而是“如何让教学资料从静态存储态，变成动态服务态”。适合三类人直接抄作业：高校教师要批量处理新学期课程资料；职业教育讲师需快速适配不同培训大纲；教育科技公司做课件自动化工具时，能直接参考其 Agent 分工逻辑与数据流转设计。关键词 WorkBuddy、教案、PPT、多 Agent 协同、数据库原理与应用，不是标签，而是这套方案的四个技术支点——WorkBuddy 是执行底座，教案是结构化输出目标，PPT 是可视化交付载体，多 Agent 协同是实现复杂逻辑拆解的核心范式，而数据库原理与应用，则是验证这套流程是否真正“懂教学”的严苛考题。

2. 教学资料的“散装”本质与 WorkBuddy 的协同架构设计

2.1 为什么传统方法在教学资料处理上必然失效？

很多人以为“整理资料=重命名+归类文件夹”，但教学资料的“散装”本质远不止于此。以《数据库原理与应用》为例，它的散装性体现在三个不可分割的维度：

第一是语义碎片化。同一知识点分散在不同载体中：教材 PDF 里有“封锁协议”的定义，Word 笔记里有“两阶段锁”的手绘流程图，Excel 表格里存着“死锁检测算法”的伪代码，而学生提问截图里则藏着真实困惑——“为什么时间戳协议不能完全避免幻读？”。这些内容在物理上分离，在语义上却高度耦合。传统搜索只能匹配关键词，无法理解“时间戳协议→幻读→隔离级别→并发控制”这条隐含的知识链。

第二是结构非对齐。教材目录是“第7章事务管理”，MOOC 视频分集叫“ACID 与隔离级别详解”，而你自己的教案草稿可能按“问题驱动”组织：“学生常问的3个事务误区”。三套结构互不映射，强行合并只会制造逻辑断层。我试过用 Notion 手动建立双向链接，结果维护成本极高——每次更新一个知识点，就得同步修改十几处关联。

第三是意图模糊化。一份“B+ 树插入过程.png”图片，对教师是教学演示素材，对学生是复习图示，对助教是批改参考依据。同一份资料承载多重教学意图，但文件属性里没有任何字段能标记“适用场景：课堂演示/课后自学/考试重点”。没有意图标注，自动化就失去决策依据。

这三点叠加，决定了任何单点工具（如 PDF 提取工具、PPT 插件、笔记软件）都无法根治问题。必须用系统级方案——而 WorkBuddy 的多 Agent 架构，恰恰是为这种复杂、异构、高意图密度的任务设计的。

2.2 WorkBuddy 多 Agent 协同的底层分工逻辑

WorkBuddy 不是“一个大模型包打天下”，而是把教学资料处理任务拆解成四个专业 Agent，每个 Agent 专注一个不可替代的子任务，并通过标准化数据契约（Data Contract）交换信息。这种设计源于我对教育场景的长期观察：优秀教师备课时，大脑也在进行类似分工——有人负责梳理知识脉络（架构师），有人深挖案例细节（研究员），有人设计呈现方式（视觉设计师），有人校验教学效果（质量官）。WorkBuddy 把这种人类认知模式，转化成了可部署的工程模块。

Knowledge Extractor Agent（知识抽取 Agent）：专精于非结构化文本与图像的理解。它不简单 OCR，而是结合数据库领域知识库（我预置了《数据库系统概念》第六版术语表、SQL 标准语法树、常见错误模式库），对 PDF 文字进行语义增强解析。例如看到“T1: R(A), W(A), R(B)；T2: R(A), W(A), R(B)”，它能自动识别这是“事务调度示例”，并提取出读写操作序列、冲突关系、可串行化判定结论，而非仅存为字符串。对“B+ 树分裂示意图.png”，它调用轻量级 CV 模型定位节点、指针、键值，再结合领域规则生成结构化描述：“根节点键值[15,30]，左子树含键值[5,10,12]，右子树含键值[35,40,45]，分裂后新根键值30”。
Curriculum Mapper Agent（课程映射 Agent）：解决结构非对齐问题。它内置了三套权威课程结构模板：高等教育出版社《数据库原理及应用教程》目录、MOOC 平台“数据库系统概论”课程大纲、以及我自定义的“问题导向教学法”结构（按“典型问题→原理支撑→案例验证→常见误区”组织）。当 Knowledge Extractor 输出“封锁粒度”知识点时，它不靠关键词匹配，而是用图神经网络计算语义距离，将该知识点锚定到三套结构中最优位置——比如在教材结构中归属“第6章并发控制”，在问题导向结构中则归入“典型问题：如何平衡并发性能与数据一致性？”。
Pedagogy Formatter Agent（教学格式化 Agent）：把知识转化为教学资产。它掌握教学法硬规则：定义类内容必须配生活类比（如“事务回滚就像微信转账失败后自动退款”），算法类内容必须有分步执行动画脚本（如“B+ 树插入”拆解为“查找叶节点→插入键值→判断溢出→分裂节点→更新父节点”5帧），易错点必须生成对比表格（如“共享锁 vs 排他锁”列“能否读取”“能否写入”“能否兼容其他锁”）。它输出的不是纯文本，而是带元标签的 Markdown：[concept:ACID][analogy:银行转账][difficulty:core]，这些标签成为后续 PPT 生成的指令源。
PPT Generator Agent（PPT 生成 Agent）：最后的交付引擎。它不生成“通用 PPT”，而是严格遵循 Pedagogy Formatter 输出的元标签与结构指令。例如收到[concept:B+树分裂][animation:step-by-step][visual:tree-diagram]，它调用本地安装的 python-pptx 库，动态生成 5 页 PPT：第1页展示未分裂状态，第2页高亮待插入键值，第3页显示分裂临界点，第4页呈现新节点结构，第5页用箭头动画演示指针重连。配色方案由教学场景决定：课堂演示页用深蓝背景+白字（高对比度），自学材料页用浅灰背景+深蓝字（护眼），考试重点页加红色边框+放大镜图标。

四个 Agent 之间不共享内存，只通过 Kafka 消息队列传递结构化 JSON 数据包，每个包包含source_id（原始文件哈希）、knowledge_id（知识唯一标识）、curriculum_path（课程结构路径）、pedagogy_meta（教学元标签）。这种松耦合设计带来两个关键优势：一是可单独升级某个 Agent（比如换用更强的 CV 模型处理手写板书），不影响整体流程；二是所有操作可审计——我能查到某页 PPT 的第3帧动画，源自哪份 PDF 的第12页第4段文字，经哪个 Agent 的哪次处理生成。

2.3 为什么选 WorkBuddy 而非其他 AI 工具？

市面上有大量“AI 做 PPT”工具，但它们在教学场景中集体失效，原因很现实：

通用大模型缺乏领域纵深：让 ChatGPT 写“数据库事务隔离级别”PPT，它能罗列四种级别，但无法判断“可重复读”在 MySQL 和 PostgreSQL 中的实现差异，更不会提醒你：讲解时必须强调“幻读”在范围查询中的表现，否则学生做实验会困惑。WorkBuddy 允许我注入领域知识库（如 MySQL 官方文档片段、PostgreSQL 源码注释），让 Agent 在推理时调用这些“外挂记忆”。
单体架构无法应对多意图：一个“学生错题汇总.xlsx”文件，对 Knowledge Extractor 是数据源，对 Curriculum Mapper 是知识点分布热力图，对 Pedagogy Formatter 是“常见误区”素材库。通用工具要求你先手动分类再分别处理，而 WorkBuddy 的 Agent 可同时消费同一份输入，各自产出不同维度的结构化输出。
黑盒流程不可控：某款 PPT 工具生成的“索引优化”页，把 B 树和哈希索引用同一张图示意，技术上错误。我无法干预它的中间决策。WorkBuddy 的每个 Agent 都暴露可配置参数：Knowledge Extractor 的置信度阈值（低于0.85的提取结果自动进入人工审核队列），Curriculum Mapper 的结构匹配权重（教材目录权重0.6，MOOC大纲权重0.3，自定义结构权重0.1），这些参数让我始终握有最终解释权。

最关键的是部署形态——WorkBuddy 支持本地化部署，所有教学资料（包括学生作业、考试题库）不出内网。这对高校教师是刚需，不是功能选项。我测试过把整门课的 PDF、Word、Excel、PNG 扔进 WorkBuddy 工作区，总数据量 2.3GB，处理耗时 18 分钟，生成教案 Markdown 127 页，PPT 89 页，全部离线完成。这种可控性，是云端 SaaS 工具永远无法提供的教学尊严。

3. 实战全流程拆解：从散装文件夹到可交付教案与 PPT

3.1 环境准备与 WorkBuddy 初始化配置

WorkBuddy 的安装本身不复杂，但教学场景的特殊性决定了初始化配置才是成败关键。我用的是 WorkBuddy 企业版 2.4.1（Linux Ubuntu 22.04 LTS），所有组件均部署在本地服务器，不依赖任何外部 API。以下是必须完成的六项配置，缺一不可：

第一步：创建教学领域知识库
这不是简单的“上传文档”，而是构建一个可查询的向量数据库。我用 ChromaDB 作为向量存储，嵌入模型选用text2vec-large-chinese（针对中文教材优化）。知识库包含三类内容：

权威教材原文：高等教育出版社《数据库原理及应用教程》PDF 全文（已去除页眉页脚，OCR 识别准确率 99.2%）；
标准术语表：从 SQL 标准文档、IEEE 计算机词典中提取的 1276 个数据库术语，每条含定义、英文名、常见变体（如“封锁”也收录“加锁”“锁定”）；
错误模式库：过去三年收集的学生典型错误，每条含错误代码、错误现象、正确写法、教学提示（如“WHERE 子句中使用聚合函数未加 GROUP BY”对应提示：“聚合函数作用域是分组后，GROUP BY 是分组指令”）。

提示：知识库初始化后，必须运行validate_knowledge_integrity.py脚本校验术语覆盖度。我曾发现“多粒度封锁”词条缺失，导致相关知识点提取失败，及时补全后才继续流程。

第二步：定义课程结构 Schema
在 WorkBuddy 后台的curriculum_schema.json中，我定义了三层结构：

{ "course": "数据库原理与应用", "chapters": [ { "id": "ch6", "name": "并发控制", "sections": [ {"id": "6.1", "name": "事务特性", "learning_objectives": ["掌握ACID四要素"]}, {"id": "6.2", "name": "封锁协议", "learning_objectives": ["理解两阶段锁原理"]} ] } ] }

这个 Schema 不是静态目录，而是教学逻辑骨架。Curriculum Mapper Agent 会严格按此结构归类知识点，并自动检查“学习目标”字段是否被覆盖——如果某知识点找不到匹配的 learning_objectives，它会触发告警，避免知识遗漏。

第三步：配置 Agent 工作流
在workflow_config.yaml中声明四个 Agent 的执行顺序与数据契约：

agents: - name: knowledge_extractor input: ["*.pdf", "*.docx", "*.txt", "*.png"] output: "knowledge_json" params: {confidence_threshold: 0.85, max_context_length: 2048} - name: curriculum_mapper input: "knowledge_json" output: "mapped_json" params: {schema_ref: "curriculum_schema.json", match_weight: [0.6, 0.3, 0.1]} - name: pedagogy_formatter input: "mapped_json" output: "pedagogy_md" params: {analogy_db: "teaching_analogies.json", animation_rules: "animation_rules.json"} - name: ppt_generator input: "pedagogy_md" output: "output_pptx" params: {template_path: "/templates/database_classic.pptx", font: "思源黑体"}

特别注意animation_rules.json：我为数据库核心算法预设了 27 条动画规则，如“B+树分裂”必须生成 5 帧，“查询执行计划”必须用颜色区分扫描方式（全表扫描红，索引扫描蓝，哈希连接绿）。

第四步：准备原始资料文件夹
我的database_raw/文件夹结构如下：

database_raw/ ├── textbook/ # 教材扫描件 │ └── db_concept_6th.pdf ├── notes/ # 教师手写笔记（已转为 PNG） │ └── ch6_lock_protocol.png ├── exercises/ # 练习题 │ ├── sql_practice.xlsx │ └── transaction_quiz.docx ├── videos/ # MOOC 字幕 │ └── video05_transcript.txt └── student_work/ # 学生作业（脱敏处理） └── midterm_errors.xlsx

注意：所有文件名禁止中文括号、空格、特殊符号。WorkBuddy 默认忽略.开头的隐藏文件，所以.gitignore这类文件可安全存在。

第五步：设置教学意图标签体系
在intent_tags.json中定义 12 个教学意图标签，每个标签绑定生成规则：

{ "class_demo": {"prio": 1, "ppt_layout": "full_image", "animation": "step_by_step"}, "self_study": {"prio": 2, "ppt_layout": "two_column", "font_size": 18}, "exam_focus": {"prio": 3, "ppt_layout": "highlight_box", "border_color": "red"} }

当 Knowledge Extractor 识别到“死锁检测算法”时，会根据上下文自动打上class_demo标签，触发 PPT Generator 使用全图布局+分步动画。

第六步：验证工作流健康度
运行workbuddy health-check --all，它会：

测试 Knowledge Extractor 对 PDF 的 OCR 准确率（要求 ≥98%）；
验证 Curriculum Mapper 能否将“时间戳协议”正确映射到ch6.3；
检查 Pedagogy Formatter 是否能为“幻读”生成生活类比（我预设的类比是“淘宝秒杀时库存显示不一致”）；
确认 PPT Generator 能加载指定模板并替换占位符。
只有全部通过，才允许启动正式处理。

3.2 核心处理环节：四个 Agent 的实操细节与参数调优

Knowledge Extractor Agent：让非结构化资料开口说话

这个 Agent 的核心能力不是“识别文字”，而是“理解教学语境”。以处理ch6_lock_protocol.png（一张手写板书照片）为例，它的处理链路如下：

预处理：调用 OpenCV 进行二值化、去噪、倾斜校正。我实测发现，对教师手写体，cv2.adaptiveThreshold比全局阈值更稳定，尤其处理粉笔字迹时。
OCR 与结构识别：使用 PaddleOCR v2.6，但关键在后处理——它不直接输出文字，而是构建“教学元素图”：
- 将图像划分为逻辑区域（标题区、公式区、示意图区、批注区）；
- 对公式区调用 LaTeX-OCR，将手写公式\frac{d}{dx}f(x)转为标准 LaTeX；
- 对示意图区，用 YOLOv8n 检测“锁图标”“事务框”“时间轴”，再用图卷积网络（GCN）推断元素关系（如“锁图标指向事务框”表示“事务持有锁”）。
语义增强解析：这才是真正的智能。当它识别到手写文字“两段锁=扩展段+收缩段”，会：
- 查询知识库，确认“两段锁”即“Two-Phase Locking”，标准缩写为 2PL；
- 匹配错误模式库，发现该表述易与“两阶段提交（2PC）”混淆，自动添加校验标签[disambiguate:2PL_vs_2PC]；
- 提取隐含条件：“扩展段不能释放锁”“收缩段不能获取锁”，生成结构化 JSON：
```
{ "concept": "两阶段锁协议", "definition": "事务执行分为扩展段和收缩段...", "constraints": ["扩展段只增锁", "收缩段只释锁"], "common_misconception": "与两阶段提交协议名称相似但原理不同" }
```

参数调优心得：

confidence_threshold设为 0.85 是经验阈值。低于此值的内容（如模糊的公式）进入人工审核队列，我每天花 15 分钟处理，比返工整个 PPT 高效得多；
max_context_length设为 2048，因为数据库概念定义通常很短，过长会导致上下文稀释，比如把“封锁粒度”和“索引类型”错误关联。

Curriculum Mapper Agent：在混沌中重建教学秩序

这个 Agent 的价值，在于它解决了“同一知识点在不同资料中表述不一”的痛点。以“可串行化”为例：

教材 PDF 写：“可串行化是最高隔离级别”；
MOOC 字幕说：“可串行化调度等价于某串行调度”；
学生错题 Excel 记录：“SELECT ... FOR UPDATE 在可串行化下仍可能死锁”。

Curriculum Mapper 不做简单合并，而是执行三步映射：

语义统一：调用 Sentence-BERT 计算三段文字的余弦相似度，确认它们指向同一概念，生成统一 IDcon:serializability。
结构锚定：将con:serializability与课程 Schema 匹配。教材目录中它在ch6.4，MOOC 大纲中在week7，我的问题导向结构中在problem:how_to_avoid_inconsistency。Mapper 根据权重（0.6:0.3:0.1）选择ch6.4为主路径，但保留其他路径作为“跨章节链接”，供后续生成教案时使用。
缺口检测：检查ch6.4的 learning_objectives 是否被覆盖。教材强调“定义”，MOOC 强调“判定”，学生错题暴露“实践陷阱”。Mapper 发现“实践陷阱”未在 learning_objectives 中，自动创建待办事项：“补充 learning_objectives：分析可串行化下的典型并发陷阱”。

实操技巧：我在curriculum_schema.json中为每个章节设置了min_coverage_ratio（最低覆盖比例）。ch6.4设为 0.9，意味着该章节知识点覆盖率必须 ≥90%，否则整个工作流暂停。这倒逼我补全了 MOOC 中缺失的“快照隔离”内容，反而提升了教案完整性。

Pedagogy Formatter Agent：把知识翻译成教学语言

这个 Agent 是 WorkBuddy 最具教学智慧的部分。它输出的不是普通 Markdown，而是带执行指令的教学中间格式。以处理con:serializability为例，它生成：

# 可串行化（Serializability） [concept:serializability][difficulty:advanced][intent:class_demo] ## 定义 可串行化调度是指：多个事务并发执行的结果，与某个串行执行的结果完全相同。 [analogy:交通调度] 想象十字路口的车辆（事务），红绿灯（调度器）决定谁先过。可串行化就像所有车按单一方向（如先A后B）依次通过，结果与A先B后或B先A后完全一致。 ## 判定方法 - **优先图法**：构建事务依赖图，无环则可串行化 - **冲突可串行化**：仅考虑读写冲突，忽略写写冲突 [animation:priority_graph] 1. 显示事务 T1、T2 2. 添加 T1→T2 边（T1 写 A，T2 读 A） 3. 添加 T2→T1 边（T2 写 B，T1 读 B） 4. 高亮环形结构 → “存在环，不可串行化” ## 常见误区 | 误区 | 正解 | 教学提示 | |------|------|----------| | “可串行化=无死锁” | 死锁是资源竞争问题，可串行化是结果等价问题 | 死锁可发生于任何隔离级别，可串行化是调度性质 |

关键配置说明：

[intent:class_demo]触发 PPT Generator 使用全屏动画；
[animation:priority_graph]调用预设的动画规则，生成 4 帧 PPT；
表格中的“教学提示”字段，来自错误模式库，确保直击学生痛点。

注意：Pedagogy Formatter 会自动检测 Markdown 中的 LaTeX 公式（如 $T_1 \rightarrow T_2$ ），并转换为 PPT 中的 MathType 兼容格式，避免字体丢失。

PPT Generator Agent：精准交付教学视觉资产

这个 Agent 的强大，在于它把教学逻辑变成了像素级指令。以生成“优先图法”动画为例：

模板解析：加载database_classic.pptx，定位animation_placeholder占位符；
帧生成：根据[animation:priority_graph]指令，调用 python-pptx 创建 4 页：
- 第1页：纯白背景，居中显示“T1”“T2”两个圆角矩形；
- 第2页：在 T1 下方添加“写A”，T2 下方添加“读A”，并画箭头 T1→T2；
- 第3页：在 T2 下方添加“写B”，T1 下方添加“读B”，并画箭头 T2→T1；
- 第4页：高亮两个箭头形成环，右侧弹出红色文本框：“存在环 → 不可串行化！”；
样式注入：所有文字用“思源黑体”，箭头粗细 2.5pt，圆角矩形填充色按事务区分（T1 蓝，T2 橙）；
动画编排：每页设置“淡入”进入，箭头设置“擦除”动画（从起点到终点），文本框设置“缩放”动画。

避坑经验：

务必在 PPT 模板中预设好所有占位符（title_placeholder,content_placeholder,animation_placeholder），WorkBuddy 不会自动创建新占位符；
字体嵌入：Linux 系统默认无“微软雅黑”，我用fontconfig将“思源黑体”映射为sans-serif，确保导出 PPT 在 Windows 上不换字体；
图片压缩：对 PNG 示意图，Agent 自动用pngquant压缩至 80% 质量，单页 PPT 体积从 15MB 降至 2.3MB，播放更流畅。

3.3 输出成果验证：教案与 PPT 的教学可用性检验

生成的成果不是终点，而是教学闭环的起点。我建立了三级验证机制：

第一级：机器校验
运行workbuddy validate-output --all，它检查：

教案 Markdown 中所有[concept:*]标签是否能在知识库中找到对应条目（防止幻觉）；
PPT 中所有动画帧数是否匹配[animation:*]指令（如priority_graph必须生成 4 帧）；
每页 PPT 的字体、字号、配色是否符合intent_tags.json规则（如exam_focus页必须有红色边框）。
未通过项自动归入validation_failed/目录，标注失败原因。

第二级：教学逻辑校验
我用一个 Python 脚本模拟学生视角：

随机抽取教案中 5 个知识点，检查其“定义→类比→案例→误区”链条是否完整；
对 PPT 中的 3 个动画，手动播放并计时：B+ 树分裂动画是否严格 5 帧？每帧停留是否 ≥2 秒？
验证跨章节链接：点击教案中“参见 ch5.2 索引结构”，是否能跳转到对应 PPT 页？

第三级：真实课堂检验
这才是终极考验。我选了 3 个班级平行授课：

A 班用传统 PPT（我手工制作）；
B 班用 WorkBuddy 生成 PPT（未修改）；
C 班用 WorkBuddy PPT + 我微调了 2 页（增加一个学生提问的真实案例）。
课后问卷显示：B 班学生对“可串行化”概念理解正确率 72%，A 班 58%，C 班 81%。差距不在内容深度，而在教学节奏——WorkBuddy 的分步动画让抽象概念变得可触摸，而我的手工 PPT 一页塞满文字，学生跟不上。

4. 常见问题与实战排查技巧：那些 WorkBuddy 不会告诉你的细节

4.1 知识抽取失败：手写体识别不准怎么办？

现象：notes/ch6_lock_protocol.png中的“两段锁”被识别为“雨段锁”，导致后续所有处理错误。

排查思路：

先确认是 OCR 问题还是语义理解问题——用workbuddy debug ocr --file ch6_lock_protocol.png查看原始 OCR 输出，发现确实是“雨段锁”；
检查 PaddleOCR 的中文模型是否适配粉笔字。实测发现PP-OCRv3对印刷体准，对粉笔字差，切换为chinese_cht模型（专为繁体/手写优化）后，准确率升至 93%；
但仍有 7% 错误，这时启用“领域词典强制纠正”：在ocr_correction_dict.json中添加"雨段锁": "两段锁"，Agent 会在 OCR 后自动替换。

独家技巧：对高频错别字，我用正则批量修正。比如手写“封锁”常被识为“风锁”，在ocr_postprocess.py中加入：

text = re.sub(r'风锁', '封锁', text) text = re.sub(r'死所', '死锁', text)

比训练新模型快 10 倍，且效果稳定。

4.2 课程映射偏差：知识点被分到错误章节

现象：学生错题 Excel 中的“MVCC 实现”被映射到ch6.4 可串行化，但 MVCC 属于ch7.2 隔离级别实现。

根本原因：Curriculum Mapper 的语义匹配权重设置不合理。原配置中教材目录权重 0.6，但学生错题更贴近 MOOC 大纲（权重应提高）。

解决方案：

临时调整权重：workbuddy config set mapper.match_weight "[0.4, 0.5, 0.1]"；
更彻底的做法：为student_work/目录单独配置映射策略，在workflow_config.yaml中增加：
```
- name: curriculum_mapper_student input: "student_work/*.xlsx" output: "mapped_student_json" params: {schema_ref: "mooc_schema.json", match_weight: [0.2, 0.7, 0.1]}
```
这样学生错题走专用映射通道，与教材处理解耦。

4.3 PPT 生成异常：动画帧数不符或字体丢失

现象：[animation:bplus_split]指令生成了 3 帧，而非要求的 5 帧；Windows 打开 PPT 时所有文字变成宋体。

排查步骤：

检查animation_rules.json中bplus_split的定义是否完整：

"bplus_split": { "frames": 5, "elements": ["leaf_node", "insert_key", "overflow_check", "split_nodes", "update_parent"] }

缺少frames字段会导致默认 3 帧；

字体问题根源在 Linux 系统字体映射。运行fc-list | grep "Source"确认思源黑体已安装，再执行：
```
echo 'fonts.conf' > ~/.fonts.conf # 内容：将 Source Han Sans CN 映射为 sans-serif
```
重启 WorkBuddy 服务生效。

救命技巧：当 PPT 导出后出现乱码，不用重跑整个流程。用python-pptx脚本直接修复：

from pptx import Presentation prs = Presentation("output.pptx") for slide in prs.slides: for shape in slide.shapes: if hasattr(shape, 'text_frame') and shape.text_frame: for paragraph in shape.text_frame.paragraphs: for run in paragraph.runs: run.font.name = 'Source Han Sans CN' prs.save("fixed.pptx")

4.4 教学意图错配：自学材料页用了课堂演示动画

现象：exercises/sql_practice.xlsx中的练习题，本应生成self_study意图的双栏 PPT，却生成了class_demo的全屏动画。

原因：Knowledge Extractor 在识别 Excel 时，将“练习题”误判为“课堂案例”，因为两者都含 SQL 代码。

解决方法：

在intent_rules.json中添加显式规则：

{ "file_pattern": "exercises/*.xlsx", "intent": "self_study", "override": true }

更智能的做法：让 Knowledge Extractor 学习区分“案例”与“练习”。我在错误模式库中新增样本：
- 案例特征：含“演示”“说明”“如”等引导词，SQL 后跟结果截图；
- 练习特征：含“请写出”“完成以下”“结果是什么”，SQL 后无结果。
  重新训练 Knowledge Extractor 的分类器，准确率从 78% 提升至 94%。