From doc-smith
Generates AI images for technical diagrams including architecture, flowcharts, sequence, and concept diagrams. Supports editing existing images, custom ratios, sizes, locales via Gemini SDK or AFS CLI backends.
npx claudepluginhub aigne-io/doc-smith-skills --plugin doc-smithThis skill uses the workspace's default tool permissions.
使用 AI 生成图片,支持技术图表、架构图、流程图等。
Generates or edits images using AI models (FLUX, Gemini) via OpenRouter Python script. For photos, illustrations, artwork, visual assets, concept art; excludes technical diagrams like flowcharts.
Generates and edits images using Google's Gemini Nano Banana Pro model (gemini-3-pro-image-preview) via bash API calls. Supports logos, product mockups, photo edits; requires GEMINI_API_KEY.
Generates and edits images using Gemini CLI image models for blog featured images, YouTube thumbnails, icons, diagrams, patterns, illustrations, and visuals. Activates on create, generate, make, draw, design, or edit image requests.
Share bugs, ideas, or general feedback.
使用 AI 生成图片,支持技术图表、架构图、流程图等。
# 基础用法:描述要生成的图片
/doc-smith-images "系统架构图,展示微服务之间的调用关系"
# 指定输出路径
/doc-smith-images "用户登录流程图" --savePath ./images/login-flow.png
# 指定宽高比
/doc-smith-images "系统架构图" --ratio 16:9
/doc-smith-images "数据流向图" -r 4:3
# 指定图片尺寸
/doc-smith-images "概念图" --size 4K
# 指定图片中文字的语言
/doc-smith-images "API 调用流程" --locale en
# 编辑已有图片(基于原图修改)
/doc-smith-images "优化配色和布局" --update ./images/old.png --savePath ./images/new.png
/doc-smith-images "把标题改为英文" -u ./images/arch.png --savePath ./images/arch-en.png
# 组合使用
/doc-smith-images "微服务架构图" --ratio 16:9 --locale zh --savePath ./docs/arch.png
| Option | Alias | Description |
|---|---|---|
--savePath <path> | 图片保存路径(必需) | |
--ratio <ratio> | -r | 宽高比:1:1, 5:4, 4:3, 3:2, 16:9, 21:9(默认 4:3) |
--size <size> | -s | 图片尺寸:2K, 4K(默认 2K) |
--locale <lang> | -l | 图片中文字语言(默认 zh) |
--update <path> | -u | 基于已有图片编辑 |
--context <text> | -c | 提供上下文信息,帮助生成更准确的图片 |
--backend <type> | 指定后端:gemini-sdk 或 afs-cli,跳过自动检测 |
| 图片类型 | 推荐比例 | 说明 |
|---|---|---|
| 架构图 | 16:9 或 4:3 | 系统架构、模块关系、组件结构 |
| 流程图 | 4:3 或 3:2 | 业务流程、数据流向、状态转换 |
| 时序图 | 16:9 | 交互时序、调用链路 |
| 概念图 | 4:3 | 概念关系、层次结构 |
| 示意图 | 4:3 或 1:1 | 功能示意、原理说明 |
若提供了 --backend 参数(gemini-sdk 或 afs-cli),直接使用指定后端,跳过以下检测流程。此参数由调用方(如 doc-smith-create、doc-smith-localize)在前置检测后传入。
若未提供 --backend,按优先级检测可用的图片生成后端。检测只执行一次,后续所有图片生成/编辑操作使用同一后端。
检查环境变量 GEMINI_API_KEY 是否已设置且非空:
echo "$GEMINI_API_KEY" | head -c 5
若输出非空,选定 Gemini SDK 后端。
然后检查依赖是否已安装:
ls <skill-directory>/scripts/node_modules/@google/genai 2>/dev/null
若目录不存在,自动安装:
cd <skill-directory>/scripts && npm install
若 Gemini API Key 未配置,检查 AFS CLI:
which afs 确认已安装~/.afs-config/config.toml 是否存在且包含 path = "/aignehub" 条目cd ~ && afs exec /.actions/mount --path /aignehub --uri aignehub://若两个条件均满足,选定 AFS CLI 后端。
若以上两种后端均不可用,必须停下来让用户做选择,禁止自动默认为 skip。
使用 AskUserQuestion 工具向用户提供以下选项:
export GEMINI_API_KEY="your-key" 并重新执行npm install -g @aigne/afs-cli@beta 安装 AFS CLI,然后自动挂载 aignehub,完成后使用 AFS CLI 后端继续工作流等待用户明确选择后,按对应方案执行。未经用户确认不得跳过图片生成。
根据是否提供 --update 参数,选择不同的工作流程。
当未提供 --update 参数时,生成全新的图片。
若检测到 Gemini SDK 后端,调用生图脚本:
node <skill-directory>/scripts/generate.mjs \
--mode=generate \
--desc="$PROMPT" \
--savePath="$OUTPUT_PATH" \
--aspectRatio="$RATIO" \
--locale="$LOCALE" \
--documentContent="$CONTEXT"
参数说明:
--desc:用户传入的图片描述--savePath:图片保存路径--aspectRatio:宽高比(如 4:3、16:9),默认 4:3--locale:图片中文字语言,默认 zh--documentContent:--context 提供的文档内容(可选)脚本会自动读取 GEMINI_API_KEY、构建 prompt、调用 Gemini API 并保存图片。
成功时输出 JSON:{"message": "图片已保存到 ..."}
失败时以非零退出码退出。
若检测到 AFS CLI 后端,手动构建 prompt 并调用 AFS CLI:
步骤 1: 构建 Prompt
参考 <skill-directory>/references/prompts.md 中的系统提示词和用户提示词模板,将以下要素组合成完整的 prompt:
references/prompts.md 中「系统提示词(System Prompt)」部分的全部内容--desc 参数)--context 提供的文档内容(如有)--locale 指定的语言(默认 zh)--ratio 指定的宽高比(默认 4:3)使用「用户提示词模板」中「标准文本生图模式」的模板格式,将上述要素填入对应的占位符。
将系统提示词和用户提示词合并为一个完整的 prompt 字符串($FULL_PROMPT)。
步骤 2: 宽高比映射到像素尺寸
将 --ratio 参数映射为 AFS CLI 所需的像素尺寸:
| 宽高比 | 像素尺寸 |
|---|---|
| 1:1 | 1024x1024 |
| 5:4 | 1280x1024 |
| 4:3 | 1024x768(默认) |
| 3:2 | 1536x1024 |
| 16:9 | 1792x1024 |
| 21:9 | 2048x1024 |
步骤 3: 调用 AFS CLI 生成图片
afs exec /aignehub/providers/google/gemini-3-pro-image-preview/.actions/generateImage \
--prompt "$FULL_PROMPT" \
--size "$PIXEL_SIZE" \
--json
步骤 4: 解析返回结果并下载图片
# 解析 URL
URL=$(echo "$JSON_RESULT" | jq -r '.data.images[0].url')
# 下载图片到指定路径
curl -sL "$URL" -o "$SAVE_PATH"
ls -la "$SAVE_PATH"
file "$SAVE_PATH" # 必须包含 "JPEG image data" 或 "PNG image data"
关键约束:若 file 输出为 data 或其他非图片格式(即不包含 JPEG image data / PNG image data),说明图片在传输或存储过程中损坏(常见原因:服务端将二进制误当 UTF-8 处理,高位字节被替换为 U+FFFD)。此时必须:
rm "$SAVE_PATH"当提供了 --update 参数时,基于原图进行编辑。
# 验证原图文件存在且为有效图片
file "$UPDATE_PATH" # 必须包含 "JPEG image data" 或 "PNG image data"
若文件不存在或非有效图片,报错终止。
node <skill-directory>/scripts/generate.mjs \
--mode=edit \
--desc="$EDIT_INSTRUCTION" \
--sourcePath="$SOURCE_IMAGE" \
--savePath="$OUTPUT_PATH" \
--sourceLocale="$SOURCE_LOCALE" \
--targetLocale="$TARGET_LOCALE" \
--aspectRatio="$RATIO"
参数说明:
--desc:编辑指令(如"把标题改为英文")--sourcePath:原图路径(--update 指定的路径)--savePath:输出图片路径(若未指定,则覆盖原图)--sourceLocale:原图文字语言(默认 zh)--targetLocale:目标语言(翻译场景使用,如 en)--aspectRatio:宽高比(默认 4:3)脚本会自动处理翻译场景(当 sourceLocale ≠ targetLocale 时自动增强 prompt)。
步骤 2: 构建编辑 Prompt
重要:编辑模式不使用系统提示词。完整的生成性系统提示词(颜色方案、节点规则、布局指南等)会引导模型重新创作而非编辑。编辑模式仅使用 <skill-directory>/references/prompts.md 中「图片编辑模式」的模板。
根据编辑目的选择合适的 prompt 策略:
翻译场景(目标是将图片中的文字翻译为其他语言):
"用户认证" → "User Auth")通用编辑场景(修改元素、调整样式等):
{desc}--context,填入 {documentContent}Prompt 长度约束:编辑模式的 prompt 总长度应控制在 500 词以内,避免过长的指令压过"基于原图编辑"的意图。
步骤 3: 调用 AFS CLI 编辑图片
afs exec /aignehub/providers/google/gemini-3-pro-image-preview/.actions/generateImage \
--prompt "$FULL_PROMPT" \
--image "$UPDATE_PATH" \
--json
注意:Prompt 必须明确要求"参考传入的图片并返回新的图片",否则模型可能只返回文字而不返回图片。
步骤 4: 解析返回结果并保存图片
# 确定保存路径(若未指定 savePath,则覆盖原图)
FINAL_PATH="${SAVE_PATH:-$UPDATE_PATH}"
# 解析 URL 并下载
URL=$(echo "$JSON_RESULT" | jq -r '.data.images[0].url')
curl -sL "$URL" -o "$FINAL_PATH"
ls -la "$FINAL_PATH"
file "$FINAL_PATH" # 必须包含 "JPEG image data" 或 "PNG image data"
关键约束:与模式 A 相同,若输出文件非有效图片格式,删除后重试(最多 2 次)。
返回生成的图片路径,供调用方使用。
当 doc-smith 主流程检测到 AFS Image Slot:
<!-- afs:image id="architecture" desc="系统架构图,展示各模块关系" -->
主流程调用本 Skill 处理。后端检测在 Skill 内部自动完成,调用方无需关心后端选择。
Gemini SDK 后端:由脚本直接调用 Gemini API 生成并保存图片。
node <skill-directory>/scripts/generate.mjs \
--mode=generate \
--desc="$PROMPT" \
--savePath="$OUTPUT_PATH" \
--aspectRatio="4:3" \
--locale="zh"
AFS CLI 后端:构建 prompt 后通过 AFS CLI 调用生图服务。
afs exec /aignehub/providers/google/gemini-3-pro-image-preview/.actions/generateImage \
--prompt "$FULL_PROMPT" \
--size "1024x768" \
--json
错误: GEMINI_API_KEY 未配置。请设置环境变量后重试。
错误: 未检测到可用的图片生成后端
当前状态:
- GEMINI_API_KEY: 未设置
- AFS CLI: 未安装 / 未挂载
请选择以下方案之一:
1. 设置 GEMINI_API_KEY 环境变量(推荐)
2. 安装 AFS CLI: npm install -g @aigne/afs-cli@beta
3. 跳过图片生成(将从文档中移除图片引用)
错误: afs 命令未找到
请安装 AFS CLI:
npm install -g @aigne/afs-cli@beta
错误: /aignehub 路径不存在或未挂载
请在用户根目录下执行以下命令挂载 aignehub:
cd ~ && afs exec /.actions/mount --path /aignehub --uri aignehub://
挂载成功后会在 ~/.afs-config/config.toml 中写入配置。
错误: 图片生成失败
可能原因:
1. prompt 描述不清晰
2. 网络连接问题
3. API 配额用尽
4. 后端服务异常
建议:
1. 优化 prompt 描述,更具体地说明图片内容
2. 检查网络连接
3. 稍后重试
错误: 图片下载失败
请检查:
1. AFS CLI 返回的 URL 是否可访问
2. 网络连接是否正常
3. 保存路径是否有写入权限
错误: 原图文件无效
指定的图片文件不存在或格式不正确。
请确认文件路径正确,且文件为有效的 PNG 或 JPEG 图片。
错误: 图片编辑返回空结果
后端返回的图片数据为空,可能原因:
1. 原图格式不被支持
2. 编辑请求被模型拒绝
3. Prompt 未明确要求返回图片,模型只返回了文字
4. 网络或服务端临时异常
建议:
1. 检查原图是否为标准 PNG/JPEG 格式
2. 确保 prompt 中包含"返回新的图片"等明确指令
3. 调整编辑描述后重试
4. 重试 1-2 次,排除临时异常