SuperAPI AI Directory
Partner中文AI newsFavorites
Skillszhy-article-illustrator

zhy-article-illustrator

Design & creation

View repository

Updated 10-16 01:31

About this skill

zhy-article-illustrator

Purpose

Automatically plan and generate illustrations for any Markdown article. By default, the skill uses "high-completion editorial visuals" as the global quality baseline: not simple illustrations, not decorative icon collages, and not low-information-density sketches. The system first generates a unified visual bible for the article, then generates structured prompts for each image, so that illustrations for the same article share a unified style language while adjusting composition, information focus, and layout according to section content.

By default, prioritize compatibility with the Gemini Nano Banana workflow, and by default use the Xiaomi Gemini compatible interface; it also supports Gemini native proxy / relay station mode and the official Gemini interface.

When to Use

  • User requests "illustrate article", "illustrate article", "add images to article"
  • zhy-wechat-writing Step 6 call of the skill (with_illustrations=true）
  • The user wants to generate high-completion feature visuals more suitable for WeChat Official Account scenarios
  • The user wants to upload local images to Qiniu Cloud to obtain a CDN URL

Prerequisites

  • The article Markdown file already exists
  • At least one available image generation channel has been configured:
    • Official Gemini direct connection:GEMINI_API_KEY or GOOGLE_API_KEY
    • Gemini native proxy / relay station: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 (skill root directory .env in the QINIU_ACCESS_KEY / QINIU_SECRET_KEY / QINIU_BUCKET / QINIU_DOMAIN）

Workflow

Step 1: Analyze the article

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

Operations：

  1. Read article_path the complete content
  2. Parse the article structure: title, section headings (## / ###), paragraph count, code block positions
  3. Identify core information points:
    • Key concepts / terminology explanations -> suitable for infographics
    • Comparisons / difference descriptions -> suitable for comparison charts
    • Steps / process descriptions -> suitable for flowcharts
    • Architecture / framework descriptions -> suitable for architecture diagrams
    • Data / statistics -> suitable for data visualization
    • Scenarios / narrative descriptions -> suitable for feature illustrations or editorial scene images
  4. Based on density determine the illustration strategy:
    • minimal: Illustrate only the 1-2 most core information points
    • balanced: One image per ## level main section
    • rich: One image about every 300 words or for each important paragraph
  5. Determine slug：
    • If the user provides slug: use directly
    • Otherwise derive from the article H1 title kebab-case
  6. Create output directory:{article_dir}/illustrations/{slug}/

Output: Article structure analysis results, list of illustration positions

Step 2: Generate visual bible and illustration plan

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

Operations：

  1. First generate the article-level visual_bible, save to {article_dir}/illustrations/{slug}/visual-bible.md
  2. visual_bible must cover:
    • quality_baseline: uniformly adopt high-completion editorial visual / feature illustration standards
    • visual_theme: the overall style direction of this article
    • color_system: primary color, secondary color, accent color, background tendency
    • graphic_language: graphic language, lines/materials/light perception, information hierarchy method
    • layout_discipline：Page whitespace, module density, rhythm between the title area and content area
    • text_policy：Default Simplified Chinese; only english_terms_whitelist terms in retain English
    • negative_rules：No simple drawings, childish cartoons, meaningless decorations, garbled English, or random mixed styles
  3. Then generate an outline entry for each illustration position, including at least:
    • position：Insertion position (after which chapter/paragraph)
    • purpose：What information this image should convey
    • image_type：Comparison diagram / flowchart / architecture diagram / data chart / scene image / editorial feature visual
    • core_message：The single core expression of this image
    • content_blocks：Content blocks that must appear in the image
    • text_blocks：Titles, labels, and annotations that need to appear in the image (Simplified Chinese by default)
    • english_terms_used：The subset of English terms allowed to appear in this image
    • layout_hint：Layout direction and information zoning
    • filename：Output file name (format:NN-简短描述.png）
    • alt_text：Alt text for the Markdown image
  4. Save to {article_dir}/illustrations/{slug}/outline.md
  5. At the same time, generate an independent prompt file for each image, save to {article_dir}/illustrations/{slug}/prompts/

outline.md format：

---
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: Generate images

Goal：Based on visual_bible + outline, generate high-quality image files

Operations：

  1. Build a structured prompt for each image; the prompt must simultaneously inherit:
    • Global quality baseline: high-completion editorial visuals, not simple drawings
    • Article-level visual_bible
    • Single-image content planning
  2. The prompt must include the following layers:
    • 任务定位：This is a finished, production-grade feature visual that can be used directly in a WeChat official account article
    • 风格锚点：Reuse the unified visual language of this article
    • 画面主体：Core objects, information modules, foreground/midground/background relationships
    • 版式结构：How the title area, content area, comparison area, process area, and data area are organized
    • 信息层级：Priority of the main title, secondary labels, and supplementary explanations
    • 文字规则：By default, all visible text uses Simplified Chinese; only whitelisted terms retain English
    • 质量要求：Rich details, clear hierarchy, strong layout feel, avoid template feel
    • 禁止项：Childish, vague, overly decorative, meaningless icon stacking, garbled English
  3. For Nano Banana / Gemini-type models, prioritize optimizing the following characteristics:
    • Complete image information, clear instructions, specific elements
    • Keep text display as short and accurate as possible; avoid long explanatory text
    • Every image in the same article shares a unified color palette, unified graphic language, and unified level of completion
    • Images should feel more like editorial feature visuals, not ordinary illustrations
  4. Save all prompts to {article_dir}/illustrations/{slug}/prompts/ directory
  5. Call this skill's built-in script to generate images:
    • Script path:scripts/image-gen.ts
    • Parameters:--prompt "<提示词内容>" --output "<输出路径>" --ar <宽高比>
    • Optional:--provider gemini|google|xiaomi|openai
    • Optional:--model <模型名>
    • Optional:--base-url <Gemini 原生代理基础地址>
    • Optional:--api-key <临时 key>
    • Optional:--image-size <清晰度/尺寸标识>(such as Xiaomi's 1K）
    • Optional:--ref <参考图路径>(Gemini multimodal scenario)
    • Parallel generation：A maximum of 4 concurrent tasks is recommended
  6. If you need one-click completion of planning + image generation + insertion back into the article, you can directly call: 
    node scripts/illustrate-article.ts --article <article.md>
    • If using the Xiaomi Gemini compatible interface, you may add:--image-provider xiaomi --image-model gemini-3-pro-image-preview --image-size 1K
  7. Failure handling:
    • Single failure -> retry once, you may fine-tune the layout, text density, or prohibited items in the prompt
    • Still failing -> record in the failure list, continue to the next image
    • Do not interrupt the overall process

Output: list of image files, failure list

Step 4: Upload to image hosting (optional)

Trigger condition：upload=true

Goal: upload the generated images to Qiniu Cloud and obtain CDN URLs

Operations：

  1. Check the Qiniu Cloud configuration: read the skill root directory .env
  2. Call the upload script: 
    bun run scripts/qiniu-upload.ts --file <本地路径> --key <远程路径>
  3. Remote key format:illustrations/{slug}/{filename}
  4. Upload one by one, recording the CDN URL of each
  5. If upload fails, keep the local path and do not interrupt the process

Output：uploaded_urls list (CDN URL or null）

Step 5: Insert into article copy

Goal: create an article copy with image references

Operations：

  1. Copy article_path to article.illustrated.md(same directory)
  2. Insert an image reference at each position specified by the outline:
    • If already uploaded (has CDN URL):![alt_text](CDN_URL)
    • If not uploaded:![alt_text](illustrations/{slug}/{filename})
  3. For images that failed to generate, insert a placeholder comment: 
    <!-- IMAGE PLACEHOLDER: {filename} — {purpose} -->
  4. Output completion summary:
    • illustrated_article_path
    • Success / failure / upload statistics
    • List of failed images and reasons

Output：illustrated_article_path

Data Flow

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

Error Handling

Failure scenario Handling method
Article file does not exist Immediately error out and exit
Gemini / proxy configuration missing Prompt the user to configure IMAGE_PROVIDER、IMAGE_API_KEY, optionally 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 as needed XIAOMI_BASE_URL / XIAOMI_IMAGE_SIZE
Single image generation failed Retry once; if it still fails, record and skip, continue to the next image
Poor results due to too much text Shorten the title/label/annotation length and retry
Qiniu Cloud configuration missing Prompt the user to configure the skill root directory .env, skip the upload step
Qiniu Cloud upload failed Keep the local path, record the error, continue to the next image
slug directory already exists Use directly (overwrite files with the same name)

Example Usage

Default Nano Banana style illustrations：

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 the Gemini native proxy：

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 the Xiaomi Gemini compatible interface：

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 the English whitelist terms：

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

Notes

  • The global quality baseline is fixed at highly polished editorial visuals; do not generate simple decorative images
  • Different articles may have different visual styles, but the same article must share a unified style system
  • By default, all visible text uses Simplified Chinese; only whitelist terms remain in English
  • Always create a copy (article.illustrated.md), do not modify the original text
  • Image references must use relative paths and the / separator (local mode)
  • Save the prompt to prompts/ Table of contents, for easy tracing and regeneration after manual adjustments
  • 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
  • The Xiaomi/Gemini compatible interface can be configured through image_provider=xiaomi and custom image_base_url configuration; the open-source repository does not preset any private relay address