企业官网建设流程全解析

OpenMAIC 智能课堂语音规范：speech-guidelines 提示词片段的设计原理与实战应用

【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC

导读

本文聚焦 OpenMAIC（Open Multi-Agent Interactive Classroom）提示词体系中的核心片段speech-guidelines，它定义了多 Agent 课堂中 AI 教师与助教的"说话方式"——这是一段直接决定课堂沉浸感与自然度的规则集。读完本文，你将掌握：该片段在 lib/prompts 模板体系中的装配位置、八条语音铁律的逐条设计动机与源码证据、它与 JSON 输出格式、长度控制、白板动作等相邻规则的协同机制，以及如何在不改动仓库的前提下验证与调优这类提示词片段。

一、片段定位：它是"说什么"与"怎么说"之间的桥梁

在 OpenMAIC 的多 Agent 课堂里，Agent 的每一次回复并不是自由文本，而是一个由action与text对象交错组成的 JSON 数组：action负责在舞台上触发视觉效果（聚光灯、激光笔、白板绘制），text才是 Agent 真正说出口的内容。这带来一个关键问题——模型很容易把"自己在做什么"当成"要讲给学生的内容"，从而说出"让我来添加一个图表"这类自指式旁白。

lib/prompts/snippets/speech-guidelines.md 正是为此而生：它专门约束text对象的内容应该长什么样。片段标题自带的(CRITICAL)标记表明，这段规则被设计为不可省略的硬性约束，而非建议性措辞。

片段文件本身十分精简，但它是整个提示词体系的"行为底线"之一。从 lib/prompts/types.ts 可以看到，SnippetId联合类型中显式注册了'speech-guidelines'，与action-types、element-types、whiteboard-reference等片段并列，说明它是一等公民级别的可复用提示词构件。

二、八条语音铁律逐条拆解

片段正文包含 8 条规则，下面结合仓库源码逐条解读其设计动机与落地方式。

1. 效果与语音并发触发

Effects fire concurrently with your speech — students see results as you speak

规则要求 Agent 把"视觉呈现"与"口头讲解"设计为并行而非串行。从 lib/orchestration/prompt-builder.ts 中的排序原则可以看到配套的落地约定：

- spotlight/laser actions should appear BEFORE the corresponding text object (point first, then speak) - whiteboard actions can interleave WITH text objects (draw while speaking)

也就是说，聚光灯/激光笔这类"指向"动作必须先于文本出现（先指、后说），而白板绘制类动作则允许与文本交错（边画边说）。这正是为了让课堂节奏像真实教师一样流畅：学生看到画面变化的同时听到解释，而不是先等一段冗长说明、再看到内容凭空出现。

2. 文本内容 = 说出口的课堂语言

Text content is what you SAY OUT LOUD to students - natural teaching speech

这一定义在 lib/prompts/templates/agent-system/system.md 的输出格式规则中再次强调：type:"text"对象的content字段即"speech text"（语音文本）。它会被 TTS 合成朗读给学生听，因此必须是口语化的教学语言，而不是面向渲染器的说明文字。

3–4. 禁止自指式旁白

Do NOT say "let me add...", "I'll create...", "now I'm going to..." Do NOT describe your actions - just speak naturally as a teacher

这是最容易犯、也是课堂上最容易出戏的错误。lib/prompts/templates/agent-system/system.md 中专门设了"Bad Examples"区块来固化反面教材：

[{"type":"text","content":"Let me open the whiteboard"},{"type":"action",...}] (Don't announce actions!) [{"type":"text","content":"I'm going to draw a diagram for you..."}] (Don't describe what you're doing!) [{"type":"text","content":"Action complete, shape has been added"}] (Don't report action results!)

三个坏例子分别对应"预告动作""描述动作""汇报结果"三种典型的自指旁白，均被明令禁止。设计意图很清晰：学生的注意力应该被引导到知识本身，而不是 AI 的操作日志。

5. 画面自会说话，无需口头报幕

Students see action results appear on screen - you don't need to announce them

这条与第 4 条互为表里。白板绘制、公式弹出等动作的结果由渲染层直接呈现，Agent 的口头文本只需要承接讲解职责。lib/prompts/templates/agent-system-wb-teacher/system.md 中"Draw conservatively. 1-3 elements per response"的约束同样服务于这一理念——画面元素服务于"一个关键知识点"，剩下的交给语音。

6. 语音不依赖动作成败

Your speech should flow naturally regardless of whether actions succeed or fail

这是一条极具工程深度的容错设计。动作由动作引擎异步执行，可能因参数非法、元素缺失等原因失败；但课堂节奏不能因此被打断。规则强制要求语音文本在逻辑上独立于动作执行结果——即使某个动作失败，Agent 说出的话依然成立，避免出现"我刚才的图表好像没画出来"这类让课堂坍塌的台词。

7. 文本内容禁止使用 Markdown

NEVER use markdown formatting (blockquotes >, headings #, bold **, lists -, code blocks) in text content — it is spoken aloud, not rendered

text内容最终会被 TTS 朗读，任何 Markdown 标记都会原样混入语音，造成灾难性的朗读效果。这条规则与 lib/prompts/templates/agent-system/system.md 中"Output a single JSON array — no explanation, no code fences"的格式约束互为补充：JSON 数组层面不允许代码围栏，text 内容层面不允许 Markdown 标记，双层防线确保语音文本纯净。

8. 长度与口语化风格（模板级强化）

片段正文之外，lib/orchestration/prompt-builder.ts 还在模板层补充了口语化要求与分角色长度目标：

- Length targets count ONLY your speech text (type:"text" content). Actions do NOT count toward length. - Speak conversationally and naturally — this is a live classroom, not a textbook. Use oral language, not written prose.

并按照角色区分长度档位：教师约 100 字符、助教约 80 字符、学生约 50 字符（1–2 句话）。注意其精心设计的细节：动作不计入长度，从而鼓励 Agent 大胆使用动作、不必担心"动作多了导致语音超长"。

三、装配机制：snippet 如何在构建期拼入系统提示词

speech-guidelines 不是硬编码在某个模板里的文本，而是通过{{snippet:speech-guidelines}}语法装配进 agent-system 模板 的。该模板同时服务于agent-system-wb-teacher、agent-system-wb-assistant、agent-system-wb-student三套白板角色变体，因此这段语音规范对所有角色一次性生效。

从 lib/prompts/loader.ts 的processSnippets实现可以看到装配机制：

export function processSnippets(template: string): string { return template.replace(/\{\{snippet:(\w[\w-]*)\}\}/g, (_, snippetId) => { return loadSnippet(snippetId as SnippetId); }); }

loadSnippet从lib/prompts/snippets/<id>.md读取文件内容并trim()后直接拼接。三个关键特性值得注意：

1. 构建期静态拼装：snippet 在系统提示词加载时完成注入，最终发送给 LLM 的是拼装完成的完整提示词，不存在运行时动态取用的开销。
2. 缺失即失败：lib/prompts/README.md 明确记载，{{snippet:name}}在文件缺失时会直接抛错，而不是像变量插值那样静默透传。拼写错误（例如speach-guidelines）会在加载阶段立即暴露，绝不会带着残缺提示词去调用 LLM。
3. 处理顺序固定：README 规定处理顺序为"先 snippet 拼装 → 再条件块 → 最后变量插值"，因此 snippet 内部也可以包含{{#if}}块与{{variable}}占位符。

从 lib/prompts/index.ts 可以看到，对外暴露的 API 包含loadPrompt、loadSnippet、buildPrompt、processSnippets等函数，而buildPrompt(promptId, variables)返回{ system, user }完整提示词对。

四、与相邻提示词片段的协同

speech-guidelines 不是孤岛，它与 lib/prompts/snippets 下的其他片段及模板内联规则构成一张约束网：

尤其值得注意白板助教规范中的设计哲学：助教被要求"默认只说话、白板动作是最后手段"，这与 speech-guidelines 第 5 条"画面自会说话"形成互补——不同角色通过不同的"语音/动作配比"实现课堂分工，但都共享同一条语音自然度底线。

五、测试与质量保障：如何守住语音规范不回归

模板类改动最怕"悄悄回归"，仓库用结构断言测试替代了早期的字节级快照测试。tests/prompts/templates.test.ts 的注释说明了动机：结构断言能在提示词内容有意微调时避免强制快照更新，同时捕获真正的回归（缺失变量、角色派发损坏等）。

针对 snippet 机制本身，tests/prompts/loader.test.ts 覆盖了两个关键行为：

• 正常加载：loadSnippet('speech-guidelines')能正确读到片段内容；
• 失败即抛错：未知的 snippet id 抛异常而非静默透传，确保拼写错误在加载期被拦截。

tests/prompts/templates.test.ts 还专门断言了"whiteboard-reference snippet 已接入每个角色模板"，同样的结构断言模式也可以推广到 speech-guidelines——从源码结构看，这类"关键 snippet 必须装配到所有角色模板"的断言，正是防止语音规范被某条角色分支遗漏的有效手段。

lib/prompts/README.md 给出了本地验证的最低成本路径：运行pnpm test tests/prompts即可执行模板烟测套件；若需端到端验证（Agent 循环 + 模板拼装 + 聊天/导演集成），可启动 dev server 后使用白板 eval 工具链跑一个场景。README 还特别提到，loadPrompt与loadSnippet每次调用都直接读盘、无缓存——这意味着提示词 Markdown 的改动无需重启 dev server 即可生效，非常适合提示词工程师快速迭代语音规则。

六、给提示词工程师的落地建议

综合片段本体与仓库实现，可以提炼出几条可复用的工程经验：

1. 规则要"可证伪"：speech-guidelines 的每条规则都能用一句具体的正例或反例验证（如坏例子区块），比抽象的"请自然说话"更容易被 LLM 遵守、也更容易写测试断言。
2. 片段化 + 失败即报错：把跨模板复用的行为约束抽成 snippet，借助 loader 的抛错机制让拼写错误在加载期暴露，而不是污染线上提示词。
3. 语音与动作解耦：长度统计只计入type:"text"内容、语音不依赖动作成败，这两条设计让模型敢于并发触发动作，也容忍动作引擎的偶发失败。
4. 分角色但共享底线：教师/助教/学生在长度、绘制频率上分级约束，但"不说旁白、不用 Markdown、口语化"是所有人的共同底线，通过单一 snippet 装配保证一致性。

七、总结

speech-guidelines 虽只是 lib/prompts/snippets 下的一个 8 行 Markdown 片段，却是 OpenMAIC"多 Agent 沉浸式课堂"体验的关键地基：它把"AI 教师"从"报幕员"拉回"讲解者"的位置，通过{{snippet:}}机制在构建期注入所有角色模板，并与 JSON 输出格式、动作排序、分角色长度控制等规则协同，最终让学生听到的是流畅、自然、聚焦于知识本身的课堂语音。理解这条片段的装配路径与约束逻辑，也就理解了如何为多 Agent 教学系统设计高质量的语音行为规范——它是提示词工程中"行为约束"一类问题的范本实现。

【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC