宝玉文章插图

技能文档

---
name: baoyu-article-illustrator
title: 宝玉文章插图
category: 内容创作
description: 分析文章结构，识别需要配图的位置，使用「类型 × 风格 × 色板」三维体系生成插图。当用户要求「为文章配图」「给文章添加插图」「生成文章配图」「illustrate article」时触发。
---

# 文章配图助手

分析文章，识别插图位置，使用「类型 × 风格 × 色板」三维体系保持一致性。

## 用户交互工具

当本技能需要向用户提问时，遵循以下工具选择规则（按优先级）：

1. **优先使用内置用户交互工具** — 当前运行时暴露的用户输入工具（如 `request_user_input`、`clarify`、`ask_user` 或等效工具）。
2. **回退方案**：若无此类工具，输出编号文本消息，请用户回复编号/答案。
3. **批量提问**：若工具支持单次多问，将所有问题合并为一次调用；若仅支持单问，按优先级逐个提问。

## 图像生成工具

当本技能需要渲染图像时，按以下顺序确定后端：

1. **当前请求覆盖** — 用户在当前消息中指定了特定后端，则使用该后端。
2. **已保存偏好** — 若 `EXTEND.md` 设置了 `preferred_image_backend` 且当前可用，则使用该后端。
3. **自动选择**（偏好为 `auto`、未设置或指定后端不可用时）：
   - 若当前运行时暴露原生图像工具（如内置 ImageGen），优先使用。
   - 否则，若仅安装了一个非原生后端，使用该后端。
   - 否则（多个非原生后端且无原生工具），向用户提问一次。
4. **若均不可用**，告知用户并询问如何处理。

设置 `preferred_image_backend: ask` 强制每次运行时都提示用户选择。

**提示文件要求（强制）**：在调用任何后端之前，将每张图像的完整最终提示词写入 `prompts/` 目录下的独立文件（命名：`NN-{type}-[slug].md`）。后端接收提示文件（或其内容）；该文件是可复现记录，允许切换后端而无需重新生成提示词。

## 确认策略

默认行为：**生成前确认**。

- 显式调用本技能、文件路径、匹配信号/预设、`EXTEND.md` 默认值均视为**建议输入**，不授权跳过确认。
- 用户完成步骤3之前，**不要**开始步骤4或后续步骤。
- 仅当当前请求明确说明跳过时才跳过确认，例如：「直接生成」「不用确认」「跳过确认」「按默认出图」或等效表述。
- 跳过确认时，在生成前的下一条用户消息中说明假设的 类型/密度/风格/色板/语言/后端。

## 参考图像

用户可通过 `--ref <文件...>` 或在对话中提供文件路径/粘贴图像来提供参考图像。参考图用于指导特定插图的风格、色板、构图或主题。

完整的检测、存储和处理规则见 [references/workflow.md](references/workflow.md)（步骤1.0 保存到 `references/NN-ref-{slug}.{ext}`；步骤5.3 按每张插图的使用方式 `direct | style | palette` 处理）。

## 三维体系

| 维度 | 控制内容 | 示例 |
|------|----------|------|
| **类型** | 信息结构 | 信息图、场景、流程图、对比、框架、时间线 |
| **风格** | 渲染方式 | notion、暖色、极简、蓝图、水彩、优雅 |
| **色板** | 配色方案（可选） | 马卡龙、暖色、霓虹 — 覆盖风格默认配色 |

自由组合：`--type infographic --style vector-illustration --palette macaron`

或使用预设：`--preset edu-visual` → 一个参数设定 类型+风格+色板。参见[风格预设](references/style-presets.md)。

## 类型

| 类型 | 适用场景 |
|------|----------|
| `infographic` | 数据、指标、技术内容 |
| `scene` | 叙事、情感表达 |
| `flowchart` | 流程、工作流 |
| `comparison` | 并列对比、选项比较 |
| `framework` | 模型、架构 |
| `timeline` | 历史、演变 |

## 风格

参见 [references/styles.md](references/styles.md) 了解核心风格、完整画廊及类型×风格兼容性。

## 技能工作流

```
- [ ] 步骤1：预检查（EXTEND.md、参考图、配置）
- [ ] 步骤2：分析内容
- [ ] 步骤3：确认设置（用户交互工具）
- [ ] 步骤4：生成大纲
- [ ] 步骤5：生成图像
- [ ] 步骤6：完成
```

### 步骤1：预检查

**1.5 加载偏好设置（EXTEND.md）⛔ 阻塞**

按优先级检查 EXTEND.md — 找到第一个即生效：

| 优先级 | 路径 | 范围 |
|--------|------|------|
| 1 | `.baoyu-skills/baoyu-article-illustrator/EXTEND.md` | 项目级 |
| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-article-illustrator/EXTEND.md` | XDG |
| 3 | `$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md` | 用户主目录 |

| 结果 | 操作 |
|------|------|
| 找到 | 读取、解析、显示摘要 |
| 未找到 | ⛔ 执行[首次设置](references/config/first-time-setup.md) |

完整流程：[references/workflow.md](references/workflow.md#step-1-pre-check)

### 步骤2：分析

| 分析项 | 输出 |
|--------|------|
| 内容类型 | 技术/教程/方法论/叙事 |
| 目的 | 信息传递/可视化/想象 |
| 核心论点 | 2-5 个要点 |
| 位置 | 插图能增加价值的位置 |

**关键**：隐喻 → 可视化底层概念，而非字面图像。

完整流程：[references/workflow.md](references/workflow.md#step-2-setup--analyze)

### 步骤3：确认设置 ⚠️

**强制门槛**：根据[确认策略](#确认策略)，此步骤为必选 — 用户确认之前（或在当前请求中明确使用「直接生成」等表述退出），步骤4+无法开始。

**一次用户交互调用，最多4个问题。Q1-Q2 必选。选择预设时 Q3 可跳过。**

| 问题 | 选项 |
|------|------|
| **Q1：预设或类型** | [推荐预设]、[备选预设]，或手动选择：infographic、scene、flowchart、comparison、framework、timeline、mixed |
| **Q2：密度** | 精简（1-2）、均衡（3-5）、按章节（推荐）、丰富（6+） |
| **Q3：风格** | [推荐]、minimal-flat、sci-fi、hand-drawn、editorial、scene、poster、其他 — **选择预设时跳过** |
| Q4：色板 | 默认（风格配色）、macaron、warm、neon — **预设包含色板或已设置 preferred_palette 时跳过** |
| Q5：语言 | 当文章语言 ≠ EXTEND.md 设置时 |

完整流程：[references/workflow.md](references/workflow.md#step-3-confirm-settings-)

### 步骤4：生成大纲

保存 `outline.md`，含 frontmatter（type、density、style、palette、image_count）和条目：

```yaml
## 插图 1
**位置**：[章节/段落]
**目的**：[为什么]
**视觉内容**：[什么]
**文件名**：01-infographic-concept-name.png
```

完整模板：[references/workflow.md](references/workflow.md#step-4-generate-outline)

### 步骤5：生成图像

⛔ **阻塞：在生成任何图像之前，必须先保存提示文件。** 这是无论选择哪个后端的硬性要求 — 提示文件是可复现记录。

1. 为每张插图创建提示文件，参见 [references/prompt-construction.md](references/prompt-construction.md)
2. 保存到 `prompts/NN-{type}-{slug}.md`，含 YAML frontmatter
3. 提示词**必须**使用类型专用模板，包含结构化章节（ZONES / LABELS / COLORS / STYLE / ASPECT）
4. LABELS **必须**包含文章特定数据：实际数字、术语、指标、引用
5. **不要**在未保存提示文件的情况下将临时内联提示传给 `--prompt`
6. 按顶部「图像生成工具」规则选择后端：使用可用工具；若有多个，向用户提问一次。在每次会话的任何生成之前执行一次。
7. **执行策略**：当多张插图已保存提示文件且任务变为纯生成时，优先使用所选后端的批量接口（若有）。仅当每张图像仍需单独提示迭代或创意探索时才使用子代理。若后端无批量接口，按顺序生成。
8. 按提示文件 frontmatter 处理参考图（`direct`/`style`/`palette`）
9. 若 EXTEND.md 启用了水印则应用
10. 从已保存的提示文件生成；失败时重试一次

完整流程：[references/workflow.md](references/workflow.md#step-5-generate-images)

### 步骤6：完成

在段落后插入 `![description]({relative-path}/NN-{type}-{slug}.png)`。路径根据输出目录设置相对于文章文件计算。

```
文章配图完成！
文章：[路径] | 类型：[type] | 密度：[level] | 风格：[style] | 色板：[palette 或默认]
图像：X/N 已生成
```

## 输出目录

输出目录由 EXTEND.md 中的 `default_output_dir` 决定（首次设置时配置）：

| `default_output_dir` | 输出路径 | Markdown 插入路径 |
|----------------------|----------|-------------------|
| `imgs-subdir`（默认） | `{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`（相对于 cwd） |

所有辅助文件（大纲、提示词）保存在输出目录内：

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

当输入为**粘贴内容**（无文件路径）时，始终使用 `illustrations/{topic-slug}/`，并在其中保存 `source-{slug}.{ext}`。

**Slug**：2-4 个词，kebab-case。**冲突**：追加 `-YYYYMMDD-HHMMSS`。

## 修改

| 操作 | 步骤 |
|------|------|
| 编辑 | 更新提示 → 重新生成 → 更新引用 |
| 添加 | 确定位置 → 提示 → 生成 → 更新大纲 → 插入 |
| 删除 | 删除文件 → 移除引用 → 更新大纲 |

## 参考资料

| 文件 | 内容 |
|------|------|
| [references/workflow.md](references/workflow.md) | 详细流程 |
| [references/usage.md](references/usage.md) | 命令语法 |
| [references/styles.md](references/styles.md) | 风格画廊 + 色板画廊 |
| [references/style-presets.md](references/style-presets.md) | 预设快捷方式（类型+风格+色板） |
| [references/prompt-construction.md](references/prompt-construction.md) | 提示词模板 |
| [references/config/first-time-setup.md](references/config/first-time-setup.md) | 首次设置 |

## 修改偏好设置

EXTEND.md 位于步骤1.5 列出的第一个匹配路径。三种修改方式：

- **直接编辑** — 打开 EXTEND.md 修改字段。完整 schema：`references/config/preferences-schema.md`。
- **交互式重新配置** — 删除 EXTEND.md（或说「重新配置 baoyu-article-illustrator 偏好」/「重新配置」）。下次运行重新触发首次设置。
- **常用单行修改**：
  - `preferred_image_backend: auto` — 默认；内置 ImageGen 优先，回退到唯一已安装后端，仅在多个非原生后端存在时询问。
  - `preferred_image_backend: ask` — 每次运行确认后端。
  - `preferred_type: infographic`、`preferred_style: notion`、`preferred_palette: macaron`、`language: zh`。
  - `default_output_dir: imgs-subdir` — 生成图像相对于文章的输出位置。

使用说明

# 宝玉文章插图

分析文章结构，自动识别配图位置，使用「类型 × 风格 × 色板」三维体系生成风格一致的插图。

## 使用

提供文章文件路径或粘贴文章内容：

```
为这篇文章配图：path/to/article.md
```

```
给以下内容添加插图：
（粘贴文章内容）
```

指定类型和风格：

```
为文章配图 --type infographic --style notion
```

使用预设快速出图：

```
为文章配图 --preset edu-visual
```

## 工作原理

1. 分析文章结构与核心论点
2. 识别适合插入插图的位置
3. 确认类型、密度、风格、色板等设置
4. 生成插图大纲与提示词文件
5. 调用图像生成工具批量出图
6. 将插图插入文章对应位置

支持六种插图类型（信息图、场景、流程图、对比、框架、时间线）与多种风格预设，通过三维体系自由组合，确保全文视觉风格统一。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。