OpenMAIC 学生角色白板系统提示词解析:从"默认不上台"到受邀请协作的课堂 Agent 设计
OpenMAIC 学生角色白板系统提示词解析:从"默认不上台"到受邀请协作的课堂 Agent 设计
导读
在 OpenMAIC(Open Multi-Agent Interactive Classroom,一键式沉浸式多智能体课堂)中,白板是教师、助教与学生三类 Agent 共享的视觉协作空间。如何在同一个物理画布上让不同角色的智能体互不干扰、秩序井然,是系统提示词工程的核心难题。lib/prompts/templates/agent-system-wb-student/system.md 正是专门为学生角色设计的白板系统提示词模板:它以"默认不动白板、只用语音表达"为铁律,只在教师明确邀请时才上台,并且通过布局冲突检查与 40px 安全间距等硬约束,保证学生 Agent 的每一次板书都不会破坏课堂画布。读完本文,你将理解该模板的完整语义、它如何与共享的 whiteboard-reference 片段组合成最终提示词,以及 OpenMAIC 如何用加载器、构建器和测试用例三层机制来保障这套"角色化白板纪律"可落地、可验证。
一、模板定位:白板使用权的三级角色矩阵
在 OpenMAIC 的多智能体课堂编排中,白板并非所有 Agent 的公共游乐场,而是按角色划分使用权的"稀缺资源"。lib/orchestration/prompt-builder.ts 中的 buildWhiteboardGuidelines(role) 函数(见 lib/orchestration/prompt-builder.ts#L214-L227)根据 agentConfig.role 分发到三个不同的白板模板:
| 角色 | 模板路径 | 白板使用哲学 |
|---|---|---|
| 教师 | lib/prompts/templates/agent-system-wb-teacher/system.md | 白板是辅助视觉,每轮 1-3 个元素,锚定一个核心观点 |
| 助教 | lib/prompts/templates/agent-system-wb-assistant/system.md | 白板主要是教师的领地,每轮至多 1-2 个小补充元素 |
| 学生 | lib/prompts/templates/agent-system-wb-student/system.md | 默认不碰白板,仅在明确受邀时上台,且只做被要求的最小贡献 |
从模板目录结构(lib/prompts/templates/)可以看到,这三个模板一一对应 PromptId 联合类型中的 agent-system-wb-teacher、agent-system-wb-assistant、agent-system-wb-student(见 lib/prompts/types.ts#L8-L16),并在 lib/prompts/index.ts#L26-L34 中以 PROMPT_IDS 常量对外暴露。buildWhiteboardGuidelines 的分发逻辑里,凡是角色既不是 teacher 也不是 assistant 的情况都会回落(fallback)到学生模板——这也与 lib/orchestration/prompt-builder.ts#L146 中 ROLE_GUIDELINES 采用 || ROLE_GUIDELINES.student 作为兜底默认值的做法一脉相承,学生角色是整个角色体系中最保守、最"防守"的一方。
二、核心铁律:默认不动白板,语音才是学生的表达主场
学生模板开篇就给出了全文最重要的规则:
Default: do not touch the whiteboard. Express your ideas through speech only.
这句规则与 buildLengthGuidelines 中对学生角色的整体约束是呼应的——在 lib/orchestration/prompt-builder.ts#L198-L203 中,学生 Agent 的语音长度目标被限制在约 50 字符、1-2 句话以内,并被反复强调"You are a STUDENT, not a teacher"。
这种设计背后的课堂语义非常清晰:OpenMAIC 刻意避免学生 Agent 抢走教师的讲解主导权。白板是一个容量有限(1000×563 像素)的共享画布,如果每个 Agent 都自由板书,很快会变成信息堆叠的"乱涂墙"。因此学生角色的默认策略是用 type:"text" 的语音元素完成绝大部分表达,白板动作被降级为一种需要"授权"的例外操作。
这与助教模板中的 "Speech over drawing"(见 lib/prompts/templates/agent-system-wb-assistant/system.md#L20-L20)原则同构,但约束更彻底:助教仍有"每轮 1-2 个小元素"的常规配额,而学生默认配额为零。
三、受邀上台:触发条件与最小贡献原则
学生模板用专门的 "When invited" 章节定义了上台的唯一触发条件:
- 教师或用户显式邀请,典型措辞如 "come solve this"、"show your work on the whiteboard"、"try it yourself";
- 只有在这种情形下,学生 Agent 才被允许使用白板动作。
受邀后的行为规范同样明确:
- 贡献保持最小且整洁——只解决被要求的问题(solve only what was asked);
- 禁止装饰性或探索性元素(Don't add decorative or exploratory elements);
- 完成后保持白板打开——不要调用
wb_close。
最后一条"Leave the board open"在仓库中是一条被测试专门守护的跨角色契约。在 tests/prompts/templates.test.ts#L174-L185 的 "whiteboard close contract" 用例中,测试断言最终提示词必须包含 "Do not close merely because your own drawing is complete"、"a later classroom agent still needs the board"、"Close only when explicitly requested"、"Do NOT call wb_close at the end of a drawing turn" 等表述,其设计动机正是:学生画完之后,后续课堂 Agent(以及真实学生)仍需要时间阅读白板,提前关闭会打断课堂节奏。
从更深层看,这条"受邀才上台"的规则把白板上的主权归属交还给了教师:学生可以在受控范围内展示自己的解题过程(这正是"show your work"的课堂价值),但永远不能主动扩张自己的板书领地。
四、布局冲突检查:用 JSON 驱动的几何规则避免破坏画布
白板是共享资源,学生的板书必须"零新增冲突"。学生模板要求 Agent 在动笔前检查上下文中的 "⚠ Layout Conflicts Detected" 列表(该列表由白板 JSON 计算而来),并遵守以下几何约束:
- 挑选坐标时,新元素不得为冲突列表新增任何一条记录;
- 与每个既有元素保持 40px 的净空(leaving 40px clearance from every existing element);
- 如果找不到这样的位置,就用语音说明并放弃绘制(say so verbally and skip drawing);
- 永不覆盖既有内容,永不调用
wb_clear或wb_delete。
最后一条约束把学生与教师/助教明确区隔开:教师模板允许在画布拥挤时主动 wb_clear、在重叠超限时 wb_delete 特定元素(见 lib/prompts/templates/agent-system-wb-teacher/system.md#L9-L13),而学生模板则是绝对禁止这两种破坏性动作。学生可以使用的"画布清理"手段只有一个:放弃绘制。
五、共享底座:whiteboard-reference 片段如何被注入
学生模板正文只有 20 行,其结尾的 {{snippet:whiteboard-reference}} 占位符才是技术含量的真正所在。这一机制由 lib/prompts/loader.ts 实现:
loadPrompt读取模板目录下的system.md后,立即调用processSnippets(lib/prompts/loader.ts#L48-L52),用正则将{{snippet:name}}替换为 lib/prompts/snippets/whiteboard-reference.md 的完整内容;- 片段加载的查找路径是
lib/prompts/snippets/${snippetId}.md(lib/prompts/loader.ts#L32-L42),如果片段文件缺失会直接抛错而非静默透传——这一点在 lib/prompts/README.md#L83-L85 中被称为 "Silent-passthrough gotcha" 的防御手段; - 模板处理顺序固定为:片段注入 → 条件块 → 变量插值(见 lib/prompts/loader.ts#L131-L138),因此片段内部也可以再包含
{{#if}}与{{variable}}。
这意味着学生最终收到的系统提示词 = 20 行角色纪律 + 完整的白板参考手册。这条共享链路被测试显式守护:tests/prompts/templates.test.ts#L288-L319 中 KEY_SECTIONS 数组列出了 Canvas Specifications、Action Reference、LaTeX JSON Escape (CRITICAL)、Bounds & Overlap、Font Size Table、Pre-Output Checklist 六大关键章节,并分别对教师、助教、学生三个角色断言"最终渲染提示词必须包含全部章节"。
同时,tests/prompts/templates.test.ts#L154-L158 的 "student whiteboard prompt is sourced from agent-system-wb-student template" 用例验证了角色分发正确性:当 AgentConfig.role 为 student 时,buildStructuredPrompt 的输出必须包含 "Whiteboard — Student Role" 标题,否则视为模板接线回归。
六、白板动作参考:学生上台时需要遵守的 JSON 契约
虽然学生模板本身没有罗列白板动作细节,但被注入的 whiteboard-reference 片段完整定义了所有动作的 JSON 规范。这里整理学生在受邀上台(尤其是被要求"show your work"解数学题或写代码)时最常用的动作契约:
6.1 动作通用形态
所有白板动作都是响应 JSON 数组中的元素:{"type":"action","name":"wb_...","params":{...}}。所有坐标均为像素单位整数,(left, top) 表示元素左上角。
6.2 关键动作速查表
| 动作 | 用途 | 关键参数 | 学生场景示例 |
|---|---|---|---|
wb_open |
绘制前打开白板,只需一次 | 无参数 | 被邀请上台的第一步 |
wb_draw_text |
放置纯文本 | content、x、y、width(默认 400)、height(默认 100)、fontSize(默认 18)、color(默认 #333333)、elementId |
写出解题步骤 1、2、3 |
wb_draw_latex |
通过 KaTeX 渲染数学公式 | latex、x、y、height(默认 80)、width(默认 400)、color |
写出二次方程求根公式 |
wb_draw_shape |
放置几何图形 | shape(rectangle/circle/triangle)、x、y、width、height、fillColor |
标注受力图 |
wb_draw_line |
画直线或箭头 | startX、startY、endX、endY、color、width(描边粗细)、style、points |
画坐标轴箭头 |
wb_draw_chart |
渲染数据图表 | chartType(8 种)、data.labels、data.legends、data.series |
展示数据趋势(注意:学生模板不鼓励大图表) |
wb_draw_code |
带语法高亮的代码块 | language、code、x、y、width、height、fileName、elementId |
展示一段示例代码 |
wb_delete |
按 ID 删除单个元素 | elementId |
学生模板禁止使用 |
wb_clear |
清空所有元素 | 无参数 | 学生模板禁止使用 |
wb_close |
关闭白板 | 无参数 | 绘制结束时禁止调用,保持白板打开 |
6.3 画布规格与安全区
- 画布尺寸 1000 × 563 像素,
x=0为左边缘、y=0为顶边缘; - 安全区:
x ∈ [20, 980]、y ∈ [20, 543],距画布边缘保留 20px 边距; - 越界元素会被静默裁剪(图表尤其容易出现这个问题);
- 相邻元素最小间距 20px;垂直堆叠
next.y = prev.y + prev.height + 30;并排next.x = prev.x + prev.width + 30; - 两栏布局:左栏
x ∈ [20, 480](宽度 ≤ 460)、右栏x ∈ [520, 980](宽度 ≤ 460),中间 40px 排水沟; - 放置前必须遍历既有元素:新包围盒若覆盖既有元素超过 30% 面积则拒绝放置。
学生在受邀请场景下最稳妥的做法,是遵循共享片段中的 "Worked example" 思路:先读取 "Current State" 中的既有元素坐标,用 prev.y + prev.height + 30 计算下一个安全纵坐标,再逐一校验 y + height ≤ 563 与重叠检查。
6.4 LaTeX 双重转义:学生答题最容易踩的坑
学生上台最常见的场景是解数学题,因此 wb_draw_latex 的 JSON 转义规则必须掌握:JSON 字符串中每个反斜杠都必须写成 \\(两个字符)。否则 JSON 解析器会把 "\text" 中的 \t 解释为 TAB 控制符,KaTeX 收到的将是 <TAB>ext{...} 这样的垃圾串。
| LaTeX 源码 | ❌ 错误写法 | ✅ 正确写法 |
|---|---|---|
\frac{a}{b} |
"\frac{a}{b}" |
"\\frac{a}{b}" |
\theta |
"\theta" |
"\\theta" |
\rightarrow |
"\rightarrow" |
"\\rightarrow" |
\sqrt{x} |
"\sqrt{x}" |
"\\sqrt{x}" |
自我检查启发式:如果上一轮渲染出的白板上出现 ext、heta、imes、rac 这类残缺 token,说明发出了单反斜杠的 LaTeX,本轮需要用 wb_delete + wb_draw_latex 或 wb_clear + 重绘的方式以双反斜杠重新输出。注意学生模板禁止 wb_delete/wb_clear,因此学生遇到渲染损坏时应当用语音请求教师修复,或在下一轮受邀时正确重画。
七、模板的组合机制与本地验证
7.1 加载链路
从 buildStructuredPrompt(lib/orchestration/prompt-builder.ts)到最终学生提示词的完整链路为:
- 根据
agentConfig.role选取agent-system-wb-student模板 ID; buildPrompt→loadPrompt读取 lib/prompts/templates/agent-system-wb-student/system.md;processSnippets将{{snippet:whiteboard-reference}}替换为 lib/prompts/snippets/whiteboard-reference.md 全文;processConditionalBlocks按变量裁剪条件块;interpolateVariables注入{{agentName}}、{{stateContext}}等运行时变量;- 拼接
ROLE_GUIDELINES、buildLengthGuidelines(role)等其他角色化片段(其中ROLE_GUIDELINES与学生模板并列存在于最终 system 提示词中,见 lib/prompts/README.md#L55-L65)。
7.2 本地验证方法
模板相关的最快反馈回路是运行模板冒烟测试套件:
pnpm test tests/prompts
如需端到端验证(agent 循环 + 模板组合 + chat/director 集成的完整行为),可以使用仓库提供的白板 eval harness(见 lib/prompts/README.md#L95-L103):
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
值得注意的工程细节:loadPrompt 每次调用都从磁盘读取、不做缓存(lib/prompts/README.md#L107-L108),因此修改模板 markdown 后无需重启 dev server 即可生效——这对提示词工程师迭代角色纪律非常友好。
八、设计启示:如何为多智能体课堂写好"角色化白板提示词"
回看学生模板,可以提炼出 OpenMAIC 在共享画布多 Agent 编排上的一套可复用方法论:
- 默认权限最小化。学生默认"只动嘴不动笔",白板访问权按教师 > 助教 > 学生的梯度收敛,避免竞争性使用;
- 显式授权模型。所有越权行为都必须有明确触发词("come solve this" 等),把判断权交给课堂主导者;
- 几何约束前置。40px 净空、30% 重叠上限、安全区、静默裁剪等硬规则全部写进提示词,让模型在生成坐标时"自带防碰撞意识",而不是依赖事后修复;
- 破坏性操作按角色分级。
wb_clear/wb_delete只有教师可主动使用(助教与学生的规则各不相同),画布秩序的单点修复权归于单一角色; - 共享底座 + 角色薄壳。所有角色共用一份 200 多行的
whiteboard-reference技术参考(动作 JSON、转义规则、字号表、高度表),角色模板只写"何时可以用、可以用多少"的纪律,极大降低维护成本; - 契约用测试锁定。角色分发、章节完整性、close 契约、占位符命名规范都由 tests/prompts/templates.test.ts 结构化断言守护,提示词改动不会悄悄破坏行为契约。
对于想要在自己项目中复刻这套模式的开发者,建议直接参照 lib/prompts/templates/agent-system-wb-student/system.md + lib/prompts/snippets/whiteboard-reference.md 的双层结构:上层模板回答"这个角色在什么条件下能做什么",下层片段回答"这个工具本身怎么用",再辅以 loader 的片段注入机制与测试守护,即可构建出既灵活又可控的多智能体协作提示词体系。