Mermaid 图表技能 chunkithwang/craft-mermaid

Craft Mermaid Skill

Skill
Claude Code
Codex
Node
License

一个面向 Codex、Claude Code 和其他本地 Agent 的 Mermaid Skill。它把 Craft Agents 的图表选择、生成、渲染和视觉复检流程封装成可移植 Skill，并使用相同的 beautiful-mermaid 渲染器系列与匹配的明暗主题。

这个项目交付规范化 .mmd 源码和高分辨率 .png 文件，而不是依赖宿主对 Mermaid 代码块的默认预览。这样在不同 Agent 中使用时，图表外观更稳定。

30 秒开始

npx skills add https://github.com/chunkithwang/craft-mermaid --skill craft-mermaid

安装 Skill 后，让同一个安装 Agent 继续在实际安装目录初始化并验证渲染运行时：

CRAFT_MERMAID_DIR="/absolute/path/to/craft-mermaid"
node "$CRAFT_MERMAID_DIR/scripts/setup-runtime.mjs"

常见安装位置包括项目内的 .agents/skills/craft-mermaid、用户级的 ~/.agents/skills/craft-mermaid、~/.codex/skills/craft-mermaid 或 ~/.claude/skills/craft-mermaid。以安装器实际返回的路径为准。
初始化脚本会执行锁定版本的 npm ci 和 npm test；因为这一步可能访问网络并修改 Skill 目录，安装 Agent 应先请求授权，但不应把它拆成另一项安装任务。

安装后直接对 Agent 说：

用 Craft Mermaid 把这套支付流程画成一张高清流程图，并做视觉复检。

也可以试这些请求：

把这份系统设计整理成 Craft 风格的架构图。
用时序图说明 OAuth 登录流程，使用深色主题。
把这段 Mermaid 渲染成高清 PNG，检查是否有文字裁切或节点重叠。

安装

方式一：Skills CLI 安装（推荐）

npx skills add https://github.com/chunkithwang/craft-mermaid --skill craft-mermaid

安装器完成后，让安装 Agent 使用它报告的 Skill 目录完成依赖安装与验证：

CRAFT_MERMAID_DIR="/absolute/path/to/installed/craft-mermaid"
node "$CRAFT_MERMAID_DIR/scripts/setup-runtime.mjs"

setup-runtime.mjs 不应省略。Skills CLI 只安装 Skill 文件，不会执行项目脚本；这个初始化入口会检查 Node.js 版本、执行 npm ci，再运行 smoke test。Skill 的决策流程可以在没有依赖时被 Agent 读取，但 PNG 渲染、确定性检查和视觉复检链路将无法完整执行。

方式二：把下面这段话直接发给 AI

帮我安装 craft-mermaid Skill。请按下面步骤执行：

1. 确认本机已安装 Node.js 20 或更高版本。
2. 执行
npx skills add https://github.com/chunkithwang/craft-mermaid --skill craft-mermaid。
3. 不要在 skills add 完成后停止。找到安装器返回的实际 craft-mermaid 目录；依赖安装可能访问网络并修改该目录，因此先向我请求授权。
4. 获得授权后，运行
node /scripts/setup-runtime.mjs。它会依次执行锁定依赖的
npm ci 和 npm test，任一步失败都视为安装未完成。
5. 检查 SKILL.md、assets/、references/ 和 scripts/runtime/ 是否存在，并告诉我实际安装路径和测试结果。

把这段话发给 Codex、Claude Code、Cursor 或其他有文件系统和 shell 权限的 Agent，它可以完成安装和验证。

方式三：手动命令行

Codex：

git clone https://github.com/chunkithwang/craft-mermaid.git ~/.codex/skills/craft-mermaid
node ~/.codex/skills/craft-mermaid/scripts/setup-runtime.mjs

Claude Code：

git clone https://github.com/chunkithwang/craft-mermaid.git ~/.claude/skills/craft-mermaid
node ~/.claude/skills/craft-mermaid/scripts/setup-runtime.mjs

其他支持 Agent Skills 的工具，请把完整仓库克隆到该工具约定的 Skill 目录，再执行同一个 scripts/setup-runtime.mjs 初始化入口。

Skills CLI 更新

明确指定要更新项目级还是全局 Skill：

项目级bash
npx skills update craft-mermaid --project

全局
npx skills update craft-mermaid --global

如果 Skills CLI 报告 Craft Mermaid 已更新，它会替换 Skill 目录，原来的 scripts/runtime/node_modules 不会被恢复。更新 Agent 必须继续定位实际安装目录，并在获得依赖安装授权后运行： bash
CRAFT_MERMAID_DIR="/absolute/path/to/installed/craft-mermaid"
node "$CRAFT_MERMAID_DIR/scripts/setup-runtime.mjs"

如果 Skills CLI 报告已经是最新版，则不要重复安装依赖。

也可以把下面这段话直接发给 AI：

帮我更新 craft-mermaid Skill。请先确认它是项目级还是全局安装，再使用对应的 npx skills update craft-mermaid --project 或 --global。不要在文件更新后停止：如果 Skills CLI 确认 Craft Mermaid 已更新，找到更新后的实际 Skill 目录，先向我请求依赖安装授权，再运行
node /scripts/setup-runtime.mjs，并报告更新路径和测试结果。
如果它已经是最新版，不要重复执行依赖安装。

手动 Git 更新 bash
CRAFT_MERMAID_DIR="/absolute/path/to/installed/craft-mermaid"
git -C "$CRAFT_MERMAID_DIR" pull
node "$CRAFT_MERMAID_DIR/scripts/setup-runtime.mjs"

在 Git 实际拉取到新提交后重新执行初始化入口，使本地运行时与仓库中的 package-lock.json 保持一致，并立即验证渲染链路。

DeepSeek Harness 安装（bundle）

这个仓库同时是一个 DeepSeek Harness profile bundle：根目录 package.json 声明 dsh.bundle.patch，cordis.patch.yml 注册一个只服务于本仓库自身的 skill 提供器，以及 craft_mermaid_render / craft_mermaid_setup 两个模型工具。
bash
dsh plugin --profile web add "github:chunkithwang/craft-mermaid#main"
dsh --profile web

装好后在会话里直接说「用 Craft Mermaid 画一张……」，或让 Agent 调用上述工具。
根目录的 SKILL.md 会被自动发现为 skill；其余文件布局与 Codex / Claude Code 安装方式完全一致，两种分发互不影响。

注意：bundle 安装只带文件、不会自动执行依赖安装。首次安装后运行一次 craft_mermaid_setup（或在 bundle 目录执行
node scripts/setup-runtime.mjs），bundle 更新后同样需要重跑。

为什么不只输出 Mermaid 代码块

不同编辑器和聊天客户端可能使用不同 Mermaid 版本、主题和布局参数。相同源码在宿主预览中不一定拥有相同外观。

Craft Mermaid 会：

1. 根据内容选择兼容的图表类型和方向。
2. 用固定版本的 beautiful-mermaid 和 Craft 明暗主题渲染。
3. 生成规范化 Mermaid 源码和高分辨率 PNG。
4. 在内存中对 SVG 中间结果做确定性检查，不写入 SVG 文件。
5. 在宿主支持查看图片时复检 PNG，并最多自动修复两轮。

因此，可移植的视觉结果是生成的 PNG，而不是聊天界面重新渲染的代码块。

支持的图表

| 图表 | Mermaid 语法 | 适合场景 |
| 流程图 / 架构图 | graph、flowchart | 工作流、系统关系、决策路径 |
| 状态图 | stateDiagram-v2 | 生命周期、状态迁移 |
| 时序图 | sequenceDiagram | API、认证、服务调用 |
| 类图 | classDiagram | 类型和继承关系 |
| ER 图 | erDiagram | 数据模型和实体关系 |
| XY 图 | xychart-beta | 简单趋势、柱线对比 |

为了保持 Craft 兼容模式的渲染效果，当前不会静默切换到 Mermaid CLI、Kroki 或其他渲染器。遇到不支持的图表类型时，Skill 会说明限制，而不是输出一个外观不同但未标注的结果。

直接使用渲染器

除了让 Agent 自动调用，也可以直接运行： bash
node /absolute/path/to/craft-mermaid/scripts/runtime/render.mjs \
--input diagram.mmd \
--out-dir output \
--theme craft-light \
--json

可用参数： text --input Mermaid 源文件，必填 --out-dir 输出目录，必填 --theme craft-light|craft-dark --scale 默认 3 --max-width 默认 4096 --max-height 默认 3072 --json 向标准输出打印机器可读校验结果

典型输出： text diagram.mmd diagram.png

输入和输出位于同一目录时，规范化源码会写为 diagram.normalized.mmd，不会覆盖原文件。

视觉复检

Skill 会先在内存中检查 SVG 中间结果的尺寸、危险内容和异常复杂度，再在宿主有图片查看能力时检查 PNG 的文字裁切、节点重叠、边线交叉、可读性、分组和留白。校验结果不会额外写成报告文件。

视觉复检有明确边界：

- 宿主能查看图片时，Agent 才能将结果标记为 passed 或 failed。
- 宿主不能查看图片时，只能记录为 skipped，不能把源码检查冒充视觉通过。
- 自动调整最多两轮，之后会保留产物并报告未解决问题。

评分和复检数据格式见 references/visual-review.md。

平台支持

| 平台 | 状态 | 说明 |
| Codex | 支持 | 可生成文件、运行渲染器并查看 PNG |
| Claude Code | 支持 | 可生成文件和运行渲染器；视觉复检取决于宿主图片能力 |
| Cursor / 其他本地 Agent | 可用 | 需要支持 Agent Skills、文件读写和 shell 命令 |
| 普通 Chatbot | 不推荐 | 缺少文件系统或命令执行时只能生成源码，无法保证渲染结果 |

环境与一致性说明

- 需要 Node.js 20 或更高版本。
- 运行时固定使用 beautiful-mermaid@1.1.3 和 @resvg/resvg-js@2.6.2。
- 提供 craft-light 和 craft-dark 两套主题。
- 内存中的 SVG 会把主题色解析为具体颜色、清理折线端点的亚像素残段，并使用固定尺寸的箭头 marker，避免方向偏转；它只参与校验和 PNG 光栅化，不会落盘。
- PNG 默认按 3 倍像素密度渲染，上限为 4096×3072；可通过 --scale 和最大尺寸参数调整。渲染时使用系统字体回退，不同系统的文字度量可能轻微不同。
- 自定义 style 或 classDef 会覆盖便携主题，除非用户明确要求，否则 Skill 会避免使用。

目录结构 text craft-mermaid/ ├── SKILL.md ├── agents/ │ └── openai.yaml ├── assets/ │ └── themes/ │ ├── craft-light.json │ └── craft-dark.json ├── references/ │ ├── syntax.md │ └── visual-review.md └── scripts/ ├── setup-runtime.mjs └── runtime/ ├── render.mjs ├── inspect-svg.mjs ├── smoke-test.mjs ├── package.json └── package-lock.json

来源与许可证

本项目包含从 Craft Agents OSS 适配的工作流指导、Mermaid 语法文档、源码规范化逻辑、渲染器配置和默认主题值。
详细归属见 NOTICE。

项目采用 Apache License 2.0。运行时依赖遵循各自的软件许可证。