OpenMAIC Interactive 场景 Widget 字段完全参考从 content 根结构到 patch_stage 实战编辑【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC本文是 OpenMAICOpen Multi-Agent Interactive Classroom中scene.type interactive场景的scene.content结构化字段权威参考。它覆盖 content 根节点五个字段、六种 Ultra 交互模式WidgetConfig变体simulation / diagram / code / game / visualization3d / procedural-skill的完整字段表与类型语义并结合patch_stage/read_stage/grep_stage三件套给出大型 HTML 文档与 widget 配置的高精度编辑工作流。读完本文你将能正确读写 interactive 场景源码、避免判别器不一致与字段失配等常见陷阱并直接用 Agent 工具对场景做零风险的精修。1. 适用对象与数据来源本章描述的是scene.content在scene.type为interactive时的形态。其字段定义并非凭空而来而是来自四处事实来源的汇合共享的 interactive contract由openmaic/dsl包提供其WidgetConfigBase基类型要求每个配置必须具备type判别字段但允许 App 自定义扩展字段App 侧六个WidgetConfig变体的 TypeScript 联合类型定义在 lib/types/widgets.tsSimulationConfig、DiagramConfig、CodeConfig、GameConfig、Visualization3DConfig、ProceduralSkillConfig最终汇合为WidgetConfig联合类型applyWidgetEdit配置合并与写路径见 course-edit/apply.tsvalidateAppScene运行时的结构校验器见 lib/document-store/validators.ts。理解这条来源链至关重要TypeScript 类型比运行时校验更严格。patch_stage的写入屏障只在根节点之下做结构校验对widgetConfig内部保持历史宽容见第 3 节因此能写进去不代表渲染器能消化。2. Interactive content 根结构一个合法的 interactive 场景 content 根如下{ type: interactive, html: !doctype html..., widgetType: simulation, widgetConfig: { type: simulation } }根节点共五个字段字段类型必填含义typestring是固定为interactive必须与scene.type一致htmlstring条件性完整 HTML 文档渲染时作为 iframe 的srcDocurlstring条件性iframe 的src回退值仅在html缺失时使用widgetTypewidget-type 联合否历史遗留/顶层 widget 判别器widgetConfigobject否类型化的 Ultra 交互模式配置两个关键约束与语义html与url至少其一必须是字符串。注意空字符串也是字符串历史文档允许存在空串。两者同时存在时contract 将html视为srcDoc源url作为html缺失时的回退。这一点在渲染侧得到印证——interactive-renderer.tsx 中srcDoc取patchHtmlForIframe(content.html)只有当patchedHtml不存在时才用content.url作为src。在运行时的validateAppScenelib/document-store/validators.ts中interactive 分支的校验要点是html或url必须有一个是字符串、html必须是字符串、widgetConfig必须是对象防止原始值在 hydration 时in抛错而在widgetConfig内部刻意保持宽容以兼容历史存储形态。3. Widget 判别器discriminator与一致性铁律合法的 widget 类型共六种simulation diagram code game visualization3d procedural-skill判别器出现的位置有两个顶层widgetType与widgetConfig.type。applyWidgetEdit在做set_config合并时会保留已有配置的类型它优先取widgetConfig.type缺失时回退到widgetType。也就是说顶层指针raw pointer可以独立地分别写这两个判别器所有同时存在的判别器必须保持一致否则渲染器无法确定用哪个变体解释字段。另外必须警惕改动配置类型时必须同步替换该变体专属字段。例如把simulation改成diagram若仍保留variables而缺少nodes/edges就会被渲染器拒绝——这正属于运行时校验宽容、TypeScript 类型却严格要求的落差区。4. 六种 WidgetConfig 变体详解以下六种变体均在 lib/types/widgets.ts 中定义并继承自openmaic/dsl的WidgetConfigBase要求type允许扩展字段。4.1simulation— 参数化仿真实验字段类型含义typesimulation判别器conceptstring被仿真的概念descriptionstring面向学习者的解释variablesSimulationVariable[]可调数值输入每个SimulationVariable的字段字段类型必填含义namestring是状态键state keylabelstring是面向学习者的标签minnumber是下界maxnumber是上界defaultnumber是初始值unitstring否展示单位stepnumber否控件增量可选的presets是数组每个预设形如{ name: Heavy object, variables: { mass: 10 } }类型层不保证的语义需作者自行负责default是否落在min/max之间、step是否为正、每个 preset 的键是否都是已声明的变量名。第 8 节的 Worked example 2 会展示为何要在写后自查default max。4.2diagram— 流程图/思维导图/层级图/系统图字段类型必填合法值/含义typediagram是判别器diagramTypestring union是flowchart/mindmap/hierarchy/systemdescriptionstring是面向学习者的解释nodesDiagramNode[]是图的顶点edgesDiagramEdge[]是有向连接revealOrderstring[]否按揭示顺序排列的节点 id节点DiagramNode字段类型必填取值idstring是节点标识labelstring是可见标签position{x:number,y:number}否显式坐标detailsstring否附加描述typestring union否default/decision/start/end边DiagramEdge必须包含字符串id、from、tolabel可选。类型层同样无法证明边的端点或revealOrder里的 id 一定存在于nodes中——写边之前务必先核对节点清单。4.3code— 代码练习与自动评测字段类型必填合法值/含义typecode是判别器languagestring union是python/javascript/typescript/java/cppdescriptionstring是任务说明starterCodestring是学习者的初始程序testCasesCodeTestCase[]是评测用例hintsstring[]是学习者提示solutionstring是参考答案测试用例要求字符串id、input、expected可选字段为字符串description与布尔isHidden。特别提醒solution、隐藏的预期结果isHidden: true的 expected与隐藏用例都属于源数据而非可见文本。用read_stage detail:text这类文本投影搜不到它们必须改用grep_stage scope:source见第 6 节。同样地写入屏障不强制测试用例 id 唯一也不校验代码能否在所选语言中通过解析——这两点依赖 Agent 或人工自行把关。4.4game— 答题/谜题/策略/卡牌游戏字段类型必填含义typegame是判别器gameTypestring union是quiz/puzzle/strategy/carddescriptionstring是面向学习者的游戏描述questionsGameQuestion[]否类测验游戏内容scoringobject是计分控制achievementsobject array否具名解锁条件题目GameQuestion必须包含id、question、type、options、correcttype为single或multipleoptions为string[]correct为 number 或 number 数组。类型层不声明该数字是 0 基下标、1 基下标还是选项 id——不要猜测去读一个相邻的正常工作的 game 并沿用其约定可选字段为字符串explanation与数字points。计分scoringcorrectPoints必填可选的数字字段为speedBonus、comboMultiplier、penalty。成就achievements每项要求字符串id、name、description、icon、condition其中condition的含义与书写语言不由类型规定。4.5visualization3d— 三维场景可视化根字段字段类型取值typeliteralvisualization3dvisualizationTypeunionmolecular/solar/anatomy/geometry/physics/customdescriptionstring面向学习者的描述objectsobject array场景对象每个对象要求id与下列类型之一sphere | box | cylinder | cone | torus | plane | custom可选对象字段name: stringposition: {x,y,z}rotation: {x,y,z}scale: number | {x,y,z}children: Visualization3DObject[]层级对象materialanimation材质material的type为basic、lambert、phong、standard或emissive可选字段color、emissive字符串、wireframe、transparent布尔与opacity数字数字取值范围未在类型中规定。动画animation的type为orbit、rotate、bounce或pulse可选speed数字与axisx/y/z。可选根级interactions使用下列类型之一orbit | zoom | pan | slider | button | toggle它们可携带target、label、param与数字型min、max、default、step。可选camera包含数字向量position、target与数字fov。可选lighting包含环境光、平行光与点光源颜色为字符串、强度为数字、带位置的光源可携带{x,y,z}。可选presets携带字符串name、可选字符串description与开放的state: Recordstring, unknown。诚实边界渲染器对单位的解释、坐标系手性、以及custom对象负载的受支持格式均不由这些类型规定。在缺少可参照的正常示例时不要在范围之外自造值——先读渲染器代码再动手。4.6procedural-skill— 分步程序技能训练字段类型必填含义typeprocedural-skill是判别器taskstring是学习者总任务descriptionstring是任务说明toolsstring[]否命名工具/资源stepsProceduralSkillStep[]是有序流程successCriteriastring[]否整体完成标准每个步骤ProceduralSkillStep要求字符串id、title、description可选字段为tools: string[]与successCriteria: string[]。类型层不强制步骤中的工具名必须出现在根tools中、id 必须唯一、成功标准必须可机检。5. HTML 分支iframe srcDoc 与文本投影html是完整 HTML 文档字符串不是幻灯片富文本方言。共享 contract 规定它经 iframesrcDoc渲染渲染侧 interactive-renderer.tsx 的patchHtmlForIframe会先加工 HTML 再交给InteractiveIframeHost且以sceneId为键在 keep-alive 池中常驻 iframe详见 InteractiveIframeHost.tsx 与 e2e 用例interactive-iframe-keepalive-619.spec.ts。在写路径上patch_stage做结构校验后直接存储字符串不会调用applyHtmlEdits——通用指针set会精确替换整个字符串。而read_stage detail:text会移除 script/style 块与标签、折叠空白后在剩余文本上搜索它是投影projection不是浏览器渲染更不是消毒器sanitizer。安全相关结论必须克制安全策略、iframe sandbox 标志、CSP、脚本执行与网络访问都不由这些数据类型确立不要从本章内容反向推断它们。6. 大型 HTML 与长文本用 str_replace不要整体 set一个 27 KB 的交互文档不应该用set整体重写重复传输整串开销大且任何转录错误都会静默破坏页面。只改一处时用str_replace精确替换存储串中的锚点。推荐的黄金流程用read_stage读detail:source在/content/html中定位精确片段用patch_stageop:str_replace 短而唯一的锚点再次read_stage detail:source再用grep_stage验证改动生效且无残留。示例把重力仿真的一个常量调慢27 KB 文档内改一处第一步读源码read_stage({ path: /scenes/3, detail: source })在源码中定位/content/html contains const speed 0.015 * dt第二步只改这一处patch_stage({ target: /scenes/3, intent: Slow the gravity simulation, ops: [ { op: str_replace, path: /content/html, oldText: const speed 0.015 * dt, newText: const speed 0.006 * dt } ] })第三步验证再次read_stage detail:source然后grep_stage搜0.015期望 0 命中、0.006期望 1 命中。str_replace的行为约束与 dsl-tools.ts 的参数声明一致锚点必须在存储串中恰好出现一次0 命中则整个补丁被拒绝错误信息含出现次数多次命中时需扩展锚点或设置replaceAll:truenewText可为空字符串用于删除锚点oldText与newText都不能包含读侧媒体省略占位符仅当整串确实要变时才用set。7. 常见陷阱清单把本章当作写入前的自检单widgetType与widgetConfig.type不一致指针从/widgetConfig/...开始而非/content/widgetConfig/...指针必须根植于该场景的精确源码改了配置类型却未替换变体专属字段仿真default落在取值范围之外图的边指向不存在的节点 id游戏correct使用猜出来的下标约定期望隐藏的代码测试数据出现在文本搜索里它们属于scope:source整体重写配置对象导致丢失未知的历史字段校验通过 ≠ 语义完整TypeScript 说某字段必填但历史运行时校验器在widgetConfig之下很宽容一个被接受的不完整配置会在渲染器中失败。接受只证明结构合法不证明语义完整。8. 三个完整实操示例8.1 示例 1修改仿真引导文案读源码read_stage({ path: /scenes/scene_widget, detail: source })定位/content/widgetConfig/type simulation /content/widgetConfig/description Change the mass只改叶子节点patch_stage({ target: /scenes/scene_widget, intent: Clarify how to operate the simulation, ops: [ { op: set, path: /content/widgetConfig/description, value: Drag the mass slider and compare the acceleration. } ] })再次读源码验证type、variables与presets均未被改动——这正是补丁叶子节点原则的落地。8.2 示例 2调整单个仿真边界读源码用name定位变量下标/content/widgetConfig/variables/0/name mass /content/widgetConfig/variables/0/max 10打补丁patch_stage({ target: /scenes/3, intent: Extend the mass experiment range, ops: [ { op: set, path: /content/widgetConfig/variables/0/max, value: 20 } ] })读回后自查default max——校验器不会替你查这一点见第 4.1 节。8.3 示例 3替换整个 HTML 文档先读源码确认该场景用的是html而非仅有url然后精确替换文档串patch_stage({ target: /scenes/3, intent: Replace the interactive document copy, ops: [ { op: set, path: /content/html, value: !doctype htmlhtmlbodymainNew activity/main/body/html } ] })读detail:source验证精确字节再读detail:text验证New activity出现在文本投影中——两种读取视角各司其职source 证明写对text 证明可见。9. 硬性规则Hard Rules判别器一致content 与 widget 的判别器必须保持一致补丁叶子只为改一个标签而整体替换配置是不允许的以 TypeScript 联合类型为创作契约即使历史写入校验器宽容也按 lib/types/widgets.ts 的严格要求书写隐藏数据用 source 搜索隐藏测试、答案、id、状态一律走grep_stage scope:source写后必读回每一次写入之后都要读回验证。10. 深入阅读关联文档本体skills/agent-runtime/stage-dsl/references/widget.mdApp 侧类型定义lib/types/widgets.tsStage DSL 工具实现read_stage / patch_stage / grep_stage / str_replace 语义lib/server/agent-runtime/dsl-tools.ts写入与盘点逻辑inventoryScene 对 interactive 的处理widgetType回退widgetConfig.typelib/server/agent-runtime/course-edit/apply.ts运行时结构校验interactive 分支lib/document-store/validators.tsiframe 渲染与 keep-alivecomponents/scene-renderers/interactive-renderer.tsx、components/scene-renderers/InteractiveIframeHost.tsx端到端验证用例e2e/tests/interactive-iframe-keepalive-619.spec.ts【免费下载链接】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），仅供参考