Preface

dsh-maestro-diagram is a hybrid plugin in the DeepSeek Harness (DSH) ecosystem, positioned as Maestro Diagram Studio. It runs as a Host-only plugin and works together with the maestro-skills/skills/diagram-studio skill to provide deterministic validation and drift detection capabilities for SA-level diagrams.

The core goal of this plugin is to establish a “Single Source of Truth”: use GitHub-native Mermaid as the source code, combine it with editorial-style HTML+SVG output, and ensure consistency between diagrams and code through tool calls rather than a large language model (LLM).

Core Features

  1. mermaid_verify: Mermaid syntax validation tool. It is based on mermaid.parse() and can optionally integrate mermaid-cli, returning errors as structured objects rather than throwing exceptions, making it easier for Agents to fix them.
  2. mermaid_drift: Code-to-diagram drift detection tool. It scans and compares Mermaid nodes/edges with the code root directories (packages/*, govard, maestro-skills), identifying elements that exist in the diagram but are missing in the code, or stale edges.
  3. 5 diagram types: Supports standard Mermaid diagram types, including flowchart (component/architecture), sequenceDiagram (sequence), classDiagram (class diagram), erDiagram (entity relationship), and stateDiagram (state machine).
  4. Editorial-style HTML: Supports generating self-contained HTML files. It includes visual Tokens such as paper (#f5f5f5), ink (#2d3142), and accent (#eb6c36), and adjusts content presentation based on the audience (Team or Client), such as folding source code and hiding footers.
  5. GitHub-native integration: The default output preserves GitHub Mermaid rendering, serving as the Single Source of Truth for source code.

Installation and Enablement

This plugin runs in Host-only mode. After installation, reload the Host to register the tools.

# 安装插件
dsh plugin add @ddtcorex/dsh-maestro-diagram

Typical Usage

In a DSH Agent workflow, using this plugin generally follows these steps:

  1. Load the skill: Load the diagram-studio skill. This skill selects the diagram type based on semantic patterns and enforces editorial specifications (such as density and accent color).
  2. Write and validate: Write the Mermaid code into a document (such as docs/architecture.md) and call the mermaid_verify tool. The Agent must fix the code until ok: true.
  3. Audience rendering:
    • If the audience is Team/Internal, generate HTML containing inline SVG, collapsible source code, and an editorial-style card.
    • If the audience is Client/External, generate clean HTML containing only SVG, with source code and decorative elements hidden.
  4. Drift detection: Before committing code, call mermaid_drift to check whether the nodes in the diagram match the code implementation, and fix missingInCode or staleEdges.

Tool Interface

mermaid_verify

Used to validate Mermaid syntax and ensure that diagrams can be rendered.

// 调用示例
mermaid_verify({
  input: "graph TD; A-->B;", // 或文件内容
  isPath: false,
  strict: true // 开启反模式警告（如 shadow, legacy graph）
})

// 返回结构
{
  ok: boolean,
  errors: { line, col, msg }[],
  warnings: { msg }[]
}

mermaid_drift

Used to compare a Mermaid diagram with the source code and identify inconsistencies.

// 调用示例
mermaid_drift({
  diagramPath: "docs/architecture.md",
  codeRoots: ["packages/*", "govard", "maestro-skills"]
})

// 返回结构
{
  missingInCode: string[],    // 图中有但代码中未定义的节点
  staleEdges: { from, to }[], // 图中存在但代码逻辑已废弃的边
  missingInDiagram: string[], // 代码中有但图中未展示的节点
  summary: string
}

Technical Details and Build

  • Dependencies: Depends on mermaid 10.9.0.
  • Build requirements: A flat lib/index.js file must be generated (rootDir: src/host). If lib/host/index.js exists instead of lib/index.js, starting dsh web will fail with ERR_MODULE_NOT_FOUND.
  • Publishing: Publish using pnpm; the --access public parameter must be added.
# 构建插件
pnpm --dir packages/dsh-maestro-diagram run build

# 运行测试
pnpm --dir packages/dsh-maestro-diagram run test

# 验证 TypeScript
pnpm --dir packages/dsh-maestro-diagram run verify

Notes

  • Host-only: The current version (v1) does not include a client package; tools are registered in the Host process.
  • Publishing rules: When dependencies use the workspace: protocol, publishing must use pnpm publish --access public; npm publish is not allowed, otherwise dependency issues may occur.
  • Style rules: The plugin includes a set of visual specifications (Tokens), including focal and muted definitions, to ensure consistent diagram styling.
  • License: MIT License; some editorial style inspiration is derived from cathrynlavery/diagram-design.

For more details and design documentation, refer to: GitHub Repository