A document illustration generation tool based on AI intelligent analysis. Global planning, parallel generation, and asynchronous insertion efficiently add illustrations to documents.
Core workflow (5 steps)
备份 → 全局规划插入点 → 并行生成图片 → 异步插入原文 → 清理备份
Step 0: Back up the original file
Create a backup before making changes to ensure safe rollback:
import shutil
backup_path = f"{doc_path}.illustrator-backup"
shutil.copy2(doc_path, backup_path)
All subsequent operations are performed directly on the original file.
Step 1: Determine all insertion positions globally
Read the complete document and plan the insertion positions for all images at once:
- Use the Read tool to read the complete document
- AI analyzes the content structure and identifies core themes
- Determine for each themeprecise insertion anchors(line number + context text)
- Output an insertion plan table:
插入计划：
[1] 行 15 后 | 锚点: "## Rules 的诞生" | 主题: Rules 演化历程
[2] 行 42 后 | 锚点: "## Commands 打包" | 主题: 工作流打包
[3] 行 78 后 | 锚点: "## MCP 动态能力" | 主题: 第三方集成
...
[cover] 行 1 前 | 封面图 | 主题: 全文概要
Key: Insertion anchors use context text (rather than pure line numbers), so that even if earlier insertions cause line number shifts, subsequent insertions can still be located via the anchors.
Step 2: Generate all images in parallel
Use the Agent tool to launch all image generation subtasks in parallel:
对每个插入计划项，同时启动一个 Agent：
Agent 1: generate_single_image.py --title "..." --content "..." --output images/illustration-01.png
Agent 2: generate_single_image.py --title "..." --content "..." --output images/illustration-02.png
Agent 3: generate_single_image.py --title "..." --content "..." --output images/illustration-03.png
...
- All Agents execute concurrently without waiting for each other
- Each Agent returns the image path or an error message when finished
- Expected total time = time for a single image (10-20s), rather than N * time for a single image
Step 3: Insert into the original text asynchronously
Insert immediately after each Agent finishes, without waiting for other Agents:
- Agent finishes → obtain the image path
- In the original document,via the anchor text,locate the insertion position (without relying on line numbers)
- Use the Edit tool to insert a Markdown image reference after the anchor:
 - Insertion uses anchor text matching, so earlier insertions do not affect later positioning
Handling position shifts：
- Each insertion increases the number of lines in the document
- Use anchor text (such as
## Rules 的诞生) rather than line numbers for positioning - Inserting from the end of the document toward the beginning can also avoid position shift issues
Step 4: Verify and clean up
After all images have been inserted:
- Verify: Check that all planned
![...]()references in the original document have been inserted - Verify: Check that all image files exist in the
images/directory - Success → Delete the backup file
{doc_path}.illustrator-backup - Failure → Keep the backup file and report which images failed to generate/insert, so the user can restore from the backup
完成: 6/6 张配图已插入原文档
已清理备份文件
Configuration options
Before execution, Claude will ask (or infer from the user's message):
| Option | Value | Default |
|---|---|---|
| Image aspect ratio | 16:9 / 3:4 | 16:9 |
| Whether it is a cover image | Yes/No | No |
| Number of content illustrations | 3-10 | Recommended based on document length |
| Style | gradient-glass / ticket / vector-illustration | gradient-glass |
If the user has already specified it in the request (e.g., "portrait, ticket style, 8 images"), use it directly and do not ask again.
Style Quick Reference
| Style | Keywords | Suitable for |
|---|---|---|
| gradient-glass | Glassmorphism, aurora gradient, tech feel | Technical documentation, product introductions |
| ticket | Black-and-white contrast, ticket structure, minimalist | Data reports, infographics |
| vector-illustration | Flat illustration, retro color palette, geometric | Tutorials, stories, branding |
Style files are located in the styles/ directory.
Technical Details
| Item | Value |
|---|---|
| API Model | Gemini 2.0 Flash Image Preview |
| 16:9 Resolution | 2560x1440 (2K) / 3840x2160 (4K) |
| 3:4 Resolution | 1920x2560 (2K) / 2880x3840 (4K) |
| Time per image | ~10-20s |
| Parallel time | ~10-20s (total, not multiplied by N) |
| Dependencies | pip install google-genai pillow python-dotenv |
| API Key | .env in GEMINI_API_KEY or environment variables |
Scripts
scripts/generate_single_image.py— single image generation (for Agent parallel calls)scripts/generate_illustrations.py— legacy batch sequential generation (retained for compatibility)