OpenMAIC 任务引擎Task Engine职业实训课程设计指南从 procedural-skill 工作流到 GO/STOP 安全判定【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC导读本文基于 OpenMAIC 仓库内置的vocational技能职业实训文档完整讲解「任务引擎Task Engine」模式的课程设计方法它如何把一条真实职业任务拆解为任务简报、操作工位procedural-skill、GO/STOP 决策关卡与完成核验而不是一堂概念课。读完本文你将掌握SKILL.md的场景结构与命名规范、outline-constraints.json机器可校验的硬约束、widgetOutline的真实字段契约以及生成侧大纲、场景内容、教师动作序列、路由归一化的完整调用链与约束门控可以直接据此为 OpenMAIC 设计或评审职业实训课程。一、技能是什么vocational的任务引擎定位OpenMAICOpen Multi-Agent Interactive Classroom的 Agent 运行时通过skills/目录向教学 Agent 注入可复用的课程设计能力。每个技能是一个目录包含SKILL.md与可选的outline-constraints.json结构性约束文件加载与调用机制实现在 lib/server/agent-runtime/skills.tsAgent 发现pi 的loadSkills()解析 frontmatterformatSkillsForSystemPrompt()把 name/description/location 写入系统提示词大纲注入技能正文与渲染后的约束一起被注入大纲生成器的teacherContext槽位skillOutlineContext()由独立的大纲 LLM 调用在技能约束下规划生成后校验checkOutlineAgainstSkill()用约束文件对返回的大纲做机器检查违规项作为工具结果诊断返回给 Agent由 Agent 决定是否重新规划。vocational技能的定义位于 skills/agent-runtime/vocational/SKILL.md其 frontmatter 明确了触发条件Vocational / technical training courses. Plans the course as a hands-on work task with an operation flow, tool and equipment state, safety boundaries and GO/STOP judgements, instead of a concept lecture. Use when the requirement names a real occupational task, a piece of equipment, a clinical or industrial procedure, or a certification skill.它面向的是真实职业任务、设备操作、临床或工业流程、考证技能。学习者的可见名称是「任务引擎」Task Engine内部 widget 名称如procedural-skill不得暴露给学习者但大纲 JSON 必须携带渲染器需要的真实 widget 契约。二、场景结构一次职业任务而不是一堂课SKILL.md明确了任务引擎场景的四段式骨架位置场景类型职责开头恰好 1 个slide任务简报工作任务、任务边界、培训目标、关键步骤、安全边界/风险提示、完成标准GO/STOP 标准。不是行业历史或概念定义页主体操作工位序列同一任务的按序操作阶段准备与设备检查 → 逐步操作 → 验证、测量或记录 → 交接/完成核验主体≥ 3 个interactive且widgetType: procedural-skill动手阶段学习者对照工具与状态逐步操作不安全或乱序操作会得到后果反馈主体≥ 1 个quiz定位为 GO/STOP 决策检查点面对异常读数或不安全条件继续、复查还是停机。不是词汇测验结尾完成核验以完成标准收尾而不是概念总结2.1 场景命名读起来像操作步骤场景标题应按工作步骤而非主题命名好「断电确认与验电」「绝缘电阻测量与判读」「异常读数继续还是停线」差「什么是低压配电柜」「配电柜的发展历史」「本课总结」2.2 禁止项Prohibited纯理论场景、概念讲座、公式推导泛泛的「课程总结」/「回顾」收尾页把所有动手场景做成同一个勾选清单checklist。要变化呈现方式检查单、测量仪表盘、步骤排序、故障排查等。2.3 非职业实训场景的降级如果需求没有操作流、没有工具或设备状态、没有安全或通过/失败判定例如数学推导、诗歌赏析Agent 需要在对话中一句话说明并规划普通课程不要强行给无流程的主题套用procedural-skill。对应实现中生成服务通过sanitizeNonTaskEngineOutline()把非任务引擎模式下的procedural-skill大纲强制降级为diagram见下文第五节。三、机器可校验的硬约束outline-constraints.json与SKILL.md同目录的 skills/agent-runtime/vocational/outline-constraints.json 是技能的可机检部分。它被同时用于两处渲染进大纲提示词 对模型输出做检查违规会作为工具结果诊断返回让 Agent 重新规划。完整内容{ $comment: Structural constraints for the vocational skill. Rendered into the outline prompt AND checked against the models output; violations come back to the agent as a tool-result diagnostic so it can re-plan. See lib/server/agent-runtime/skills.ts., allowedTypes: [slide, quiz, interactive], firstSceneType: slide, typeMix: [ { type: interactive, min: 3 }, { type: quiz, min: 1 }, { type: slide, max: 3 } ], requiredWidgetTypes: [procedural-skill], requiredWidgetOutlineFields: [task, steps, successCriteria] }逐项解读allowedTypes整门课只允许slide、quiz、interactive三种场景类型firstSceneType: slide第 1 场必须是任务简报幻灯片typeMixinteractive至少 3 场、quiz至少 1 场、slide至多 3 场requiredWidgetTypesinteractive 场景中必须至少出现一次procedural-skillrequiredWidgetOutlineFields每个 interactive 场景的widgetOutline必须填充task、steps、successCriteria三个字段。对应校验器在 lib/server/agent-runtime/skills.ts 的checkOutlineAgainstSkill()逐条核对场景数、类型白名单、首场景类型、类型配比、必需 widget 类型、widgetOutline必填字段以及「相邻 interactive 场景不得复用同一 widgetType」。值得注意的设计取舍是只报诊断、不自动改写一份规划是一个连贯整体机械翻转场景类型去满足配比会产生由 linter 拼装的课程因此违规列表交给 Agent 判断修复。renderConstraints()负责把约束渲染成提示词中的人类可读文本例如 At least 3 scenes of type interactive.、Every interactive scenes widgetOutline must populate: task, steps, successCriteria.。持久化场景也有一条对应检查路径checkScenesAgainstSkill()仅做诊断、永不回滚持久化其中requiredWidgetOutlineFields属于计划期字段因持久化场景不保留 widget-outline 草稿而被显式剔除。四、procedural-skill 场景的 widgetOutline 契约SKILL.md要求每个procedural-skill场景用真实契约填充widgetOutline字段说明取值/要求procedureType流程类型枚举repair、assembly、inspection、operation、customtask当前工位执行的具体任务具体操作描述tools该工位需要的工具、仪表、PPE 或材料列表steps该工位的有序操作至少包含一个判断/决策步骤successCriteria学习者如何判定本工位通过阈值、读数、状态而不是理解了概念errorConsequences跳步或不安全操作的后果风险检出、不安全状态、检查受阻、需复查、偏差检出、告警/报警、条件未解除不得继续类型层面的契约可进一步对照 DSL 参考文档 skills/agent-runtime/stage-dsl/references/widget.md 中procedural-skill一节根字段为type: procedural-skill、task、description、可选tools: string[]、steps: ProceduralSkillStep[]、可选successCriteria: string[]每个 step 必须含id、title、description可选tools与successCriteria。类型声明不强制 step 工具名出现在根tools、id 唯一或 successCriteria 可机检——这些是语义责任需要作者自行保证。4.1 一个可落地的 widgetOutline 示例{ id: scene_8, type: interactive, title: 绝缘电阻测量与判读, description: 学习者完成验电后对线路进行绝缘电阻测量并对照安全阈值判读结果。, keyPoints: [测量步骤, 阈值判读, 安全完成条件], order: 8, widgetType: procedural-skill, widgetOutline: { procedureType: inspection, task: 对已完成断电确认的低压配电柜出线回路测量绝缘电阻并判读, tools: [绝缘电阻表兆欧表, 绝缘手套, 验电器, 工作票], steps: [ 确认回路已断电并验电, 选择正确的量程并校表, 按顺序连接测试线并测量, 记录读数并对照安全阈值判读 ], successCriteria: [绝缘电阻读数不低于安全阈值, 测量记录完整, 无跳步或未验电情况], errorConsequences: [未验电直接测量导致触电风险, 读数低于阈值仍送电将造成设备损坏, 乱序操作触发告警并要求复查] } }五、从技能到大纲生成链路与门控vocational技能不是孤立的一份提示词而是嵌入在完整的任务引擎生成链路中。相关实现集中在 app/api/generate/scene-outlines-stream/route.ts 与 lib/prompts/templates/task-engine-outlines/system.md/user.md大纲提示词模板。5.1 适配性闸门Suitability Gate任务引擎大纲提示词第一步是判断需求是否为职业流程任务。适合的特征包括真实或模拟的工作任务、含步骤/检查/测量/记录/交接的操作流、存在工具/设备/材料/环境/患者/车辆/机器/人员状态、存在安全边界/质量标准/阈值/风险状态/完成标准、存在有意义的 GO/STOP、安全/不安全、通过/失败、复查、受阻、继续等决策、以及不安全或错误操作的真实后果。适合的示例NEV 电池包更换前的安全确认、低压配电柜送电前安全确认与绝缘检查、静脉输液患者身份核验与滴速设置训练、气体保护焊工前设备检查与试焊参数确认。不适合的示例勾股定理讲解、牛顿第二定律介绍、诗歌赏析、机器学习基础概念。5.2 任务引擎混合结构10–14 场对适合的任务大纲提示词要求生成 10–14 场的完整实训序列默认 10–12 场并且第 1 场必须是slide简报页覆盖任务目的、边界、培训目标、关键步骤、安全边界、完成标准/GO-STOP 标准使用稳定的 PPT 布局顶部标题一句话目标、中部恰好 3 张信息卡任务目的 / 关键风险 / 任务边界、中下部 4–6 个宏观训练阶段、底部 1 条紧凑 GO/STOP 标准安全红线须独立成卡5–7 场procedural-skill操作/确认工位2–4 场说明场景slide至多 1 场diagram2–4 场挑战场景interactivegame任务引擎混合结构中不得输出 code、simulation、visualization3d、pbl 或普通 quiz 场景。场景分解要求把整个任务拆成可训练的操作段风险识别/工单确认、PPE/工具/仪表检查、隔离/停机/设置/校准/检查/验证、测量/阈值/读数判读、异常处理或返工、GO/STOP 安全决策、完成核验或交接确认。提示词中还给出了一个 NEV-A12 的 12 场示例结构可作为设计蓝本。5.3 路由归一化与门控scene-outlines-stream路由对任务引擎模式输出做归一化normalizeTaskEngineOutlineslide场景剥除widgetType/widgetOutline/interactiveConfigprocedural-skill场景用兜底值补齐widgetOutlineprocedureType缺省inspection、task缺省用户需求、tools缺省[required PPE, task checklist]、steps缺省三段式、successCriteria与errorConsequences亦有缺省普通 widget 类型原样保留。同时sanitizeNonTaskEngineOutline()对非任务引擎模式返回的procedural-skill做净化降级删除procedureType/task/tools/steps/successCriteria/errorConsequences并把widgetType改为diagram——源码注释明确写道 procedural-skill is gated behind taskEngineMode to protect ordinary MAIC generation即procedural-skill被门控在任务引擎模式之后以保护普通 MAIC 生成。lib/server/agent-runtime/generation-tools.ts中的交互页面工具同样注明procedural-skill仅限任务引擎模式使用。六、场景内容生成procedural-skill widget 的完整 HTML 契约大纲定稿后每个procedural-skill工位会生成一个自包含 HTML 文档通过 iframesrcDoc渲染生成契约完整定义在 packages/openmaic/generation/templates/procedural-skill-content/system.md 与 user.md。6.1 核心原则流程实操不是勾选清单程序性练习不是静态说明任务完成不是步骤计分有状态的练习不是被动讲解轻量操作代理不是完整物理/机械模拟。学习者必须做出至少一次决策、判断、测量或工具选择——点完成不能是唯一有意义的交互。6.2 内嵌配置 Schema生成的 HTML 必须内嵌script typeapplication/json idwidget-config配置{ type: procedural-skill, task: ..., description: ..., tools: [...], steps: [ { id: step-1, title: ..., description: ..., tools: [...], successCriteria: [...] } ], successCriteria: [...], errorConsequences: [...] }要求type必须精确为procedural-skillstep id 使用稳定的 DOM 友好 idstep-1、step-2…输入只有纯步骤字符串时须转换为最小 step 对象保留输入的 error consequences 用于不安全/错误反馈路径配置保持通用不得硬编码演示场景。6.3 交互要求可机检的硬性标准可见步骤控件#step-1-control等必须是真实可点击控件button/input/select或带显式点击与键盘处理器包含可见文本Complete stepCheckMeasureChooseGoStop禁止空容器div idstep-1-control/div点击必须至少更新一个可见状态#progress-display、步骤行 class、#feedback-panel、#state-panel或成功标准门控反馈面板#feedback-panel为必选项#state-panel不能替代它状态面板须随交互变化reset 时恢复初始状态不得是静态装饰文本判断/决策步骤至少一个步骤是判断型交互模式包括选择正确工具、判断读数是否在安全阈值内、输入/确认测量值、决定失败检查是否需返工或复查、判断设备/任务安全与否、按当前状态选择下一步操作后果反馈至少一条错误/不安全路径要显示真实后果或状态变化风险检出、不安全状态、检查受阻、需复查、偏差检出、告警/报警、条件未解除不得继续不得只用 Correct/Wrong/Try again也不得用分数替代后果操作代理至少一个轻量操作代理带安全阈值范围的测量读数、仪表/表盘/指示灯/状态信号、工具使用状态、检查结果、安全状态信号简单、确定性、本地化不加载外部资源、不做复杂机械模拟成功标准门控成功标准必须基于真实状态更新初次加载不得显示已完成1/N 步完成不得把整体成功标准标记为完成reset 须把成功标准恢复为 pending重置可见、可点、可用的#reset-btn必须调用中央resetState()或等效全量重置路径恢复completedSteps、进度、反馈、状态/风险/决策/代理值、步骤行 class、成功标准与初始控件启停状态——不是仅改一个文本节点。6.4 运行时状态同步与 postMessage 契约生成的 JavaScript 必须让学习者点击与平台 widget 动作共享同一状态模型单一中央状态对象 单一renderState()/updateUI()渲染路径。点击处理与SET_WIDGET_STATE不得维护两套互不兼容的更新逻辑。平台经 iframe 消息下发动作时event.data.type为消息类型字段生成代码只允许支持四种既有类型消息类型读取字段行为SET_WIDGET_STATEdata.state支持data.state.completedSteps同步内部状态并按共享渲染路径重绘步骤行、进度、反馈、状态面板与成功标准HIGHLIGHT_ELEMENTdata.target对目标元素施加临时可见轮廓ANNOTATE_ELEMENTdata.targetdata.content可选在目标附近显示临时注释无 content 时不抛错REVEAL_ELEMENTdata.target使隐藏目标可见稳定教师动作目标stable selectors#task-panel、#tool-list、#step-list、[data-step-idstep-1]、#step-1-control、#step-1-feedback、#success-criteria、#progress-display、#feedback-panel、#reset-btn。规则明确禁止window.parent.postMessage、禁止发明新消息类型、禁止引入 iframe→平台回调。DOM 操作必须空值安全const el document.querySelector(...); if (!el) return;缺失的可选元素不得导致Cannot set properties of null。6.5 视觉风格多样化procedural-skill是训练机制不是固定视觉风格。模板明确要求不要把每个 widget 都做成深色仪表盘或勾选面板可选的呈现方向包括浅色步骤卡板、工单台、安全检查站、测量站、流程看板、模拟器式控制台、GO/STOP 决策站、交接检查板、故障排查站。无论视觉风格如何都必须保留任务操作、状态、决策、反馈、进度、重置、完成核验、稳定选择器与 postMessage 兼容不得把视觉变化变成只读 PPT。6.6 教师动作序列交互场景还需生成教师动作序列模板见 packages/openmaic/generation/templates/interactive-actions/system.md。输出为 JSON 数组type:text为教师旁白type:action使用四种合法动作名widget_highlight、widget_setState、widget_annotation、widget_reveal。对 procedural-skill widget 推荐优先使用[data-step-idstep-1]、#step-1-control、#progress-display、#reset-btn等稳定目标widget_setState的状态字段建议completedSteps、currentStep、feedback。设计原则要求单一教师声音、同会话连续性首页问候、中间页自然过渡、末页收尾3–8 条为自然教学节奏。七、测试保障契约的可验证性仓库通过多层测试固化上述契约可作为实现的直接证据tests/prompts/task-engine-outlines.test.ts 与 tests/generation/task-engine-outline-route.test.ts验证任务引擎大纲的结构首场 slide 简报、10–14 场、procedural-skill 配比、widgetOutline 字段完整性tests/generation/scene-content-route-vocational-gate.test.ts验证procedural-skill在非任务引擎模式被门控/降级tests/prompts/procedural-skill-content-quality-contract.test.ts 与 tests/generation/procedural-skill-content-gates.test.ts验证 widget 内容的质量契约决策交互、后果反馈、操作代理、成功标准门控、稳定选择器、reset 全量恢复、SET_WIDGET_STATE同步渲染等tests/agent-runtime/generation-tools.test.ts覆盖技能发现、约束渲染与大纲校验回路。这些测试与 lib/server/agent-runtime/skills.ts、app/api/generate/scene-outlines-stream/route.ts、packages/openmaic/generation/templates/procedural-skill-content/system.md 共同构成「技能文档 → 可机检约束 → 生成提示词 → 内容契约 → 校验门控」的完整证据链。八、实战检查清单为一个职业实训需求设计任务引擎课程时建议按如下顺序自检适配性需求是否有操作流、工具/设备状态、安全与通过/失败判定没有则走普通课程不使用procedural-skill结构首场是否为slide任务简报任务目的/关键风险/任务边界 3 卡 4–6 个宏观阶段 1 条 GO/STOP 标准总场次是否在 10–14 之间interactive ≥ 3、quiz ≥ 1、slide ≤ 3工位每个 procedural-skill 场景的widgetOutline是否填全procedureType/task/tools/steps/successCriteria/errorConsequencessteps 是否含至少一个判断步骤命名场景标题是否读起来像工作步骤而非主题差异化是否避免了所有动手场景都是同一勾选清单/深色仪表盘quiz 是否是 GO/STOP 决策而非词汇测验收尾是否以完成核验/交接确认收尾而非概念总结遵循以上检查项即可用 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），仅供参考