OpenMAIC 多智能体课堂代理系统提示模板解析JSON 动作协议、角色编排与白板协作机制【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAICOpen Multi-Agent Interactive ClassroomOpenMAIC通过提示模板把 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的通用系统提示骨架它不针对某一次具体生成而是描述一个课堂代理应该如何说话、如何行动、如何组织每一次回复。围绕它还有三个按角色细分的白板模板以及若干可复用片段snippetagent-system-wb-teacher教师角色白板纪律见 system.mdagent-system-wb-assistant助教角色白板纪律见 system.mdagent-system-wb-student学生角色白板纪律见 system.mdspeech-guidelines语音输出通用规则见 speech-guidelines.mdwhiteboard-reference白板画布、坐标系、动作参数与 LaTeX 转义的全量参考见 whiteboard-reference.md。模板 ID 统一注册在两个地方lib/prompts/types.ts 中的PromptId字符串字面量联合类型以及 lib/prompts/index.ts 中的PROMPT_IDS常量。PROMPT_IDS使用satisfies Recordstring, 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 Users Turn注入课堂实时状态并规定用户最新消息优先于既定授课计划的响应铁律。{{studentProfileSection}}、{{peerContext}}、{{languageConstraint}}三个变量位于 Classroom Role 段之后分别承载学生画像、同伴上下文其他代理的发言摘要与语言约束指令。这意味着同一个模板文件可以同时服务面向个性化学生的教学与多代理同堂讨论两类场景差异全部由变量注入模板本身保持稳定。三、JSON 数组输出协议动作与语音的复合消息格式模板中最核心的硬约束是输出格式。原文规则完整如下这是课堂代理可执行动作开白板、画图、标注幻灯片与语音同时流出的协议基础You MUST output a JSON array for ALL responses. Each element is an object with atypefield.输出单一 JSON 数组——无解释、无代码围栏no explanation, no code fencestype: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——Dont announce actions!描述正在做的事Im going to draw a diagram for you...——Dont describe what youre doing!汇报动作结果Action complete, shape has been added——Dont 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_codeWHITEBOARD CLOSE RULECRITICAL回复结尾禁止调用wb_close白板保持打开让学生有时间阅读只有需要回到幻灯片画布例如对幻灯片元素使用 spotlight / laser时才关闭。频繁开关白板会分散注意力wb_delete按 ID 精确删除元素状态中以[id:xxx]形式展示优先于wb_clearwb_draw_code/wb_edit_code修改已有代码块必须用wb_edit_codeinsert_after、insert_before、delete_lines、replace_lines它能产生平滑的行级动画删除重建会丢失动画连续性。wb_draw_code仅用于创建全新代码块。此外{{mutualExclusionNote}}会注入白板 / 幻灯片画布互斥规则白板打开时幻灯片画布被隐藏针对幻灯片元素的 spotlight / laser 将不可见若需使用它们必须先wb_close。反之白板关闭时wb_draw_*仍可隐式打开白板但会遮住幻灯片画布。六、响应优先级铁律用户最新消息永远优先模板用一整节Responding to the Users 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 评测PORT3100 pnpm dev EVAL_CHAT_MODELprovider:model EVAL_SCORER_MODELprovider: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_textcontent、x、y可选width(400)、height(100)、fontSize(18)、color(#333333)、elementId纯文本禁止混入 LaTeXwb_draw_shapeshape(rectangle/circle/triangle)、x、y、width、height可选fillColor(#5b9bd5)无函数曲线图元抛物线不要用三角形/折线凑wb_draw_linestartX、startY、endX、endY可选width(2)、style(solid/dashed)、points([,] → 可为arrow)width是描边粗细而非长度wb_draw_latexlatex、x、y可选height(80)、width(400)、color、elementId所有反斜杠在 JSON 中必须写成\\wb_draw_chartchartType(bar/column/line/pie/ring/area/radar/scatter)、x、y、width、height、data.labels、data.legends、data.series超出画布会被静默裁剪wb_draw_tablex、y、width、height、data(string[][])首行为表头单元格为纯文本勿放公式wb_draw_codelanguage、code、x、y可选width(500)、height(300)、fileName、elementId高度约等于 32(头部) 22×行数 16wb_edit_codeelementId、operation、lineId/lineIds、content行 ID如L1、L2需从状态读取禁止猜测wb_delete/wb_clearelementId/ 无优先wb_deletewb_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_deletewb_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 thistry it yourself时才绘制且不wb_clear、不wb_delete。这份角色 × 权限的分层设计让多代理同屏协作时白板不会陷入互相覆盖的混乱。十、小结agent-system模板以JSON 数组 动作 语音的复合输出为核心协议以用户最新消息优先为响应铁律再通过角色化的长度指南、白板纪律与运行时变量注入把同一个骨架复用到教师、助教、学生三种代理上。它同时示范了一个值得借鉴的工程实践提示词以文件形式管理lib/prompts/templates由统一的 loader 负责 snippet 展开、条件块与变量插值并用pnpm test tests/prompts下的断言守住渲染结果不得残留{{…}}的底线。对于希望深度定制课堂代理行为新增动作、调整角色话术、扩充白板图元的开发者而言理解这份模板的骨架与变量契约是进入 OpenMAIC 编排层的第一步。【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenMAIC 多智能体课堂代理系统提示模板解析：JSON 动作协议、角色编排与白板协作机制
OpenMAIC 多智能体课堂代理系统提示模板解析JSON 动作协议、角色编排与白板协作机制【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAICOpen Multi-Agent Interactive ClassroomOpenMAIC通过提示模板把 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的通用系统提示骨架它不针对某一次具体生成而是描述一个课堂代理应该如何说话、如何行动、如何组织每一次回复。围绕它还有三个按角色细分的白板模板以及若干可复用片段snippetagent-system-wb-teacher教师角色白板纪律见 system.mdagent-system-wb-assistant助教角色白板纪律见 system.mdagent-system-wb-student学生角色白板纪律见 system.mdspeech-guidelines语音输出通用规则见 speech-guidelines.mdwhiteboard-reference白板画布、坐标系、动作参数与 LaTeX 转义的全量参考见 whiteboard-reference.md。模板 ID 统一注册在两个地方lib/prompts/types.ts 中的PromptId字符串字面量联合类型以及 lib/prompts/index.ts 中的PROMPT_IDS常量。PROMPT_IDS使用satisfies Recordstring, 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 Users Turn注入课堂实时状态并规定用户最新消息优先于既定授课计划的响应铁律。{{studentProfileSection}}、{{peerContext}}、{{languageConstraint}}三个变量位于 Classroom Role 段之后分别承载学生画像、同伴上下文其他代理的发言摘要与语言约束指令。这意味着同一个模板文件可以同时服务面向个性化学生的教学与多代理同堂讨论两类场景差异全部由变量注入模板本身保持稳定。三、JSON 数组输出协议动作与语音的复合消息格式模板中最核心的硬约束是输出格式。原文规则完整如下这是课堂代理可执行动作开白板、画图、标注幻灯片与语音同时流出的协议基础You MUST output a JSON array for ALL responses. Each element is an object with atypefield.输出单一 JSON 数组——无解释、无代码围栏no explanation, no code fencestype: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——Dont announce actions!描述正在做的事Im going to draw a diagram for you...——Dont describe what youre doing!汇报动作结果Action complete, shape has been added——Dont 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_codeWHITEBOARD CLOSE RULECRITICAL回复结尾禁止调用wb_close白板保持打开让学生有时间阅读只有需要回到幻灯片画布例如对幻灯片元素使用 spotlight / laser时才关闭。频繁开关白板会分散注意力wb_delete按 ID 精确删除元素状态中以[id:xxx]形式展示优先于wb_clearwb_draw_code/wb_edit_code修改已有代码块必须用wb_edit_codeinsert_after、insert_before、delete_lines、replace_lines它能产生平滑的行级动画删除重建会丢失动画连续性。wb_draw_code仅用于创建全新代码块。此外{{mutualExclusionNote}}会注入白板 / 幻灯片画布互斥规则白板打开时幻灯片画布被隐藏针对幻灯片元素的 spotlight / laser 将不可见若需使用它们必须先wb_close。反之白板关闭时wb_draw_*仍可隐式打开白板但会遮住幻灯片画布。六、响应优先级铁律用户最新消息永远优先模板用一整节Responding to the Users 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 评测PORT3100 pnpm dev EVAL_CHAT_MODELprovider:model EVAL_SCORER_MODELprovider: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_textcontent、x、y可选width(400)、height(100)、fontSize(18)、color(#333333)、elementId纯文本禁止混入 LaTeXwb_draw_shapeshape(rectangle/circle/triangle)、x、y、width、height可选fillColor(#5b9bd5)无函数曲线图元抛物线不要用三角形/折线凑wb_draw_linestartX、startY、endX、endY可选width(2)、style(solid/dashed)、points([,] → 可为arrow)width是描边粗细而非长度wb_draw_latexlatex、x、y可选height(80)、width(400)、color、elementId所有反斜杠在 JSON 中必须写成\\wb_draw_chartchartType(bar/column/line/pie/ring/area/radar/scatter)、x、y、width、height、data.labels、data.legends、data.series超出画布会被静默裁剪wb_draw_tablex、y、width、height、data(string[][])首行为表头单元格为纯文本勿放公式wb_draw_codelanguage、code、x、y可选width(500)、height(300)、fileName、elementId高度约等于 32(头部) 22×行数 16wb_edit_codeelementId、operation、lineId/lineIds、content行 ID如L1、L2需从状态读取禁止猜测wb_delete/wb_clearelementId/ 无优先wb_deletewb_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_deletewb_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 thistry it yourself时才绘制且不wb_clear、不wb_delete。这份角色 × 权限的分层设计让多代理同屏协作时白板不会陷入互相覆盖的混乱。十、小结agent-system模板以JSON 数组 动作 语音的复合输出为核心协议以用户最新消息优先为响应铁律再通过角色化的长度指南、白板纪律与运行时变量注入把同一个骨架复用到教师、助教、学生三种代理上。它同时示范了一个值得借鉴的工程实践提示词以文件形式管理lib/prompts/templates由统一的 loader 负责 snippet 展开、条件块与变量插值并用pnpm test tests/prompts下的断言守住渲染结果不得残留{{…}}的底线。对于希望深度定制课堂代理行为新增动作、调整角色话术、扩充白板图元的开发者而言理解这份模板的骨架与变量契约是进入 OpenMAIC 编排层的第一步。【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考