baoyu-article-illustrator实战：为长文安排有解释力的插图

文章配图的难点不是“画得漂亮”，而是知道哪一段值得用图解释。baoyu-article-illustrator 先分析结构、决定插图位置，再组合信息类型、绘制风格与配色，最后把图片引用插回 Markdown。

本文基于固定提交源码核对；案例是操作示例，非付费服务或账号实测。本文没有实际生成图片，也不承诺模型效果、耗时或费用。

一、适用场景与边界

适合已有正文的技术解释、操作教程、方法论文章和叙事文章。例如一篇缓存教程，真正需要图解的通常是读写路径、失效过程和方案对比，而不是每个小标题都放一张装饰图。

技能将设计拆成三个维度：Type 决定信息组织方式，Style 决定视觉表现，Palette 可覆盖默认颜色。类型包括 infographic、scene、flowchart、comparison、framework、timeline。同一篇文章可以保持风格一致，但让不同插图分别承担比较、流程或场景任务。

这里的流程图、框架图仍然由图像后端生成位图，不等于可精确编辑的工程图。需要逐字可控、连接关系可审查的 SVG 时，应改用技术图解。源码还明确禁止在缺少图像后端时，偷偷用 HTML、SVG 或 Canvas 代替约定的位图出图。

二、前置依赖与按需安装

需要支持 Agent Skills、能读取正文和写入附件的 Agent 环境，以及至少一个可用图像后端。后端可以是运行时原生能力，也可以是单独安装并配置的图片生成后端。安装配图技能本身不会自动获得服务额度、API Key 或账号授权。

仓库 README 核实过的安装入口如下，本文只展示，不执行：

1	npx skills add jimliu/baoyu-skills --skill baoyu-article-illustrator --agent codex

Claude Code 用户可将 codex 替换为 claude-code。

安装时仅选择 baoyu-article-illustrator；缺少后端时再按需补齐。该命令没有锁定本文提交，安装后要检查版本差异。若使用固定提交的源码目录，Codex 项目级方式是把完整技能目录复制或链接到项目的 .agents/skills/baoyu-article-illustrator/，不能只复制 SKILL.md，因为工作流和模板位于 references/。

三、输入、输出和修改范围

输入可以是 Markdown 文件、粘贴文本，以及用户拥有使用权的参考图片。文件输入能计算准确的相对附件路径；粘贴内容则会保存源内容，默认进入 illustrations/{topic-slug}/。

常规文件输入默认将内容保存到正文目录下的 imgs/：

outline.md：插图编号、插入位置、作用和视觉内容。
prompts/NN-{type}-{slug}.md：每张图的完整提示词。
NN-{type}-{slug}.png：最终图片。
正文中的 ![描述](imgs/图片文件名.png)：普通 Markdown 图片引用。

输出目录由 default_output_dir 控制，还支持与文章同目录、illustrations/ 子目录或独立主题目录。不要把“输出目录”误认为“绝不改正文”：最终步骤会插入图片引用。对正式笔记使用前，应明确允许修改哪一个正文文件，并保留原稿。

四、可复制的 Agent 请求

以下是自然语言请求，不是终端命令。替换为真实文件路径后再发送：

请使用 baoyu-article-illustrator 处理我提供的《缓存设计入门.md》。
受众是刚接触后端开发的工程师，只为能降低理解成本的段落配图。
先检查偏好和可用图像后端，说明哪些内容会离开本机。
推荐三张图：读取路径、缓存失效过程、两种更新策略的对比。
优先使用统一的简洁技术风格，中文标签，不新增原文没有的数据。
先让我确认类型、密度、风格、配色、语言和后端，再生成。
所有最终提示词先落盘，图片放在正文旁的 imgs 子目录。
仅允许插入图片引用，不改动原文论点；不要发布文章。

若当前只想评估方案，可以再补一句“本轮只讨论插图计划，不调用图像后端、不修改正文”。这属于用户限定执行范围，不是虚构的 CLI 开关。

五、案例：把缓存教程拆成三张解释图

第一步，检查偏好。 工作流先查找 EXTEND.md。未找到时首次设置是阻塞步骤，不能跳过去直接出图。先确定语言、输出位置和后端偏好，可避免图已经生成才发现落在错误目录。

第二步，分析正文。 将教程归为技术说明，提取“命中时发生什么”“失效后如何恢复”“策略之间有何取舍”三条主线。若原文把缓存比作“仓库”，图应解释访问层级，而不是机械画一座仓库；源码强调应可视化比喻背后的概念。

第三步，确认设计。 可以把读取路径设为 flowchart、更新策略设为 comparison，保持统一风格。密度 balanced 的建议范围是三至五张；本例明确三张即可。文件路径、已有偏好和自动推荐都不代表用户已经授权跳过确认。

第四步，保存可追溯材料。 在 outline.md 标注每张图插在什么段落之后，以及它解决哪个理解障碍。每张最终提示词都应独立落盘，按类型模板记录区域、标签、颜色、风格与比例。正文中真实出现的术语和数字才能进入标签，不能为了让图看起来专业而编造指标。

第五步，生成并回填。 选好后端后，先确认本批次提示词全部存在，再使用后端批处理或运行时并行能力。默认并行批量为四，不代表必须凑四张；失败项重试一次，不重做已经成功的图片。最后把普通 Markdown 引用插到约定段落后，并报告成功数量与未完成项。

第六步，人工读图。 检查箭头方向、标签含义、文字是否溢出。若图写错“缓存命中”，应修改提示词并用新输出路径重生成，保留错误候选作对照，不能用程序涂掉错误文字再覆盖正确文字。

六、配置与后端选择

偏好文件按“项目 → XDG → 用户目录”查找，命中第一个即停止：

.baoyu-skills/baoyu-article-illustrator/EXTEND.md
${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-article-illustrator/EXTEND.md
$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md

可讨论的已核实字段包括 preferred_type、preferred_style、preferred_palette、language、default_output_dir、generation_batch_size 和 preferred_image_backend。例如让 Agent 保存“中文、附件放 imgs、后端每次询问”，对应 language: zh、default_output_dir: imgs-subdir、preferred_image_backend: ask。

后端选择先看当前请求的明确指定，再看保存偏好，然后才自动发现。自动路径优先运行时原生工具；没有原生能力、却存在多个非原生后端时，应询问用户。参考图的 direct、style、palette 三种用途不同：直接传图需要后端支持，抽取风格和颜色则应写入提示词，不能声称后端实际看过未传入的图片。

七、验收清单与排错

[ ] 每张图都能对应一个明确段落和解释目标，没有重复表达。
[ ] 原文数字、专有名词、关系方向与图中文字一致。
[ ] 生成前已有提示词文件，失败重试和修改均可追溯。
[ ] 正文只发生批准的修改，图片引用使用相对路径。
[ ] Obsidian 阅读视图与 Hexo 预览均能找到附件。
[ ] 发布目录不包含密钥、参考图中的隐私信息或无关备份。

找不到后端：先区分“技能安装完成”和“服务已配置可用”，不要把缺少 API Key 当成文章分析失败。中文难读：减少图内长句，修正提示词后重生成，而非程序覆盖文字。附件在 Obsidian 可见、博客不可见：检查 Hexo 发布链是否复制 imgs/，不能只同步 Markdown。偏好不生效：检查项目级配置是否覆盖了用户目录中的修改。