baoyu-article-illustrator

文章插图工具

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

用户输入工具

当此技能提示用户时，请按以下优先级选择工具：

1. 优先使用当前 Agent 运行时提供的内置用户输入工具，例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何同类工具。
2. 回退方案：如果没有此类工具，则输出带编号的纯文本消息，并请用户针对每个问题回复所选编号或答案。
3. 批量提问：如果工具支持每次调用提出多个问题，则将所有适用问题合并到一次调用中；如果每次只能提出一个问题，则按优先级逐个提问。

下文中对 AskUserQuestion 的具体引用仅为示例；在其他运行时中，请替换为对应的本地工具。

图像生成工具

此技能需要渲染图片时，请按以下顺序确定后端：

1. 当前请求指定的后端——如果用户在当前消息中指定了某个后端，则使用该后端。
2. 已保存的偏好——如果 EXTEND.md 将 preferred_image_backend 设置为当前可用的后端，则使用该后端。
3. 自动选择（偏好设置为 auto、未设置或固定的后端不可用时）：
   • Codex（imagegen）——首先检查可用技能／工具清单。如果其中列出了名为 imagegen 的技能，则表示你正在 Codex 中运行，必须使用该技能：通过 Skill 工具调用，并设置 skill: "imagegen"，传入已保存提示词文件的内容（以及符合 Codex imagegen 自身参数要求的输出路径和宽高比）。Codex imagegen 是该运行时的官方光栅图后端，优先级高于任何非原生技能（例如 baoyu-image-gen），除非用户明确指定了其他 preferred_image_backend。
   • 通过 codex exec 使用 Codex（codex-imagegen）——如果当前运行时未提供原生 imagegen 技能，但 codex CLI 位于 PATH 上且已登录 Codex，则通过 baoyu-image-gen --provider codex-cli 调用（优先）；如果 baoyu-image-gen 不可用，则直接调用随附的封装程序。详细信息、参数和运行时发现流程位于 references/codex-imagegen.md——仅在选择此分支时加载该文件。
   • Cursor（GenerateImage）——如果运行时提供原生 GenerateImage 工具，则表示你正在 Cursor 中运行，其优先级高于任何非原生技能，与 Codex imagegen 相同。需要特别注意两点：(a) 它没有宽高比参数——请在作为 description 传入的提示词中明确说明目标宽高比／尺寸；(b) 它不接受输出目录——图片会保存到工具管理的位置，因此生成后请将文件复制／移动到此技能预期的输出路径（例如 outputs/.../NN-xxx.png）。参考图片应放入 reference_image_paths。
   • 其他运行时原生工具——如果运行时提供其他原生图像工具（例如 Hermes image_generate），则以相同方式使用。
   • 否则，如果恰好安装了一个非原生后端（例如 baoyu-image-gen），则使用它。
   • 否则（存在多个非原生后端且没有运行时原生工具），请向用户询问一次——与其他初始问题合并提问。
4. 如果没有任何可用后端，请告知用户并询问接下来如何处理。

⛔ 绝不可用 SVG、HTML、canvas 或其他基于代码的渲染方式代替光栅图像生成。 Codex imagegen 自身的说明指出，当“输出应为位图素材，而非仓库原生代码或矢量图”时，应使用它。如果无法通过第 3 步确定光栅图后端，请转到第 4 步并询问用户——不得悄悄输出 SVG、编写内嵌 <svg> 标记或生成 HTML/CSS 艺术图作为替代。即使文章／章节看起来“像是图表”，也同样适用：调用此规则的使用者技能已确定它需要的是光栅图片。 ⛔ 绝不要通过在生成的位图上涂抹来修复渲染后的文字。 不要使用 ImageMagick、Pillow、Canvas、SVG、HTML/CSS、OCR 脚本或任何其他程序化叠加方式，遮盖、改写、擦除、描边或替换已生成插图中的标签、说明文字或任何其他文本。如果文字有误或不清晰，请使用修正后的提示词重新生成、重新绘制并减少或不添加图片内文字，或询问用户要保留哪个不完美的候选项。

设置 preferred_image_backend: ask 会强制每次运行都执行第 3 步提示，不受可用后端影响。用户可通过下方的 ## Changing Preferences 部分更改固定使用的后端。

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

上文中的具体工具名称（imagegen、GenerateImage、image_generate、baoyu-image-gen）仅为示例——请替换为遵循相同规则的本地等效工具。

批量生成策略

本次运行的所有提示词文件均已保存并验证后，默认分批生成图片。

优先顺序：

1. 如果所选后端有原生批处理／多任务接口，请使用该接口。每项任务都必须保留各自的提示词文件、输出路径、宽高比和直接参考图片。
2. 如果没有原生批处理接口，但运行时可以并行调用工具，则每次最多调度 generation_batch_size 张图片。默认值：4。当前消息中的明确用户请求（例如 --batch-size 4 或“并行4张一起生成”）优先于 EXTEND.md。
3. 如果既不支持原生批处理，也无法并行调用工具，则按顺序生成。

规则：

• 批次中的所有提示词文件都已写入磁盘前，绝不要开始生成首批图片。
• 失败的项目重试一次，不要重新生成成功的项目。
• 不要仅为并行渲染图片而使用子 Agent。仅在单独进行提示词迭代或创意探索时使用子 Agent。

确认策略

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

• 将明确的技能调用、文件路径、匹配的信号／预设和 EXTEND.md 默认值视为推荐输入。它们都不能授权跳过确认。
• 用户完成第 3 步之前，不要开始第 4 步或之后的步骤。
• 仅当当前请求明确要求跳过确认时才跳过，例如：“直接生成”“不用确认”“跳过确认”“按默认出图”或含义相同的措辞。
• 如果用户明确跳过确认，请在下一条面向用户的更新中说明假定的类型／密度／风格／配色／语言／后端，然后再生成。

参考图片

用户可以通过 --ref <files...> 提供参考图片，也可以提供文件路径／在对话中粘贴图片。参考图片用于指导特定插图的风格、配色、构图或主体。

完整的检测、存储和处理规则见 references/workflow.md（第 1.0 步保存至 references/NN-ref-{slug}.{ext}；第 5.3 步按每张插图处理用途 direct | style | palette）。当所选后端支持批量输入时，每个提示词文件 references: 前置信息中用途为 direct 的条目都应传入其批量请求载荷，以便后端传递这些参考图片（例如，baoyu-image-gen 支持为每项任务指定 ref）。

三个维度

维度	控制项	示例
类型	信息结构	信息图、场景、流程图、对比、框架、时间线
风格	呈现方式	notion、温暖、简约、蓝图、水彩、优雅
配色	配色方案（可选）	马卡龙、温暖、霓虹 — 覆盖风格的默认配色

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

也可使用预设：--preset edu-visual → 一个标志即可设置类型 + 风格 + 配色。参见 风格预设。

类型

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

风格

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

工作流

- [ ] Step 1: Pre-check (EXTEND.md, references, config)
- [ ] Step 2: Analyze content
- [ ] Step 3: Confirm settings (AskUserQuestion)
- [ ] Step 4: Generate outline
- [ ] Step 5: Generate images
- [ ] Step 6: Finalize

步骤 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	用户主目录

结果	操作
找到	阅读、解析并显示摘要
未找到	⛔ 运行 first-time-setup

完整流程：references/workflow.md

步骤 2：分析

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

重要：将隐喻转化为对底层概念的可视化，而不是照字面呈现。

完整流程：references/workflow.md

步骤 3：确认设置 ⚠️

硬性门槛：根据确认政策，此步骤为必需 — 用户在此处确认（或在当前请求中明确选择不确认，例如说“直接生成”或同义表述）之前，不得开始步骤 4 及后续步骤。

仅进行一次 AskUserQuestion，最多 4 个问题。Q1-Q2 为必答项。若未选择预设，则 Q3 也为必答项。

问题	选项
Q1：预设或类型	[推荐预设]、[其他预设]，或手动选择：infographic、scene、flowchart、comparison、framework、timeline、mixed
Q2：密度	minimal（1-2）、balanced（3-5）、per-section（推荐）、rich（6+）
Q3：风格	[推荐]、minimal-flat、sci-fi、hand-drawn、editorial、scene、poster、Other — 若已选择预设则跳过
Q4：配色	Default（风格配色）、macaron、warm、neon — 若预设包含配色或已设置 preferred_palette，则跳过
Q5：语言	当文章语言 ≠ EXTEND.md 中的设置时

完整流程：references/workflow.md

步骤 4：生成大纲

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

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

完整模板：references/workflow.md

步骤 5：生成图片

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

1. 对于每幅插图，按照 references/prompt-construction.md 创建提示词文件
2. 使用 YAML frontmatter 保存到 prompts/NN-{type}-{slug}.md
3. 提示词必须使用带有结构化章节（ZONES / LABELS / COLORS / STYLE / ASPECT）的特定类型模板
4. LABELS 必须包含文章专属数据：实际数字、术语、指标、引述
5. 禁止在未先保存提示词文件的情况下，向 --prompt 传入临时内联提示词
6. 根据顶部的 ## Image Generation Tools 规则选择后端：使用可用的后端；如果有多个，请询问用户一次。每个会话中，在生成图片之前只执行一次。
   • codex-imagegen 调用方式：当规则指定使用 codex-imagegen 时，请参阅 references/codex-imagegen.md 中的调用约定（优先使用 baoyu-image-gen --provider codex-cli 路径、运行时包装器发现、参数说明、标准输出架构、批处理语义）。
7. 执行策略：按照 ## Batch Generation Policy 的规定分批生成：优先使用后端原生批处理，其次使用运行时并行工具调用，最后才依次生成。默认批次大小为 4，除非 EXTEND.md 或当前请求另有规定。
8. 按提示词 frontmatter 处理参考项（direct/style/palette）
9. 如果 EXTEND.md 已启用，则添加水印
10. 根据已保存的提示词文件生成；失败时重试一次

完整流程：references/workflow.md

步骤 6：完成

在段落后插入 ![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

输出目录

输出目录由 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/usage.md	命令语法
references/styles.md	风格库 + 调色板库
references/style-presets.md	预设快捷方式（类型 + 风格 + 调色板）
references/prompt-construction.md	提示词模板
references/config/first-time-setup.md	首次设置

更改偏好设置

EXTEND.md 位于 Step 1.5 中列出的第一个匹配路径。可通过以下三种方式更改：

• 直接编辑 — 打开 EXTEND.md 并更改字段。完整架构：references/config/preferences-schema.md。
• 交互式重新配置 — 删除 EXTEND.md（或询问“reconfigure baoyu-article-illustrator preferences”/“重新配置”）。下次运行时会重新触发首次设置。
• 常见的单行修改：
  • preferred_image_backend: auto — 默认值；优先使用运行时原生工具，若只有一个已安装的后端则回退到该后端，只有存在多个非原生后端时才会询问。
  • preferred_image_backend: codex-imagegen — 固定使用 Codex 内置工具。
  • preferred_image_backend: baoyu-image-gen — 固定使用 baoyu-image-gen 技能。
  • preferred_image_backend: ask — 每次运行时确认后端。
  • generation_batch_size: 4 — 运行时支持并行生成调用时，默认并发渲染的图像数量。
  • preferred_type: infographic、preferred_style: notion、preferred_palette: macaron、language: zh。
  • default_output_dir: imgs-subdir — 生成的图像相对于文章的写入位置。