doc-smith-images

Doc-Smith Image Generation

Use AI to generate images, supporting technical diagrams, architecture diagrams, flowcharts, and more.

Usage

# 基础用法：描述要生成的图片
/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

Specify the language of the text in the image

/doc-smith-images "API call flow" --locale en

Edit an existing image (modify based on the original image)

/doc-smith-images "optimize color scheme and layout" --update ./images/old.png --savePath ./images/new.png /doc-smith-images "change the title to English" -u ./images/arch.png --savePath ./images/arch-en.png

Combined usage

/doc-smith-images "microservices architecture diagram" --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`，按优先级检测可用的图片生成后端。检测只执行一次，后续所有图片生成/编辑操作使用同一后端。

### 优先级 1: Gemini SDK（推荐）

检查环境变量 `GEMINI_API_KEY` 是否已设置且非空：

```bash
echo "$GEMINI_API_KEY" | head -c 5

If the output is non-empty, select the Gemini SDK backend.

Then check whether the dependencies are installed:

ls <skill-directory>/scripts/node_modules/@google/genai 2>/dev/null

If the directory does not exist, install automatically:

cd <skill-directory>/scripts && npm install

Priority 2: AFS CLI

If the Gemini API Key is not configured, check the AFS CLI:

1. Run which afs to confirm it is installed
2. Check whether ~/.afs-config/config.toml exists and contains the path = "/aignehub" entry
3. If installed but not mounted, mount automatically:cd ~ && afs exec /.actions/mount --path /aignehub --uri aignehub://

If both conditions are met, select the AFS CLI backend.

No available backend

If neither of the above two backends is available,you must stop and let the user make a choice; automatically defaulting to skip is prohibited。

Use the AskUserQuestion tool to provide the user with the following options:

1. Configure Gemini API Key(recommended):export GEMINI_API_KEY="your-key" and re-execute
2. Install AFS CLI and continue: automatically execute npm install -g @aigne/afs-cli@beta to install AFS CLI, then automatically mount aignehub, and after completion continue the workflow using the AFS CLI backend
3. Skip image generation: automatically remove image references from the document, clean up related text and metadata files, and then terminate the workflow

Wait for the user to make an explicit choice, then execute according to the corresponding plan. Image generation must not be skipped without the user's confirmation.

Workflow

Depending on whether the --update parameter is provided, choose a different workflow.

Mode A: Generate a new image (default)

When the --update parameter is not provided, generate a completely new image.

Use the Gemini SDK backend

If the Gemini SDK backend is detected, call the image generation script:

node <skill-directory>/scripts/generate.mjs \
  --mode=generate \
  --desc="$PROMPT" \
  --savePath="$OUTPUT_PATH" \
  --aspectRatio="$RATIO" \
  --locale="$LOCALE" \
  --documentContent="$CONTEXT"

Parameter description:

• --desc: the image description passed in by the user
• --savePath: the image save path
• --aspectRatio: aspect ratio (e.g., 4:3、16:9), default 4:3
• --locale: language of the text in the image, default zh
• --documentContent：--context the document content provided (optional)

The script will automatically read GEMINI_API_KEY, build the prompt, call the Gemini API, and save the image. On success, output JSON:{"message": "图片已保存到 ..."} On failure, exit with a non-zero exit code.

Use the AFS CLI backend

If the AFS CLI backend is detected, manually build the prompt and call the AFS CLI:

Step 1: Build the Prompt

Refer to <skill-directory>/references/prompts.md the system prompt and user prompt templates, and combine the following elements into a complete prompt:

• System prompt：references/prompts.md all content in the "System Prompt" section of
• User description: the image description passed in by the user (the--desc parameter)
• Context：--context Provided document content (if any)
• Language：--locale Specified language (default zh)
• Aspect ratio：--ratio Specified aspect ratio (default 4:3)

Using the template format of "Standard Text-to-Image Mode" in the "User Prompt Template", fill the above elements into the corresponding placeholders.

Merge the system prompt and user prompt into a single complete prompt string ($FULL_PROMPT）。

Step 2: Map aspect ratio to pixel dimensions

Map the --ratio parameter to the pixel dimensions required by AFS CLI:

Aspect ratio	Pixel dimensions
1:1	1024x1024
5:4	1280x1024
4:3	1024x768(default)
3:2	1536x1024
16:9	1792x1024
21:9	2048x1024

Step 3: Call AFS CLI to generate the image

afs exec /aignehub/providers/google/gemini-3-pro-image-preview/.actions/generateImage \
  --prompt "$FULL_PROMPT" \
  --size "$PIXEL_SIZE" \
  --json

Step 4: Parse the returned result and download the image

# 解析 URL
URL=$(echo "$JSON_RESULT" | jq -r '.data.images[0].url')

# 下载图片到指定路径
curl -sL "$URL" -o "$SAVE_PATH"

Verify the generation result (common to both backends)

ls -la "$SAVE_PATH"
file "$SAVE_PATH"  # 必须包含 "JPEG image data" 或 "PNG image data"

Key constraint: If file outputs as data or another non-image format (i.e., does not contain JPEG image data / PNG image data), it indicates the image was corrupted during transmission or storage (common cause: the server mistakenly handles binary as UTF-8, and high bytes are replaced with U+FFFD). In this case, you must:

1. Delete the corrupted file:rm "$SAVE_PATH"
2. Re-execute the generation step (retry at most 2 times)
3. If all 3 attempts fail, report an error and inform the user that the image generation service is abnormal

Mode B: Edit an existing image (--update)

When the --update parameter is provided, edit based on the original image.

Step 1: Verify the original image (common)

# 验证原图文件存在且为有效图片
file "$UPDATE_PATH"  # 必须包含 "JPEG image data" 或 "PNG image data"

If the file does not exist or is not a valid image, report an error and terminate.

Use the Gemini SDK backend

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"

Parameter description:

• --desc: Edit instruction (e.g., "change the title to English")
• --sourcePath: Original image path (--update specified path)
• --savePath: Output image path (if not specified, overwrite the original image)
• --sourceLocale: Original image text language (default zh）
• --targetLocale: Target language (used in translation scenarios, e.g., en）
• --aspectRatio: Aspect ratio (default 4:3）

The script automatically handles translation scenarios (automatically enhances the prompt when sourceLocale ≠ targetLocale).

Use the AFS CLI backend

Step 2: Build the edit prompt

Important: Edit mode does not use the system prompt. The complete generative system prompt (color scheme, node rules, layout guidelines, etc.) would guide the model to recreate rather than edit. Edit mode only uses the template of "Image Editing Mode" in <skill-directory>/references/prompts.md .

Choose an appropriate prompt strategy based on the editing purpose:

Translation scenario(the goal is to translate the text in the image into another language):

1. First use the Read tool to view the original image and identify all text labels in the image
2. Build a source→translation mapping table (e.g., "用户认证" → "User Auth"）
3. Use the "Translation-Specific Template" in prompts.md and fill the mapping table into the prompt

General editing scenario(modify elements, adjust styles, etc.):

1. Use the "General Editing Template" in prompts.md
2. Fill the user's edit instruction into {desc}
3. If there is --context, fill in {documentContent}

Prompt length constraint: The total prompt length for edit mode should be kept within 500 words to avoid overly long instructions overriding the intent of "editing based on the original image".

Step 3: Call AFS CLI to edit the image

afs exec /aignehub/providers/google/gemini-3-pro-image-preview/.actions/generateImage \
  --prompt "$FULL_PROMPT" \
  --image "$UPDATE_PATH" \
  --json

Note: The prompt must explicitly require "refer to the passed-in image and return a new image", otherwise the model may only return text and not return an image.

Step 4: Parse the returned result and save the image

# 确定保存路径（若未指定 savePath，则覆盖原图）
FINAL_PATH="${SAVE_PATH:-$UPDATE_PATH}"

# 解析 URL 并下载
URL=$(echo "$JSON_RESULT" | jq -r '.data.images[0].url')
curl -sL "$URL" -o "$FINAL_PATH"

Validate the edit result (common to both backends)

ls -la "$FINAL_PATH"
file "$FINAL_PATH"  # 必须包含 "JPEG image data" 或 "PNG image data"

Key constraint: Same as Mode A; if the output file is not a valid image format, delete it and retry (up to 2 times).

Return result

Return the path of the generated image for the caller to use.

Integration with the doc-smith process

When the doc-smith main process detects an AFS Image Slot:

<!-- afs:image id="architecture" desc="系统架构图，展示各模块关系" -->

The main process calls this Skill to handle it. Backend detection is completed automatically within the Skill, and the caller does not need to care about backend selection.

Gemini SDK backend: The script directly calls the Gemini API to generate and save the image.

node <skill-directory>/scripts/generate.mjs \
  --mode=generate \
  --desc="$PROMPT" \
  --savePath="$OUTPUT_PATH" \
  --aspectRatio="4:3" \
  --locale="zh"

AFS CLI backend: After building the prompt, call the image generation service through the AFS CLI.

afs exec /aignehub/providers/google/gemini-3-pro-image-preview/.actions/generateImage \
  --prompt "$FULL_PROMPT" \
  --size "1024x768" \
  --json

Error handling

Gemini API Key not configured (when using the SDK backend)

错误: GEMINI_API_KEY 未配置。请设置环境变量后重试。

No available backend

错误: 未检测到可用的图片生成后端

当前状态:
- GEMINI_API_KEY: 未设置
- AFS CLI: 未安装 / 未挂载

请选择以下方案之一:
1. 设置 GEMINI_API_KEY 环境变量（推荐）
2. 安装 AFS CLI: npm install -g @aigne/afs-cli@beta
3. 跳过图片生成（将从文档中移除图片引用）

AFS CLI not installed (when using the AFS CLI backend)

错误: afs 命令未找到

请安装 AFS CLI:
npm install -g @aigne/afs-cli@beta

aignehub not mounted (when using the AFS CLI backend)

错误: /aignehub 路径不存在或未挂载

请在用户根目录下执行以下命令挂载 aignehub:
cd ~ && afs exec /.actions/mount --path /aignehub --uri aignehub://

挂载成功后会在 ~/.afs-config/config.toml 中写入配置。

Image generation failed

错误: 图片生成失败

可能原因:
1. prompt 描述不清晰
2. 网络连接问题
3. API 配额用尽
4. 后端服务异常

建议:
1. 优化 prompt 描述，更具体地说明图片内容
2. 检查网络连接
3. 稍后重试

Image download failed (when using the AFS CLI backend)

错误: 图片下载失败

请检查:
1. AFS CLI 返回的 URL 是否可访问
2. 网络连接是否正常
3. 保存路径是否有写入权限

Original image file is invalid (--update mode)

错误: 原图文件无效

指定的图片文件不存在或格式不正确。
请确认文件路径正确，且文件为有效的 PNG 或 JPEG 图片。

Edit returned an empty result (--update mode)

错误: 图片编辑返回空结果

后端返回的图片数据为空，可能原因:
1. 原图格式不被支持
2. 编辑请求被模型拒绝
3. Prompt 未明确要求返回图片，模型只返回了文字
4. 网络或服务端临时异常

建议:
1. 检查原图是否为标准 PNG/JPEG 格式
2. 确保 prompt 中包含"返回新的图片"等明确指令
3. 调整编辑描述后重试
4. 重试 1-2 次，排除临时异常