dsh-maestro-diagram: Mermaid Verify & Drift Tools

前言¶

dsh-maestro-diagram 是 DeepSeek Harness (DSH) 生态中的一个混合型插件，定位为 Maestro Diagram Studio。它作为 Host-only 插件运行，与 maestro-skills/skills/diagram-studio 技能协同工作，旨在为 SA 级别的图表提供确定性的验证与差异检测能力。

该插件的核心目标是建立“单一事实来源”：以 GitHub 原生 Mermaid 为源代码，结合编辑风格的 HTML+SVG 输出，通过工具调用而非大语言模型（LLM）来确保图表与代码的一致性。

核心功能¶

mermaid_verify: Mermaid 语法验证工具。它基于 mermaid.parse() 并可选集成 mermaid-cli，将错误以结构化对象返回而非抛出异常，便于 Agent 修复。
mermaid_drift: 代码与图表差异检测工具。扫描 Mermaid 节点/边与代码根目录（packages/*, govard, maestro-skills）的对比，识别图中存在但代码中缺失的元素或过时的边。
5 种图表类型: 支持标准 Mermaid 图表类型，包括 flowchart (组件/架构)、sequenceDiagram (时序)、classDiagram (类图)、erDiagram (实体关系) 以及 stateDiagram (状态机)。
编辑风格 HTML: 支持生成自包含的 HTML 文件。包含 paper (#f5f5f5)、ink (#2d3142)、accent (#eb6c36) 等视觉 Token，根据受众（Team 或 Client）调整内容展示（如折叠源码、隐藏页脚等）。
GitHub 原生集成: 默认输出保留 GitHub Mermaid 渲染，作为源代码的单一事实来源。

安装与启用¶

该插件为 Host-only 模式，安装后需重载 Host 以注册工具。

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

典型用法¶

在 DSH Agent 工作流中，使用该插件通常遵循以下步骤：

加载技能: 加载 diagram-studio 技能。该技能负责根据语义模式选择图表类型，并强制执行编辑规范（如密度、强调色）。
编写与验证: 将 Mermaid 代码写入文档（如 docs/architecture.md），调用 mermaid_verify 工具。Agent 需修复代码直至 ok: true。
受众渲染:
- 若受众为 Team/Internal，生成包含内联 SVG、折叠源码和编辑风格卡的 HTML。
- 若受众为 Client/External，生成仅包含 SVG 的干净 HTML，隐藏源码和装饰性元素。
差异检测: 在提交代码前，调用 mermaid_drift 检测图中节点与代码实现是否一致，修复 missingInCode 或 staleEdges。

工具接口¶

mermaid_verify¶

用于验证 Mermaid 语法，确保图表可渲染。

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

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

mermaid_drift¶

用于对比 Mermaid 图谱与源代码，发现不一致之处。

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

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

技术细节与构建¶

依赖: 依赖 mermaid 10.9.0。
构建要求: 必须生成平铺的 lib/index.js 文件（rootDir: src/host）。如果存在 lib/host/index.js 而非 lib/index.js，dsh web 启动将失败并报 ERR_MODULE_NOT_FOUND。
发布: 使用 pnpm 发布，必须添加 --access public 参数。

# 构建插件
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

注意事项¶

Host-only: 当前版本 (v1) 不包含客户端包，工具注册在 Host 进程中。
发布规范: 依赖项使用 workspace: 协议时，发布必须使用 pnpm publish --access public，禁止使用 npm publish，否则会导致依赖问题。
风格规范: 插件内置了一套视觉规范（Tokens），包含 focal 和 muted 类定义，确保图表风格统一。
许可证: MIT 许可证，部分编辑风格灵感来源于 cathrynlavery/diagram-design。

更多细节与设计文档请参考：GitHub 仓库