Claude Code 万能生图 Skill — 让 Claude 自动选用 Mermaid / PlantUML / AI 生图三种引擎之一生成图片。
- 三引擎自动路由：Claude 读
SKILL.md中的决策表，根据你的自然语言意图自动挑选合适引擎，模糊场景会主动反问而不是瞎画。 - 零本地依赖：纯在线 API 调用，不需要安装 Java、Chromium、Graphviz、Mermaid CLI、jar 包。npm 包体积 < 100KB，安装时间 < 5 秒。
- 跨平台：Windows / macOS / Linux 行为完全一致，路径解析、shell 命令均经过实测。
- npm 一键安装：
npx @openx123/universal-image-skill install即装即用。 - 备份式更新：升级时旧目录改名为
.bak-<旧版本>，自动保护用户.env，永远不会静默覆盖你的配置。 - PlantUML 高质量增强：内置 C4-PlantUML / AWS / Azure 图标库
!include速查表，Claude 会在画云架构时主动用上官方图标，告别"无图标的纯方框"。
- Node.js >= 20
- Claude Code（任意桌面端，已能识别
~/.claude/skills/目录） - 一个 OpenAI 兼容协议的中转站（仅 AI 生图引擎需要）
# 安装 Skill 到 ~/.claude/skills/universal-image/
npx @openx123/universal-image-skill install
# 交互式填入中转站地址、密钥、模型名等
npx @openx123/universal-image-skill config
# 重启 Claude Code，让它加载新 Skill重启后对 Claude 说一句：
/universal-image 帮我画一个claude web端多agents对话的原型图
Claude 会自动调用生图引擎，把图片写到当前工作目录的 ./output/ 下，并在回复中用 Markdown 引用。
下面这些一句话指令都能稳定触发对应引擎，不需要你显式指定引擎名。
你：画一张用户注册的流程图，包含校验邮箱、发送验证码、写库三个步骤。
Claude：[调用 render-mermaid.mjs] → 输出 ./output/img-...-mermaid-xxxx.png
你：给我画一个微服务下单的时序图，参与者有客户端、订单服务、库存服务、支付服务。
Claude：[Mermaid sequenceDiagram] → 输出 png
你：画一个 AWS 上的微服务部署架构图，包含 ALB、ECS Fargate、RDS、ElastiCache、S3。
Claude：[PlantUML + aws-icons-for-plantuml] → 输出带官方 AWS 图标的 png
你：用 C4 模型画我们订单系统的容器图，包含 Web 前端、API 网关、订单服务、库存服务、Postgres。
Claude：[PlantUML + C4_Container.puml] → 输出标准 C4 容器图
你：画一张电商订单表和商品表的 ER 图，订单包含多条订单项。
Claude：[PlantUML ER] → 输出 png（Mermaid 的 ER 语法较弱，PlantUML 更合适）
你：生成一张赛博朋克风格的城市夜景，霓虹灯反射在湿漉漉的街道上，电影质感。
Claude：[调用 render-image.mjs，模型走 IMAGE_MODEL] → 输出 png
你：帮我生成一张产品发布会的横版海报背景，深蓝色科技感，留白给标题。
Claude：[AI 生图] → 输出 png
你：给我做张图。
Claude：你想要哪一类？流程/时序/UML 之类的结构图我用 Mermaid 或 PlantUML 画；
写实/插画/海报这类我用 AI 生图。请补充一下。
| 引擎 | 适用场景 | 后端 | 速度 | 可控性 | 写实度 |
|---|---|---|---|---|---|
| Mermaid | 流程图、时序图、状态机、类图、甘特图、思维导图 | mermaid.ink 在线服务 |
快 | 高 | 无 |
| PlantUML | 复杂 UML（用例、组件、部署、ER）、序列图复杂分支、云架构（C4 / AWS / Azure 图标库） | plantuml.com 官方 / 自建 Kroki |
中 | 高 | 无 |
| AI 生图 | 真实照片、插画、艺术风、产品概念图、营销素材、海报封面 | OpenAI 兼容协议中转站 | 慢 | 中 | 高 |
Claude 内部的判断逻辑（写在 SKILL.md 给它读）：
用户意图
├─ 流程 / 时序 / 状态 / 甘特 / 类图 / 思维导图 → Mermaid
├─ 用例图 / 组件图 / 部署图 / ER 图 / 云架构 → PlantUML
├─ 真实 / 照片 / 插画 / 艺术 / 海报 / 封面 / 写实 → AI 生图
└─ 模糊场景 → 反问，否则默认 Mermaid
- 不用 Mermaid 画 ER 图（语法弱，改用 PlantUML）
- 不用 PlantUML 画海报 / 营销图（无写实样式，改用 AI 生图）
- 不用 AI 生图画精确的流程 / UML（不可控，改用 Mermaid / PlantUML）
执行 npx @openx123/universal-image-skill config 会交互式生成 ~/.claude/skills/universal-image/.env。你也可以手动编辑，字段如下：
| 字段 | 必填 | 默认值 | 说明 |
|---|---|---|---|
IMAGE_API_BASE_URL |
是 | — | 中转站的 OpenAI 兼容 API 地址，需含 /v1，例：https://your-proxy.com/v1 |
IMAGE_API_KEY |
是 | — | 中转站密钥，通常以 sk- 开头 |
IMAGE_MODEL |
否 | gpt-image-2 |
调用的模型名，可换成中转站支持的其他生图模型 |
| 字段 | 必填 | 默认值 | 说明 |
|---|---|---|---|
MERMAID_INK_URL |
否 | https://mermaid.ink |
Mermaid 渲染服务地址，可指向自建的 mermaid.ink 镜像，避免公网限速或数据泄露 |
| 字段 | 必填 | 默认值 | 说明 |
|---|---|---|---|
PLANTUML_SERVER_URL |
否 | https://www.plantuml.com/plantuml |
PlantUML 渲染服务地址，可换成自建 PlantUML server 或 Kroki 实例 |
| 字段 | 必填 | 默认值 | 说明 |
|---|---|---|---|
OUTPUT_DIR |
否 | ./output |
图片输出目录，默认相对当前工作目录 |
DEFAULT_FORMAT |
否 | png |
默认输出格式，可选 png / jpg / svg（依各引擎支持情况而定） |
# AI 生图
IMAGE_API_BASE_URL=https://your-proxy.com/v1
IMAGE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
IMAGE_MODEL=gpt-image-2
# Mermaid
MERMAID_INK_URL=https://mermaid.ink
# PlantUML
PLANTUML_SERVER_URL=https://www.plantuml.com/plantuml
# 输出
OUTPUT_DIR=./output
DEFAULT_FORMAT=png所有命令均可通过 npx @openx123/universal-image-skill <command> 调用。
| 命令 | 作用 |
|---|---|
install |
把 skill/ 整目录复制到 ~/.claude/skills/universal-image/，若已存在则备份旧版本 |
config |
交互式生成或编辑 .env，并对每个引擎做一次烟测，报告可用性 |
update |
拉 npm registry 检查新版本，展示 changelog，确认后重新执行 install 流程 |
uninstall |
移除 ~/.claude/skills/universal-image/ 目录（备份目录保留，可手动清理） |
version |
显示当前已安装版本与 npm 上的最新版本 |
--help |
显示帮助 |
update 只负责把已下载到本地的 npm 包内容重新部署到 ~/.claude/skills/，它不会自动升级全局 npm 包本身。如果你想拿到最新代码，先：
npm install -g @openx123/universal-image-skill@latest
npx @openx123/universal-image-skill installnpx 用户每次都会拉最新版，可以直接：
npx @openx123/universal-image-skill@latest install本 Skill 的三个引擎都会把数据上行到对应服务，请根据你的合规要求选择使用。
| 引擎 | 上行内容 | 默认目的地 | 自建建议 |
|---|---|---|---|
| Mermaid | 你的 Mermaid 源码 | mermaid.ink（社区公共服务） |
内网部署 mermaid.ink 并设置 MERMAID_INK_URL |
| PlantUML | 你的 PlantUML 源码 | plantuml.com（官方公共服务） |
自建 PlantUML server 或 Kroki 并设置 PLANTUML_SERVER_URL |
| AI 生图 | 你的 prompt 与生成参数 | 你在 .env 中配置的中转站 |
中转站本身由你选择和负责，建议优先用合规的官方服务 |
任何包含商业机密、个人隐私、内部架构敏感信息的内容，强烈建议先自建服务再使用。本仓库代码不会主动收集任何用户数据。
- 确认目录已存在：
- Windows：
%USERPROFILE%\.claude\skills\universal-image\SKILL.md - macOS / Linux：
~/.claude/skills/universal-image/SKILL.md
- Windows：
- 完全退出 Claude Code 后再启动（重新加载 Skill 索引）。
- 用
npx @openx123/universal-image-skill version确认本地版本与 npm 上的版本一致。
- 检查
.env中IMAGE_API_KEY是否复制完整、是否还在有效期内。 - 确认
IMAGE_API_BASE_URL末尾是/v1这种 OpenAI 兼容路径，而非中转站首页 URL。 - 用
npx @openx123/universal-image-skill config再跑一次烟测看错误详情。
- 公共服务（
mermaid.ink、plantuml.com）会限速，长时间不可用时可切换到自建实例。 - 检查防火墙 / 代理是否拦截了出站 HTTPS 请求。
- 内置
lib/http.mjs已自带 3 次重试 + 30s 超时，仍然失败说明远端确实有问题。
- 所有内部路径都用
path.join拼接，正常不应该出现路径分隔符问题。 - 若你手动改了
OUTPUT_DIR，避免使用反斜杠转义（用正斜杠或\\）。 - 若仍异常，请带上完整错误堆栈到 Issues 提交。
本 Skill 不会自动清理 ./output/，请在你的工作流里自行归档或定期删除。
欢迎 Issue 与 PR。本地开发流程：
git clone https://github.com/openx123/universal-image-skill.git
cd universal-image-skill
# 零运行时依赖，但用 npm install 准备好 .npmrc 等
npm install
# 跑 Node 内置测试
npm test
# 本地链接，方便联调
npm link
universal-image-skill --help
# 改完想看效果，直接 install 到本机 Claude
universal-image-skill installuniversal-image-skill/
├── bin/ # npx 入口
├── installer/ # install / update / config / paths
├── skill/ # 真正部署到 ~/.claude/skills/ 的内容
│ ├── SKILL.md # 给 Claude 读的路由说明（项目最关键的文件）
│ ├── scripts/ # 三个引擎的 render-*.mjs
│ └── lib/ # config / http / output 通用工具
├── tests/ # node --test
├── .github/workflows/ # CI + Release
├── package.json
├── README.md
├── LICENSE
└── CHANGELOG.md
- 提交信息使用 Conventional Commits：
feat:/fix:/docs:/refactor:/test:/chore: - 新引擎或修改
.env字段时同步更新 README 的"配置说明"和SKILL.md的路由表 - PR 自动跑 CI（Linux / macOS / Windows × Node 20 / 22），全绿后再合并
维护者：
# 1. 更新 CHANGELOG.md，bump package.json 版本
npm version patch # 或 minor / major
# 2. 推 tag 触发自动 release
git push --follow-tags.github/workflows/release.yml 会自动 npm publish 并创建 GitHub Release。
MIT © 2026 OpenX123