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

dsh-maestro-diagram — Maestro Diagram Studio（仅 Host）

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

- Skill： maestro-skills/skills/diagram-studio/SKILL.md（rank 350）——教会 agent 何时/如何绘图，在 5 种 Mermaid 类型中选择，强制编辑纪律（密度 4/10，强调色 1-2），并决定受众（Team vs Client）。
- Plugin： packages/dsh-maestro-diagram（本包，仅 Host，rootDir: src/host，inject: ['sessions','tools']）——将 mermaid_verify 和 mermaid_drift 暴露为可逆的 ctx.tools.register effects。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 plugin（仅 Host，无需重启 skill provider，但 Host 需要重载以加载 tools）
dsh plugin add @ddtcorex/dsh-maestro-diagram

仅使用 skill（无 Host tools）：git pull + pnpm --dir maestro-skills run build —— 然后运行 node maestro-skills/skills/diagram-studio/scripts/verify-mermaid.mjs 。

Tools

mermaid_verify

input: string（Mermaid 源码，或当 isPath=true 时的文件内容） isPath: boolean?（若为 true，input 被视为文件路径，提取 mermaid 块） strict: boolean?（若为 true，对反模式发出警告：shadow、graph legacy、rounded-2xl）
→ { ok: boolean, errors: {line,col,msg}[], warnings: {msg}[] }

确定性的 mermaid.parse() + 可选的 mermaid-cli validate。永不抛出——返回 isError 形态供 agent 修复。

mermaid_drift

diagramPath: string（例如 docs/architecture.md） codeRoots: string[]?（默认 ["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）

全部共享 tokens paper #f5f5f5 / ink #2d3142 / accent #eb6c36 / muted #8a94a6 / link #4a90e2，来自 references/style-guide.md（classDef focal/muted，无 shadow，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）——按表格区分 Team 与 Client
- Deck PDF docs/diagrams/maestro-harness-deck.pdf（A4 横向，3 页）——始终遵循 Client 规则，仅 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。对 client 隐藏源码/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 verify + 3 drift)
pnpm --dir packages/dsh-maestro-diagram run verify # tsc --noEmit
pnpm --dir maestro-skills run build # skill provider
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。