# Lov Illustrate

> 依据文档内容选择真实素材、图表或生成图并校验插入位置。支持明确输入与结果回读。Use to illustrate a document with evidence and relevant images.

- Skill: `lovstudio/lov-illustrate` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add lovstudio/lov-illustrate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lovstudio/lov-illustrate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: lovstudio (https://skillmd.com/u/lovstudio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lovstudio/lov-illustrate

---


# 图解文档 · Document Visuals

为 Markdown 文档智能分析插图位置，并行生成/检索图片，输出带插图的增强版文档。

## Triggers

### Activate when

- 用户要求“给文章配图”“补插图”“生成文章插画”或“illustrate this document”。
- 用户希望为长文规划真实素材、对照图、过程图、数据图表或程序化合成图。

### Do not activate when

- 用户只要求生成一张独立图片，不需要文章级选图、插入与视觉节奏；使用对应图像 Skill。
- 用户只要求给现有图片加 Caption、边框或 Logo；使用 `lov-image-decorator`。
- 用户要求发布公众号文章或修改远端草稿；使用 `lov-publish-wechat-article`。
- 用户只要求审阅正文内容，不需要插图规划或图片文件。

## 参数格式
`<file_path> [--auto] [--style <style>] [--max <n>]`

- `file_path`: 必填，md文件路径
- `--auto`: 跳过确认，直接生成
- `--style`: 图片风格（默认：从 design-guide.md 读取，回退 warm-academic）
- `--max`: 最大插图数量（默认：不限，由AI决定）

## 工作流

### Step 1: 读取文档 + 加载品牌风格

1. 读取目标文档
2. 尝试读取 `${SKILL_WORKSPACE_ROOT}/design/design-guide.md`，提取 AI 生图 prompt 模板和色彩体系
3. 如果存在品牌风格，后续所有 AI 生图 prompt 必须注入品牌色彩和质感关键词
4. 如果计划制作包含可编辑文字的 HTML、SVG、Canvas、Pillow 或其他程序化合成图，
   **必须完整读取 `references/text-rendering-safety.md`**，并在方案中登记文本语言与字体来源

### Step 2: 分析文档结构 + 实体提取

分析：
- 文章结构（标题层级、段落分布）
- 内容主题（每个章节的核心概念）
- 情绪节奏（叙事高潮、转折点）
- 已有图片位置
- **数据密集区域**（表格、多产品/多概念并列对比）
- **可量化信息**（ARR、用户数、增长率等需要图表的数据）

**关键步骤：实体与证据候选提取（必做）**

在规划插图前，先逐段扫描文档，列出所有可联网检索的真实实体：

```
| 实体 | 类型 | 出现位置 | 可检索素材 |
|------|------|---------|-----------|
| Cursor IDE | 产品 | L12 | 产品界面截图、博文封面 |
| Sam Altman | 人物 | L45 | 新闻照片 |
| GPT-4发布会 | 事件 | L78 | 发布会现场照片 |
| arXiv:2602.11988 | 论文 | L199 | 论文图表 |
| github.com/openai/symphony | 开源项目 | L121 | GitHub页面截图、终端UI |
```

**实体类型覆盖**：产品/工具、人物、公司、事件、地点、论文/研究、博客文章、开源项目、终端/CLI 界面

这张表是后续插图方案的候选输入，不是图片配额。只有素材能帮助读者理解论点、验证
现场、看见变化或获得必要视觉休息时才进入方案；正文已经清楚、图片只会机械重复时
可以不配。真实人物与活动素材还要记录授权状态、来源场景和能否公开组合。

### Step 3: 规划插图方案

为每个建议插图位置生成方案（必须标注关联实体和搜索策略）：

```
| # | 位置 | 插图主题 | 类型 | 关联实体 | 搜索策略/prompt |
|---|------|---------|------|---------|----------------|
| 1 | L12 | ELIZA对话界面 | 联网检索 | ELIZA | "ELIZA chatbot original screenshot" |
| 2 | L47 | Web演进时间线 | AI生图 | 无（纯抽象） | editorial timeline illustration... |
| 3 | L136 | ARR增长对比 | 数据图表 | Notion/Airtable/Linear | 先调研数据再绘制 |
| ...
```

#### 类型决策树（按优先级）

```
该插图是否涉及真实产品/人物/事件/地点？
├─ 是 → 联网检索（产品截图、历史照片、官方图表、新闻图片）
│       └─ 搜不到合适素材？→ AI生图（概念化表达）
└─ 否 → 该插图是否涉及可量化数据？
         ├─ 是 → 数据图表（先调研获取可溯源数据，再绘制）
         └─ 否 → 是否需要精确、可编辑的文字或结构？
                  ├─ 是 → 程序化合成图（HTML/SVG/Canvas 等）
                  └─ 否 → AI生图（概念插画）
```

**硬性规则（违反则方案不合格）：**

1. **价值驱动而非实体配额**：每张图必须至少承担证据、解释、对比、过程或节奏中的
   一项任务；无法说明读者收益时删除，不因文章提到某个实体就强制配图。
2. **真实实体优先真实素材**：产品、事件、论文、项目和公共人物优先使用可溯源截图、
   照片或原图。只有用户提供了合法输入并明确要求风格化、编辑或概念化表达时，才用
   生成式模型处理真实实体，并如实标注 provenance。
3. **来源场景一致**：同一组对照或合成图中的人物、活动与原图必须来自文章所述场景。
   获得授权只解决权利问题，不代表其他场合的素材适合混入当前公共叙事。
4. **原图真源**：比较“原图 / 结果”时，原图必须回到活动相册、相机文件或经核验的
   原始附件，不能把裁切图、风格化结果或聊天缩略图误当原图。
5. **AI 占比自检**：AI 图较多时逐张复核是否真的需要，以及是否会把可验证事实变成
   虚构视觉；不设置机械百分比门槛。
6. **生成方式如实标注**：联网素材合成、程序化排版、数据图表、生成式编辑与纯生成
   是不同 provenance；不得互相冒充。

#### 特殊类型：Hero Image（可选）

Hero 只在它能提供封面之外的新信息、建立强现场或显著提升首屏吸引力时使用。不要
为了模板完整生成“全文摘要图”，也不要让一张高大的概念图把真正的开头和证据推到
首屏之外。已有高质量人物照、结果对照或正文首图能够完成任务时，省略额外 Hero。

### Step 4: 用户确认（除非 --auto）

使用 宿主的聚焦提问工具 展示插图方案表格，让用户：
- 确认/删除/调整每个插图位置和类型
- 选项：「全部确认」「我来调整后继续」

### Step 5: 数据调研（如有数据图表类型）

如果方案中包含「数据图表」类型的插图：
1. 逐项调研每个数据主题，获取**带来源的精确数据点**
2. 汇总数据表格，展示给用户确认数据准确性
3. 确认后再生成图表

**数据图表的prompt必须包含：**
- 每个数据点的精确数值
- 图表底部标注数据来源（Sources: ...）
- 使用品牌色彩体系

### Step 6: 并行生成图片

确认后，使用 Task 工具并行处理每张图片：

**AI生图流程**：
- 优先调用当前宿主已经提供的图像生成工具或 Plugin 能力
- 若宿主只提供本地脚本，由使用者显式传入脚本路径；不得依赖某个客户端专属环境变量
- 输出到 `<doc_dir>/attachments/ill-<n>-<slug>.png`，并保留 prompt 与生成方式收据

Prompt 构建规则：
- 基于文章上下文生成详细英文 prompt
- **注入品牌风格**（从 Step 1 加载的 design-guide 提取关键词）
- 默认风格关键词：warm off-white background (#F9F9F7), terracotta (#CC785C) accents, charcoal (#181818) text, matte paper texture, editorial illustration style
- 避免文字/人脸（AI生图弱点）——数据图表除外
- 宽幅构图（适合文章内嵌）

**联网检索流程**：
- 使用 Task 工具并行搜索
- 优先官方素材、公开图表
- curl 下载到 attachments/ 目录
- 验证下载文件是有效图片（file 命令检查）

**数据图表流程**：
- 使用 Step 5 调研获得的精确数据构建 prompt
- prompt 中列出每个数据点的精确数值
- 图表底部必须标注来源
- 使用 `-q high` 生成更高精度

**程序化合成图流程**：
- 使用 HTML/CSS、SVG、Canvas 或等价确定性工具排版精确文字、图表和资料卡片
- 每个文本 run 必须声明正确 `lang`，并使用与该语言匹配且覆盖全部字符的显式字体栈
- 中日文并列或混排时拆成独立语言 run；禁止把日文字体放在简中 run 的首位，反之亦然
- 在截图或栅格化前执行 `references/text-rendering-safety.md` 的字体覆盖与实际字体门禁
- Chromium 页面可使用 `scripts/audit_html_fonts.py` 生成机器可读字体收据；`ok=false` 时不得交付图片
- 记录合成源、素材来源、请求字体、实际字体、语言和输出图片的对应关系

### Step 6.4: 文字渲染门禁（含文字图片必做）

1. 按语言 run 检查字符覆盖，任何正文字符缺字都必须先修复字体栈，不能依赖未知系统 fallback
2. 对最终截图所用的真实浏览器回读实际 PostScript 字体与 glyph count，不能只检查 CSS 声明
3. 纯简中或纯日文 run 默认只允许一套 CJK 字体；有意混植必须在方案和收据中逐项声明
4. `lang` 只负责语言语义和本地化字形选择，不会自动跳过字体栈首位的错误区域字体
5. 图片栅格化后 fallback 已固化，公众号、Markdown 或下游 CSS 无法修复；门禁必须发生在导出前

### Step 6.5: 图片质量校验

对每张下载/生成的图片，使用 Read 工具查看验证：
- **联网检索图**：确认内容匹配目标产品（非同名但不同的产品、非无关图片）
- **AI生图**：确认视觉主题与 alt 描述一致
- **程序化合成图**：确认字体收据 `ok=true`，并人工查看 CJK 字形、基线、标点和换行
- **所有图片**：记录像素尺寸、宽高比和按文章正文宽度渲染后的预计高度；单张图过高、
  上下留白显著或连续多张占据多个手机屏幕时，必须裁切、重排或删除。
- **过程 / 对照图**：只保留视觉上不同且推动理解的阶段，删除重复帧和过早出现的最终
  状态；统一子图视觉尺寸与间距，把真正变化的区域放大，背景保持中性，不额外套用会
  干扰比较的目标风格。
- **生成式人物图**：检查脸、身体、手指、服装、饰品与物件是否符合源图和真实世界；
  过程只展示真实发生过的调试状态，不为叙事补造畸形或失败帧。
- 不合格的图片重新搜索/生成

### Step 7: 组装输出

在原文档的指定位置插入图片引用：

Markdown 中写入一条标准图片引用，alt 描述读者需要的内容，路径使用实际生成文件；
例如 `!\[描述性 alt\]\(attachments/ill-N-slug.png\)`。

#### Caption 与图内文字

1. Caption 是面向读者的编辑文案，不是图片内容的机械复述。读者一眼可见的信息无需
   再写；没有证据、归属或理解任务时宁可不写 Caption。
2. 图内烧录文字、Decorator Caption 与 Markdown 图注只能保留一种。图片已经自带
   标题或说明时，删除外部重复图注；需要可访问性的信息留在 alt，不再作为第二份文案。
3. 过程图的文字只点出本质变化，例如“基于真实世界修复模型常识性错误”；不要为每
   张子图写长句解释肉眼可见的动作、数量和位置。
4. 来源与引申资料在对应位置低调呈现；多项资料逐项分行或分点，不堆到文章底部。

#### 精确插入定位规则（必须逐条检查）

Step 3 规划的是章节级粗略位置，Step 7 组装时必须精确到段落级。逐张图执行以下检查：

1. **先提后图**：图片必须插在其所配内容**首次被提及之后**，不得出现在内容之前。例：报告截图必须在报告被引用/讨论之后，不能在报告被提及的上一个章节末尾。
2. **不割裂语义单元**：以下结构视为不可分割的语义单元，图片不得插入其内部：
   - 连续引用块（多个 `>` blockquote 属于同一论述）
   - 递进/收束段落对（"A是什么...→ 所以A意味着..."）
   - 论点+论据（"**观点。** 具体展开..."）
   - 排比/并列结构（"第一...第二...第三..."）
3. **收束优先**：如果一个概念有明确的收束句（"会说，即会做。""数据不会说谎。"等金句/总结），图片应插在收束句**之后**而非之前。
4. **自检方法**：插入后，朗读图片前后各1-2段。如果读起来感觉"话说到一半被打断"，则位置错误，需下移到语义完整处。

文件命名规则：
- 图片：`ill-<序号>-<语义slug>.png`（如 `ill-5-arr-comparison.png`）
- 输出文档：原文件名加 `-illustrated` 后缀（如 `v5-illustrated.md`）

### Step 8: 完成报告

输出简要报告：
- 生成了 N 张插图（X 联网检索 + Y AI生图 + Z 数据图表 + W 程序化合成图）
- 输出文件路径
- 对含文字图片提供字体审计收据路径与实际字体摘要
- 用 Read 工具展示一张代表性图片预览

## 插图位置选择原则

1. **证据优先**：真实现场、聊天、结果和变化过程优先于装饰性概念图。
2. **Hero 可省略**：正文首图或第一组证据已经有吸引力时，不再叠加摘要型 Hero。
3. **移动端视觉预算**：同时看图片数量、宽高比、预计屏高、相邻空白与连续图片长度；
   没有固定“每多少字一张”或“每节至少几张”的配额。
4. **概念转换处**：只有图片能真正帮助换挡时才作为分隔，不用空泛配图切断论证。
5. **数据横比**：多个并列产品或概念优先一张清楚的对比图，而不是逐个配图。
6. **演变过程**：用最少的不同阶段说明变化；子图数量、尺寸和间距服从信息差异，
   不为凑齐网格复制帧。
7. **情绪高潮**：优先真实照片、对话或结果；生成式插图不能替代真实关系与现场。



## Execution boundary

自然语言请求即可触发；无需旧 slash 路径、参数插值或指定助手。明确解析当前请求中的
项目、目标文件、选项与输出位置；用当前宿主实际提供的文件、搜索、CLI 和浏览器能力。
项目依赖版本与外部 API 在执行时核实，不能假设示例是现行配置。随包脚本从 Skill 根解析，
业务文件从目标项目根解析。先读当前状态，保护已有未提交内容与其他任务的暂存区。
分析、预览请求保持只读；修改、提交、推送、部署和发布各依当前请求的明确范围执行。
不绕过保护、自动发送消息、强制结束用户进程或抢前台。失败保留可诊断原始错误。

## Composition

执行前读取 [能力组合](references/skill-composition.md)，按明确制品交接相邻能力。

## Runtime context (shared)

运行前读取本包 `skill.yaml` 与 [Profile 合同](references/user-profile.md)。优先级为当前请求、
项目上下文、本 Skill records、共享 preferences、brand/user Profile、安全默认值。
只读取声明字段；没有专用运行时的宿主可使用 `scripts/profile_store.py` 读取共享 Profile。
配置缺失只问影响结果的一个问题。用户明确要求长期保存的值通过该脚本原子写入，
报告实际路径；不保存推断、凭据或其他任务的资料。