Mermaid 图表工作室ddtcorex/dsh-maestro-diagram

dsh-maestro-diagram — Maestro 图表工作室（仅 Host）

用于 SA 级图表的混合 技能 + 插件：GitHub 原生 Mermaid（单一事实来源）+ 编辑级 HTML+SVG（自包含，无 JS）+ 确定性 verify/drift（工具调用 > LLM）。

- 技能： maestro-skills/skills/diagram-studio/SKILL.md（rank 350）—— 教导 agent 何时/如何绘制，在 5 种 Mermaid 类型中选择，强制编辑纪律（密度 4/10，强调色 1-2），并决定受众（Team vs Client）。
- 插件： packages/dsh-maestro-diagram（本包，仅 Host，rootDir: src/host，inject: ['sessions','tools']）—— 将 mermaid_verify 和 mermaid_drift 暴露为可逆的 ctx.tools.register 效果。v1 无 Client bundle。

灵感来自 cathrynlavery/diagram-design（MIT，39 种编辑类型，tokens paper/ink/accent）+ diagram-drift + dsh-mermaid。默认输出保持 GitHub Mermaid（依据“render được trên github là ok”）；当 audience: client 时，HTML 编辑版是显式的 export: html。

安装

作为 DSH 插件（仅 Host，无需重启 skill provider，但 Host 需要重载以加载工具）
dsh plugin add @ddtcorex/dsh-maestro-diagram
或通过轻量 meta-bundle（在验证前为可选，尚未加入 meta v2）
dsh plugin add @ddtcorex/dsh-maestro-meta

仅使用技能（无 Host 工具）：git pull + pnpm --dir maestro-skills run build —— 然后 node maestro-skills/skills/diagram-studio/scripts/verify-mermaid.mjs 。

工具

mermaid_verify

input:  string (Mermaid source or file content when isPath=true)
isPath: boolean? (if true, input is treated as file path, extracts mermaid blocks)
strict: boolean? (if true, warns on anti-patterns: shadow, graph legacy, rounded-2xl)
→ { ok: boolean, errors: {line,col,msg}[], warnings: {msg}[] }

确定性 mermaid.parse() + 可选的 mermaid-cli 验证。从不抛出 —— 返回 isError 形状供 agent 修复。

mermaid_drift

diagramPath: string (e.g. docs/architecture.md)
codeRoots:   string[]? (default ["packages/","govard","maestro-skills"])
→ { missingInCode: string[], staleEdges: {from,to}[], missingInDiagram: string[], summary: string }

解析 Mermaid 节点/边，对比扫描 codeRoots（package.json 名称、govard/internal/、skills）。灵感来自 diagram-drift —— 在 PR 前标记 missingInCode / staleEdges / missingInDiagram。

支持的用例（全部已验证 —— 见 SKILL.md § Supported Cases）

5 种图表类型（从 39 种编辑类型映射而来）：
- flowchart TB/LR —— 组件 + 连接（架构）—— docs/architecture.md §1.1
- sequenceDiagram —— 随时间变化的消息（turn 生命周期）—— docs/specs/2026-08-27-harness-turn-flow-sequence.md
- classDiagram —— 类 + 操作（ReviewProvider  queued）
所有共享令牌 paper #f5f5f5 / ink #2d3142 / accent #eb6c36 / muted #8a94a6 / link #4a90e2 来自 references/style-guide.md（classDef focal/muted，无阴影，rx:6）。

2 类受众（每个 HTML 控制 4 个元素）：
- 团队 / 内部（team|internal|engineering 或 "cho team"）→ HTML 同时包含：内联 SVG + Mermaid source 折叠 + Editorial tokens 卡片 + 带 verify/drift 的 About 页脚。示例：harness-architecture.html 16K（1 个 svg，1 个 pre），harness-turn-flow-sequence.html 31K。
- 客户 / 外部（client|pitch|deck 或 "cho khách"）→ HTML 仅包含 SVG，无 ，无 tokens 卡片，页脚缩减为 Generated via diagram-studio — 2026-08-27。示例：...-client.html 12K/30K（1 个 svg，0 个 pre），PNG 124K/65K。

3 种输出：
- docs/architecture.md / docs/specs/-design.md 中的 GitHub 原生 Mermaid（始终显示源码）
- Editorial HTML docs/diagrams/.html（自包含内联 SVG/CSS，无 JS）——按表格区分团队与客户
- Deck PDF docs/diagrams/maestro-harness-deck.pdf（A4 横向，3 页）——始终遵循客户规则，仅 PNG

3 个验证用例：
- 解析成功 → 5/5 PASS
- 解析失败（空、A-->）→ ok:false, line:2
- 反模式严格模式（shadow:true）→ warnings:1
- 漂移 missingInCode 0 / 文件缺失抛出 ENOENT

此 harness 上的 2 个实时案例研究：
- 架构流程图（10 个插件 + meta）——harness-architecture.html 16K → ...-client.html 12K ——PNG 238K→124K ——Deck 第 1 页
- 回合流时序图（6 个参与者）——harness-turn-flow-sequence.html 31K（svg 28K，经由 mermaid-cli 11.16.0）→ ...-client.html 30K ——PNG 100K→65K + ...-rendered.png 20K ——Deck 第 2 页

以上全部经过实时验证：packages/dsh-maestro-diagram 8/8，maestro-workspace -r verify 13 个包 Done，chrome 无头 980×1400 截图，pdfinfo Pages:3。

用法（agent）

1. 加载 diagram-studio 技能——它会根据语义模式选择 flowchart 与 sequenceDiagram 与 classDiagram 与 erDiagram 与 stateDiagram。
2. 说明 type, size (85%/100%), what will be cut due to budget (density 4/10) 并等待重定向（confirm-before-drawing）。
3. 将 Mermaid 写入 docs/specs/-design.md（或 docs/architecture.md §1.1），调用 mermaid_verify——修复直到 ok:true。
4. 如果 audience: client，还需渲染 editorial HTML：mermaid-cli -i .mmd -o .svg → 按受众表将内联 SVG 嵌入 docs/diagrams/.html，然后 chrome --screenshot → PNG 和 --print-to-pdf → deck。为客户隐藏源码/tokens/页脚。
5. 在 PR 之前，运行 mermaid_drift --diagram docs/architecture.md --roots packages/*,govard,maestro-skills——通过修补文档或代码来修复 missingInCode。

CLI 回退（无插件）：node maestro-skills/skills/diagram-studio/scripts/verify-mermaid.mjs docs/architecture.md

构建与验证
sh
pnpm --dir packages/dsh-maestro-diagram run build   # must create lib/index.js flat (rootDir: src/host)
pnpm --dir packages/dsh-maestro-diagram run test    # 8/8（5 项验证 + 3 项漂移）
pnpm --dir packages/dsh-maestro-diagram run verify  # tsc --noEmit
pnpm --dir maestro-skills run build                 # 技能提供方
pnpm --dir maestro-workspace -r verify              # 13 个包已完成

lib/index.js 扁平结构是必需的——test -f lib/index.js 必须为 0（而不是 lib/host/index.js），否则 dsh web 启动会失败并报 ERR_MODULE_NOT_FOUND。在任何真实重启之前，先在临时端口上进行干启动。

发布

此包是公开的（private:false、workspace:^ 依赖）。只能使用 pnpm publish --access public 发布——切勿使用 npm publish（会在 tarball 中留下 workspace:）。技能分发参见 maestro-skills/README.md，设计参见 docs/specs/2026-08-27-diagram-studio-design.md。

许可证

MIT——参见 LICENSE。编辑类 token/风格指南摘自 cathrynlavery/diagram-design（MIT），署名见 maestro-skills/skills/diagram-studio/references/diagram-design-learnings.md。