开放课堂 THU-MAIC/dsh-openmaic

dsh-openmaic

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

dsh-openmaic 是 DeepSeek Harness 插件，注册四个工具和一个苏格拉底式教学技能：

- openmaic_generate：对你的智能体说「帮我做一节关于 X 的课」，插件把需求提交到 open.maic.chat，等待异步生成任务，返回可播放的课堂链接。
- openmaic_slide：智能体写一张 OpenMAIC 幻灯片（PPTist 风格的 Slide JSON），插件用 OpenMAIC 官方渲染器渲染（文本、形状、图片、表格、图表、公式、代码）。
- openmaic_widget：智能体按内置约定写一个 OpenMAIC 风格交互组件（模拟、游戏或代码）；代码边写边流式输出，随后就地渲染成沙箱卡片。
- openmaic_render：智能体写一段内联 HTML 教学片段（概念卡、测验、讲解），插件直接在对话里渲染成沙箱卡片。
- openmaic-teach 技能：把会话变成一节苏格拉底式 OpenMAIC 课，用引导提问来教学，并随时引入幻灯片、组件和卡片作为辅助。

效果长什么样

用户: 帮我做一节量子物理入门课模型 → 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

交互组件：

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

安装

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

然后重启 dsh web 并刷新。插件自带编译好的 lib/，所以用 git 安装不需要构建步骤。

配置

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

| 键 | 默认值 | 说明 |
| baseUrl | https://open.maic.chat | API 地址。指向 http://localhost:3000 可对接本地 OpenMAIC 开发。 |
| accessCode | "" | open.maic.chat 的邀请码。线上还没启用，留空即可；启用后填上。 |
| pollIntervalMs | 5000 | 轮询间隔，单位 ms。生成很慢，填 60000 比默认值更友好。 |
| maxWaitMs | 600000 | 单个任务的上限，10 分钟。 |

API 流程

1. 如果设置了 accessCode，先 POST /api/access-code/verify，之后的请求带上 openmaic_access cookie。
2. POST /api/generate-classroom，带上需求，以及你传入的可选参数。返回 jobId 和 pollUrl。
3. 轮询 GET {pollUrl}，直到任务 succeeded 或 failed，或者 maxWaitMs 超时。
4. 成功后返回 {baseUrl}/classroom/{classroomId}（或服务端提供的 result.url）。

范围

- openmaic_generate：生成课堂并返回可播放链接。
- openmaic_slide：用官方渲染器渲染一张 OpenMAIC 幻灯片。
- openmaic_widget：渲染智能体编写的模拟 / 游戏 / 代码组件（完整 HTML 文档）。智能体编写代码时实时流式传输，写完后渲染。
- openmaic_render：把内联 HTML 教学片段渲染成沙箱卡片。
- openmaic-teach：苏格拉底式教学会话，以上述工具作为辅助。

slide / widget / render 这三个工具不做服务端生成；它们渲染的内容由智能体编写，遵循 OpenMAIC SDK 契约（@openmaic/dsl、@openmaic/generation、@openmaic/renderer）。

路线图

- 接入剩余组件类型（diagram、visualization3d、procedural-skill）。
- 动作回路回到模型（教学智能体交互：高亮 / 标注 / 揭示组件元素）。

开发

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

脚本从 PATH 上的 dsh 定位 harness 检出目录；设置 DSH_CHECKOUT 可针对指定检出目录构建。

许可证

MIT