universal-image

name	universal-image
description	万能生图 Skill。根据用户意图自动选用 PlantUML / AI 生图两种引擎之一生成图片，保存到本地并以 Markdown 形式呈现。触发词：生成流程图、画时序图、画状态图、画类图、画甘特图、画思维导图、UML 图、用例图、组件图、部署图、ER 图、画云架构、画 AWS 架构、画 Azure 架构、画 C4 架构、生成海报、生成卡片、生成插图、AI 画图、生成示意图、做张图、画一张、render diagram、draw architecture。

万能生图 Skill

本 Skill 提供两个渲染脚本，按用户意图选用其一即可生成图片。脚本位于 ~/.claude/skills/universal-image/scripts/（Windows 为 %USERPROFILE%\.claude\skills\universal-image\scripts\）。

---

1. 何时触发本 Skill

用户消息包含以下意图之一时启用：

• 画图相关动词：画一张 / 做张图 / 生成 / 渲染 / draw / render / generate
• 图类型名词：流程图、时序图、状态图、类图、甘特图、思维导图、用例图、组件图、部署图、ER 图、架构图、海报、卡片、插图、示意图、封面
• 显式指明引擎：用 plantuml、用 AI 画 / 用 image2
• 上下文中已有 plantuml 源码代码块需要渲染成图

---

2. 路由决策表（关键）

第 0 优先级：用户明示了引擎就严格按用户的来，不要换。

• 「用 image2 画」「让 GPT 画」「用 AI 生图」「画一张照片/插画/原型图」→ 必须用 AI 生图，绝不能因为「画的是流程图」就偷换成 PlantUML
• 「用 plantuml 画」「画一个 PlantUML 架构」→ 必须用 PlantUML

第 1 优先级：用户没指定引擎时，按内容类型路由。默认走 AI 生图（视觉效果好），仅当用户明确要"工程图表"才走 PlantUML。

用户意图	引擎	脚本
流程图 / 活动图、时序图（含 alt/loop/par 复杂分支）、状态机（FSM）、类图、甘特图、用例图、组件图、部署图、对象图、ER 图、C4 架构、云架构（AWS/Azure/GCP/K8s）、思维导图——精确、结构化的工程图表	PlantUML	render-plantuml.mjs
其他一切视觉需求：照片、插画、艺术、海报、封面、IP 形象、Logo、产品概念图、营销素材、原型图、示意图、概念图、用户旅程图、git 分支图，以及所有模糊「画一张」类请求	AI 生图（默认）	render-image.mjs

为什么 AI 生图是默认而不是「反问」：用户说「画一张 X」往往就是想要好看的视觉成品。AI 生图视觉效果远好于 PlantUML（后者是工程线框风格），且 image2 对"原型图/示意图"也能给出可用的视觉草稿。PlantUML 只在用户明确需要精确、结构化、可文本编辑的图表时才用。

反例（错误路由，禁止）：

• 用户说「用 image2 画一张登录流程图」→ 必须走 AI 生图（用户明示了引擎）。绝不要因为关键词「流程图」改路由
• 用户说「用 plantuml 画一张赛博朋克城市」→ 必须走 PlantUML（用户明示了引擎，结果可能不好看，那是用户的选择）
• 用户说「画一张登录流程图」（没指定引擎）→ 走 PlantUML（"流程图"是结构化工程图）
• 用户说「画一张登录页原型图」（没指定引擎）→ 走 AI 生图（"原型图"想要视觉成品，不是流程图）
• 用户说「画一张图给我看看」（模糊）→ 默认走 AI 生图（不再反问）
• 用户说「画一张用户旅程图」（没指定引擎）→ 走 AI 生图（旅程图重视觉表达，不在 PlantUML 清单里）
• ER 图、云架构图都走 PlantUML（结构精确、有图标库），不要交给 AI 生图（画不准）

---

3. 调用契约（所有脚本统一）

CLI 参数

参数	适用脚本	含义
--input <file>	plantuml	从文件读源码
--inline "<src>"	plantuml	内联传源码（短源码用，含特殊字符需转义）
--stdin	plantuml	从标准输入读源码（推荐长源码用此方式）
--prompt "<text>"	image	AI 生图的文字描述（必填）
--output-dir <dir>	全部	图片输出目录，默认 ./output
--source-dir <dir>	plantuml	源码（.puml）输出目录，默认同 --output-dir。文档模式专用
--format png|svg	plantuml	输出格式，默认 png
--dpi <50-600>	plantuml	PNG 渲染 dpi，默认 200（约 2x 清晰度，不要随便改小）
--format png|jpeg|webp	image	输出格式，默认 png
--ratio <ratio>	image	推荐用这个，6 个比例预设（见 4.5 节比例表）
--tier 1k|2k|4k	image	配合 --ratio 选档位，默认 2k（主流推荐）
--size WxH	image	直接指定像素，宽高须 16 的倍数、单边 ≤3840。优先级高于 --ratio
--quality low|medium|high	image	质量档位，省略由模型默认（通常 medium）
--background transparent|opaque|auto	image	背景，transparent 仅 png/webp 可用，jpeg 无透明通道
--filename <name>	全部	自定义文件名（含扩展名）

返回值（stdout 最后一行 JSON）

成功：

{
  "ok": true,
  "engine": "plantuml",
  "path": "/abs/path/to/output/img-20260524-103045-plantuml-a3f7.png",
  "sourceCode": "@startuml\nA -> B\n@enduml",
  "sourcePath": "/abs/path/to/output/img-20260524-103045-plantuml-a3f7.puml",
  "size": null,
  "durationMs": 1340
}

失败：

{
  "ok": false,
  "engine": "plantuml",
  "error": {
    "code": "PLANTUML_HTTP_FAILED",
    "message": "Upstream returned 500",
    "httpStatus": 500
  }
}

退出码：成功 0，失败 1。stderr 是 debug 日志，不要解析。

---

4. 调用示例

4.1 PlantUML 流程图 / 活动图（推荐 stdin 方式）

用户：「画一张用户注册流程图」

构造 PlantUML activity 源码后用 Bash 调用：

cat <<'EOF' | node ~/.claude/skills/universal-image/scripts/render-plantuml.mjs --stdin
@startuml
start
:访问注册页;
if (已注册?) then (是)
  :跳转登录;
else (否)
  :填写表单;
  :发送验证码;
  :完成注册;
endif
stop
@enduml
EOF

Windows PowerShell 写法（用 --inline 或临时文件更稳）：

'@startuml
start
:访问注册页;
:填写表单;
:完成注册;
stop
@enduml' | node "$env:USERPROFILE\.claude\skills\universal-image\scripts\render-plantuml.mjs" --stdin

⚠️ 活动节点着色铁律：给 activity 节点上色时，只能用以下两种写法之一——

• 颜色前置：#FFE0B2:文字;
• 颜色后置+尖括号：:文字;<<#FFE0B2>>

不要把裸 #颜色 放在 ; 之后（如 :文字; #FFE0B2）。这种旧语法已被 plantuml.com 废弃，服务端不会报错中断，而是会在图的顶部追加一个警告块，里面每条废弃用法占一行 This syntax is deprecated, you must add <<#…>>…——图本体能画出来，但顶部多一坨警告很难看。

为了兜底 LLM 偶尔写错，render-plantuml.mjs 内置了 sanitizer：检测到 ;<空格>#hex 末尾结构会自动改写成 ;<<#hex>> 再发给服务端，并在 stderr 打印 [plantuml] auto-fixed N deprecated color directive(s)。这是安全网，不要依赖它——首选还是直接写对。partition / 分区目前 sanitizer 不覆盖：要给分区上色请直接写 partition "名称" <<#FFE0B2>> { … }。拿不准时直接不上色最稳妥。

解析返回值中的 path 字段后，向用户回复：

已生成流程图：

![用户注册流程](./output/img-20260524-103045-plantuml-a3f7.png)

源码已同步保存到 `./output/img-20260524-103045-plantuml-a3f7.puml`，你可以基于它继续微调。

4.2 PlantUML 时序图

cat <<'EOF' | node ~/.claude/skills/universal-image/scripts/render-plantuml.mjs --stdin
@startuml
participant 用户 as U
participant 前端 as F
participant 后端 as B
participant 数据库 as DB
U -> F: 提交表单
F -> B: POST /api/login
B -> DB: 查询用户
DB --> B: 用户数据
B --> F: JWT token
F --> U: 跳转首页
@enduml
EOF

4.3 PlantUML + C4 架构图（云架构必加 include！）

用户：「画一个微服务的容器图」

cat <<'EOF' | node ~/.claude/skills/universal-image/scripts/render-plantuml.mjs --stdin
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "用户")
System_Boundary(c1, "电商平台") {
  Container(web, "Web 应用", "Next.js", "用户浏览界面")
  Container(api, "API 网关", "Node.js", "路由与鉴权")
  Container(order, "订单服务", "Go", "下单与履约")
  ContainerDb(db, "数据库", "PostgreSQL", "订单与用户数据")
}
Rel(user, web, "HTTPS")
Rel(web, api, "JSON/HTTPS")
Rel(api, order, "gRPC")
Rel(order, db, "SQL")
@enduml
EOF

4.4 PlantUML + AWS 架构图

用户：「画一个 AWS 上的 Web 应用部署」

cat <<'EOF' | node ~/.claude/skills/universal-image/scripts/render-plantuml.mjs --stdin
@startuml
!include https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/main/dist/AWSCommon.puml
!include https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/main/dist/NetworkingContentDelivery/CloudFront.puml
!include https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/main/dist/Compute/EC2.puml
!include https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/main/dist/Database/RDS.puml

CloudFront(cdn, "CloudFront", "全球 CDN")
EC2(ec2, "EC2 集群", "应用服务器")
RDS(rds, "RDS PostgreSQL", "主数据库")
cdn --> ec2
ec2 --> rds
@enduml
EOF

4.5 AI 生图（GPT-Image）

用户：「生成一张赛博朋克风格的城市夜景」

node ~/.claude/skills/universal-image/scripts/render-image.mjs \
  --prompt "Cyberpunk city at night, neon lights reflecting on wet streets, flying cars, cinematic lighting, ultra detailed, 8k" \
  --ratio 16:9

比例 + 档位（强烈优先用 --ratio，不要直接拼像素）

按用户意图选比例，按需求精度选档位。调用后不要因网络失败就降级比例或档位（参见守则 #9）。

比例	1K 草图/测速	2K 主流（默认）	4K 画册/壁纸	适用场景
1:1	1024×1024	2048×2048	2880×2880	头像、社交配图、电商主图
16:9	1024×576	2048×1152	3840×2160	电脑壁纸、网页 banner、视频封面
9:16	576×1024	1152×2048	2160×3840	手机壁纸、海报、抖音/小红书竖版封面
4:3	1024×768	2048×1536	3072×2304	演示文稿、iPad 适配图
3:4	768×1024	1536×2048	2304×3072	小红书封面、Pinterest 配图
2:3	1024×1536	1360×2048	2336×3520	书籍封面、冲印照片、人像写真

档位选择启发：

• 用户没说精度 / 只是想看看 → 用默认 2k
• 用户说「快速试一下」「先看看效果」「批量预览」 → 加 --tier 1k --quality low
• 用户说「画册级」「印刷」「壁纸」「高清」「最终交付」 → 加 --tier 4k --quality high

调用样板：

# 默认：2K + medium 质量
node ... --prompt "..." --ratio 16:9

# 草图模式：1K + low 质量（快、省钱）
node ... --prompt "..." --ratio 9:16 --tier 1k --quality low

# 画册模式：4K + high 质量（慢、贵、精细）
node ... --prompt "..." --ratio 16:9 --tier 4k --quality high

# 透明 logo（必须 png 或 webp）
node ... --prompt "..." --ratio 1:1 --background transparent --format png

# 非常规比例：直接 --size，注意宽高须 16 倍数、单边 ≤3840
node ... --prompt "..." --size 1920x800

回复用户的样式

把英文 prompt 也回显出来，便于用户说「改一下」：

已生成图片（prompt: `Cyberpunk city at night...`，2048×1152 / 16:9）：

![赛博朋克城市](./output/img-20260524-103045-image-b8e1.png)

---

4.6 文档模式（写博客/文档时强烈推荐）

触发条件——满足任一即启用：