---
name: article-illustrator
description: 为文章生成配图。分析文章结构，判断哪些位置需要什么类型的插图（infographic/flowchart/comparison/framework/timeline/scene），生成 prompt 并调用 image-gen 生成图片，最后插入文章。当用户说"配图"、"给文章加插图"、"生成文章插图"、"illustrate this article"时触发。即使用户只说"帮这篇文章配个图"也应该触发。
---

# Article Illustrator

分析文章内容，智能匹配插图类型和位置，生成配图并插入文章。

## 视觉风格

风格不预设，由你（调用 skill 的 AI）根据文章内容自主选择最匹配的视觉风格，然后在 prompt 中**具体、明确地描述**给图片生成模型。图片生成模型只负责执行你的 prompt，不做风格判断。

**你的职责**：读完文章后，判断这篇文章适合什么视觉风格（配色、渲染方式、氛围），在 prompt 里写清楚。不同文章可以用完全不同的风格。

**底线要求**（用户偏好，从参考图中提取）：

| 维度 | 底线 |
|------|------|
| **背景** | 干净，白色或浅色为主，不要花哨纹理 |
| **布局** | 卡片/面板式容器组织信息，区域划分清晰 |
| **图形** | 扁平矢量或简化图标，不要写实照片风格 |
| **连接** | 箭头连接模块，流向一目了然 |
| **文字** | 大粗标题醒目，数据指标突出，标签简短 |
| **色彩** | 主色不超过 2-3 个，和谐不杂乱 |
| **整体** | 信息优先，专业但亲切 |

在这些底线之上，你自由选择具体风格。比如：
- AI/技术文章 → 蓝紫科技感、深色面板+亮色数据
- 对比类内容 → 左右分色对比（如蓝vs橙）
- 教程/流程 → 卡片步骤+编号圆圈+弧形箭头
- 叙事/个人向 → 暖色调、插画感更强

选好后在 prompt 里写明配色方案、渲染风格、氛围，让图片生成模型精准执行。

## 用法

```bash
# 基本用法
/article-illustrator path/to/article.md

# 指定类型
/article-illustrator path/to/article.md --type infographic

# 指定密度
/article-illustrator path/to/article.md --density rich
```

| 选项 | 说明 |
|------|------|
| `--type <name>` | 指定类型：infographic / flowchart / comparison / framework / timeline / scene / mixed |
| `--density <level>` | 密度：minimal(1-2) / balanced(3-5) / per-section / rich(6+) |

## 工作流程

```
1. 分析文章 → 2. 确认设置 → 3. 生成大纲 → 4. 写 prompt → 5. 生成图片并上传 R2 → 6. 插入远程图片 URL
```

---

### Step 1：分析文章

读完文章后做四项分析：

| 分析项 | 说明 |
|--------|------|
| 内容类型 | Technical / Tutorial / Methodology / Narrative |
| 配图目的 | 信息传达 / 概念可视化 / 氛围想象 |
| 核心论点 | 提取 2-5 个需要可视化的要点 |
| 配图位置 | 哪些段落加图能帮助理解 |

提取核心论点时关注：主论点、关键概念、对比/对照、框架/模型。

**关键**：比喻要可视化底层概念，不要画字面意思。比如文章说"书桌满了纸掉下去"，配图应该画"上下文窗口"的概念，不是画一张真的书桌。

---

### Step 2：确认设置

用 AskUserQuestion 确认，最多 3 个问题：

**Q1：插图类型**（必问）

根据分析推荐，选项包含推荐项 + 其他可选类型。

**Q2：配图密度**（必问）

| 密度 | 数量 | 场景 |
|------|------|------|
| minimal | 1-2 张 | 短文，核心概念 |
| balanced | 3-5 张 | 中等长度 |
| per-section | 每章节 1 张 | 长文（推荐） |
| rich | 6+ 张 | 全面覆盖 |

**Q3：输出目录**（如果从参数或上下文无法推断）

常见选项：`{article-dir}/imgs/{slug}/`、`{article-dir}/`、独立 `illustrations/` 目录。

---

### Step 3：生成大纲

为每张图写一个条目，保存为 `outline.md`：

```yaml
---
type: mixed
density: per-section
image_count: 5
---

## Illustration 1
**Position**: [章节/段落]
**Purpose**: [为什么需要这张图]
**Type**: [infographic/flowchart/comparison/framework/timeline/scene]
**Visual Content**: [画什么]
**Filename**: 01-{type}-{slug}.png
```

---

### Step 4：写 Prompt

为每张图创建 prompt 文件 `prompts/NN-{type}-{slug}.md`，使用对应类型的结构模板。

#### 6 种类型模板

**Infographic**（数据、指标、概念解释）：
```
[标题]

Layout: [grid/radial/hierarchical]

ZONES:
- Zone 1: [具体数据点和数值]
- Zone 2: [对比和指标]

LABELS: [文章中的实际数字、术语]
ASPECT: 16:9
```

**Flowchart**（步骤、流程、操作）：
```
[标题]

Layout: [left-right/top-down/circular]

STEPS:
1. [步骤名] - [简述]
2. [步骤名] - [简述]

CONNECTIONS: [箭头、决策节点]
ASPECT: 16:9
```

**Comparison**（vs、优劣、方案对比）：
```
[标题]

LEFT SIDE - [选项A]:
- [要点]

RIGHT SIDE - [选项B]:
- [要点]

DIVIDER: [视觉分隔]
ASPECT: 16:9
```

**Framework**（架构、模型、原理）：
```
[标题]

STRUCTURE: [hierarchical/network/matrix]

NODES:
- [概念1] - [角色]
- [概念2] - [角色]

RELATIONSHIPS: [连接关系]
ASPECT: 16:9
```

**Timeline**（历史、演变、进展）：
```
[标题]

DIRECTION: [horizontal/vertical]

EVENTS:
- [时间点1]: [里程碑]
- [时间点2]: [里程碑]

MARKERS: [视觉标记]
ASPECT: 16:9
```

**Scene**（故事、情感、氛围）：
```
[标题]

FOCAL POINT: [主体]
ATMOSPHERE: [光线、氛围]
MOOD: [情绪]
ASPECT: 16:9
```

#### Prompt 质量要求

每个 prompt 必须做到：
1. **先写布局**：构图、区域划分、方向
2. **用文章原文数据**：实际数字、术语、指标，不用占位符
3. **描述元素关系**：怎么连接、怎么对比
4. **语义化颜色**：颜色有含义（红=问题、绿=好的），但不锁定具体色号
5. **注明宽高比**

不要：模糊描述、画比喻字面意思、缺少标注、泛泛的装饰。

图中文字要大且醒目，只放关键词。**默认使用中文标注**，包括标题、标签、说明文字全部用中文。只有专有名词（品牌名、产品名如 Claude Code）可保留英文。

如果图中有人物，用简化的风格化剪影或卡通图标，不要写实人像。

**每个 prompt 必须包含明确的风格描述**：在 Step 1 分析完文章后，你应该已经决定了这组配图的视觉风格。在每个 prompt 中写清楚具体的配色方案（如 "deep indigo #3F3D9E as primary, soft lavender #B8B5E8 as secondary"）、渲染方式（如 "clean flat vector with card-based panels"）和氛围（如 "professional tech dashboard feel"）。图片生成模型不会自己选风格，你的 prompt 写什么它就画什么。

---

### Step 5：生成图片并上传 R2

用 image-gen skill 逐张生成，并且默认上传到 R2：

```bash
npx -y bun <image-gen-skill-path>/scripts/main.ts \
  --prompt "<prompt内容>" \
  --image "<临时输出路径>/NN-{type}-{slug}.png" \
  --ar 16:9 \
  --r2 \
  --r2-key "images/articles/{article-slug}/NN-{type}-{slug}.png"
```

image-gen skill 路径：优先检查项目级 `.claude/skills/image-gen/`，其次 `.agents/skills/image-gen/`。R2 配置读取 vault 根目录 `.env.r2`。

**封面图**：除了文章内插图外，默认额外生成一张封面图（`cover.png`），使用 `--ar 2.35:1` 比例（公众号封面尺寸）。封面图也必须上传 R2，使用类似 `images/articles/{article-slug}/cover.png` 的 key；插入文章 frontmatter 之后、正文之前的是 R2 公开 URL。

每张生成并上传后记录 R2 URL，报告进度："Generated + uploaded X/N"。生成失败或上传失败都重试一次，仍失败则跳过并记录。

---

### Step 6：插入远程图片 URL

在对应段落后插入 R2 公开 URL：

```markdown
![简要描述](https://your-r2-domain/images/articles/{article-slug}/NN-{type}-{slug}.png)
```

alt text 用简洁的中文描述，与文章语言一致。不要把长期图片链接写成本地 `imgs/...` 路径；本地文件只作为临时缓存。

完成后输出摘要：

```
配图完成！
文章：[path]
类型：[type] | 密度：[level]
图片：X/N 张生成并上传成功

位置：
- 01-xxx.png → R2 URL → "章节名" 之后
- 02-yyy.png → "章节名" 之后
```

---

## 内容信号 → 类型匹配速查

| 内容信号 | 推荐类型 |
|----------|----------|
| 数据、指标、数字 | infographic |
| 知识、概念、教程 | infographic |
| 技术、AI、编程 | infographic |
| 步骤、流程、操作 | flowchart |
| 架构、模型、原理 | framework |
| vs、优劣、方案对比 | comparison |
| 故事、情感、经历 | scene |
| 历史、时间线、演变 | timeline |

一篇文章可以 mixed 使用多种类型。

## 该配 vs 不该配

**该配**：核心论点（必配）、抽象概念、数据对比、流程。

**不该配**：比喻字面画面、纯装饰、泛泛通用插画。

## 输出结构

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