清华大学OpenMAIC开源多智能体AI课堂：架构拆解与工程实践

1. 从“AI课堂”这个词说起：OpenMAIC到底在解决什么问题

第一次看到“清华大学OpenMAIC：开源多智能体AI课堂”这个标题，很多人第一反应是——又一个套壳的AI教学演示？我一开始也这么想。但把项目拆开看之后，发现它想做的事情其实比“让AI讲一道题”要硬核得多：它试图用多个智能体协作的方式，去还原一个真实课堂里“老师讲、助教答疑、同学讨论、系统评测”的完整链路，而且整套东西是开源的。

先说清楚它是什么。OpenMAIC是一个面向教育场景的多智能体框架，核心思路是把一个“课堂”拆成若干角色，每个角色由一个独立的智能体承担，比如主讲智能体负责知识讲解，助教智能体负责答疑和纠错，评测智能体负责出题和判分，甚至还有负责维持课堂节奏、记录学习状态的调度智能体。这些智能体不是各干各的，而是通过一套消息传递和任务编排机制协同工作，最终对外呈现出一个“像课堂一样”的交互体验。

它能做什么？最直接的应用是：你给它一个知识点或者一份教材，它能自动生成一节结构化的课，包含讲解、例题、互动问答和随堂测验。适合谁来参考？三类人最值得看：一是做教育产品的开发者，想在自己的平台里嵌入“AI老师”能力；二是研究多智能体协作的技术人，想找一个真实可跑的工程案例；三是高校或培训机构的教研人员，想理解AI课堂的边界到底在哪。

为什么值得认真拆？因为市面上大多数“AI课堂”本质是单模型加一层提示词模板，问一句答一句，没有角色分工，没有状态管理，更没有协作。OpenMAIC的价值恰恰在于它把“多智能体”这个听起来很虚的概念，落到了具体的角色定义、通信协议和调度逻辑上。你读完能明白：一个AI课堂要跑起来，光有模型不够，还得有“组织架构”。

提示：本文所有关于OpenMAIC内部机制的描述，基于公开项目资料和同类多智能体框架的常见工程实践进行合理还原，具体实现细节请以项目仓库最新代码为准。

2. 多智能体课堂的骨架：角色分工与协作机制拆解

2.1 为什么单智能体撑不起一节课

先想一个最朴素的问题：如果只用一个通用大模型来当老师，会怎样？我实测过，效果是这样的——你问它“讲一下二叉树”，它能讲得头头是道；但你接着问“刚才那个遍历顺序我没听懂”，它可能会重新从头讲一遍，因为它没有“课堂状态”的概念。更麻烦的是，它没法同时扮演“讲解者”和“评判者”，你让它出题它出题，你让它判分它判分，但它判自己出的题时往往过于宽松。

这就是单智能体的根本缺陷：角色混淆。一个模型既要维持知识准确性，又要控制教学节奏，还要做客观评测，这三件事的目标函数其实是冲突的。讲解需要通俗和耐心，评测需要严格和标准，调度需要全局视角。让一个模型同时干这三件事，结果就是每件都干得 mediocre。

OpenMAIC的解法很直接：拆角色。主讲智能体只负责把知识讲清楚，它的提示词里写死了“用类比、分步骤、控制单次输出长度”；助教智能体只负责接住学生的追问，它的上下文里带着主讲刚刚讲过的内容摘要；评测智能体只负责出题和判分，它的提示词强调“题目必须可客观判定，判分必须给出依据”。三个角色各司其职，互不干扰。

2.2 角色之间的消息怎么传

拆完角色，下一个问题就是：它们怎么对话？这里有个工程上的关键选择——是用“共享黑板”模式，还是用“消息队列”模式。

共享黑板的意思是，所有智能体往一个公共的上下文池里读写信息，谁需要什么自己去取。这种模式实现简单，但容易出问题：主讲写了一大段讲解，助教和评测都去读，读的时候可能读到半截，状态不一致。消息队列模式则是每个智能体有独立的收件箱，消息按顺序投递，谁发给谁、发什么、什么时候发，都有明确记录。

OpenMAIC这类框架通常采用混合模式：底层用消息传递保证顺序和可追溯，同时维护一个共享的“课堂状态”对象，记录当前讲到哪、学生问了什么、评测结果如何。这个状态对象不是所有智能体都能随便改的，只有调度智能体有写权限，其他智能体通过发消息来请求更新。这样做的好处是状态变更集中可控，不会出现两个智能体同时改一个字段导致冲突。

我自己的经验是，如果你要复现类似架构，一定要把状态管理和消息传递分开。很多新手一上来就搞一个大字典到处传，跑简单 demo 没问题，一旦智能体数量超过三个，调试就是噩梦。你会分不清到底是哪个智能体在什么时候改了哪个字段。

2.3 调度智能体才是真正的“班主任”

在OpenMAIC的角色设定里，调度智能体（或者叫协调器）是最容易被低估的一个。它不直接产生教学内容，但它决定了“什么时候该谁说话”。

举个具体场景：学生输入一个问题。调度智能体先判断这个问题是“新知识点”还是“对刚才内容的追问”。如果是新知识点，它把任务派给主讲；如果是追问，它派给助教。助教回答完之后，调度再判断“是否需要出一道题巩固”，如果需要，再派给评测。评测出完题，学生作答，评测判分，判分结果回写到课堂状态，调度根据得分决定“继续下一节”还是“回头补讲”。

这一整套流程，如果没有调度智能体，就得靠硬编码的 if-else 来串。硬编码的问题是，一旦你想调整教学策略——比如“连续答对三题就跳过练习”——就得改代码。而有了调度智能体，你只需要改它的提示词或者决策逻辑，其他智能体完全不用动。这就是关注点分离带来的可维护性。

注意：调度智能体的决策逻辑如果完全交给大模型，会有不确定性问题。常见做法是“规则兜底 + 模型建议”：核心流程用规则保证稳定，边缘判断让模型给建议，两者结合。

3. 从零跑通一个最小课堂：环境准备与首次运行

3.1 依赖选型和版本坑

假设你现在要从仓库拉代码跑起来，第一关就是环境。这类多智能体项目通常依赖 Node.js 生态（前端交互 + 后端编排）或者 Python 生态（模型调用 + 数据处理）。从热词里出现“openmaic必须要用pnpm吗”这个搜索来看，项目大概率是 Node.js 技术栈，包管理器推荐 pnpm。

为什么是 pnpm 而不是 npm 或 yarn？这不是随便选的。pnpm 用硬链接和内容寻址存储来管理依赖，同一个包在磁盘上只存一份，多个项目共享。对于多智能体这种依赖树很深的项目，pnpm 安装速度快、磁盘占用小，而且它的严格依赖隔离能避免“幽灵依赖”问题——就是你没在 package.json 里声明某个包，但因为它是别人的依赖被提升上来了，你也能 import 到。这种幽灵依赖在开发时没事，一到生产构建就可能炸。

如果你非要用 npm，也能跑，但可能会遇到 peer dependency 冲突。我的建议是：先按项目文档来，文档说 pnpm 就用 pnpm。装 pnpm 很简单：

npm install -g pnpm pnpm --version

如果版本太低，用pnpm self-update升级。然后进项目目录：

pnpm install

这一步如果卡住，大概率是网络问题。可以配一下镜像源，但注意不要配来路不明的源。用官方或者国内大厂维护的镜像即可。

3.2 模型接入的配置逻辑

多智能体课堂要跑起来，必须接一个大模型作为“大脑”。OpenMAIC本身是框架，不绑定特定模型。你需要准备一个模型服务的 API Key，然后在配置文件里填进去。

配置通常长这样（以常见的环境变量方式为例）：

# .env 文件 MODEL_API_KEY=your_key_here MODEL_BASE_URL=https://api.example.com/v1 MODEL_NAME=gpt-4o-mini

这里有个经验：不要一上来就用最贵的模型。多智能体课堂一次完整流程可能调用模型十几次甚至几十次，用旗舰模型跑一遍成本很高。先用便宜的小模型把流程跑通，确认逻辑没问题，再换好模型看效果提升。而且小模型响应快，调试的时候等待时间短，体验好很多。

另一个坑是上下文长度。主讲智能体讲一段，助教要带着这段的摘要去回答追问，评测要带着知识点去出题。如果模型上下文窗口太小，摘要就得压得很短，信息损失大。建议至少选 32K 上下文以上的模型，128K 更从容。

3.3 首次启动的预期与排错

配置好之后，启动命令通常是：

pnpm dev

或者

pnpm start

第一次跑，不要期待它直接给你一个完美的课堂。更可能的情况是：前端界面出来了，你输入一个知识点，后台开始调模型，然后……卡住了。或者返回了一堆乱码似的 JSON。

这时候别慌，按这个顺序排查：

第一，看终端日志。多智能体框架一般会把每个智能体的输入输出打出来。找到第一个报错的智能体，看它的提示词是不是有问题，或者模型返回的格式是不是不符合预期。

第二，检查模型 API 是否通。用一个最简单的 curl 命令测一下你的 API Key 和 Base URL 能不能正常返回。

第三，看是不是 JSON 解析失败。多智能体之间传消息，常用 JSON 格式。如果模型返回的 JSON 多了个逗号或者少了引号，解析就会挂。很多框架有重试机制，但重试几次还失败就会报错。这时候要么调提示词让模型输出更规范，要么在代码里加容错解析。

我踩过的一个坑是：模型返回的 JSON 里带了 markdown 代码块标记（json ...），解析器不认。解决办法是在解析前先 strip 掉这些标记。这个坑很常见，几乎每个做多智能体的人都会遇到一次。

4. 让课堂真正“活”起来：提示词设计与状态管理

4.1 每个智能体的提示词该写什么

框架跑通之后，决定课堂质量的就是提示词。OpenMAIC里每个智能体的提示词，本质上是在定义“这个角色的行为边界”。

主讲智能体的提示词，核心要包含这几层：身份设定（你是一位擅长把复杂概念讲简单的老师）、输出结构（先给定义，再给类比，再给例子，最后总结）、长度控制（单次讲解不超过 300 字，避免信息过载）、禁止事项（不要出题，不要判分，那是别的角色的活）。

助教智能体的提示词，重点是上下文感知。它需要知道主讲刚刚讲了什么，所以它的输入里要带上主讲的输出摘要。它的行为定义是：只回答与当前知识点相关的追问，如果学生问的是全新知识点，引导回主讲。

评测智能体的提示词，最关键的是可判定性。它出的题必须是客观题或者有明确评分标准的简答题。提示词里要写清楚：题目必须附带标准答案和评分细则，判分时必须引用评分细则。

调度智能体的提示词，核心是路由规则。它要根据当前课堂状态和学生输入，决定下一个激活哪个智能体。这个提示词通常比较短，但规则要清晰。

提示：提示词不是写一次就完事。我自己的做法是建一个表格，记录每次调整提示词后课堂效果的变化，比如“讲解清晰度”“追问响应准确率”“题目质量”几个维度，用几次实际运行的结果来对比。

4.2 课堂状态里到底存什么

状态管理是多智能体课堂的“记忆”。没有状态，每轮对话都是独立的，助教不知道主讲讲了什么，评测不知道学生之前答对没有。

一个最小可用的课堂状态对象，通常包含这些字段：

这个状态对象由调度智能体维护，其他智能体只读。每次智能体产生输出后，调度根据输出更新状态，再决定下一步。

这里有个设计取舍：状态存多细？存太细，每次都要序列化一大坨，模型上下文塞不下；存太粗，助教回答追问时信息不够。我的经验是，摘要级别比较合适。主讲讲 500 字，摘要压到 100 字左右，保留核心定义和关键例子，细节丢掉。助教回答追问时，如果摘要不够，可以再让主讲补一句，而不是把全文都塞进去。

4.3 状态持久化：刷新页面课堂不能丢

如果只是内存里存状态，一刷新页面就全没了，体验很差。所以需要持久化。最简单的方案是存 localStorage 或者 sessionStorage，适合单机演示。如果要多人使用，就得存后端数据库。

存的时候注意：状态对象里可能包含模型生成的中间内容，体积不小。如果存 localStorage，注意 5MB 的限制。一个课堂跑下来，状态可能几百 KB，问题不大，但如果你把每次模型调用的完整输入输出都存进去，很快就爆了。只存必要字段。

另一个经验是版本化。状态对象的 schema 可能会变，比如你后来加了一个字段。如果旧状态没有这个字段，读出来就是 undefined，可能导致报错。简单做法是在状态里加一个 version 字段，读取时检查版本，不匹配就重置课堂。虽然粗暴，但省事。

5. 实测中暴露的三个典型问题与修复思路

5.1 智能体“抢话”：消息顺序错乱

跑起来之后，我遇到的第一个诡异现象是：学生刚问完问题，主讲和助教同时开始回答，前端收到两段交错的内容，读起来前言不搭后语。

排查下来，根因是消息投递没有做串行化。调度智能体判断“这个问题既需要主讲补充，又需要助教解释”，于是同时给两个智能体发了消息。两个智能体并行处理，谁先返回不一定，前端就乱了。

修复思路有两种。一种是强制串行：调度智能体一次只激活一个智能体，等它返回并更新状态后，再决定下一个。这样课堂节奏清晰，但响应会慢一点。另一种是并行但合并：允许并行，但前端要等所有相关智能体都返回后，按预设顺序拼接输出。我倾向于第一种，因为课堂本身就是有先后顺序的，串行更符合真实场景。

改完之后，课堂的“节奏感”明显好了。学生问一个问题，先看到主讲补充，再看到助教细化，最后可能还有评测出题，层次分明。

5.2 评测智能体“放水”：判分标准漂移

第二个问题是评测智能体判分不稳定。同一道题，同一个答案，第一次判 80 分，第二次判 95 分。学生看到分数变来变去，信任感直接崩了。

根因是评测智能体的提示词里没有把评分标准写死。它每次判分时，对“答案完整度”的理解都在变。大模型本身就有随机性，如果不给硬约束，输出就会漂移。

修复方案是把评分细则结构化。出题的时候，评测智能体必须同时输出一个评分细则对象，比如：

{ "question": "请解释二叉树前序遍历的顺序", "standard_answer": "根节点 -> 左子树 -> 右子树", "scoring_rules": [ {"point": "提到根节点先访问", "score": 40}, {"point": "提到左子树在右子树之前", "score": 40}, {"point": "表述清晰无歧义", "score": 20} ] }

判分时，评测智能体逐条对照评分细则，给出每条得分和依据。这样即使模型有随机性，评分框架是固定的，分数波动会小很多。

5.3 长对话后“失忆”：上下文超限的降级策略

第三个问题出现在课堂进行到十几轮之后。助教突然开始答非所问，或者重复之前已经讲过的内容。一看日志，模型调用报错“context length exceeded”。

这是多智能体课堂的经典问题：每轮对话都在往上下文里追加内容，聊得越久，上下文越长，最终超过模型窗口。

降级策略有几个层次。最粗暴的是截断：只保留最近 N 轮对话，前面的丢掉。但这样会丢失早期讲过的知识点，助教可能重复讲。好一点的是摘要压缩：把早期对话让模型总结成一段话，替换掉原始对话。这样保留了核心信息，又省了 token。

OpenMAIC这类框架通常会在状态里维护一个“长期记忆摘要”，每过几轮就更新一次。我的经验是，摘要的触发阈值不要设得太高。等到快超限才摘要，可能已经报错了。在上下文用到 70% 左右就开始压缩，留出余量。

还有一个技巧是分智能体隔离上下文。主讲智能体不需要知道评测智能体出了什么题，助教也不需要知道调度智能体的内部决策。每个智能体只带自己需要的那部分上下文，整体 token 消耗会小很多。

6. 开源这件事对教育AI意味着什么

6.1 为什么“开源”在这个场景下特别重要

教育是一个对透明度和可解释性要求很高的领域。如果一个AI课堂是黑盒，老师不知道它怎么讲课，家长不知道它怎么评分，那很难被真正信任。开源意味着任何人都可以去看它的提示词、它的调度逻辑、它的评分规则。你可以审计它有没有偏见，可以修改它来适配自己的教学大纲，可以把它部署在自己的服务器上，数据不出校园。

这也是OpenMAIC和商业AI课堂产品最大的区别。商业产品追求的是“开箱即用”，但代价是你得接受它的教学理念和数据处理方式。开源项目追求的是“可改造”，你得自己动手，但改完之后它完全属于你。

从热词里“开源知识库”“开源项目管理”“开源文档贡献”这些词的出现频率来看，大家对开源的关注点已经从“有没有代码”转向“好不好参与”。一个开源项目能不能活，不看 star 数，看有没有人持续提 PR、写文档、回答问题。OpenMAIC如果要走远，社区运营和文档质量可能比代码本身还关键。

6.2 二次开发可以往哪些方向走

如果你把基础版本跑通了，接下来可以往几个方向扩展。

第一个方向是学科特化。通用课堂的提示词是泛化的，你可以针对数学、编程、语言学习分别写专门的提示词和评测规则。数学课的评测需要能判证明题，编程课的评测需要能跑代码，这些通用框架做不了，得你自己加。

第二个方向是多模态。现在的课堂主要是文字交互，但真实课堂有板书、有图表、有语音。你可以给主讲智能体加一个“画图”工具，让它生成流程图或者示意图；给评测智能体加一个“代码执行”工具，让它能判编程题。

第三个方向是学习分析。课堂状态里积累了学生的问答记录和得分历史，这些数据可以用来做学习分析。比如识别学生的薄弱知识点，自动调整后续课堂的侧重点。这需要你在状态管理之上再加一层分析模块。

第四个方向是多课堂协同。一个调度智能体管一个课堂，那能不能让多个课堂之间共享优质讲解内容？比如A课堂的主讲讲了一个特别好的类比，能不能同步到B课堂？这涉及跨课堂的消息传递和内容审核，复杂度不低，但想象空间很大。

注意：二次开发时，建议保持核心框架不动，通过插件或者配置文件来扩展。直接改核心代码，后续上游更新时合并冲突会很痛苦。

7. 一些踩坑之后的个人体会

跑通OpenMAIC这类多智能体课堂，最大的感受是：难点不在模型，在工程。模型能力已经足够支撑一个像样的课堂了，真正花时间的是消息怎么传、状态怎么管、错误怎么处理、上下文怎么压缩。这些东西没有捷径，只能一个一个踩过来。

另一个体会是，不要追求一步到位。我一开始就想做一个全自动的完整课堂，结果每个环节都半吊子。后来改成先做“主讲+助教”两个角色，把讲解和答疑跑顺，再加评测，再加调度。每加一个角色，先确保它单独能工作，再接入整体流程。这样出问题的时候，排查范围小很多。

还有一点，日志要打全。多智能体系统里，一个输出可能是好几个智能体接力产生的。如果不把每个智能体的输入输出都记下来，出了问题根本不知道是哪一环。我现在的习惯是，每个智能体的调用都记一条结构化日志，包含时间戳、智能体名称、输入摘要、输出摘要、耗时。调试的时候直接按时间线看，一目了然。

最后说一个可能被忽略的点：课堂的“温度”。多智能体协作能保证知识传递的准确性，但课堂不只是知识传递。学生答错题的时候，评测智能体给完分数之后，是不是应该有一句鼓励？主讲讲完一个难点之后，是不是应该问一句“这里跟上了吗”？这些细节不影响功能，但影响体验。在提示词里加一两句这样的指令，成本很低，效果很好。

如果你也在做类似的东西，或者正准备入坑多智能体教育应用，我的建议是：先把最小闭环跑通，哪怕它很粗糙。跑通之后，你自然就知道下一步该优化什么了。纸上谈兵讨论架构，不如实际跑一遍来得实在。