diagram-to-image

图表转图片

通过 mermaid-red API（diagramless.xyz）将 Mermaid 图表和 Markdown 表格转换为 PNG 图片。无需繁重的本地依赖，即可生成高质量、带自定义主题的输出。

适用场景

在以下情况下使用此技能：

• 用户有 Mermaid 图表，需要将其转换为图片
• 用户有 Markdown 表格，需要将其转换为图片
• 用户正在为 X/Twitter 编写内容，需要导出视觉素材
• 用户要求“转换为图片”“导出为 PNG”“将其制作为图片”或类似操作

前提条件

捆绑脚本使用 Node.js 内置的 fetch（Node 18+）。无需安装 npm 包。

# The render script is bundled with this skill:
SKILL_DIR=~/.claude/skills/diagram-to-image/scripts
ls $SKILL_DIR/diagram-to-image.mjs

智能选择输出位置

**重要：**根据上下文确定最佳输出位置。遵循以下决策树：

1. 用户指定路径

如果用户明确提到了路径或文件名，就使用该路径或文件名。

2. 检测项目上下文

检查当前项目中常见的图片/素材目录：

# Check for existing image directories (in order of preference)
ls -d ./images ./assets ./img ./static ./public/images ./assets/images 2>/dev/null | head -1

使用找到的第一个现有目录。常见模式：

• ./images/ - 通用项目
• ./assets/ - Web 项目
• ./assets/images/ - 结构化 Web 项目
• ./public/images/ - Next.js、React 项目
• ./static/ - Hugo 及其他静态站点生成器
• ./img/ - 简写形式

3. 文章/文档上下文

如果用户正在编写文章或文档：

• 查找文档所在目录
• 如果合适，创建 images/ 子目录
• 根据文档名称和描述为图片命名

4. 对话上下文

分析对话，确定：

• 图表表示的内容 → 用于生成文件名（例如，auth-flow.png、user-journey.png）
• 正在讨论的相关文件 → 将图片放在该文件附近
• 正在讨论的主题 → 用于命名

5. 默认回退方案

如果没有上下文线索：

• 使用当前工作目录
• 根据图表内容生成描述性文件名

文件名生成

根据内容分析创建有意义的文件名：

内容模式	示例文件名
带有 auth/login 的 flowchart	auth-flow.png
带有 API 的 sequenceDiagram	api-sequence.png
erDiagram	entity-relationship.png
关于 X 的 pie 图表	x-distribution.png
gantt 图表	project-timeline.png
对比表格	comparison-table.png
数据表格	data-table.png

规则：

• 使用 kebab-case（小写字母并以连字符分隔）
• 文件名简洁且有描述性（2-4 个单词）
• 避免使用 diagram.png 或 image.png 这类通用名称
• 如果能识别主题/内容，就将其包含在文件名中

转换流程

步骤 1：分析上下文

转换前，收集上下文信息：

1. 检查当前工作目录
2. 查找现有图片目录
3. 分析图表/表格内容以确定命名方式
4. 考虑对话中提及的文件或主题

步骤 2：确定输出路径

# Example logic (implement mentally, not as literal script)
if user_specified_path:
    output_path = user_specified_path
elif exists("./images"):
    output_path = "./images/{generated_name}.png"
elif exists("./assets"):
    output_path = "./assets/{generated_name}.png"
elif exists("./public/images"):
    output_path = "./public/images/{generated_name}.png"
else:
    output_path = "./{generated_name}.png"

步骤 3：创建临时输入文件

# For Mermaid diagrams
cat > /tmp/diagram.mmd << 'DIAGRAM_EOF'
<mermaid content>
DIAGRAM_EOF

# For Markdown tables
cat > /tmp/table.md << 'TABLE_EOF'
<table content>
TABLE_EOF

步骤 4：通过 mermaid-red API 转换

API 会自动检测内容类型（Mermaid 图表或表格）。两者使用相同的命令。

使用捆绑脚本：

# Mermaid diagram
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o <output_path>.png

# Markdown table
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o <output_path>.png

# With custom theme
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o <output_path>.png --theme ocean

# Force content type (if auto-detect gets it wrong)
node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o <output_path>.png --type table

可用选项：

• --theme <name> — default、dark、forest、neutral、ocean、emerald、midnight、slate、lavender、blueprint
• --type <type> — auto（默认）、mermaid、table
• --scale <n> — 1-4（默认值：2，表示 2x DPI）
• --bg <color> — 背景颜色（默认值：white；不设置背景时使用 "transparent"）
• --server <url> — 覆盖服务地址（默认值：https://diagramless.xyz）

也可以通过 stdin 管道传入内容：

echo "graph TD; A-->B" | node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs -o out.png
cat /tmp/table.md | node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs --type table -o table.png

步骤 5：报告结果

转换后，告知用户：

1. 图片保存的完整路径
2. 选择该位置的原因（简要说明）
3. 文件大小（以字节为单位，由脚本打印）
4. 提示用户如有需要，可以指定其他位置

示例

示例 1：包含 images/ 目录的项目

上下文： 用户正在一个包含 ./images/ 目录的项目中讨论身份验证。

用户：“将其转换为图片”

flowchart TD
    A[Login] --> B{Valid?}
    B -->|Yes| C[Dashboard]
    B -->|No| D[Error]

操作：

1. 检测 ./images/ 是否存在
2. 分析内容 → 身份验证流程
3. 生成文件名：login-flow.png
4. 将内容保存到 /tmp/diagram.mmd
5. 运行：node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o ./images/login-flow.png

---

示例 2：撰写一篇关于 AI、以海洋为主题的 X 文章

上下文： 用户提到要为 X 撰写一篇关于 AI Agent 的文章。

用户：“将其制作成海洋主题的 PNG”

flowchart LR
    User --> Agent --> Tools --> Response

操作：

1. 将内容保存到 /tmp/diagram.mmd
2. 运行：node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/diagram.mmd -o ./ai-agent-flow.png --theme ocean

---

示例 3：数据对比表

用户：“将此表格导出为图片”

| Model | Speed | Accuracy |
|-------|-------|----------|
| GPT-4 | Slow | High |
| Claude | Fast | High |

操作：

1. 将内容保存到 /tmp/table.md
2. 运行：node ~/.claude/skills/diagram-to-image/scripts/diagram-to-image.mjs /tmp/table.md -o ./model-comparison.png （会自动检测为表格）

---

示例 4：用户指定位置

用户：“将此图表保存到 ~/Desktop/my-chart.png”

操作： 完全按照 ~/Desktop/my-chart.png 作为输出路径。

错误处理

• 如果无法连接 API 服务，脚本会输出清晰的错误消息
• 如果内容类型自动检测失败，请明确使用 --type mermaid 或 --type table
• 对于本地开发/测试，请使用 --server http://localhost:3000