我不想安装 10 个 AI 配图 Skill，所以自己写了一个「智能配图路由器」

最近我在整理博客里的 AI Skill。

原本想法很简单：文章写完没图，就去 GitHub 找几个能自动配图的 Skill。

结果找着找着，事情开始不对劲。技术手绘有一个，小黑隐喻有一个，微缩场景有一个，火柴人有一个，水彩还有一个。继续找下去，我大概真能给每一种画风装一个。

可文章写完以后，到底该调用哪个？

一篇讲 Git 工作流的文章，拿水彩画不太对劲；一篇项目踩坑复盘，硬塞一个架构图，又会显得像在补 PPT。更麻烦的是，同一篇文章里随手调用几个 Skill，很容易变成一张技术手绘、一张卡通、一张赛博蓝图。图倒是有了，文章像拼出来的。

我研究了 11 个配图项目；它们并不等于 11 套预设画风。最终 Router 提供 9 个可直接指定的风格、一个 Visual IP 扩展位，以及 Diagram 这条功能型路径。

于是我做了 `yf-article-illustrator`。它现在是 v1.4.0。它不只接 Markdown，也能把 HTML、TXT、结构化 JSON 和已经完成的聊天正文，先归一成同一种文章模型，再做“配图决策”。生成图片仍然是最后一步。

这篇不想复述 README。我想讲讲它是怎么从“给文章找图”变成一个 Router 的。

怎么安装：也可以直接让 AI Agent 去装

本地安装很朴素：克隆仓库，再把整个 `yf-article-illustrator/` 目录放进 Codex 的 skills 目录，刷新技能列表即可。

git clone https://github.com/yf122233455-stack/yf-article-illustrator.git
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R ./yf-article-illustrator "${CODEX_HOME:-$HOME/.codex}/skills/"

如果你不想手动找目录，可以把下面这句话直接交给你的 AI Agent：

请帮我安装这个 Skill：
https://github.com/yf122233455-stack/yf-article-illustrator

先阅读 README.md 和 SKILL.md。确认我当前使用的 Skills 目录；安装后检查 SKILL.md、references/ 和 styles/ 是否完整，最后告诉我最终安装路径以及怎么调用。

我会建议 Agent 装完后至少跑一次测试，再开始用。当前版本的完整回归是 33 / 33 通过；测试命令和覆盖范围在文章后面。

怎么用：一句话可以跑，复杂一点也能控制

最短的调用是：

使用 $yf-article-illustrator 为 article.md 自动配图。

它会先做机会筛选，默认不按字数凑图。想先看方案、暂时不生图：

使用 $yf-article-illustrator 分析 article.md，先不要生成图片。
输出 Shot List 和完整 Prompt。

明确想要手绘技术图和 4 个图点时，可以这样说：

使用 $yf-article-illustrator 为 article.md 配图。
style: technical-handdrawn
count: 4
explain-routing: true

v1.4 推荐走统一入口 `scripts/article_io.py`：它会先写不可变的 `article.source.md`，再把最终文章、图片、Prompt、Diagram 源文件、Shot List 与 Manifest 收进 `outputs/articles/<article-slug>/`。原始输入不覆盖，聊天也不再只是一次性的上下文。这篇文章本身也是先固定正文，再生成 Shot List、Prompt 和 4 张正文插图，最后落成 Markdown。

先承认一个尴尬：文章不缺图，缺的是判断

很多配图工具的默认动作都是“给我文章，出 N 张图”。这很顺手，也很危险。

因为“这段文字旁边有块空白”不是图片理由。一段背景介绍、一个普通定义、几句没有关系结构的结论，配图通常只是在占版面。读者看完不会更懂，还得花注意力确认这张图和文字有什么关系。

所以路由器的第一道门不是选风格，而是找 Visual Opportunity。它会看一段内容有没有值得可视化的锚点：概念之间的关系、流程、前后状态变化、层级、比较、故事现场，或者一个很适合记住的比喻。然后从信息增益、读者可能卡住的地方、画面是否独特、段落是否重要、是否和邻近内容重复几个角度打分。分不够，结果就该是 `no-image`。

我挺喜欢这个“不画”的能力。它让 Skill 终于不像一个勤快但不看场合的插画机。

路由的第一个分岔：插图，还是图解

这件事一开始我想得太简单，以为每一段都可以用生成图解决。后来发现，只要内容里有读者必须相信的箭头、顺序、组件关系，图就不能靠“看起来差不多”。

比如“文章 → 机会检测 → 选类型 → 锁风格 → 生成或写 Prompt → QA → 插回 Markdown”这条链路，画成一张手绘风格的流程图当然可以；但路由器内部遇到严格架构、数据流或分支时，应该先选 Diagram，再选 Mermaid、Excalidraw 之类的后端。画风可以友好，关系不能含糊。

在 v1.4.0 里，Diagram 仍然是信息类型，不是 SVG 的同义词。它没有自己的 Style，却继承文章的 Visual DNA：背景、调色板、线条性格、间距和强调方式都要和正文插图相认。语义则由不可变的 `semantic_spec` 管：节点、边、分组、方向和标签不能因为换了 Mermaid、SVG 或 Excalidraw 就变掉。SVG 仍不是默认答案，只有节点、边、文字密度和交叉风险都很低时才有资格考虑。

flowchart LR
    A[Markdown 文章] --> B[Visual Opportunity Detection]
    B --> C{值得画？}
    C -- 否 --> D[no-image]
    C -- 是 --> E{信息类型}
    E --> F[插图：锁定画风]
    E --> G[Diagram：选后端]
    F --> H[生成 / QA / 插回 Markdown]
    G --> H

上面这种关系是精确的，所以我宁可它是 Mermaid，也不要求它长得像一张“AI 图”。图解是用来让人核对逻辑的。

一篇文章只锁一种插图画风

我后来给路由器加了一个很笨但有效的规则：先在文章级别选定 `primary_illustration_style`，再让每张普通插图继承它。

技术教程通常是 `technical-handdrawn`，项目复盘更可能是 `miniature-scene`，偏方法论的文章可能选 `minimal-character`。这不是硬编码的美学偏见，而是先看文章类型、技术密度、叙事密度和语气，再锁住一个主要语言。Diagram 不再被当成另一种画风；它没有独立 Style，但也得继承同一套 Visual DNA。

这个规则解决的是一个很朴素的问题：读者翻页时，得觉得这些图属于同一篇文章。

这篇文章本身是技术开发复盘，但核心在解释一个路由系统，所以我按 `technical-handdrawn` 锁了手绘技术风格，选近白暖纸、深灰线条，配浅蓝、鼠尾草绿、浅桃和浅紫。下面三张插图都沿用这套基调；Mermaid 图的语义不变，视觉上也继承这套 DNA。

可以指定哪些风格？这里把内置风格一次看完

除了 `style: auto`，也可以在调用时写 `style: <名称>`。现在有 9 个可直接指定的内置风格；下面用同一个“文章如何找到合适的图”主题做样式预览，方便横向看出区别。真正使用时，Router 会先看文章结构，不建议为了图好看而反过来改内容。

technical-handdrawn

适合技术教程、概念和解释型文章。线条有一点手工感，但关系清楚，短标签够用。

minimal-character

适合方法论和抽象概念。一个匿名极简人物必须在画面里做关键动作，不是站在旁边当装饰。

miniature-scene

适合项目复盘、Bug、部署压力和开发故事。它把冲突放进一个小型真实场景里。

watercolor-sketch

适合随笔、旅行、城市生活和需要情绪的文章。它不该承担严格架构或精确流程。

editorial

适合观点、趋势与深度分析。它用有限色彩和抽象几何讲一个内容相关的隐喻。

stick-figure

适合初学者解释和简单比较。信息优先，精致程度靠后。

clean-infographic

适合数据、比较、框架和短摘要。遇到必须精确的箭头与节点时，仍应改走 Diagram。

knowledge-sketch

适合教学、学习笔记与章节回顾。它像一页干净的知识笔记，不该装下一整本教材。

xiaohei

小黑是当前新增的显式选择风格，适合中文文章中的概念隐喻和工作流。它不会被 `style: auto` 默认选中；想用时要明确写 `style: xiaohei`。画面是纯白底、黑色小黑角色和少量橙红蓝批注，重点依旧是动作，不是吉祥物摆拍。

还有一个 `visual-ip`，它不是现成画风，而是用户明确提供原创角色、性格、色彩和允许动作后才启用的扩展位。我没有给它生成默认样图，避免把它误当成某个现成 IP；也不建议从公开角色或创作者风格推导。

最后的兜底，不是报错，是把可执行的计划留下来

现实里，图片后端并不总在。缺权限、网络出问题、当前环境没有模型，都很常见。

我不想让一次渲染失败把文章工作流卡死，所以有了 `prompt_only` fallback。即使不生成像素，路由器还是会落下 `article.source.md`、`shot-list.md`、每张图的 Prompt、`manifest.json`，以及需要图解时的源文件。之后换个有生图能力的环境，可以接着跑，不用再从文章里猜一遍“刚才到底想画什么”。

统一流程会把最终文章写为 `article.md`、`article.html` 或 `article.json`；老的 Markdown 插入流程仍会生成独立的 `<article-stem>.illustrated.md`。无论走哪条路，稳定源稿都不覆盖。

我确实跑了一遍测试，这次是 33 / 33

写这篇时，我重新检查了本地项目的 `README.md`、`SKILL.md`、路由规则、QA 脚本、验收文档和测试。版本是 v1.4.0。

我实际执行了：

python3 -m unittest discover -s tests -v

结果是 33 / 33 通过。它不只测旧 Router：还覆盖 Existing Article、Write Then Illustrate、预写作视觉计划、正文稳定门禁、Canonical Article Model、多格式输入、不可变 Source of Truth、Prompt-only 落盘、HTML / JSON 最终输出，以及 Styled SVG、Mermaid、Excalidraw 与 Markdown 插入。

这组测试解决了一个我很在意的问题：Diagram 可以没有独立 Style，但不能变成没有视觉责任的例外。换了后端，语义不许漂；换了文章，视觉也不能散。

现在我不再收集 Skill 了

我还是会继续看新的配图 Skill。不同视觉语言都有用，手绘技术图也很适合中文技术文章。但我的安装顺序变了：先问它擅长解决哪一种内容，再决定要不要接到 Router 后面。

`yf-article-illustrator` 目前不是一个万能生成器，它更像一个很克制的调度员。该不画时不画；该画关系时用图解；该画氛围时再用插图；而一篇文章最终只说一种视觉语言。

这比再装十个 Skill 安静多了。

项目：[`yf-article-illustrator`](https://github.com/yf122233455-stack/yf-article-illustrator) · 当前本地版本：v1.4.0