Introduction

In collaborative development, architecture descriptions, data flows, and state transitions are usually better expressed with diagrams than with plain text. The philosophy of DeepSeek Harness (DSH) is “everything is a plugin,” and dsh-mermaid-comm is the plugin dedicated to diagram generation. Its core problem is: make AI prioritize outputting Mermaid diagrams by default in conversations, while ensuring diagrams are usable and safe through syntax validation and an output gate mechanism.

What Is It

dsh-mermaid-comm is a model inference plugin maintained by developer kp-z. It injects a system prompt to guide AI to use Mermaid syntax in specific scenarios and registers the mermaid_validate tool for validation. Rendering is handled by the dsh-mermaid plugin; this plugin is responsible for guidance, validation, and safety control.

Core Features

1. Behavior Guidance

The plugin injects systemPrompt.section. For topics involving architecture, data flow, sequence diagrams, state diagrams, and so on, AI is guided into an output pattern of “diagram first, then a brief explanation.”

2. Syntax Validation

The plugin registers the mermaid_validate tool. The validation process has two steps: first scan for dangerous characters, then invoke the mermaid-runtime version aligned with dsh-mermaid to perform actual parsing.

3. Output Gate

The plugin listens to assistant message events. It automatically repairs Unicode arrows and dangerous labels in Mermaid code; if a diagram fails validation, it is removed from the visible interface instead of showing the user a rendering failure.

4. Mermaid Vault

This is the core of diagram persistence. The plugin saves validated diagrams to the <workspace>/.dsh/mermaid/ directory. The file structure includes:
* INDEX.md: diagram index (topic/type/version/update time).
* <name>.mmd: current active version.
* <name>.history.md: version evolution history.

Installation and Enablement

Before installing this plugin, you need to ensure that the dsh-mermaid plugin is installed; otherwise, mermaid_validate will fail explicitly instead of silently passing.

dsh plugin --profile web add dsh-mermaid-comm
dsh plugin --profile web add dsh-mermaid

After installation, restart dsh web.

Typical Usage

By default, AI chooses an appropriate Mermaid diagram type based on context:

  • Architecture / module relationships → flowchart or classDiagram
  • Call chain / request sequence → sequenceDiagram
  • State / lifecycle → stateDiagram-v2
  • Data model / table relationships → erDiagram
  • Branching strategy / Git history → gitGraph
  • Plan / Gantt chart → gantt

Mermaid Vault Tools

The Vault directory provides four tools for model invocation:

  • mermaid_vault_list: list the index, optionally filter by type.
  • mermaid_vault_read: read the current code and history for a topic.
  • mermaid_vault_save: save or update a diagram, enforcing validation by the actual parser.
  • mermaid_vault_delete: delete a topic.

When a topic already exists, the system prompt guides the model to read the history and use save to iterate (v2, v3…), rather than redrawing from scratch, ensuring continuity in the evolution of diagrams within the conversation.

Security and Limitations

  • Naming safety: topic names are sanitized to [a-zA-Z0-9-_], preventing path traversal attacks.
  • Directory lock: all write operations are confined within the Vault directory.
  • Atomic writes: file writes use atomic operations to avoid mid-write corruption.
  • Size limits: size and version limits prevent unbounded directory growth.

Summary

dsh-mermaid-comm uses prompt injection, tool registration, and output interception to address the instability of AI-generated Mermaid diagrams, and provides a Vault mechanism that makes diagrams manageable assets.