OpenMAIC 互动工作坊workshop-style让学员在做完中学会的技能型课堂设计指南【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC互动工作坊workshop-style是 OpenMAIC Agent 运行时内置的一类课堂设计技能Skill它把整门课组织成概念→动手、概念→动手的节奏用短幻灯片铺垫任务、用互动页interactive充当练习、用速测quiz做自查最后以一个整合小项目收尾让学员离开课堂时手里握着一件做出来的东西而不只是一堆听过的知识。本文结合 workshop-style/SKILL.md 及其配套约束文件、运行时校验实现与测试完整讲解该风格的设计骨架、widgetOutline 写法、旁白与教师名单roster规范、生成器传参方式以及机器如何对成稿做可检查的约束校验——读完后你可以直接用它规划、生成并验收一门互动工作坊课程。一、workshop-style 是什么一个技能、一种课堂形态在 OpenMAIC 中技能是放在skills/agent-runtime/skill-id/SKILL.md下的结构化指令文件通过 frontmatter 声明name、title与description。workshop-style技能位于 skills/agent-runtime/workshop-style/SKILL.md其描述description明确划定了它的适用边界适用workshop、bootcamp 集训、动手实操练中学边做边学以及任何学员离开时要带走一项技能的需求或用户直接点名这一风格。不适用系统化讲授课程应使用lecture-style见 skills/agent-runtime/lecture-style/SKILL.md带工具与安全门槛的职业操作流程培训应使用vocational。从技能文件的结构看workshop-style是典型的主题技能它不重复基础构建流程而是建立在一个更底层的技能之上——文档开头明确写道 stage-designstill governs how the stage is built即课堂骨架的构建大纲、教师名单、每页一次generate_scene、完成前补齐音频一律遵循 skills/agent-runtime/stage-design/SKILL.md本技能只约束课堂里装什么、听起来像什么。workshop-style与lecture-style是一对刻意互为镜像的风格。在 tests/agent-runtime/skills.test.ts 的pedagogy style skills测试组中两者被描述为为互换而生同一份需求换一个风格重新生成产物必须肉眼可辨地不同。测试ships both styles as discoverable alternatives还校验了两个技能的 description 互相点名lecture 的文案包含workshop-styleworkshop 的文案包含lecture-style并断言workshop-style的描述包含关键词workshop与「动手」确保模型在技能清单中能准确区分两者。二、骨架概念 → 动手的节奏技能文档用五个要点定义工作坊的页面结构The shape第一页是一张短幻灯片slide只告诉学员这节课结束时你将做出什么以及你马上要试的第一件事。不要大纲、不要学科史。每个概念后面紧跟一页动手页整门课保持concept → do it的节奏粗略标准是每两页中约有一页interactive或quiz。文档给出一条硬性直觉——如果两张讲解页挨在一起其中一张是多余的If two explanatory pages ever sit next to each other, one of them is unnecessary.。interactive页就是练习每页只隔离要搭建、要改变或要追踪的一件事。相邻的 interactive 页不得复用同一个widgetType——学员从试着做走向预测再走向应用练习媒介也要跟着换。quiz页是快速自查不是考试紧跟动手页放置让学员把刚才亲眼看到的结论说出来短小精悍两三道题即可。最后一页是整合小项目一个需要同时调动多项课程组件的interactive页把前面的练习当作它的零件而不是一张总结幻灯片——这是学员结束后截图留念的那一页。这套节奏对应的页面类型可以具象为一张流程示意第 1 页 slide —— 你将做出什么 马上要试的第一件事极短 第 2 页 interactive —— 动手只做一件事 第 3 页 quiz —— 把刚才的观察说出口2~3 题 第 4 页 slide —— 下一个任务的规则、形状、一个坑 第 5 页 interactive —— 动手换一种 widgetType ... 最后一页 interactive —— 整合小项目零件齐了拼出来三、幻灯片是任务简报Slides are task briefs工作坊里的幻灯片只为让下一个练习成为可能而存在技能文档给出的上限是每张 slide 只保留两到三个keyPoints——规则、形状、那一个易错点the rule, the shape, the one gotcha其余一切放进练习页。判定标准非常直接一张能脱离练习独立读成一课的幻灯片就是太长了砍掉它让 interactive 页去教。这也与lecture-style形成鲜明对照讲授风格的正文页要求四到六个keyPoints且是完整命题而工作坊恰恰反其道而行。四、widgetOutline每个互动页的身份证技能文档规定每一个interactive页必须携带填好的widgetOutline且永远包含concept这一页练习到底关于哪一件事。空 widgetOutline 的互动页会退化成通用页面在这个风格里这等于连课程的立身之本一起丢掉。五种 widget 各自必须填充的字段在 skills/agent-runtime/workshop-style/SKILL.md 中列出widgetTypewidgetOutline 必填字段simulationconcept、keyVariables学员实际去拨动的那些量codeconcept、languagediagramconcept、diagramType、nodesgameconcept、gameType、challenge、playerControlsvisualization3dconcept、visualizationType、objects、interactions互动页上的keyPoints描述的应是任务本身以及做完任务会揭示什么——学员改什么、应该注意到什么、这个观察逼出什么结论而不是要照本宣科朗读的事实。要理解widgetType/widgetOutline在下游如何落地需要看 lib/server/agent-runtime/generation-tools.ts 中generate_scene的参数契约widgetType只对 interactive 页合法合法值为simulation/diagram/code/game/visualization3d缺省时默认simulationprocedural-skill仍被任务引擎模式门控不接受在此传入见 generation-tools.ts。widgetOutline必须是普通对象缺省规则是仅给 widgetType 时补{ concept: title }仅给 widgetOutline 时 widgetType 默认simulation见 generation-tools.ts。非 interactive 页传入这两个参数会被直接拒绝generate_sceneonly accepts widgetType/widgetOutline for interactive pages。测试 tests/agent-runtime/generation-tools.test.ts 覆盖了 widgetType/widgetOutline 透传、空值拒绝null、字符串等畸形输入不写任何内容以及裸 widgetType 自动补 concept等行为。字段底层的完整类型定义在 lib/types/widgets.ts例如SimulationConfig要求variables: SimulationVariable[]name/label/min/max/default必填unit/step可选DiagramConfig的diagramType只允许flowchart/mindmap/hierarchy/systemCodeConfig的language只允许python/javascript/typescript/java/cpp等。更完整的逐字段参考见 skills/agent-runtime/stage-dsl/references/widget.md它同时提醒simulation的默认值是否落在 min/max 区间、step是否为正、图的边端点是否真实存在等语义责任类型系统并不负责证明。五、旁白即引导Narration is facilitation技能文档指出风格正是靠旁白被听见的因此这是最需要做对的部分规则如下句子要短一到两句一条。没有人在任务挂在屏幕上的时候还有耐心听一段长段落。提问多于陈述。动手页上的旁白大多是问句或指令例如「先把这个值调到最大看看会发生什么」「你觉得下一步会往哪边偏」「试完再往下看。」陈述句只留给学员已经亲眼看到效果之后的那个时刻。把活儿交给学员然后让开。说完做什么就停。一个在练习开跑之前就把答案讲完的旁白等于取消了这次练习。两个声音对话。教师布置任务助理共同促进者co-facilitator做反应、替学员去试错、问出大家心里都在想的问题。交替的短回合而不是独白。鼓励可以有但必须跟在一次尝试之后并且绑在具体事实上——「注意你刚才那一下曲线立刻翻过去了」而非「太棒了」。这套叙事要求在测试中同样被固化为可检查的事实tests/agent-runtime/skills.test.ts 的carries the narration style through the fields the generators actually read测试断言workshop-style与lecture-style的正文必须同时包含materialFacts、brief、set_roster、voiceDesign这四个字段名以及 exactly one teacher 这句话——即风格必须通过生成器真正读取的字段来传递。六、教师名单一位教师 一位协办助理运行时只允许恰好一位教师在set_roster的实现里对应硬校验set_roster needs exactly 1 teacher, got ...见 lib/server/agent-runtime/roster-tools.ts。因此工作坊的对话双声部是主讲教师 协办助理assistant而不是两位教师。技能文档对 roster 的写法要求用set_roster写教师名单一位用任务语言说话的实干型教师hands-on practitioner who talks in tasks一位温暖、敏捷、敢于当场出错的助理名单保持精简保证回合清晰可读把「short turns, question-first, encouraging」写进 personas把明快的节奏写进voiceDesign.delivery。set_roster的入参契约roster-tools.ts逐项支撑了这些要求至少 2 名 agent 且恰好 1 名teacher否则报错at-least-2-agents/teacher-count每个 agent 的persona要求 2~3 句、用课堂语言书写的人格与教学/学习风格描述而不是角色标签voice必须绑定list_voices返回的providerId::voiceId对克隆音色则绑定register_voice返回的精确对绝不凭空发明 id无可用音色时可省略运行时回退到部署默认voiceDesign含identity如 middle-aged male teacher、texture如 warm low-pitched slightly husky、delivery如 calm measured encouraging三个字符串字段——short turns, question-first 这类节奏正是写进delivery的。七、把风格带进生成器关键在字段文本一个容易被误解的事实OpenMAIC 没有大纲生成器。课程计划在对话中敲定然后调用create_stage再对每一页调用一次generate_scene每次一页、按升序、携带显式 brief。页面内容与旁白由互相隔离的调用分别生成每个调用只能看到该页的 brief、页面内容与当前 roster——所以在提示词里点一下技能名不会产生任何效果只有写进那些字段里的文本才会被下游看到。据此技能文档给出三条显式传递路径把概念→练习的节奏与结尾整合项目写进每一页generate_scene的brief把双声部引导方式写进set_roster的每个 persona把每页的旁白指令通过generate_scene.materialFacts传入例如「旁白为引导式短句一到两句一条提问多于陈述」「本页先让学员动手结论留到操作之后」。从实现看materialFacts会被作为该页的keyPoints与技能目标写入见 generation-tools.ts与brief一起成为页面生成与旁白生成共同的依据。整体构建顺序由 skills/agent-runtime/stage-design/SKILL.md 规定先在对话中用ask_user敲定逐页计划title / type / brief→create_stage课程在系列中则一并传folderId→ 生成任何页面之前先set_roster→ 每页一次generate_scene→list_scenes核对持久化结果。生成失败的处理规则确定性失败不重试、invalid-model-output改 brief 不改教学意图后重试一次、重试仍失败则留下空页继续后续页并如实报告缺口也都在这份底层技能里。八、场景命名用祈使句给动作起名工作坊的页面标题命名的是学员要去做什么一律祈使句好「把这段循环改成能跑的」「调参数找出它崩掉的那一刻」「用今天的三块拼一个能用的小工具」不好「循环的概念」「参数敏感性分析」「综合练习」这一节与幻灯片是任务简报同源标题、keyPoints、旁白都服务于同一个原则——工作坊的每一寸内容都是为了促成学员的下一个动作。九、机器可检查的那一半outline-constraints.json 与运行时校验技能文档无法表达的部分被单独放进约束文件 skills/agent-runtime/workshop-style/outline-constraints.json其中$comment说明该风格的主张是概念→动手的节奏因此可检查的一半是动手页占比——用比例而非幻灯片页数上限来表达从而在任何课程长度下都成立同时配一个绝对下限保证短工作坊里也有真练习而最后一页是整合项目旁白短句、提问优先这两项刻意不在此检查前者没有末页规则后者非结构性问题靠 keyPoints、roster persona 与逐页 materialFacts 承载。该文件的实际内容{ allowedTypes: [slide, quiz, interactive], firstSceneType: slide, typeMix: [ { type: interactive, min: 3, minRatio: 0.4 }, { type: quiz, min: 2 } ], allowedWidgetTypes: [simulation, diagram, code, game, visualization3d], requiredWidgetOutlineFields: [concept], noConsecutiveSameWidgetType: true }这些约束在运行时如何被执行可以在 lib/server/agent-runtime/skills.ts 中逐条对应约束文件与 SKILL.md 同目录、作为兄弟文件加载——frontmatter 是模型可见的契约这个文件是检查器的契约混在一起会让每次 schema 调整都改动模型读取的内容见 skills.tscheckOutlineAgainstSkillskills.ts逐条落地firstSceneType校验第 1 页必须是slidetypeMix校验绝对数量interactive 至少 3、quiz 至少 2与占比interactive 少于 40% 时报错错误消息形如 interactivescenes are X% of the course, the skill requires at least 40%allowedWidgetTypes与noConsecutiveSameWidgetType负责 widget 层面的约束requiredWidgetOutlineFields检查每个 interactive 页的widgetOutline.concept非空null、空数组、空字符串均判缺失checkScenesAgainstSkillskills.ts把已持久化的真实页面投影成可检查形状再做同一套校验——注意requiredWidgetOutlineFields是仅计划期约束持久化场景不保留 widgetOutline 草稿因此被刻意剔除。校验是诊断性的违规会作为 tool-result 诊断返回给 Agent 以便它重新规划持久化不会被回滚。测试给出了这套校验的完整行为画像tests/agent-runtime/skills.test.tsaccepts its own page mix一个典型工作坊型计划slide → interactive(code) → quiz → slide → interactive(simulation) → interactive(diagram) → quiz → slide → interactive(game) → interactive(visualization3d)通过workshop-style约束且这个计划里相邻 interactive 页的 widgetType 全部不同rejects the other style page mix讲授型计划大量 slide、单个 quiz、单个 interactive套到 workshop 约束下必然报出 interactive... at least 3 与 quiz... at least 2反之工作坊型计划套到lecture-style约束下必然报出 slide 占比与 interactive 上限违规——这从反面证明了两种风格确实肉眼可辨地不同。十、什么时候不适用把不是工作坊的请求挡在门外技能文档最后明确给出边界如果主题没有可练的东西——历史叙事、鉴赏课、只需要理解的知识体系——就用一句话说明并改用lecture-style。理由很直接给没有任务的主题硬加练习产出的只是忙碌工作busywork而学员对这种东西的识别速度比什么都快。对照lecture-styleskills/agent-runtime/lecture-style/SKILL.md可以更清楚地看到这条分界线讲授风格让一个声音把学员从不知道带到能解释页面为解释服务而非打断它每四到五页才出现一次刻意而稀少的 quizinteractive 至多一页且只给全课机制最重的那一个概念结尾收在论证而非要点回顾上。一个把练的需求包装成讲授的课程是学员看完了却用不上的课程——反之亦然。结语一份可直接执行的检查清单综合技能文档、约束文件与运行时实现可以用一份清单验收工作坊风格是否成立第 1 页是slide且很短讲清你将做出什么 马上要试的第一件事interactive 页至少 3 个、占比不低于 40%quiz 至少 2 个每个 interactive 页都带非空的widgetOutline.conceptwidgetType 属于simulation/diagram/code/game/visualization3d相邻互动页不重复同一种 widget幻灯片只留 2~3 个keyPoints其余交给练习旁白一到两句一条、提问多于陈述、双声部对话、鼓励绑在具体行为上——通过 persona 与materialFacts写进生成器真正读取的字段roster 恰好一位教师加一位协办助理节奏写在voiceDesign.delivery最后一页是整合小项目而非总结页标题是祈使句。对照 skills/agent-runtime/workshop-style/outline-constraints.json 与 lib/server/agent-runtime/skills.ts 的checkOutlineAgainstSkill实现前三条可以由运行时自动校验并回传诊断其余各条是技能文档要求 Agent 在写作时自行携带的风格责任——这也是 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），仅供参考
