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：

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

# 全局
npx skills update craft-mermaid --global

如果 Skills CLI 报告 Craft Mermaid 已更新，它会替换 Skill 目录，原来的 scripts/runtime/node_modules 不会被恢复。更新 Agent 必须继续定位实际安装 目录，并在获得依赖安装授权后运行：

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 更新

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 两个模型工具。

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，而不是聊天界面重新渲染的代码块。

支持的图表

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

直接使用渲染器

除了让 Agent 自动调用，也可以直接运行：

node /absolute/path/to/craft-mermaid/scripts/runtime/render.mjs \
  --input diagram.mmd \
  --out-dir output \
  --theme craft-light \
  --json

可用参数：

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

典型输出：

diagram.mmd
diagram.png

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

视觉复检

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

视觉复检有明确边界：

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

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

平台支持

环境与一致性说明

• 需要 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

会避免使用。

目录结构

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](./NOTICE)。

项目采用 [Apache License 2.0](./LICENSE)。运行时依赖遵循各自的软件许可证。