OpenMAIC 多智能体课堂代理系统提示模板解析:JSON 动作协议、角色编排与白板协作机制

原创2026-09-09 09:57:262,226 阅读
文章标签:人工智能AI Agent多智能体Agent 编排教育前端后端RAG视频处理本地部署

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 整体可以拆成四个层次,每一层解决一类问题:

  1. 角色定义层:# Role + ## Your Personality + ## Your Classroom Role,通过 {{agentName}}、{{persona}}、{{roleGuideline}} 等变量注入代理的名字、性格与课堂职责;
  2. 输出协议层:# Output Format + ## Format Rules,规定"任何回复必须是 JSON 数组"这一硬约束;
  3. 行为规范层:## Ordering Principles、## Whiteboard Guidelines、# Available Actions,规定说话与动作的先后顺序、白板使用边界、可用动作清单;
  4. 上下文层:# 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 type field.

  1. 输出单一 JSON 数组——无解释、无代码围栏(no explanation, no code fences);
  2. type:"action" 对象包含 name 与 params(动作名 + 参数);
  3. type:"text" 对象包含 content(要说出口的语音文本);
  4. 动作与文本对象可以任意交错、自由排序;
  5. 以 ] 结尾的闭合括号标志着本次回复结束;
  6. 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

三个值得关注的工程细节:

  1. snippet 找不到会直接抛错——{{snippet:speach-guidelines}} 这类拼写错误会在加载阶段失败,而不是把字面量漏给 LLM;
  2. 未知变量名静默透传——interpolate('hello {{missing}}', {}) 会原样返回 'hello {{missing}}'。这是有意设计(支持局部渲染),但意味着占位符拼写错误会把字面 {{…}} 发给 LLM。防御手段是测试:tests/prompts/ 下的 templates.test.ts、media-conditional.test.ts 等用例断言渲染后的提示文本中不再包含 {{ 字样(见 expect(text).not.toContain('{{'));loader.test.ts 则验证"未知 snippetId 抛错而非透传字面量";
  3. 插值规则与命名约定——\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 编排层的第一步。

登录后查看全文
OpenMAIC