dsh-openmaic

一句话定位

把 OpenMAIC 教学平台带进 DSH：让模型把一段教学需求变成一个"点开就能上课"的课堂链接，并能在对话里就地画出交互式教学卡片、滑片和小组件，让讲解从纯文字升级成可玩、可点、可交互的演示。

核心能力

• 生成可上课的课堂链接：把一句教学需求（如"帮我做一节量子物理入门课"）提交给 open.maic.chat，等待异步生成完成，返回课堂 URL
• 渲染内联教学卡片：把模型写好的 HTML 片段（概念卡、自测题、分步演示）作为带独立 CSP 的沙盒卡片就地显示
• 渲染交互式小组件：把模型按合约写的完整 HTML 文档（模拟器、问答游戏、代码挑战）做成沙盒卡片，边写边流式预览
• 渲染单页幻灯片：把模型写的 PPTist 风格 JSON 交给 OpenMAIC 官方渲染器，画布固定 1280×720，支持文本、形状、图表、公式、代码
• 接入苏格拉底式教学 skill：把当前会话转成引导式教学对话，并按需拉取上面的卡片、滑片、小组件作为教具

技术实现

• 语言: TypeScript
• 关键依赖: @openmaic/generation（小组件后处理）、@openmaic/renderer（slide/卡片渲染）、@openmaic/dsl（DSL 类型）、echarts（图表）
• 架构模式: 双端注入——node 端通过 Cordis 插件把四个工具和一个技能 provider 注册进 DSH（tools/systemPrompt/skills），客户端运行时通过 tool.call.toolview slot 接管三类卡片的渲染
• 入口文件: src/index.ts（node 端）、src/client/index.tsx（web 端，./client 子路径）

适用场景

当用户在 DSH 里提出"帮我做一节 XX 课""画个抛体运动模拟器""把这一步用图示给我看看"这类请求时，普通 LLM 只能返回文字或静态图表。这个插件让模型直接调用 open.maic.chat 的生成 API 拿到完整课堂，或在对话里就地渲染出能点击、可交互的卡片、滑片和小组件，把"看解释"变成"上手练"。适合教育类博主、培训师、需要可视化讲解复杂概念的写作者。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:THU-MAIC/dsh-openmaic

配置项

常见问题

Q: 这个插件和 DSH 自带的"渲染 HTML"能力有什么区别？

A: openmaic_render 接收的是符合 OpenMAIC fragment 合约的内联 HTML 片段（不带文档骨架、不超过 256 KB），宿主会用带独立 CSP 的 iframe 把它包起来；openmaic_widget 接收完整 HTML 文档（带 <!doctype>/<html>/<head>/<body>），适合做模拟器、问答游戏、代码挑战；openmaic_slide 接收 PPTist 风格的 slide JSON。三者覆盖三类不同形态的可视化教学材料。

Q: 生成课堂链接需要等多久？会一直阻塞吗？

A: 课堂由 open.maic.chat 异步生成。插件默认每 5 秒轮询一次、单次最长 10 分钟（maxWaitMs）。如果到时还没完成，工具会返回"还在后台生成"并附 jobId，不会无限阻塞会话。

Q: accessCode 是什么？需要填吗？

A: accessCode 是 open.maic.chat 的邀请码，在配置 schema 里被标记为 secret 字段。当前线上还没启用邀请码校验，保持空字符串即可；将来开启后再填入。

Q: 哪些 DSH 版本能用？要不要锁 Node 版本？

A: package.json#engines.dsh 写的是 >=0.0.1，即任何 DSH 版本都能安装。源文件只用 node:fs/promises 和 node:url 这类内置模块，没在 package.json 里声明 Node 版本要求。

Q: 安装后需要重启吗？

A: 需要。README 明确说"装好后重启 dsh web 并刷新"，新工具、技能和卡片才会出现在对话里。

Q: 可以在本地跑自己的 OpenMAIC 后端吗？

A: 可以。把 baseUrl 改成 http://localhost:3000（或你本地 OpenMAIC 实例的地址）即可，所有 API 调用都会打到本地。

Q: 怎么卸载？

A: 从 cordis.patch.yml 里删除 dsh-openmaic 的 insert 行，重启 dsh web；再从 DSH profile 配置里删除该插件条目即可。

上手难度

入门 — 插件零配置即可工作；想换后端地址、调轮询节奏才需要改配置，使用门槛低。

已知问题与限制

• 当前仅 wire 了三种 widget 类型：simulation、game、code（src/widget-meta.ts:24）；README 的 Roadmap 提到 diagram、visualization3d、procedural-skill 暂未接通
• Action loop 回灌模型的交互（highlight/annotate/reveal 小组件元素）尚未实现（README Roadmap 列出）
• 浏览器端 shiki 是构建期桩模块，因此 openmaic_render 在客户端走的代码高亮路径会回退到未高亮渲染（src/client/shiki-stub.ts:20）
• 内联 HTML 片段（openmaic_render）有 256 KB 上限，超过会被工具拒绝并报错（src/fragment.ts:21）
• 课堂生成超时后返回的 jobId 暂不能在插件内继续轮询，需要后续手动去 open.maic.chat 跟进

把 OpenMAIC 带进 DeepSeek Harness。Bring OpenMAIC into DeepSeek Harness.

dsh-openmaic is a DeepSeek Harness plugin that registers four tools and a Socratic teaching skill:

• openmaic_generate: tell your agent "make me a lesson about X", and the plugin submits the requirement to open.maic.chat, waits for the async generation job, and returns a playable classroom link.
• openmaic_slide: the agent writes one OpenMAIC slide (PPTist-style Slide JSON) and the plugin renders it with OpenMAIC's official renderer (text, shapes, images, tables, charts, formulas, code).
• openmaic_widget: the agent writes an OpenMAIC-style interactive widget (simulation, game, or code) per the bundled contract; the code streams as it writes, then renders inline as a sandboxed card.
• openmaic_render: the agent writes an inline HTML teaching fragment (concept card, quiz, walkthrough) and the plugin renders it as a sandboxed card right in the conversation.
• openmaic-teach skill: turns a session into a Socratic OpenMAIC lesson, teaching by guided questioning and pulling in slides, widgets, and cards as aids.

What it looks like

用户: 帮我做一节量子物理入门课
模型 → openmaic_generate(requirement="量子物理入门课", language="zh-CN")
     ← "Classroom ID: class-abc123
        Classroom URL:
        https://open.maic.chat/classroom/class-abc123"
模型: 课堂已经生成好了，点开就能上课：
     https://open.maic.chat/classroom/class-abc123

Interactive widget:

用户: 做一个抛体运动模拟器
模型 → 按 openmaic-widget 模板写完整 HTML（流式输出）
     → openmaic_widget(html="<!doctype html>…", widgetType="simulation", title="抛体运动")
     ← "Rendered the simulation widget …"
     对话里就地出现一个可交互的 OpenMAIC 模拟器

Install

dsh plugin --profile web add git+https://github.com/THU-MAIC/dsh-openmaic.git

Then restart dsh web and refresh. The plugin ships its compiled lib/, so a git install needs no build step.

Config

dsh-openmaic:
  baseUrl: https://open.maic.chat
  accessCode: ""     # invite code; not enforced online yet, leave empty
  pollIntervalMs: 5000
  maxWaitMs: 600000

API flow

1. If accessCode is set, POST /api/access-code/verify and replay the openmaic_access cookie on later requests.
2. POST /api/generate-classroom with the requirement, plus only the optional flags you passed. Returns a jobId and pollUrl.
3. Poll GET {pollUrl} until the job is succeeded or failed, or maxWaitMs runs out.
4. On success, return {baseUrl}/classroom/{classroomId} (or the server-provided result.url).

Scope

• openmaic_generate: generate a classroom and return a playable link.
• openmaic_slide: render one OpenMAIC slide with the official renderer.
• openmaic_widget: render a simulation / game / code widget the agent writes (a full HTML document). It streams the code while the agent writes it and renders on completion.
• openmaic_render: render an inline HTML teaching fragment as a sandboxed card.
• openmaic-teach: Socratic teaching session that uses the tools above as aids.

The slide/widget/render tools do no server-side generation; they render content the agent authors against the OpenMAIC SDK contracts (@openmaic/dsl, @openmaic/generation, @openmaic/renderer).

Roadmap

• Wire the remaining widget types (diagram, visualization3d, procedural-skill).
• Action loop back to the model (teaching-agent interactions: highlight/annotate/reveal widget elements).

Development

./scripts/build.sh  # links host deps, bundles src/ to lib/ with tsdown
./scripts/test.sh   # links host deps, runs the vitest suite

The scripts locate the harness checkout from dsh on PATH; set DSH_CHECKOUT to build against a specific checkout.

License

MIT