zhy-article-illustrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

zhy-article-illustrator

Purpose

为任意 Markdown 文章自动规划并生成配图。技能默认采用“高完成度编辑视觉”作为全局质量基线：不是简单插画，不是装饰图标拼贴，也不是低信息密度草图。系统会先为文章生成统一的 visual bible，再为每张图生成结构化提示词，使同一篇文章的配图共享统一风格语言，同时根据章节内容调整构图、信息重点和版式。

默认优先兼容 Gemini Nano Banana 工作流，并默认走 Xiaomi Gemini 兼容接口；同时支持 Gemini 原生代理 / 中转站模式与官方 Gemini 接口。

Automatically plan and generate illustrations for any Markdown article. This skill uses "high-polish editorial visuals" as the default global quality baseline: not simple illustrations, not decorative icon collages, nor low-information-density sketches. The system first generates a unified visual bible for the article, then creates structured prompts for each image, ensuring all illustrations in the same article share a consistent stylistic language, while adjusting composition, information focus, and layout based on chapter content.

It is prioritized to be compatible with the Gemini Nano Banana workflow by default, and uses the Xiaomi Gemini compatible interface by default; it also supports Gemini native proxy/relay mode and the official Gemini interface.

When to Use

用户请求“为文章配图”、“illustrate article”、“add images to article”

zhy-wechat-writing

技能的 Step 6 调用（

with_illustrations=true

）

用户希望生成更适合公众号场景的高完成度专题视觉
用户希望将本地图片上传到七牛云获取 CDN URL

User requests like "illustrate article", "add images to article"

Called in Step 6 of the

zhy-wechat-writing

skill (

with_illustrations=true

)

Users want to generate high-polish thematic visuals suitable for official account scenarios
Users want to upload local images to Qiniu Cloud to get CDN URLs

Prerequisites

文章 Markdown 文件已存在
已配置至少一种可用生图通道：
- Gemini 官方直连：
```
GEMINI_API_KEY
```
  或
```
GOOGLE_API_KEY
```
- Gemini 原生代理 / 中转站：
```
IMAGE_PROVIDER=gemini
```
  、
```
IMAGE_API_KEY
```
  、可选
```
IMAGE_BASE_URL
```
- Xiaomi Gemini 兼容接口：
```
IMAGE_PROVIDER=xiaomi
```
  或
```
XIAOMI_API_KEY
```
  ，可选
```
XIAOMI_BASE_URL
```
- 若启用上传：七牛云配置已就绪（技能根目录
```
.env
```
  中的
```
QINIU_ACCESS_KEY
```
  /
```
QINIU_SECRET_KEY
```
  /
```
QINIU_BUCKET
```
  /
```
QINIU_DOMAIN
```
  ）

The Markdown article file already exists
At least one available image generation channel is configured:
- Official Gemini direct connection:
```
GEMINI_API_KEY
```
  or
```
GOOGLE_API_KEY
```
- Gemini native proxy/relay:
```
IMAGE_PROVIDER=gemini
```
  ,
```
IMAGE_API_KEY
```
  , optional
```
IMAGE_BASE_URL
```
- Xiaomi Gemini compatible interface:
```
IMAGE_PROVIDER=xiaomi
```
  or
```
XIAOMI_API_KEY
```
  , optional
```
XIAOMI_BASE_URL
```
- If upload is enabled: Qiniu Cloud configuration is ready (
```
QINIU_ACCESS_KEY
```
  /
```
QINIU_SECRET_KEY
```
  /
```
QINIU_BUCKET
```
  /
```
QINIU_DOMAIN
```
  in the
```
.env
```
  file at the skill root directory)

Workflow

Step 1: 分析文章

Step 1: Analyze the Article

目标：理解文章结构，确定配图数量、位置与表达方式

操作：

读取
```
article_path
```
的完整内容
解析文章结构：标题、各章节标题（
```
##
```
/
```
###
```
）、段落数、代码块位置
识别核心信息点：
- 关键概念 / 术语解释 -> 适合信息图
- 对比 / 差异描述 -> 适合对比图
- 步骤 / 流程描述 -> 适合流程图
- 架构 / 框架描述 -> 适合架构图
- 数据 / 统计 -> 适合数据可视化
- 场景 / 叙事描述 -> 适合专题插画或编辑场景图
根据
```
density
```
确定配图策略：
- ```
minimal
```
  ：仅为最核心的 1-2 个信息点配图
- ```
balanced
```
  ：每个
```
##
```
  级主要章节配一张图
- ```
rich
```
  ：每 300 字左右或每个重要段落配一张图
确定
```
slug
```
：
- 若用户提供
```
slug
```
  ：直接使用
- 否则从文章 H1 标题推导
```
kebab-case
```
创建输出目录：
```
{article_dir}/illustrations/{slug}/
```

输出：文章结构分析结果、配图位置列表

Goal: Understand the article structure, determine the number, positions, and expression methods of illustrations

Operations:

Read the full content of
```
article_path
```
Parse the article structure: title, chapter headings (
```
##
```
/
```
###
```
), number of paragraphs, positions of code blocks
Identify core information points:
- Key concepts/term explanations -> suitable for infographics
- Comparison/difference descriptions -> suitable for comparison charts
- Step/process descriptions -> suitable for flowcharts
- Architecture/framework descriptions -> suitable for architecture diagrams
- Data/statistics -> suitable for data visualizations
- Scene/narrative descriptions -> suitable for thematic illustrations or editorial scene images
Determine the illustration strategy based on
```
density
```
:
- ```
minimal
```
  : Only add illustrations for 1-2 core information points
- ```
balanced
```
  : Add one illustration for each major chapter at
```
##
```
  level
- ```
rich
```
  : Add one illustration every ~300 words or for each important paragraph
Determine the
```
slug
```
:
- If the user provides
```
slug
```
  : Use it directly
- Otherwise, derive a
```
kebab-case
```
  slug from the article's H1 title
Create the output directory:
```
{article_dir}/illustrations/{slug}/
```

Output: Article structure analysis results, list of illustration positions

Step 2: 生成 visual bible 与配图规划

Step 2: Generate Visual Bible and Illustration Plan

目标：为整篇文章建立统一视觉基线，并生成每张图的规划信息

操作：

先生成文章级

visual_bible

，保存到

{article_dir}/illustrations/{slug}/visual-bible.md

```
visual_bible
```
必须覆盖：
- ```
quality_baseline
```
  ：统一采用高完成度编辑视觉 / 专题配图标准
- ```
visual_theme
```
  ：本篇文章的整体风格方向
- ```
color_system
```
  ：主色、辅色、强调色、背景倾向
- ```
graphic_language
```
  ：图形语言、线条/材质/光感、信息层级方式
- ```
layout_discipline
```
  ：页面留白、模块密度、标题区与内容区节奏
- ```
text_policy
```
  ：默认简体中文；仅
```
english_terms_whitelist
```
  中的术语保留英文
- ```
negative_rules
```
  ：禁止简单画图、低幼卡通、无意义装饰、英文乱码、随意混搭风格
再对每个配图位置生成 outline 条目，至少包含：
- ```
position
```
  ：插入位置（在哪个章节/段落之后）
- ```
purpose
```
  ：这张图要传达什么信息
- ```
image_type
```
  ：对比图 / 流程图 / 架构图 / 数据图 / 场景图 / 编辑专题视觉
- ```
core_message
```
  ：本图唯一核心表达
- ```
content_blocks
```
  ：画面中必须出现的内容块
- ```
text_blocks
```
  ：图中需要出现的标题、标签、注释（默认中文）
- ```
english_terms_used
```
  ：本图允许出现的英文术语子集
- ```
layout_hint
```
  ：布局方向与信息分区
- ```
filename
```
  ：输出文件名（格式：
```
NN-简短描述.png
```
  ）
- ```
alt_text
```
  ：Markdown 图片的 alt 文本

保存到

{article_dir}/illustrations/{slug}/outline.md

同时为每张图生成独立提示词文件，保存到
```
{article_dir}/illustrations/{slug}/prompts/
```

outline.md 格式：

yaml

---
article: <article_path>
slug: <slug>
density: <density>
aspect_ratio: <ratio>
prompt_profile: <profile>
text_language: <language>
image_provider: <provider>
image_model: <model>
image_count: <N>
generated_at: <ISO timestamp>
---

输出：

visual_bible_path

、

outline_path

Goal: Establish a unified visual baseline for the entire article, and generate planning information for each illustration

Operations:

First generate the article-level

visual_bible

and save it to

{article_dir}/illustrations/{slug}/visual-bible.md

The
```
visual_bible
```
must cover:
- ```
quality_baseline
```
  : Uniformly adopt high-polish editorial visual/thematic illustration standards
- ```
visual_theme
```
  : Overall style direction of this article
- ```
color_system
```
  : Primary color, secondary color, accent color, background tendency
- ```
graphic_language
```
  : Graphic style, lines/materials/lighting, information hierarchy methods
- ```
layout_discipline
```
  : Page white space, module density, rhythm between title area and content area
- ```
text_policy
```
  : Simplified Chinese by default; only terms in the
```
english_terms_whitelist
```
  retain English
- ```
negative_rules
```
  : Prohibit simple drawings, childish cartoons, meaningless decorations, garbled English, random style mixing
Then generate outline entries for each illustration position, which must include at least:
- ```
position
```
  : Insertion position (after which chapter/paragraph)
- ```
purpose
```
  : What information this image needs to convey
- ```
image_type
```
  : Comparison chart / Flowchart / Architecture diagram / Data visualization / Scene image / Editorial thematic visual
- ```
core_message
```
  : The unique core expression of this image
- ```
content_blocks
```
  : Content blocks that must appear in the frame
- ```
text_blocks
```
  : Titles, labels, annotations needed in the image (Simplified Chinese by default)
- ```
english_terms_used
```
  : Subset of English terms allowed in this image
- ```
layout_hint
```
  : Layout direction and information partitioning
- ```
filename
```
  : Output filename (format:
```
NN-brief-description.png
```
  )
- ```
alt_text
```
  : Alt text for Markdown images

Save to

{article_dir}/illustrations/{slug}/outline.md

Simultaneously generate independent prompt files for each image, saved to
```
{article_dir}/illustrations/{slug}/prompts/
```

outline.md Format:

yaml

---
article: <article_path>
slug: <slug>
density: <density>
aspect_ratio: <ratio>
prompt_profile: <profile>
text_language: <language>
image_provider: <provider>
image_model: <model>
image_count: <N>
generated_at: <ISO timestamp>
---

Output:

visual_bible_path

outline_path

Step 3: 生成图片

Step 3: Generate Images

目标：根据

visual_bible

+ outline 生成高质量图片文件

操作：

为每张图构建结构化提示词，提示词必须同时继承：
- 全局质量基线：高完成度编辑视觉，而非简单画图
- 文章级
```
visual_bible
```
- 单图内容规划
提示词必须包含以下层次：
- ```
任务定位
```
  ：这是可直接用于公众号文章的成品级专题视觉
- ```
风格锚点
```
  ：复用本篇文章统一视觉语言
- ```
画面主体
```
  ：核心对象、信息模块、前中后景关系
- ```
版式结构
```
  ：标题区、内容区、对比区、流程区、数据区的组织方式
- ```
信息层级
```
  ：主标题、次要标签、补充说明的优先级
- ```
文字规则
```
  ：默认所有可见文字使用简体中文；仅白名单术语保留英文
- ```
质量要求
```
  ：丰富细节、清晰层级、强版式感、避免模板感
- ```
禁止项
```
  ：低幼、空泛、装饰性过强、无意义图标堆砌、英文乱码
对 Nano Banana / Gemini 类模型，优先优化以下特性：
- 画面信息完整、指令明确、元素具体
- 文本展示尽量短而准，避免大段说明文字
- 同一篇文章的每张图共享统一色系、统一图形语言、统一完成度
- 图片更像编辑专题视觉，而不是普通插图

将所有提示词保存到

{article_dir}/illustrations/{slug}/prompts/

调用本技能内置脚本生成图片：

脚本路径：
```
scripts/image-gen.ts
```

参数：

--prompt "<提示词内容>" --output "<输出路径>" --ar <宽高比>

可选：
```
--provider gemini|google|xiaomi|openai
```
可选：
```
--model <模型名>
```

可选：

--base-url <Gemini 原生代理基础地址>

可选：
```
--api-key <临时 key>
```
可选：
```
--image-size <清晰度/尺寸标识>
```
（如 Xiaomi 的
```
1K
```
）
可选：
```
--ref <参考图路径>
```
（Gemini 多模态场景）
并行生成：建议最多 4 个并发

若需要一键完成规划 + 生图 + 插回文章，可直接调用：

bash

node scripts/illustrate-article.ts --article <article.md>

若使用 Xiaomi Gemini 兼容接口，可补充：

--image-provider xiaomi --image-model gemini-3-pro-image-preview --image-size 1K

失败处理：
- 单张失败 -> 重试一次，可微调提示词中的布局、文字密度或禁止项
- 仍失败 -> 记录到失败列表，继续下一张
- 不中断整体流程

输出：图片文件列表、失败列表

Goal: Generate high-quality image files based on

visual_bible

+ outline

Operations:

Construct structured prompts for each image, which must inherit:
- Global quality baseline: High-polish editorial visuals, not simple drawings
- Article-level
```
visual_bible
```
- Single-image content plan
The prompt must include the following layers:
- ```
Task Positioning
```
  : This is a finished thematic visual directly usable in official account articles
- ```
Style Anchor
```
  : Reuse the unified visual language of this article
- ```
Main Subject
```
  : Core objects, information modules, foreground-middle-ground-background relationships
- ```
Layout Structure
```
  : Organization method of title area, content area, comparison area, process area, data area
- ```
Information Hierarchy
```
  : Priority of main title, secondary labels, supplementary explanations
- ```
Text Rules
```
  : All visible text uses Simplified Chinese by default; only whitelisted terms retain English
- ```
Quality Requirements
```
  : Rich details, clear hierarchy, strong layout sense, avoid template-like effects
- ```
Prohibited Items
```
  : Childish style, vague content, overly decorative, meaningless icon stacking, garbled English
For Nano Banana / Gemini-like models, prioritize optimizing the following features:
- Complete frame information, clear instructions, specific elements
- Text display should be as short and accurate as possible, avoid long paragraphs of explanatory text
- All images in the same article share the same color system, graphic language, and polish level
- Images should look like editorial thematic visuals rather than ordinary illustrations

Save all prompts to the

{article_dir}/illustrations/{slug}/prompts/

Step 4: 上传图床（可选）

Step 4: Upload to Image Hosting (Optional)

触发条件：

upload=true

目标：将生成的图片上传到七牛云，获取 CDN URL

操作：

检查七牛云配置：读取技能根目录
```
.env
```

调用上传脚本：

bash

bun run scripts/qiniu-upload.ts --file <本地路径> --key <远程路径>

远程 key 格式：
```
illustrations/{slug}/{filename}
```
逐张上传，记录每张的 CDN URL
上传失败时保留本地路径，不中断流程

输出：

uploaded_urls

列表（CDN URL 或

null

）

Trigger Condition:

upload=true

Goal: Upload generated images to Qiniu Cloud to obtain CDN URLs

Operations:

Check Qiniu Cloud configuration: Read the
```
.env
```
file at the skill root directory

Call the upload script:

bash

bun run scripts/qiniu-upload.ts --file <local path> --key <remote path>

Remote key format:
```
illustrations/{slug}/{filename}
```
Upload one by one, record the CDN URL of each image
If upload fails, retain the local path and do not interrupt the process

Output:

uploaded_urls

list (CDN URL or

null

)

Step 5: 插入文章副本

Step 5: Insert into Article Copy

目标：创建带有图片引用的文章副本

操作：

复制
```
article_path
```
为
```
article.illustrated.md
```
（同目录）
在 outline 指定的每个位置插入图片引用：
- 若已上传（有 CDN URL）：
```
![alt_text](CDN_URL)
```
- 若未上传：
```
![alt_text](illustrations/{slug}/{filename})
```
对生成失败的图片，插入占位注释：
markdown
```

```
输出完成摘要：
- ```
illustrated_article_path
```
- 成功 / 失败 / 上传统计
- 失败图片列表及原因

输出：

illustrated_article_path

Goal: Create an article copy with image references

Operations:

Copy
```
article_path
```
to
```
article.illustrated.md
```
(same directory)
Insert image references at each position specified in the outline:
- If uploaded (has CDN URL):
```
![alt_text](CDN_URL)
```
- If not uploaded:
```
![alt_text](illustrations/{slug}/{filename})
```
For images that failed to generate, insert a placeholder comment:
markdown
```

```
Output completion summary:
- ```
illustrated_article_path
```
- Statistics of success / failure / upload
- List of failed images and reasons

Output:

illustrated_article_path

Data Flow

text

article.md
    |
    v
Step 1: 分析文章结构 -> 配图位置列表
    |
    v
Step 2: 生成 visual-bible.md + outline.md
    |
    v
Step 3: 生成结构化 prompts -> illustrations/{slug}/*.png
    |
    v
Step 4: (--upload) 上传七牛云 -> CDN URLs
    |
    v
Step 5: 插入副本 -> article.illustrated.md

text

article.md
    |
    v
Step 1: Analyze article structure -> List of illustration positions
    |
    v
Step 2: Generate visual-bible.md + outline.md
    |
    v
Step 3: Generate structured prompts -> illustrations/{slug}/*.png
    |
    v
Step 4: (--upload) Upload to Qiniu Cloud -> CDN URLs
    |
    v
Step 5: Insert into copy -> article.illustrated.md

Error Handling

失败场景	处理方式
文章文件不存在	立即报错退出
Gemini / 代理配置缺失	提示用户配置 `IMAGE_PROVIDER` 、 `IMAGE_API_KEY` 、可选 `IMAGE_BASE_URL` ，或回退到官方 `GEMINI_API_KEY`
Xiaomi 接口配置缺失	提示用户配置 `IMAGE_PROVIDER=xiaomi` 或 `XIAOMI_API_KEY` ，并按需设置 `XIAOMI_BASE_URL` / `XIAOMI_IMAGE_SIZE`
单张图片生成失败	重试一次；仍失败记录跳过，继续下一张
文字过多导致效果差	精简标题/标签/注释长度后重试
七牛云配置缺失	提示用户配置技能根目录 `.env` ，跳过上传步骤
七牛云上传失败	保留本地路径，记录错误，继续下一张
slug 目录已存在	直接使用（覆盖同名文件）

Failure Scenario	Handling Method
Article file does not exist	Report error and exit immediately
Gemini / proxy configuration missing	Prompt the user to configure `IMAGE_PROVIDER` , `IMAGE_API_KEY` , optional `IMAGE_BASE_URL` , or fall back to the official `GEMINI_API_KEY`
Xiaomi interface configuration missing	Prompt the user to configure `IMAGE_PROVIDER=xiaomi` or `XIAOMI_API_KEY` , and set `XIAOMI_BASE_URL` / `XIAOMI_IMAGE_SIZE` as needed
Single image generation failed	Retry once; if still failed, record and skip, proceed to the next one
Poor effect due to excessive text	Retry after simplifying the length of titles/labels/annotations
Qiniu Cloud configuration missing	Prompt the user to configure the `.env` file at the skill root directory, skip the upload step
Qiniu Cloud upload failed	Retain local path, record error, proceed to the next image
Slug directory already exists	Use it directly (overwrite files with the same name)

Example Usage

默认 Nano Banana 风格配图：

yaml

article_path: articles/playwright-introduction/article.md
density: balanced
prompt_profile: nano-banana
text_language: zh-CN
image_provider: xiaomi
image_model: gemini-3.1-flash-image-preview
image_base_url: https://your-compatible-endpoint.example/v1beta
image_size: 1K
upload: false

通过 Gemini 原生代理生图：

yaml

article_path: articles/playwright-introduction/article.md
density: balanced
image_provider: gemini
image_model: gemini-3.1-flash-image-preview
image_base_url: https://your-relay.example.com/v1beta
upload: false

通过 Xiaomi Gemini 兼容接口生图：

yaml

article_path: articles/playwright-introduction/article.md
density: balanced
image_provider: xiaomi
image_model: gemini-3.1-flash-image-preview
image_base_url: https://your-compatible-endpoint.example/v1beta
image_size: 1K
upload: false

指定英文白名单术语：

yaml

article_path: articles/playwright-introduction/article.md
english_terms_whitelist:
  - Playwright
  - Chromium
  - Firefox
  - WebKit

Default Nano Banana style illustrations:

yaml

article_path: articles/playwright-introduction/article.md
density: balanced
prompt_profile: nano-banana
text_language: zh-CN
image_provider: xiaomi
image_model: gemini-3.1-flash-image-preview
image_base_url: https://your-compatible-endpoint.example/v1beta
image_size: 1K
upload: false

Generate images via Gemini native proxy:

yaml

article_path: articles/playwright-introduction/article.md
density: balanced
image_provider: gemini
image_model: gemini-3.1-flash-image-preview
image_base_url: https://your-relay.example.com/v1beta
upload: false

Generate images via Xiaomi Gemini compatible interface:

yaml

article_path: articles/playwright-introduction/article.md
density: balanced
image_provider: xiaomi
image_model: gemini-3.1-flash-image-preview
image_base_url: https://your-compatible-endpoint.example/v1beta
image_size: 1K
upload: false

Specify English whitelist terms:

yaml

article_path: articles/playwright-introduction/article.md
english_terms_whitelist:
  - Playwright
  - Chromium
  - Firefox
  - WebKit

Notes

全局质量基线固定为高完成度编辑视觉，不生成简单装饰图
不同文章可以有不同视觉风格，但同一篇文章内必须共享统一风格体系
默认所有可见文字使用简体中文；仅白名单术语保留英文
始终创建副本（
```
article.illustrated.md
```
），不修改原文
图片引用强制使用相对路径和
```
/
```
分隔符（本地模式）
提示词保存到
```
prompts/
```
目录，便于追溯和手动调整后重新生成

可使用

bun run scripts/plan-illustrations.ts --article <article.md>

自动生成

visual-bible.md

、

outline.md

和

prompts/

可使用

node scripts/illustrate-article.ts --article <article.md>

一键完成规划、出图和

article.illustrated.md

生成

Xiaomi/Gemini 兼容接口可通过
```
image_provider=xiaomi
```
与自定义
```
image_base_url
```
配置；开源仓库不预设任何私有中转地址

The global quality baseline is fixed as high-polish editorial visuals, no simple decorative images are generated
Different articles can have different visual styles, but the same article must share a unified style system
All visible text uses Simplified Chinese by default; only whitelisted terms retain English
Always create a copy (
```
article.illustrated.md
```
), do not modify the original article
Image references force the use of relative paths and
```
/
```
separators (local mode)
Prompts are saved to the
```
prompts/
```
directory for easy tracing and re-generation after manual adjustment

You can use

bun run scripts/plan-illustrations.ts --article <article.md>

to automatically generate

visual-bible.md

outline.md

and

prompts/

You can use

node scripts/illustrate-article.ts --article <article.md>

to complete planning, image generation and

article.illustrated.md

generation in one click

Xiaomi/Gemini compatible interfaces can be configured via
```
image_provider=xiaomi
```
and custom
```
image_base_url
```
; the open-source repository does not preset any private relay addresses