zhy-article-illustrator

Purpose

When to Use

• 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

• 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: Analyze the Article

1. Read the full content of

   article_path

2. Parse the article structure: title, chapter headings (

   ##

   /

   ###

   ), number of paragraphs, positions of code blocks
3. 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
4. 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
5. Determine the

   slug

   :
   • If the user provides

     slug

     : Use it directly
   • Otherwise, derive a

     kebab-case

     slug from the article's H1 title
6. Create the output directory:

   {article_dir}/illustrations/{slug}/

Step 2: Generate Visual Bible and Illustration Plan

1. First generate the article-level

   visual_bible

   and save it to

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

2. 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
3. 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
4. Save to

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

5. Simultaneously generate independent prompt files for each image, saved to

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

---
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

Step 3: Generate Images

visual_bible

1. 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
2. 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
3. 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
4. Save all prompts to the

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

   directory
5. Call the built-in script of this skill to generate images:
   • Script path:

     scripts/image-gen.ts

   • Parameters:

     --prompt "<prompt content>" --output "<output path>" --ar <aspect ratio>

   • Optional:

     --provider gemini|google|xiaomi|openai

   • Optional:

     --model <model name>

   • Optional:

     --base-url <Gemini native proxy base address>

   • Optional:

     --api-key <temporary key>

   • Optional:

     --image-size <clarity/size identifier>

     (e.g.,

     1K

     for Xiaomi)
   • Optional:

     --ref <reference image path>

     (for Gemini multimodal scenarios)
   • Parallel Generation: Maximum 4 concurrent tasks recommended
6. To complete planning + image generation + insertion back into the article in one click, directly call:
   bash

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

   • If using the Xiaomi Gemini compatible interface, add:

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

7. Failure Handling:
   • Single image generation failed -> Retry once, fine-tune layout, text density or prohibited items in the prompt if needed
   • Still failed -> Record to the failure list, proceed to the next image
   • Do not interrupt the overall process

Step 4: Upload to Image Hosting (Optional)

upload=true

1. Check Qiniu Cloud configuration: Read the

   .env

   file at the skill root directory
2. Call the upload script:
   bash

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

3. Remote key format:

   illustrations/{slug}/{filename}

4. Upload one by one, record the CDN URL of each image
5. If upload fails, retain the local path and do not interrupt the process

uploaded_urls

null

Step 5: Insert into Article Copy

1. Copy

   article_path

   to

   article.illustrated.md

   (same directory)
2. 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})

3. For images that failed to generate, insert a placeholder comment:
   markdown

   <!-- IMAGE PLACEHOLDER: {filename} — {purpose} -->

4. Output completion summary:

   • illustrated_article_path

   • Statistics of success / failure / upload
   • List of failed images and reasons

illustrated_article_path

Data Flow

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

IMAGE_PROVIDER

IMAGE_API_KEY

IMAGE_BASE_URL

GEMINI_API_KEY

IMAGE_PROVIDER=xiaomi

XIAOMI_API_KEY

XIAOMI_BASE_URL

XIAOMI_IMAGE_SIZE

.env

Example Usage

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

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

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

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

Notes

• 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