# Markdown Illustrator

> markdown-illustrator

- Skill: `huangserva/markdown-illustrator` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add huangserva/markdown-illustrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/huangserva/markdown-illustrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: huangserva (https://skillmd.com/u/huangserva)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/huangserva/markdown-illustrator

---

# markdown-illustrator

**自动为Markdown文档生成精美配图的AI技能**

## 技能描述

这是一个专门为Markdown文档自动配图的Claude Skill。分析文章结构，为关键章节生成视觉插图，支持纽约客和浮世绘等多种艺术风格，灵活配置图片生成路由。

## 核心功能

这个skill提供两大核心功能：

### 功能1：Markdown文档配图
为已完成的Markdown文档自动配图：
1. **智能分析文章内容** - 自动识别章节和关键内容
2. **生成视觉描述** - 为每个章节创建合适的配图描述
3. **自动插入图片** - 在Markdown中的合适位置插入配图

### 功能2：直接提示词生成图片
根据提示词直接生成单张图片：
1. **快速生成** - 输入提示词，立即生成图片
2. **灵活控制** - 指定风格、provider、宽高比
3. **独立使用** - 不需要Markdown文档

### 通用特性
- **多种风格支持** - 纽约客、浮世绘等艺术风格
- **灵活的图片生成路由** - 支持多个图片生成API，可自定义优先级
- **高成功率** - 自动降级机制确保生成成功

## 支持的图片生成Provider

- **google-local** - 本地Gemini API (gemini-3-pro-image)
- **modelscope** - 通义万相 Z-Image-Turbo
- **zimage** - 本地ComfyUI
- **volcengine** - 火山引擎豆包
- **apimart** - ApiMart服务

## 如何激活此技能

### Markdown文档配图
- "帮我给这篇文章配5张纽约客风格的图"
- "用markdown-illustrator给我的文档配插图"
- "给这个Markdown生成浮世绘风格的配图"
- "用ModelScope给文章配图，失败就用google-local"

### 直接提示词生成图片
- "用markdown-illustrator生成一张图：猫咪坐在书上"
- "生成一张纽约客风格的图片：武士在战斗"
- "用ModelScope生成：富士山日落"
- "生成图片：现代都市天际线，用浮世绘风格"

## 使用示例

### 示例1：基础配图
```
User: 帮我给article.md配5张纽约客风格的配图

## 配图流程

1. **分析文章结构** - 识别标题、章节、关键段落
2. **确定配图数量** - 根据文章长度和结构决定配图数量
3. **生成视觉策略** - 为每个章节生成英文的视觉描述
4. **选择艺术风格** - 应用纽约客、浮世绘等风格
5. **调用图片API** - 使用指定的provider生成图片
6. **保存和插入** - 保存图片并插入到Markdown中

## 配置选项

### 图片风格
- `newyorker` - 纽约客风格（黑白线条+红色点缀）
- `ukiyoe` - 日本浮世绘风格（鲜艳色彩）

### 图片数量
- `auto` - 自动根据文章长度决定（默认）
- `3/5/7` - 指定具体数量

### Provider优先级
- `auto` - 使用默认优先级
- `custom` - 自定义优先级列表

### 宽高比（重要！）

**支持的宽高比：**
- `16:9` - 横版电影感（默认）
- `9:16` - 竖版/手机屏幕
- `1:1` - 方形/头像
- `4:3` - 传统横版
- `3:4` - 传统竖版
- `21:9` - 超宽电影感

**场景 → 宽高比自动判断规则：**

| 场景类型 | 推荐宽高比 | 原因 |
|---------|-----------|------|
| 双人对决/对峙 | **16:9** 或 **21:9** | 左右对称构图需要横向空间 |
| 群像（3人以上） | **16:9** | 多人需要宽画面 |
| 战斗场景/动作 | **16:9** | 动作展开需要空间 |
| 风景/场景 | **16:9** 或 **21:9** | 横向展现壮观感 |
| 单人肖像 | **3:4** 或 **9:16** | 竖版突出人物 |
| 单人全身 | **9:16** | 竖版展示全身 |
| 头像/特写 | **1:1** | 方形聚焦面部 |
| 产品展示 | **1:1** 或 **4:3** | 突出主体 |

**使用方式：**
```bash
# 指定宽高比
python3 generate_image.py "双人对决场景" --aspect-ratio 16:9

# 竖版人像
python3 generate_image.py "女孩肖像" --aspect-ratio 3:4

# 方形头像
python3 generate_image.py "头像特写" --aspect-ratio 1:1
```

**自动判断示例：**
```
用户："龙珠悟空和弗利萨对决"
→ 分析：双人对决，需要横向空间
→ 自动选择：16:9

用户："生成一个女孩的头像"
→ 分析：单人头像特写
→ 自动选择：1:1

用户："悟空、贝吉塔、悟饭三人合影"
→ 分析：三人群像
→ 自动选择：16:9
```

## 工作流程示例

```python
# 1. 读取Markdown文件
# 2. 分析文章结构，提取章节
# 3. 为每个章节生成视觉描述
# 4. 调用图片生成API
# 5. 保存图片到指定目录
# 6. 在Markdown中插入图片引用
# 7. 生成带配图的新文档
```

## 依赖

- `shared-lib/image_api.py` - 统一的图片生成API
- Python 3.8+
- requests, PIL (Pillow)

## 输出

- 原始Markdown文件（不修改）
- 新的带配图的Markdown文件
- 配图文件夹（包含所有生成的图片）
- 配图报告（记录生成时间、使用的provider等）

## 注意事项

1. 图片生成需要API key或本地服务
2. 生成时间取决于provider和图片数量（通常每张7-30秒）
3. 支持自动降级：如果首选provider失败，自动尝试下一个
4. 可以指定输出目录和文件命名规则