# Article Figure Spot Skill / 文章配图Skill

自动扫描整篇文章，找出所有适合插图的位置，并**要么**在文中插入「生图提示词」占位（你稍后自行生图），**要么**一键为每个位置生成插图并写出带图片路径的文章，同时给出**每张图应对应插在文中哪一段/哪一节**的对照表，形成闭环。

## 功能概览

- **两种输入**：给出文章 Markdown 文件路径，或直接在对话里粘贴全文。
- **两种模式**：
  - **仅提示词（prompts-only）**：在文中插入生图提示块，你按提示自己跑生图工具并插入图片链接。
  - **一键生成（generate）**：自动为每个位置写 prompt、调用内置脚本生图、保存图片，并输出已插入图片的文章 + **插图与文中位置对照表**。
- **闭环说明**：结束时一定会给出一张表：**图片文件名/路径 ↔ 文中插入位置**（如「在 ## xxx 段落后」「在段首为『……』的段落后」），方便你把图插回原文。

## 使用方式

在 Cursor 中通过 Skill 调用（或按你部署的方式传入参数）：

```bash
# 仅插入生图提示词，不自动生图
/article-figure-spot path/to/article.md
/article-figure-spot path/to/article.md --prompts-only

# 一键生成所有插图并保存
/article-figure-spot path/to/article.md --generate

# 可选：控制插图密度、输出目录、语言
/article-figure-spot article.md --generate --density rich --out-dir figures --lang zh
```

### 参数说明

| 参数 | 说明 |
|------|------|
| `--prompts-only` | 只插入提示词占位，不跑生图。 |
| `--generate` | 为每个位置生图并保存，并输出带图标的文章与对照表。 |
| `--density <level>` | 插图密度：`sparse`（2–3 张）、`medium`（4–6 张）、`rich`（7+ 张），默认 `medium`。 |
| `--out-dir <dir>` | 提示词与图片的输出根目录，默认 `figure-spot/{主题 slug}/`。 |
| `--lang <code>` | 提示词与 alt 文本语言（如 `en`、`zh`），默认从文章检测。 |

## 环境变量（generate 模式）

生图使用本仓库自带的 `scripts/generate-image.mjs`（Node 运行，调用 OpenAI 图片 API）。

- **必须**：`OPENAI_API_KEY`（在技能目录或当前工作目录的 `.env` 中配置）。
- 可选：`OPENAI_BASE_URL`、`OPENAI_IMAGE_MODEL`（脚本内有默认值）。

## 输出目录结构

默认在 `figure-spot/{主题-slug}/` 下生成：

```
figure-spot/{主题-slug}/
├── source.md              # 源文章备份或引用
├── placement.md           # 位置表：序号、锚点、角色、提示摘要、文件名、文中插入位置
├── prompts/
│   ├── 01-concept-xxx.md
│   └── 02-process-yyy.md
├── 01-concept-xxx.png     # 生成的图（generate 模式）
├── 02-process-yyy.png
└── article-with-figures.md   # 已插入图片链接的文章（generate 模式）
```

- **文中插入位置**：在 `placement.md` 和**结束时的总结**里都会标明「每张图应插在文章的哪一段/哪一节」，便于你按表把图插回原文。

## 结束时的「图 ↔ 文中位置」对照

无论哪种模式，结束时都会给出一张**插图与文中插入位置对照表**，例如：

| 图片文件 | 文中插入位置 |
|----------|----------------|
| `01-concept-three-layers.png` | 在 **## 复盘的三个层次** 这一节段落后 |
| `02-process-four-steps.png` | 在段首为「推荐流程（四步）」的段落之后 |

- **Prompts-only**：按表把每张图插到对应位置；生图可依据文中 `<!-- PROMPT: ... -->` 与 `<!-- FILE: ... -->` 执行。
- **Generate**：表中所列图片已生成在 `out-dir` 下，可直接用 `article-with-figures.md` 或按表把路径插入你的原文。

## 脚本说明

- 生图脚本：`scripts/generate-image.mjs`（Node ESM）。
- 调用示例（由 Skill 在 generate 模式下自动调用）：
  ```bash
  node scripts/generate-image.mjs --promptfiles prompts/01-concept-xxx.md --image figure-spot/主题/01-concept-xxx.png --ar 16:9
  ```
- 生图依赖 OpenAI 图片 API，请自行配置 `OPENAI_API_KEY`。