前言¶
在 DeepSeek Harness（DSH）里做教学类智能体，常见做法是：让模型输出 Markdown 或 HTML，再由开发者自己接渲染、托管和交互层。课堂链接、幻灯片规范、沙箱卡片各自一套，对话里很难直接「上课」。
dsh-openmaic 由 THU-MAIC 维护，把 OpenMAIC 的能力接进 DSH：注册四个工具和一个苏格拉底式教学 skill，覆盖课堂生成、幻灯片渲染、交互组件和教学卡片。插件分类为客户端，当前 GitHub 约 22 stars、4 forks，版本 0.4.0，MIT 许可证。
这是什么¶
dsh-openmaic 是 DSH 的客户端插件。它向智能体暴露 OpenMAIC 相关工具，并在 Web 端注入客户端运行时，把模型写出的内容按 OpenMAIC SDK 契约（@openmaic/dsl、@openmaic/generation、@openmaic/renderer）就地渲染。
一句话定位：在对话里生成可播放的 OpenMAIC 课堂链接，或把幻灯片、交互 widget、教学 HTML 片段渲染成沙箱卡片；配合 openmaic-teach skill，可按引导式提问组织一节完整课。
核心功能¶
插件注册四个工具和一个 skill，职责如下。
openmaic_generate¶
把教学需求提交给 open.maic.chat，等待异步生成任务完成后，返回可打开的课堂链接。适合「帮我做一节关于 X 的课」这类端到端生成。
openmaic_slide¶
智能体按 OpenMAIC 幻灯片格式（PPTist 风格 Slide JSON）写出单页内容，插件用官方渲染器渲染，支持文本、形状、图片、表格、图表、公式和代码。
openmaic_widget¶
智能体按插件内置契约写出完整 HTML 文档（模拟器、小游戏或代码演示等）。代码在模型流式输出过程中同步展示，完成后在对话里渲染为沙箱卡片。widgetType 可标注类型，例如 simulation。
openmaic_render¶
智能体写出内联 HTML 教学片段（概念卡、测验、分步讲解等），插件在对话里渲染为沙箱卡片。与 openmaic_widget 不同，这里侧重片段式教学内容，而非完整 widget 文档。
openmaic-teach skill¶
把当前会话组织成苏格拉底式 OpenMAIC 课：通过引导提问推进，并在需要时调用上述工具插入幻灯片、widget 和卡片。
补充说明：openmaic_slide、openmaic_widget、openmaic_render 不在服务端生成内容，只负责渲染智能体按契约写出的材料；openmaic_generate 才走 OpenMAIC 在线生成 API。
安装与启用¶
下面介绍官方 README 中的安装步骤。DSH 生态采用「一切皆插件」思路；SkillHub 是社区目录站点，与 DeepSeek / 幻方无官方从属关系。
- 执行安装命令（
webprofile）：
dsh plugin --profile web add git+https://github.com/THU-MAIC/dsh-openmaic.git
- 重启
dsh web并刷新页面。插件自带编译好的lib/，git 安装无需本地 build。
可选配置写在 DSH 配置里，键名为 dsh-openmaic：
dsh-openmaic:
baseUrl: https://open.maic.chat
accessCode: "" # invite code; not enforced online yet, leave empty
pollIntervalMs: 5000
maxWaitMs: 600000
| Key | 默认值 | 说明 |
|---|---|---|
baseUrl |
https://open.maic.chat |
API 根地址；本地开发可指向 http://localhost:3000 |
accessCode |
"" |
邀请码；线上暂未强制校验，可留空 |
pollIntervalMs |
5000 |
轮询间隔（毫秒）；生成较慢时 README 建议可调到 60000 |
maxWaitMs |
600000 |
单次任务最长等待，默认 10 分钟 |
openmaic_generate 的 API 流程：若配置了 accessCode，先 POST /api/access-code/verify 并在后续请求携带 openmaic_access cookie；再 POST /api/generate-classroom 拿到 jobId 与 pollUrl；轮询 GET {pollUrl} 直至 succeeded 或 failed，或超出 maxWaitMs；成功后返回 {baseUrl}/classroom/{classroomId} 或服务端提供的 result.url。
典型用法¶
生成一整节课堂¶
用户提出课程主题后，模型调用 openmaic_generate，插件等待任务完成并返回课堂 URL：
用户: 帮我做一节量子物理入门课
模型 → 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：
用户: 做一个抛体运动模拟器
模型 → 按 openmaic-widget 模板写完整 HTML（流式输出）
→ openmaic_widget(html="<!doctype html>…", widgetType="simulation", title="抛体运动")
← "Rendered the simulation widget …"
对话里就地出现一个可交互的 OpenMAIC 模拟器
幻灯片与教学卡片的路径类似：模型先按对应 skill 契约撰写 Slide JSON 或 HTML 片段，再调用 openmaic_slide 或 openmaic_render。
适用场景与注意¶
适合谁
- 在 DSH Web 端做教学、答疑、辅导类智能体，希望对话内直接出课堂链接或可视化教具的开发者。
- 已使用或计划对接 OpenMAIC 内容规范，希望复用官方渲染器而非自建前端的同学。
使用注意
- 插件以当前
dsh进程权限运行；安装前请阅读 GitHub 源码 与 MIT 许可证，确认网络访问与配置符合你的环境要求。 openmaic_generate依赖open.maic.chat（或你配置的baseUrl）在线服务，生成耗时较长，需合理设置pollIntervalMs与maxWaitMs。- Roadmap 中提到后续会补齐更多 widget 类型（diagram、visualization3d、procedural-skill），以及教学交互回传给模型的 action loop；当前以 README 列出的能力为准。
链接¶
- 社区目录：https://www.skillhub.cn/plugins/THU-MAIC/dsh-openmaic
- 源码与文档：https://github.com/THU-MAIC/dsh-openmaic
经过上面的步骤，你可以在 DSH 对话里把 OpenMAIC 的课堂生成、幻灯片、交互组件和苏格拉底式教学串成一条可复现的工作流。
