---
name: article-illustrations
description: 分析中文文章结构、识别需要配图的位置,用 Type × Style × Palette 三维方式生成图文插图;支持用作者本人的 Q 版卡通形象(avatar-base)作为出镜角色。当用户说"为文章配图""文章插图""图文介绍""给这篇待发布文章配图""生成配图"时触发。
version: 1.0.0
metadata:
  origin: 基于 JimLiu/baoyu-skills 的 baoyu-article-illustrator 改造,图像后端替换为 Agnes agnes-image-2.0-flash,并接入个人形象 IP。
---

# Article Illustrator

Analyze articles, identify illustration positions, generate images with Type × Style × Palette consistency.

## User Input Tools

When this skill prompts the user, follow this tool-selection rule (priority order):

1. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
2. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
3. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.

Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.

## Image Generation Tools(默认 favorais gpt-image-2)

本 skill 的图像后端**默认走 favorais 中转站的 gpt-image-2**（2026-09-21 起替代火山方舟，原因：火山太贵）。统一调用脚本:

```bash
# 默认:favorais gpt-image-2(推荐)
python ~/.claude/skills/article-illustrations/scripts/volces_image.py \
  --prompt "<prompt 内容>" --size "<W x H>" --out "<输出路径>.png"

# 备选:Agnes(英文模型,仅在默认通道不可用时用)
python ~/.claude/skills/article-illustrations/scripts/agnes_image.py \
  --prompt "<prompt 内容>" --size "<W x H>" --out "<输出路径>.png"
```

- **API key**:favorais 读 `FAVORAIS_API_KEY`(env 或 `~/.claude/skills/.env`),脚本内置兜底 key;Agnes 读 `AGNES_API_KEY`。
- **默认模型**:`gpt-image-2`,endpoint `https://api.favorais.com/v1/images/generations`。
- **尺寸**:gpt-image 只支持 `1024x1024` / `1536x1024` / `1024x1536` / `auto`;横版 16:9 用 `1536x1024`,竖版用 `1024x1536`,方图 `1024x1024`。
- **prompt 来源**:必须先按「Prompt file requirement」把每张图的完整 prompt 落盘到 `prompts/NN-{type}-{slug}.md`,再把内容传给 `--prompt`。不允许跳过落盘直接内联。
- **批量**:多张图按 Batch Generation Policy 并行调用脚本(默认 ≤4 并发),失败重试一次。

**⛔ 禁止用 SVG / HTML / Canvas 冒充位图。** 找不到可用通道(key 缺失/脚本报错)时,停下来告诉用户,不要用代码渲染替代。

**⛔ 禁止用代码涂抹修补已生成图上的文字**(ImageMagick/Pillow/Canvas/OCR 覆盖)。文字错了就用修正后的 prompt 重新生成,或减少图内文字重画。

**prompt 语言与图内文字约定(按后端区分):**

| 后端 | prompt 语言 | 图内文字 |
|------|------------|----------|
| **gpt-image-2(默认)** | 中文/英文均可,中文更顺 | 仍建议**少字**;标题说明放图下方 markdown 正文,图上最多 2-4 个短标签 |
| Agnes(备选) | **必须英文** | **图内零文字**(写中文必乱码、英文也常错字) |

**Prompt file requirement (hard)**: write each image's full, final prompt to a standalone file under `prompts/` (naming: `NN-{type}-[slug].md`) BEFORE invoking any backend. The backend receives the prompt file (or its content); the file is the reproducibility record and lets you switch backends without regenerating prompts.

## 个人形象 IP(作者 Q 版角色)

本 skill 可选地把**作者本人的 Q 版卡通形象**作为插图里的出镜角色,让文章有统一的人格化记忆点。

- **定稿底片**:`E:/Obsidian/06 - 长期记忆库/assets/avatar/avatar-base.png`(白底铅笔手绘 Q 版,细黑框眼镜/寸头/浓眉/椭圆脸/黑卫衣/松弛微笑)。
- **形象约束**:`E:/Obsidian/06 - 长期记忆库/assets/avatar/my-avatar-dna.md`(固定特征 + 风格禁忌)。生成角色图前必读,关键特征(尤其眼镜、椭圆脸)不可漂移。

**何时用形象 vs 何时用纯信息图:**

| 插图性质 | 用哪个 | 调用方式 |
|----------|--------|----------|
| 叙事/拟人化/需要"人"出镜(场景、流程中的操作者、隐喻主角) | **个人形象** | 图生图:加 `--ref avatar-base.png`,prompt 描述该角色正在做的动作 |
| 结构/数据/纯图解(信息图、对比表、框架、金字塔、漏斗) | **纯信息图** | 文生图:不加 `--ref`,按 Type×Style×Palette 出图 |

**形象一致性硬规则:**
1. 角色图一律以 `avatar-base.png` 为参考图(`--ref`),不要纯文字凭空画脸。
2. 一张图里角色只承担一个核心动作,不能是装饰。
3. 形象图与信息图共用同一套调色板和"白底手绘"基调,保证整篇文章视觉统一。

**⛔ prompt 文件 frontmatter 硬规则(防止漏加 ref):**
- `type: scene` → **必须** `ref: avatar-base`,不得省略或写 `none`
- `type: comparison` 且画面含人物角色 → 同样 **必须** `ref: avatar-base`
- `type: flowchart / framework / infographic` → `ref: none`(纯结构图不出人物)
- ref 值统一写 `avatar-base`(不带 `.png` 后缀),脚本会自动匹配到底片文件

## Batch Generation Policy

After every prompt file for the run has been saved and verified, generate images in batches by default.

Priority order:

1. Use the chosen backend's native batch / multi-task interface if it exists. Each task must keep its own prompt file, output path, aspect ratio, and direct reference images.
2. If no native batch interface exists but the runtime can issue parallel tool calls, dispatch up to `generation_batch_size` images at a time. Default: `4`. An explicit user request in the current message, such as `--batch-size 4` or "并行4张一起生成", overrides EXTEND.md.
3. If neither native batch nor parallel tool calls are available, generate sequentially.

Rules:

- Never start the first batch until all prompt files for that batch exist on disk.
- Retry failed items once without regenerating successful items.
- Do not use subagents merely to parallelize image rendering. Use subagents only for separate prompt iteration or creative exploration.

## Confirmation Policy

Default behavior: **confirm before generation**.

- Treat explicit skill invocation, a file path, matched signals/presets, and `EXTEND.md` defaults as **recommendation inputs only**. None of them authorizes skipping confirmation.
- Do **not** start Step 4 or later until the user completes Step 3.
- Skip confirmation only when the current request explicitly says to do so, for example: "直接生成", "不用确认", "跳过确认", "按默认出图", or equivalent wording.
- If confirmation is skipped explicitly, state the assumed type / density / style / palette / language / backend in the next user-facing update before generating.

## Reference Images

Users may supply reference images via `--ref <files...>` or by providing file paths / pasting images in conversation. Refs guide style, palette, composition, or subject for specific illustrations.

Full detection, storage, and processing rules are in [references/workflow.md](references/workflow.md) (Step 1.0 saves to `references/NN-ref-{slug}.{ext}`; Step 5.3 processes per-illustration usage `direct | style | palette`). 参考图通过脚本的 `--ref <文件>` 传入(可多个 `--ref`,是否生效取决于中转站),角色图固定传 `assets/avatar/avatar-base.png`。

## Three Dimensions

| Dimension | Controls | Examples |
|-----------|----------|----------|
| **Type** | Information structure | infographic, scene, flowchart, comparison, framework, timeline |
| **Style** | Rendering approach | notion, warm, minimal, blueprint, watercolor, elegant |
| **Palette** | Color scheme (optional) | macaron, warm, neon — overrides style's default colors |

Combine freely: `--type infographic --style vector-illustration --palette macaron`

Or use presets: `--preset edu-visual` → type + style + palette in one flag. See [Style Presets](references/style-presets.md).

## Types

| Type | Best For |
|------|----------|
| `infographic` | Data, metrics, technical |
| `scene` | Narratives, emotional |
| `flowchart` | Processes, workflows |
| `comparison` | Side-by-side, options |
| `framework` | Models, architecture |
| `timeline` | History, evolution |

## Styles

See [references/styles.md](references/styles.md) for Core Styles, full gallery, and Type × Style compatibility.

**⭐ 待发布文章默认风格:`zh-handbook`(中文手账信息插画风)** — 见 [references/styles/zh-handbook.md](references/styles/zh-handbook.md)。当用户没指定风格时,为中文待发布文章配图**默认用这个风格**,不要用 flat-doodle 极简涂鸦。核心特征:暖米色纸底 + 手写中文大标题 + 蓝色手绘边框分区 + 卡通小人/AI机器人有故事性地"做事" + 底部金句。**图上可以直接写中文**(gpt-image-2 能写对),标题/分区名/金句必须清晰正确。

## 配图思维:结构化 + 流程化 + 总分总

为文章配图时,按这三个原则组织画面(详情见 zh-handbook.md):

1. **结构化思维**:每张图讲一个核心观点,但用结构呈现——对比(左右两区)、流程(箭头步骤①②③④)、拆解(中心辐射)、递进(问题→解法)。
2. **流程化 + 卡通 + 故事性**:让卡通小人/AI机器人在画面里做动作、有情绪、有情节,像在手账里讲一个小故事,而不是干巴巴的图。
3. **总分总拆分**:一个观点一张图装不下时,拆成多张——总览图(整体框架)→ 分论点图(每个子观点一张)→ 收尾图(金句/行动)。整套图共享同一套配色和角色,像"同一本手账的连续几页"。

## Workflow

```
- [ ] Step 1: Pre-check (EXTEND.md, references, config)
- [ ] Step 2: Analyze content
- [ ] Step 3: Confirm settings (AskUserQuestion)
- [ ] Step 4: Generate outline
- [ ] Step 5: Generate images
- [ ] Step 5.6: Compress（脚本内置，落盘即压成 ≤1280 JPEG；未压缩不得进入 Step 6 / 传图床）
- [ ] Step 6: Finalize
```

### Step 1: Pre-check

**1.5 Load Preferences (EXTEND.md) ⛔ BLOCKING**

Check EXTEND.md in priority order — the first one found wins:

| Priority | Path | Scope |
|----------|------|-------|
| 1 | `.baoyu-skills/article-illustrations/EXTEND.md` | Project |
| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/article-illustrations/EXTEND.md` | XDG |
| 3 | `$HOME/.baoyu-skills/article-illustrations/EXTEND.md` | User home |

| Result | Action |
|--------|--------|
| Found | Read, parse, display summary |
| Not found | ⛔ Run [first-time-setup](references/config/first-time-setup.md) |

Full procedures: [references/workflow.md](references/workflow.md#step-1-pre-check)

### Step 2: Analyze

| Analysis | Output |
|----------|--------|
| Content type | Technical / Tutorial / Methodology / Narrative |
| Purpose | information / visualization / imagination |
| Core arguments | 2-5 main points |
| Positions | Where illustrations add value |

**CRITICAL**: Metaphors → visualize underlying concept, NOT literal image.

Full procedures: [references/workflow.md](references/workflow.md#step-2-setup--analyze)

### Step 3: Confirm Settings ⚠️

**Hard gate**: this step is mandatory per the [Confirmation Policy](#confirmation-policy) — Steps 4+ cannot start until the user confirms here (or explicitly opts out with "直接生成" / equivalent wording in the current request).

**ONE AskUserQuestion, max 4 Qs. Q1-Q2 REQUIRED. Q3 required unless preset chosen.**

| Q | Options |
|---|---------|
| **Q1: Preset or Type** | [Recommended preset], [alt preset], or manual: infographic, scene, flowchart, comparison, framework, timeline, mixed |
| **Q2: Density** | minimal (1-2), balanced (3-5), per-section (Recommended), rich (6+) |
| **Q3: Style** | [Recommended], minimal-flat, sci-fi, hand-drawn, editorial, scene, poster, Other — **skip if preset chosen** |
| Q4: Palette | Default (style colors), macaron, warm, neon — **skip if preset includes palette or preferred_palette set** |
| Q5: Language | When article language ≠ EXTEND.md setting |

Full procedures: [references/workflow.md](references/workflow.md#step-3-confirm-settings-)

### Step 4: Generate Outline

Save `outline.md` with frontmatter (type, density, style, palette, image_count) and entries:

```yaml
## Illustration 1
**Position**: [section/paragraph]
**Purpose**: [why]
**Visual Content**: [what]
**Filename**: 01-infographic-concept-name.png
```

Full template: [references/workflow.md](references/workflow.md#step-4-generate-outline)

### Step 5: Generate Images

⛔ **BLOCKING: Prompt files MUST be saved before ANY image generation.** This is a hard requirement regardless of which backend is chosen — the prompt file is the reproducibility record.

1. For each illustration, create a prompt file per [references/prompt-construction.md](references/prompt-construction.md)
2. Save to `prompts/NN-{type}-{slug}.md` with YAML frontmatter
3. Prompts **MUST** use type-specific templates with structured sections (ZONES / LABELS / COLORS / STYLE / ASPECT)
4. LABELS **MUST** include article-specific data: actual numbers, terms, metrics, quotes
5. **DO NOT** pass ad-hoc inline prompts to `--prompt` without saving prompt files first
6. 渲染统一走 favorais 脚本(见顶部「Image Generation Tools」),`python .../scripts/volces_image.py --prompt <prompt 文件内容> --size <WxH> --out <输出路径>`;角色图加 `--ref <avatar_base>`(Agnes 为备选)。
7. **Execution strategy**: Generate in batches per the `## Batch Generation Policy`: runtime parallel tool calls first, sequential only as fallback. Default batch size is 4 unless EXTEND.md or the current request overrides it.
8. Process references (`direct`/`style`/`palette`) per prompt frontmatter
9. Apply watermark if EXTEND.md enabled
10. Generate from saved prompt files; retry once on failure
11. **生成后立刻压缩**：`volces_image.py` / `agnes_image.py` 落盘后自动调用 `scripts/compress_image.py`（最长边 1280、JPEG q85，6MB PNG → ~200KB）。扩展名可能变为 `.jpg`。⛔ 禁止跳过压缩把原图插入正文或 `--images` 上传。传 CSDN 图床仍是 article-writing 步骤⑤，在④人工确认图片之后。

Full procedures: [references/workflow.md](references/workflow.md#step-5-generate-images)

### Step 6: Finalize

Insert `![description]({relative-path}/NN-{type}-{slug}.{ext})` after paragraphs. `{ext}` 以压缩后的实际落盘为准（大图会从 `.png` 变成 `.jpg`）。Path computed relative to article file based on output directory setting.

```
Article Illustration Complete!
Article: [path] | Type: [type] | Density: [level] | Style: [style] | Palette: [palette or default]
Images: X/N generated
```

## Output Directory

**⭐ 本项目（Obsidian 待发布文章）固定目录规则 —— 不要换会话就忘，每次都按这套落盘：**

| 文件类型 | 固定落点 | 说明 |
|---------|---------|------|
| 文章正文 | `06 - 长期记忆库/待发布/AI工具-<主题>.md` | 待发布固定目录，见 [[article-writing]] |
| **文章配图** | `06 - 长期记忆库/待发布/imgs/<主题slug>/NN-<type>-<slug>.png` | **按主题建子目录**（如 `imgs/ai-tools/`、`imgs/zhongpian/`），多篇同主题共享一个子目录 |
| prompt 落盘 | `待发布/imgs/<主题slug>/prompts/NN-<type>-<slug>.md` | 跟图片同主题子目录下 |
| outline | `待发布/imgs/<主题slug>/outline.md` | 同上 |
| **IP 形象底片** | `06 - 长期记忆库/assets/avatar/avatar-base.png` | 固定，角色图 `--ref` 用它 |
| 形象约束 | `06 - 长期记忆库/assets/avatar/my-avatar-dna.md` | 生成角色图前必读 |
| 参考照片 | `06 - 长期记忆库/assets/ref/` | 原始照片，喂图生图用 |
| 历史/废稿图 | `06 - 长期记忆库/assets/backup/` | 旧版本、测试图归档，**不留在 imgs/ 里** |

**目录纪律（防止散落，踩过的坑）：**
1. **按主题建子目录，不在 `imgs/` 根目录平铺。** 一组文章共用一个主题子目录（如这次 6 篇用 `imgs/ai-tools/` + `imgs/zhongpian/`）。
2. **测试图 / 风格试验图 / 旧版本** 一律移到 `assets/backup/`，不混在正式配图目录里（避免误传图床、误嵌入文章）。
3. **生成图和 prompt 同目录**：`imgs/<主题>/` 放 png，`imgs/<主题>/prompts/` 放对应 prompt 文件，可复现。
4. 文章里引用用**相对路径** `imgs/<主题>/NN.jpg`（压缩后扩展名以落盘为准），由 `publish.py --images` 传 CSDN 图床回填成公网 URL。顺序：**生图 → 压缩 → ④确认 → ⑤传 CSDN 图床**，禁止未压缩直接传。

---

通用规则（非本项目 / 未指定时）：Output directory is determined by `default_output_dir` in EXTEND.md (set during first-time setup):

| `default_output_dir` | Output Path | Markdown Insert Path |
|----------------------|-------------|----------------------|
| `imgs-subdir` (default) | `{article-dir}/imgs/` | `imgs/NN-{type}-{slug}.png` |
| `same-dir` | `{article-dir}/` | `NN-{type}-{slug}.png` |
| `illustrations-subdir` | `{article-dir}/illustrations/` | `illustrations/NN-{type}-{slug}.png` |
| `independent` | `illustrations/{topic-slug}/` | `illustrations/{topic-slug}/NN-{type}-{slug}.png` (relative to cwd) |

All auxiliary files (outline, prompts) are saved inside the output directory:

```
{output-dir}/
├── outline.md
├── prompts/
│   └── NN-{type}-{slug}.md
└── NN-{type}-{slug}.png
```

When input is **pasted content** (no file path), always uses `illustrations/{topic-slug}/` with `source-{slug}.{ext}` saved alongside.

**Slug**: 2-4 words, kebab-case. **Conflict**: append `-YYYYMMDD-HHMMSS`.

## Modification

| Action | Steps |
|--------|-------|
| Edit | Update prompt → Regenerate → Compress → Update reference |
| Add | Position → Prompt → Generate → Compress → Update outline → Insert |
| Delete | Delete files → Remove reference → Update outline |

Text correction policy:

- If any rendered text (labels, captions, etc.) is misspelled, garbled, hard to read, or visually weak, do not patch the bitmap with code.
- For text-correction regenerations, write a new prompt file and a new output path so the flawed candidate is preserved for comparison.
- Post-processing is limited to crop, resize, compression, or format conversion that does not alter text or the main composition.

## References

| File | Content |
|------|---------|
| [references/workflow.md](references/workflow.md) | Detailed procedures |
| [references/usage.md](references/usage.md) | Command syntax |
| [references/styles.md](references/styles.md) | Style gallery + Palette gallery |
| [references/style-presets.md](references/style-presets.md) | Preset shortcuts (type + style + palette) |
| [references/prompt-construction.md](references/prompt-construction.md) | Prompt templates |
| [references/config/first-time-setup.md](references/config/first-time-setup.md) | First-time setup |

## Changing Preferences

EXTEND.md lives at the first matching path listed in Step 1.5. Three ways to change it:

- **Edit directly** — open EXTEND.md and change fields. Full schema: `references/config/preferences-schema.md`.
- **Reconfigure interactively** — delete EXTEND.md (or ask "reconfigure baoyu-article-illustrator preferences" / "重新配置"). The next run re-triggers first-time setup.
- **Common one-line edits**:
  - `preferred_image_backend: agnes` — 固定走 Agnes 脚本(当前唯一后端)。
  - `generation_batch_size: 4` — default number of images to render concurrently when the runtime supports parallel generation calls.
  - `preferred_type: infographic`, `preferred_style: notion`, `preferred_palette: macaron`, `language: zh`.
  - `default_output_dir: imgs-subdir` — where to write generated images relative to the article.