OpenMAIC 多智能体课堂代理系统提示模板解析:JSON 动作协议、角色编排与白板协作机制
OpenMAIC 多智能体课堂代理系统提示模板解析:JSON 动作协议、角色编排与白板协作机制
Open Multi-Agent Interactive Classroom(OpenMAIC)通过提示模板把 LLM 塑造成沉浸式课堂中的"教师""助教""学生"等不同角色。本文以仓库中的核心模板 lib/prompts/templates/agent-system/system.md 为主体,结合 lib/prompts/loader.ts、lib/orchestration/prompt-builder.ts 等源码,深入拆解这套系统提示的骨架设计、JSON 数组输出协议、白板动作规范与变量插值机制。读完本文,你将掌握如何理解并二次编排这类多智能体课堂提示,以及如何让代理同时完成"说话、开白板、画图、标注幻灯片"的复合动作而不出格式错误。
一、模板定位:agent-system 在提示体系中的角色
在 OpenMAIC 的提示管理体系中,所有提示模板以 Markdown 文件形式存放在 lib/prompts/templates/<prompt-id>/ 目录下,其中 system.md 为必需文件。agent-system 是课堂代理(classroom agent)的通用系统提示骨架,它不针对某一次具体生成,而是描述"一个课堂代理应该如何说话、如何行动、如何组织每一次回复"。
围绕它还有三个按角色细分的白板模板,以及若干可复用片段(snippet):
agent-system-wb-teacher:教师角色白板纪律(见 system.md);agent-system-wb-assistant:助教角色白板纪律(见 system.md);agent-system-wb-student:学生角色白板纪律(见 system.md);speech-guidelines:语音输出通用规则(见 speech-guidelines.md);whiteboard-reference:白板画布、坐标系、动作参数与 LaTeX 转义的全量参考(见 whiteboard-reference.md)。
模板 ID 统一注册在两个地方:lib/prompts/types.ts 中的 PromptId 字符串字面量联合类型,以及 lib/prompts/index.ts 中的 PROMPT_IDS 常量。PROMPT_IDS 使用 satisfies Record<string, PromptId> 约束,保证常量值与类型联合严格一致——这是仓库工程上防止"拼错模板名"的第一道防线。
二、模板骨架:从角色设定到输出格式的四段式结构
agent-system/system.md 整体可以拆成四个层次,每一层解决一类问题:
- 角色定义层:
# Role+## Your Personality+## Your Classroom Role,通过{{agentName}}、{{persona}}、{{roleGuideline}}等变量注入代理的名字、性格与课堂职责; - 输出协议层:
# Output Format+## Format Rules,规定"任何回复必须是 JSON 数组"这一硬约束; - 行为规范层:
## Ordering Principles、## Whiteboard Guidelines、# Available Actions,规定说话与动作的先后顺序、白板使用边界、可用动作清单; - 上下文层:
# Current State、## Responding to the User's Turn,注入课堂实时状态,并规定"用户最新消息优先于既定授课计划"的响应铁律。
{{studentProfileSection}}、{{peerContext}}、{{languageConstraint}} 三个变量位于 Classroom Role 段之后,分别承载学生画像、同伴上下文(其他代理的发言摘要)与语言约束指令。这意味着同一个模板文件可以同时服务"面向个性化学生的教学"与"多代理同堂讨论"两类场景,差异全部由变量注入,模板本身保持稳定。
三、JSON 数组输出协议:动作与语音的复合消息格式
模板中最核心的硬约束是输出格式。原文规则完整如下,这是课堂代理可执行动作(开白板、画图、标注幻灯片)与语音同时流出的协议基础:
You MUST output a JSON array for ALL responses. Each element is an object with a
typefield.
- 输出单一 JSON 数组——无解释、无代码围栏(no explanation, no code fences);
type:"action"对象包含name与params(动作名 + 参数);type:"text"对象包含content(要说出口的语音文本);- 动作与文本对象可以任意交错、自由排序;
- 以
]结尾的闭合括号标志着本次回复结束; - CRITICAL:任何回复都必须以
[开头——即使上一轮消息被中断,也不能把残缺响应当作纯文本继续,每一条回复都必须是完整、独立的 JSON 数组。
模板同时给出 Good Examples 与 Bad Examples。例如这条合法样例,先 wb_open 打开白板、再 wb_draw_text 书写化学方程式、最后用语音讲解:
[{"type":"action","name":"wb_open","params":{}},{"type":"action","name":"wb_draw_text","params":{"content":"Step 1: 6CO₂ + 6H₂O → C₆H₁₂O₆ + 6O₂","x":100,"y":100,"fontSize":24}},{"type":"text","content":"Look at this chemical equation — notice how the reactants and products correspond."}]
而以下三类是明确禁止的反面样例:
- 宣告动作("Let me open the whiteboard")——Don't announce actions!
- 描述正在做的事("I'm going to draw a diagram for you...")——Don't describe what you're doing!
- 汇报动作结果("Action complete, shape has been added")——Don't report action results!
其背后的理念来自 speech-guidelines 片段:效果(effects)与语音并发触发,学生看着画面听讲解,代理只需要像真人老师一样自然说话,无需复述动作本身。
四、Ordering Principles:动作与语音的时序规则
模板通过 {{orderingPrinciples}} 变量注入时序约束,该变量由 prompt-builder.ts 按当前场景是否包含幻灯片动作(spotlight / laser)来决定:
- 有幻灯片动作时:
spotlight/laser动作必须出现在对应的 text 对象之前(先指,后说);白板动作可与 text 对象交错(边画边说); - 仅有白板动作时:白板动作可与 text 对象自由交错。
这一设计保证了"指向幻灯片元素"与"口头讲解"的因果顺序稳定,避免出现"已经讲完却还没圈出重点"的时序倒挂。
五、Available Actions 与白板协作规范
模板通过 {{actionDescriptions}} 注入当前代理真正可用的动作描述,动作集由 getEffectiveActions(agentConfig.allowedActions, sceneType) 按代理权限与当前场景类型过滤生成(见 tool-schemas.ts 相关实现)。白板动作族包括:
wb_open/wb_close:打开 / 关闭白板;wb_draw_text/wb_draw_shape/wb_draw_chart/wb_draw_latex/wb_draw_table:绘制文本、几何图形、数据图表、LaTeX 公式、表格;wb_draw_line:画直线或箭头;wb_draw_code/wb_edit_code:创建代码块、按行编辑已有代码块;wb_delete/wb_clear:按元素 ID 删除单个元素 / 清空全部元素。
模板中的白板使用准则强调"用白板讲解概念,但别让白板变成幻灯片的镜像":
- 适合用白板的场景:需要图示、公式、数据图表、表格、连线、代码演示或分步推导的概念。数学公式用
wb_draw_latex,数据可视化用wb_draw_chart,结构化数据用wb_draw_table,代码演示用wb_draw_code; - WHITEBOARD CLOSE RULE(CRITICAL):回复结尾禁止调用
wb_close,白板保持打开让学生有时间阅读;只有需要回到幻灯片画布(例如对幻灯片元素使用 spotlight / laser)时才关闭。频繁开关白板会分散注意力; wb_delete:按 ID 精确删除元素(状态中以[id:xxx]形式展示),优先于wb_clear;wb_draw_code/wb_edit_code:修改已有代码块必须用wb_edit_code(insert_after、insert_before、delete_lines、replace_lines),它能产生平滑的行级动画;删除重建会丢失动画连续性。wb_draw_code仅用于创建全新代码块。
此外 {{mutualExclusionNote}} 会注入白板 / 幻灯片画布互斥规则:白板打开时幻灯片画布被隐藏,针对幻灯片元素的 spotlight / laser 将不可见;若需使用它们,必须先 wb_close。反之白板关闭时 wb_draw_* 仍可隐式打开白板,但会遮住幻灯片画布。
六、响应优先级铁律:用户最新消息永远优先
模板用一整节(Responding to the User's Turn)规定课堂代理的响应纪律,核心一句话:用户最近一条消息永远优先于继续既定授课计划,先把用户真正说的话回应掉,再恢复课程进度;"假装什么都没发生继续讲课"被视为失败。
具体分支规则可总结如下:
| 用户消息类型 | 代理应做的响应 |
|---|---|
| 提问(数值、是非、定义、比较、如何做) | 先给出具体答案,不转向邻近话题 |
| 导航/节奏请求("慢一点""深入讲""跳下一页") | 节奏类调整口播;实际翻页代理无法操作时,明确说明自己不能翻页并给出操作提示,不得假装已翻页 |
| 格式/语言请求("用中文讲""explain in Arabic""简短些") | 立即切换,本条与后续回复保持一致 |
| 无法完成的需求("做个视频"等) | 直说"我没法直接生成视频",并提供最接近的可行替代(在幻灯片或白板上走一遍) |
| 纠错("公式写错了,应该是 NO3-") | 先承认并直接改正,不跳到别的点 |
| 表达沮丧/困惑("你答非所问""我没听懂") | 先找出沮丧消息背后真正未满足的需求,简短致歉后满足该需求,不转向新话题 |
| 指代不清("帮我看下这个") | 不猜话题,问一个简短具体的澄清问题,并给出具体选项 |
| 纯确认("ok""嗯""got it") | 不制造问答,继续教学且不再重新问候;若同时带疑问则按疑问处理 |
| 真不知道 | 直接说"我不太确定",不答非所问 |
同时强调:"启发思考(Inspire thought)"与"同伴差异化(peer-differentiation)"必须发生在已回应完用户请求之后,绝不跳过用户的实际请求。这条铁律确保多智能体课堂在自由讨论时不会"各说各话"而忽略学生。
七、模板变量与运行时组装:buildStructuredPrompt 全流程
模板中的占位符并非手写拼接,而是在运行时由 buildStructuredPrompt 统一组装。它构造的 vars 对象覆盖了模板全部插槽:
| 模板占位符 | 运行时来源 |
|---|---|
{{agentName}} / {{persona}} |
agentConfig.name / agentConfig.persona |
{{roleGuideline}} |
ROLE_GUIDELINES[agentConfig.role],按 teacher / assistant / student 分支 |
{{studentProfileSection}} |
buildStudentProfileSection(userProfile),无画像时输出空串 |
{{peerContext}} |
buildPeerContextSection(agentResponses, agentConfig.name) |
{{languageConstraint}} |
storeState.stage?.languageDirective |
{{formatExample}} / {{orderingPrinciples}} / {{spotlightExamples}} / {{slideActionGuidelines}} / {{mutualExclusionNote}} |
按 hasSlideActions(是否含 spotlight / laser)选择幻灯片版或纯白板版 |
{{actionDescriptions}} |
getActionDescriptions(effectiveActions) |
{{stateContext}} |
buildStateContext(storeState) |
{{virtualWhiteboardContext}} |
buildVirtualWhiteboardContext(storeState, whiteboardLedger) |
{{lengthGuidelines}} |
buildLengthGuidelines(agentConfig.role) |
{{whiteboardGuidelines}} |
buildWhiteboardGuidelines(agentConfig.role),内部加载对应角色的白板模板 |
{{discussionContextSection}} |
buildDiscussionContextSection(discussionContext, agentResponses) |
需要注意,ROLE_GUIDELINES 与 buildLengthGuidelines 目前仍以 TS 模板字符串形式存在于 prompt-builder.ts 与 prompt-builder.ts,尚未迁移到 Markdown 片段——lib/prompts/README.md 对此有专门说明。角色指南的内容决定了代理的课堂分工:
- teacher(主教师):控制课程节奏、幻灯片与推进,负责用 spotlight/laser 引导注意力,用白板画图与公式;可调用全部动作;
- assistant(助教):补位答疑、用更简单的语言重述、提供具体例子与背景;白板仅做少量补充,不喧宾夺主;
- student(学生):积极参与讨论、提问、观察、回应,回复保持 1-2 句,仅在被教师明确邀请时才使用白板。
长度指南也按角色分级:教师总语音约 100 字、助教约 80 字、学生约 50 字且最多 1-2 句。模板明确指出:长度只统计 type:"text" 的语音内容,动作不计入长度,代理可以放心使用任意数量的动作。
八、模板引擎:snippet、条件块与变量插值的处理顺序
loader.ts 实现了三类占位符的处理,处理顺序固定为:先 snippet 展开 → 再条件块 → 最后变量插值,因此 snippet 内部可以继续包含 {{#if}} 块与 {{变量}}:
| 语法 | 语义 | 处理函数 |
|---|---|---|
{{variableName}} |
调用方通过 buildPrompt(id, vars) 提供 |
interpolateVariables |
{{snippet:snippet-name}} |
加载时把片段文件内容拼入 | processSnippets |
{{#if conditionName}}...{{/if}} |
条件为真时保留内容,否则整块删除 | processConditionalBlocks |
三个值得关注的工程细节:
- snippet 找不到会直接抛错——
{{snippet:speach-guidelines}}这类拼写错误会在加载阶段失败,而不是把字面量漏给 LLM; - 未知变量名静默透传——
interpolate('hello {{missing}}', {})会原样返回'hello {{missing}}'。这是有意设计(支持局部渲染),但意味着占位符拼写错误会把字面{{…}}发给 LLM。防御手段是测试:tests/prompts/下的templates.test.ts、media-conditional.test.ts等用例断言渲染后的提示文本中不再包含{{字样(见expect(text).not.toContain('{{'));loader.test.ts则验证"未知 snippetId 抛错而非透传字面量"; - 插值规则与命名约定——
\w+只匹配字母数字下划线,因此 kebab-case 占位符(如{{next-agent}})不会被替换;约定统一使用 camelCase。变量值是对象时会被JSON.stringify(value, null, 2)格式化后注入。
加载层面,loadPrompt / loadSnippet 每次调用都从磁盘读取、不做缓存,Markdown 修改无需重启 dev server 即可生效(见 README 的 Loading 一节)。快速验证模板改动可用:
pnpm test tests/prompts
如需端到端验证(代理循环 + 模板组装 + chat/director 集成),可运行白板 eval 评测:
PORT=3100 pnpm dev &
EVAL_CHAT_MODEL=<provider:model> EVAL_SCORER_MODEL=<provider:model> \
pnpm eval:whiteboard --base-url http://localhost:3100 \
--scenario econ-tech-innovation
九、白板参考片段:坐标系、参数表与 LaTeX 转义陷阱
{{whiteboardGuidelines}} 注入的白板模板都以 {{snippet:whiteboard-reference}} 收尾,共享同一份全量参考 whiteboard-reference.md。其核心内容如下:
画布规格与坐标系:画布为 1000 × 563 像素,x = 0 在左缘、x = 1000 在右缘,y = 0 在顶部、y = 563 在底部,每个元素的 (left, top) 即其左上角。安全区建议 x ∈ [20, 980]、y ∈ [20, 543],即四边留 20px 边距。水平居中 x = (1000 - width) / 2,垂直居中 y = (563 - height) / 2;双栏布局为左栏 x ∈ [20, 480]、右栏 x ∈ [520, 980](40px 间隔)。
常用动作参数速查:
| 动作 | 关键参数 | 默认值/要点 |
|---|---|---|
wb_open |
无 | 绘制阶段开始时调用一次即可 |
wb_draw_text |
content、x、y;可选 width(400)、height(100)、fontSize(18)、color(#333333)、elementId |
纯文本,禁止混入 LaTeX |
wb_draw_shape |
shape(rectangle/circle/triangle)、x、y、width、height;可选 fillColor(#5b9bd5) |
无函数曲线图元,抛物线不要用三角形/折线凑 |
wb_draw_line |
startX、startY、endX、endY;可选 width(2)、style(solid/dashed)、points(["",""] → 可为"arrow") |
width 是描边粗细而非长度 |
wb_draw_latex |
latex、x、y;可选 height(80)、width(400)、color、elementId |
所有反斜杠在 JSON 中必须写成 \\ |
wb_draw_chart |
chartType(bar/column/line/pie/ring/area/radar/scatter)、x、y、width、height、data.labels、data.legends、data.series |
超出画布会被静默裁剪 |
wb_draw_table |
x、y、width、height、data(string[][]) |
首行为表头;单元格为纯文本,勿放公式 |
wb_draw_code |
language、code、x、y;可选 width(500)、height(300)、fileName、elementId |
高度约等于 32(头部) + 22×行数 + 16 |
wb_edit_code |
elementId、operation、lineId/lineIds、content |
行 ID(如 L1、L2)需从状态读取,禁止猜测 |
wb_delete / wb_clear |
elementId / 无 |
优先 wb_delete,wb_clear 慎用 |
wb_close |
无 | 绘制回合结尾禁用,仅在回幻灯片画布前调用 |
LaTeX JSON 转义(CRITICAL):这是白板上出错率最高的一环。JSON 字符串中每个 LaTeX 反斜杠都必须写成 \\(两个字符)。因为 "\text" 会被 JSON 解析器把 \t 解释为 ASCII TAB 控制符,KaTeX 收到的将是一个残缺的命令。常见被破坏的命令包括:\t → \text、\theta、\times;\r → \rightarrow、\Rightarrow、\rho;\f → \frac、\forall;\b → \beta、\binom;\v → \varphi、\vec;\n → \neq、\notin。正确写法示例:
{"type":"action","name":"wb_draw_latex","params":{"latex":"\\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}","x":100,"y":80,"height":80}}
自检启发式:若上一轮渲染的白板上出现 ext、heta、imes、rac、ightarrow 等字面量残片,就说明单反斜杠泄漏了,应使用 wb_delete + wb_draw_latex 或 wb_clear 后重画。
边界与重叠:硬边界为 x ≥ 0、x + width ≤ 1000、y ≥ 0、y + height ≤ 563;相邻元素最小间距 20px;垂直堆叠 next.y = prev.y + prev.height + 30,并排 next.x = prev.x + prev.width + 30。放置新元素前要遍历已有元素,新包围盒不得覆盖任一既有元素超过 30% 面积;空间紧张时三选一:wb_delete 旧元素、缩小新元素、或扫描画布象限找空白区域。
字号与视觉重量:fontSize 必须取自字号表——白板标题 28-32、小节标题 20-24、正文/批注 16-18、说明/小字 12-14,禁止随意使用 8、11、48、64 等自由值。单行文本的匹配高度约为 ceil(fontSize × 1.5) + 20。LaTeX 元素与相邻文本需视觉重量匹配:height:80 的公式视觉上约等于 28px 文本,不要在大公式旁放 14px 小字注释。
多角色白板纪律:教师模板要求"每回合只画 1-3 个元素",先看当前状态避免重复绘制,白板拥挤时先 wb_clear,冲突列表非空时本回合首个动作必须是 wb_delete/wb_clear;助教模板限定"每回合最多 1-2 个补充元素",且永不 wb_clear、不删除教师元素,白板已 ≥6 个元素时本回合只说话;学生模板默认不动白板,仅在教师明确邀请(如"come solve this""try it yourself")时才绘制,且不 wb_clear、不 wb_delete。这份"角色 × 权限"的分层设计,让多代理同屏协作时白板不会陷入互相覆盖的混乱。
十、小结
agent-system 模板以"JSON 数组 = 动作 + 语音的复合输出"为核心协议,以"用户最新消息优先"为响应铁律,再通过角色化的长度指南、白板纪律与运行时变量注入,把同一个骨架复用到教师、助教、学生三种代理上。它同时示范了一个值得借鉴的工程实践:提示词以文件形式管理(lib/prompts/templates),由统一的 loader 负责 snippet 展开、条件块与变量插值,并用 pnpm test tests/prompts 下的断言守住"渲染结果不得残留 {{…}}"的底线。对于希望深度定制课堂代理行为(新增动作、调整角色话术、扩充白板图元)的开发者而言,理解这份模板的骨架与变量契约,是进入 OpenMAIC 编排层的第一步。