前言¶
在 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 的課堂生成、幻燈片、交互組件和蘇格拉底式教學串成一條可復現的工作流。
