baoyu-article-illustrator

文章配图

改编自 baoyu-article-illustrator，适用于 Hermes Agent 的工具生态系统。

分析文章，确定插图位置，并生成在 类型 × 风格 × 配色 上保持一致的图片。

适用场景

当用户要求为文章配图、为文章添加图片、为内容生成插图，或使用“为文章配图”“illustrate article”或“add images”等表达时，触发此技能。用户会提供一篇文章（文件路径或粘贴的内容），还可以指定类型、风格、配色或密度。

三个维度

维度	控制内容	示例
类型	信息结构	infographic、scene、flowchart、comparison、framework、timeline
风格	呈现方式	notion、warm、minimal、blueprint、watercolor、elegant
配色	配色方案（可选）	macaron、warm、neon — 覆盖风格的默认颜色

可自由组合：type=infographic, style=vector-illustration, palette=macaron。

也可以使用预设：edu-visual → 一次设置类型、风格和配色。参见 style-presets.md。

类型

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

风格

核心风格、完整风格库以及类型 × 风格兼容性，请参见 references/styles.md。

输出结构

{output-dir}/
├── source-{slug}.{ext}    # Only for pasted content
├── outline.md
├── prompts/
│   └── NN-{type}-{slug}.md
└── NN-{type}-{slug}.png

默认输出目录：

输入	输出目录	Markdown 插入路径
文章文件路径	{article-dir}/imgs/	imgs/NN-{type}-{slug}.png
粘贴的内容	illustrations/{topic-slug}/（当前工作目录）	illustrations/{topic-slug}/NN-{type}-{slug}.png

如果用户要求采用其他布局（例如图片与文章放在一起，或使用 illustrations/ 子目录），请遵照用户要求。

Slug：2-4 个词，使用 kebab-case。冲突时：追加 -YYYYMMDD-HHMMSS。

核心原则

• 可视化概念，而非比喻 — 如果文章使用了比喻（例如“电锯切西瓜”），应呈现其背后的概念，而不是字面画面。
• 标签使用文章中的数据 — 使用文章中的实际数字、术语和引文，而非通用占位内容。
• 提示词文件用于复现 — 每张插图都必须在生成图片前，将提示词保存到 prompts/ 目录下。
• 清除机密信息 — 写入任何内容前，检查源内容中是否包含 API 密钥、令牌或凭据。

工作流

- [ ] Step 1: Detect reference images (if provided)
- [ ] Step 2: Analyze content
- [ ] Step 3: Confirm settings (clarify tool)
- [ ] Step 4: Generate outline
- [ ] Step 5: Generate prompts
- [ ] Step 6: Generate images (image_generate)
- [ ] Step 7: Finalize

步骤 1：检测参考图片

如果用户提供了参考图片（内联粘贴的路径、附件或 URL）：

1. 对每张参考图片调用 vision_analyze，并提供路径或 URL，以及关于风格、配色、构图和主体的问题。通过 write_file 将返回的描述记录到 {output-dir}/references/NN-ref-{slug}.md。
2. 不要尝试使用 write_file / read_file 复制二进制文件 — 这些工具只能处理文本。如果需要在记录中保存本地副本，请使用 terminal（cp "$src" "{output-dir}/references/NN-ref-{slug}.{ext}"）。此技能本身无需读取二进制文件；根据视觉分析描述即可完成工作。
3. 由于 image_generate 不接受图片输入，因此在步骤 5 中，提示词会嵌入视觉分析描述。

完整流程请参见：references/workflow.md。

步骤 2：分析

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

读取源内容（文件路径 → read_file，或粘贴的文本），并使用 write_file 将分析写入 {output-dir}/analysis.md。

完整流程：references/workflow.md。

步骤 3：确认设置

使用 clarify 工具。将相互独立的问题放入同一个 questions 数组（最多 5 个）。如果用户的请求中已有答案，则跳过相应问题。

顺序	问题	选项
Q1	预设或类型	[推荐预设]、[备选预设]，或手动选择：信息图、场景、流程图、对比、框架、时间线、混合
Q2	密度	极简（1-2）、均衡（3-5）、按章节（推荐）、丰富（6+）
Q3	风格 （若在 Q1 中选择了预设则跳过）	[推荐]、极简扁平、科幻、手绘、编辑风、场景、海报
Q4	配色 （可选）	默认（风格配色）、马卡龙、暖色、霓虹
Q5	语言 （仅当文章语言不明确时）	文章语言 / 用户语言

不要连续提出超过 2-3 个 clarify 问题。如果用户已在请求中指定这些设置，则全部跳过。

完整流程：references/workflow.md。

步骤 4：生成大纲 → outline.md

使用 write_file 将 {output-dir}/outline.md 保存为包含 frontmatter（type、density、style、palette、image_count）且每幅插图各有一个条目的文件：

## Illustration 1
**Position**: [section/paragraph]
**Purpose**: [why]
**Visual Content**: [what to show]
**Filename**: 01-infographic-concept-name.png

完整模板：references/workflow.md。

步骤 5：生成提示词

阻断要求：生成任何图像之前，每幅插图都必须有已保存的提示词文件——提示词文件是可复现性的记录。

对每幅插图：

1. 按照 references/prompt-construction.md 创建提示词文件。
2. 使用 write_file 将文件保存到 {output-dir}/prompts/NN-{type}-{slug}.md，并添加 YAML frontmatter。
3. 提示词必须使用按类型区分、包含结构化章节（ZONES / LABELS / COLORS / STYLE / ASPECT）的模板。
4. LABELS 必须包含文章中的具体数据：实际数字、术语、指标、引文。
5. 根据提示词 frontmatter 处理参考资料（direct/style/palette）——对于 direct 用法，将参考资料的文字描述嵌入提示词中（因为 image_generate 不接收参考图像输入）。

步骤 6：生成图像

对每个提示词文件：

1. 调用 image_generate(prompt=..., aspect_ratio=...)。image_generate 会返回包含图像 URL 的 JSON 结果；它不会写入磁盘，也不接受输出路径。
2. 将提示词中的 ASPECT 映射到 image_generate 的枚举值：16:9 → landscape、9:16 → portrait、1:1 → square。自定义比例 → 最接近的命名宽高比。
3. 通过 terminal 将返回的 URL 下载到 {output-dir}/NN-{type}-{slug}.png（例如 curl -sSL -o "{output-dir}/NN-{type}-{slug}.png" "{url}"）。
4. 生成失败时，自动重试一次。

注意：底层图像生成后端由用户配置（默认：FAL FLUX 2 Klein 9B），不能通过 image_generate 由 Agent 选择。不要将模型名称写入提示词并期待系统据此路由。

步骤 7：完成

在相应段落之后插入 ![description]({relative-path}/NN-{type}-{slug}.png)。替代文本应为文章语言的简洁描述。

报告：

Article Illustration Complete!
Article: [path] | Type: [type] | Density: [level] | Style: [style] | Palette: [palette or default]
Images: X/N generated

修改

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

参考资料

文件	内容
references/workflow.md	详细流程
references/usage.md	调用示例
references/styles.md	风格图库 + 调色板图库
references/style-presets.md	预设快捷方式（类型 + 风格 + 调色板）
references/prompt-construction.md	提示词模板

注意事项

1. 数据完整性至关重要——绝不要总结、改述或更改源数据中的统计数字。“73% increase”应保持为“73% increase”。
2. 清除机密信息——在将源内容写入任何输出文件之前，检查其中是否包含 API 密钥、令牌或凭据。
3. 不要按字面意思描绘比喻——应将其背后的概念可视化。
4. 提示词文件是必需的——没有保存的提示词文件，就不能生成图像。该文件可让你稍后重新生成图像或切换后端。
5. image_generate 的宽高比——该工具支持 landscape、portrait 和 square。自定义宽高比会映射到最接近的选项。
6. image_generate 返回的是 URL，而非本地文件——在文章中插入本地图片路径之前，务必通过 terminal（curl）下载图片。
7. Agent 不得选择后端——image_generate 使用用户配置的模型（默认：FAL FLUX 2 Klein 9B）。不要在提示词中写入 "use <model> to generate this"，并期待它据此路由。