Preface¶

The common approach to building educational agents in DeepSeek Harness (DSH) is to have the model output Markdown or HTML, with developers handling the rendering, hosting, and interaction layers themselves. Classroom links, slide specifications, and sandbox cards each have their own setup, making it difficult to “teach” directly within a conversation.

dsh-openmaic, maintained by THU-MAIC, integrates the capabilities of OpenMAIC into DSH: it registers four tools and a Socratic teaching skill, covering classroom generation, slide rendering, interactive components, and teaching cards. The plugin is categorized as a client-side plugin, currently with about 22 stars and 4 forks on GitHub, version 0.4.0, under the MIT license.

What This Is¶

dsh-openmaic is a client-side plugin for DSH. It exposes OpenMAIC-related tools to the agent and injects a client-side runtime into the web interface, rendering content generated by the model on-the-fly according to the OpenMAIC SDK contracts (@openmaic/dsl, @openmaic/generation, @openmaic/renderer).

In one sentence: It generates playable OpenMAIC classroom links within a conversation, or renders slides, interactive widgets, and teaching HTML snippets into sandbox cards. Combined with the openmaic-teach skill, it can organize a complete lesson through guided questioning.

Core Features¶

The plugin registers four tools and one skill, with the following responsibilities.

openmaic_generate¶

Submits teaching requirements to open.maic.chat and waits for the asynchronous generation task to complete, returning an openable classroom link. Suitable for end-to-end generation like “Help me make a lesson about X.”

openmaic_slide¶

The agent writes single-page content according to the OpenMAIC slide format (PPTist-style Slide JSON), which the plugin renders using the official renderer, supporting text, shapes, images, tables, charts, formulas, and code.

openmaic_widget¶

The agent writes a complete HTML document following the plugin’s built-in contract (simulator, mini-game, or code demo, etc.). The code is displayed synchronously during the model’s streaming output and rendered as a sandbox card in the conversation upon completion. The widgetType can indicate the type, e.g., simulation.

openmaic_render¶

The agent writes inline HTML teaching snippets (concept cards, quizzes, step-by-step explanations, etc.), which the plugin renders as sandbox cards in the conversation. Unlike openmaic_widget, this focuses on snippet-based teaching content rather than complete widget documents.

openmaic-teach skill¶

Organizes the current session into a Socratic OpenMAIC lesson: progresses through guided questioning and calls the above tools as needed to insert slides, widgets, and cards.

Additional note: openmaic_slide, openmaic_widget, and openmaic_render do not generate content server-side; they only render materials written by the agent according to the contract. Only openmaic_generate uses the OpenMAIC online generation API.

Installation and Enabling¶

Below are the installation steps from the official README. The DSH ecosystem adopts an “everything is a plugin” philosophy. SkillHub is a community directory site with no official affiliation with DeepSeek / High-Flyer.

1. Execute the installation command (web profile):

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

2. Restart dsh web and refresh the page. The plugin comes with pre-compiled lib/; git installation does not require a local build.

Optional configurations are written in the DSH config under the key dsh-openmaic:

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

The API flow for openmaic_generate: If accessCode is configured, it first POST /api/access-code/verify and carries the openmaic_access cookie in subsequent requests; then POST /api/generate-classroom to get jobId and pollUrl; polls GET {pollUrl} until succeeded or failed, or exceeds maxWaitMs; upon success, returns {baseUrl}/classroom/{classroomId} or the result.url provided by the server.

Typical Usage¶

Generating an Entire Classroom¶

After the user proposes a course topic, the model calls openmaic_generate, and the plugin waits for the task to complete and returns the classroom URL:

User: Help me make an introductory quantum physics lesson
Model → openmaic_generate(requirement="Introductory quantum physics lesson", language="zh-CN")
     ← "Classroom ID: class-abc123
        Classroom URL:
        https://open.maic.chat/classroom/class-abc123"
Model: The classroom has been generated. Click to start the lesson:
     https://open.maic.chat/classroom/class-abc123

Rendering an Interactive Simulator in Conversation¶

When the user requests a visual demonstration, the model writes HTML according to the openmaic-widget template and then calls openmaic_widget:

User: Create a projectile motion simulator
Model → Writes complete HTML according to openmaic-widget template (streaming output)
     → openmaic_widget(html="<!doctype html>…", widgetType="simulation", title="Projectile Motion")
     ← "Rendered the simulation widget …"
     An interactive OpenMAIC simulator appears on-the-fly in the conversation

Slides and teaching cards follow a similar path: the model first writes Slide JSON or HTML snippets according to the respective skill contracts, then calls openmaic_slide or openmaic_render.

Use Cases and Considerations¶

Who It’s For

• Developers building educational, Q&A, or tutoring agents in the DSH Web interface who want classroom links or visual teaching aids directly within conversations.
• Those already using or planning to align with OpenMAIC content specifications who wish to reuse the official renderer instead of building a custom frontend.

Usage Notes

• The plugin runs with the current dsh process permissions; before installation, please read the GitHub source code and the MIT license to ensure network access and configuration meet your environment requirements.
• openmaic_generate relies on the online service at open.maic.chat (or your configured baseUrl), which can take a long time to generate. Set pollIntervalMs and maxWaitMs reasonably.
• The roadmap mentions future additions of more widget types (diagram, visualization3d, procedural-skill) and an action loop for teaching interactions to feed back to the model; current capabilities are as listed in the README.

Links¶

• Community Directory: https://www.skillhub.cn/plugins/THU-MAIC/dsh-openmaic
• Source Code & Documentation: https://github.com/THU-MAIC/dsh-openmaic

Following the steps above, you can chain OpenMAIC’s classroom generation, slides, interactive components, and Socratic teaching into a reproducible workflow within DSH conversations.