AI agent skill · by @cat-xierluo

Svg Book Illustrator

书籍/文章 SVG 配图生成工具，专注于架构图、流程图、层次图等专业技术配图。当用户需要为书籍章节或正式文章生成配图、创建架构图/流程图/层次图，或提到"章节配图"、"书籍插图"、"架构图"、"流程图"时使用此技能。

Archived 2026-10-23 · Source updated 2026-10-11 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

# SVG Book Illustrator

为书籍章节和正式文章生成简洁专业的 SVG 技术配图。

> 本 Skill 生成**静态 SVG**，直接嵌入 Markdown 文件（`<svg>` 标签），风格为简洁专业、透明背景 + 按模板语义分类配色（v1.7.0：层级类 layer/tree/金字塔走 G1-G4 灰度梯度；多样性类 flow/matrix/hub/cycle 走 P1-P8 多色调色板），适合纸质出版。

## 快速开始

```
/svg-book-illustrator @path/to/chapter.md
```

## 核心工作流程

### 第一阶段：分析章节，规划插图

1. 读取章节 Markdown 文件
2. 如果 `references/diagram-catalog.md` 有当前章节的预定义插图，匹配之
3. 扫描章节内容，识别适合配图的位置：
   - 架构描述处（"X 层"、"体系"、"架构"等）
   - 流程描述处（"步骤"、"流程"、"阶段"等）
   - 对比描述处（"vs"、"对比"、"前后"等）
   - 层次描述处（"层级"、"分类"、"金字塔"等）
   - 循环描述处（"循环"、"迭代"、"闭环"等）
   - 生态/关系描述处（"生态"、"要素"、"关系"等）
   - 多维数值对比描述处（"维度"、"能力评估"、"理论 vs 实际"、"国内外对比"、"模型适配"等）→ radar
   - Skill 介绍/结构描述处（"Skill"、"SKILL.md"、"三件套"、"references/scripts"、"输入→输出"等）→ skill-card
   - 多角色/多主体时间推进描述处（"时间轴"、"多角色"、"推进"、"节点"、"诉讼时效"、"案件流程"等）→ timeline-lane
   - 两维交叉对照描述处（"风险×条款"、"特征矩阵"、"覆盖度"、"交叉对照"、"评估表"等）→ matrix-grid
   - 三分类/三版本对仗描述处（"三种"、"三类"、"三栏"、"三方案"、"三种打法"等）→ three-col
4. 在合适位置插入占位符 `[[FIG:N:简要描述]]`（N 从 1 开始编号）
5. 列出所有规划的插图（类型、位置、描述），除非用户明确要求先确认，否则继续生成 SVG

**插图密度**：每章「一节一张」为基准，数万字章节 6-8 张，宁精勿滥；纯 walkthrough / 总结节可省图避免冗余。密度指标：**图/节 ≥ 0.7、图/万字 ≥ 0.8**，低于判「偏少」并提示补图位置（详见第四阶段 + `references/review-checklist.md`）。

### 第二阶段：生成 SVG

完成插图规划后，逐张生成：

1. 根据插图描述选择布局模板（flow / layer / matrix / hub / tree / cycle / radar / skill-card / timeline-lane / matrix-grid / three-col，或组合模板）
2. 读取 `references/layout-templates.md` 获取模板规范
3. 按 `references/style-guide.md` 的设计规范生成 SVG 代码
4. 在 `<svg>` 根写入当前项目唯一的 `data-figure-id="fig-chNN-sN-NN"`；模板中的 `fig-template-*` 仅为示例，落稿前必须替换
5. 将 `<svg>` 标签嵌入 Markdown，替换对应占位符
6. 在 SVG 下方添加图注：`**图 N-X：图标题**`

### 第三阶段：归档

生成完成后，提取所有 SVG 到独立文件：

```bash
python scripts/extract_svgs.py path/to/chapter.md --output output/figures/
```

### 第四阶段：审查与验收（必须过四道门禁）

生成 + 嵌入后，逐章过审查门禁，详见 `references/review-checklist.md`：

**① 配图密度审查**：图/节 ≥ 0.7、图/万字 ≥ 0.8；低于判「偏少」，列出可补图的小节。跨章均衡——相邻章密度不宜骤变（认知/入门篇图密度不应远低于方法/实战篇）。

**② 图-正文论点一致性审查**：每张图回溯所在小节，核对节点数 / 层级名 / 流程方向 / 对比维度 与正文表述一致；替换 mermaid / ASCII 图时原信息（节点、关系、标注）不丢失；图注准确概括图内容，不夸大不遗漏。

**③ 字宽/坐标硬算自检（v1.8.5+，先于视觉目检）**：生成器产出后，按 **CJK≈Fpx/字、Latin≈0.55Fpx/字** 估算文字宽度 ≤ 容器宽，相邻元素 y 差 ≥ 20px，viewBox H 足够——**计算闸**，防视觉目检对"轻微溢出/贴近"漏检（v1.8.5 radar 图例重叠、three-col 子卡片溢出两例均靠此抓出）。详见 `references/review-checklist.md` §③。

**④ 视觉目检（多模态渲染后眼检）**：SVG 用受控字体渲染为 PNG（快速预览运行 `python3 scripts/render_svg.py input.svg output.png`；高 DPI 运行 `node scripts/svg2png.js input.svg output.png 300`）后，用多模态模型逐张查——文字不溢出容器、框不重叠（间距 ≥24px）、箭头落位方向正确、语义线未被误删、分叉连续、标签卡与编号清楚、字号可读（节点≥16px 副≥12px）、黑白可辨、整体美观留白合理。发现问题回改 SVG 坐标，复检直到目检通过。

> **多模态生产提示**：若环境支持图像理解，④ 必须真正"看"渲染图，不能只靠 xmllint / rsvg 无警告间接验证——语法通过 ≠ 布局美观，溢出/重叠/箭头错位只有肉眼（或多模态模型）能发现。但视觉目检对"轻微溢出/贴近"易判 OK，故须先过 ③ 字宽硬算自检。

**形状包含窄语义（v1.8.10+）**：默认把 shape/shape 包含或重叠当作待修布局问题，先改坐标，不得用 `data-overlap-role="decoration"`、`data-allow-overlap` 或任意自造 role 掩盖。只有外层 area shape 确实承担“面板承载内层信息卡”等容器语义时，才在外层写单图唯一的安全原生 `id`、`data-overlap-role="container"`、明示承载关系的 `data-overlap-note` 与可静态证明非透明的 hex/rgb/hsl `fill`；namespaced 假属性、透明/继承/paint server/零 opacity 容器和孤立 note 都无效。该声明只是让意图可审计，不证明几何正确；最终必须由 writing-reviewer v0.16+ render gate 以真实浏览器几何复核，并在 evidence 中记录实际命中的 outer / inner / reason。详见 `references/style-guide.md` §六与 `references/review-checklist.md` §⓪/④。

**生产器契约回归（v1.8.9+）**：修改 `scripts/gen-*.py` 或 `references/layout-templates.md` 后，必须运行：

```bash
python3 -m unittest discover -s scripts/tests -p 'test_*.py' -v
```

只有退出码为 0 才能进入合并候选。该测试实际执行全部生成器，并检查模板文档中的全部 SVG 代码块；viewBox 必须严格为 `0 0 720 H`，根 `width` 必须为 720、`height` 必须等于 H；`data-figure-id` 必须存在、格式安全且在同一批产物中不重复；XML、`<style>`、元素 `style=`、任一元素的 `font-family`、class/CSS 变量和背景矩形任一不合规都会失败。任何 `data-overlap-role` 也必须严格满足上面的 `container + 单图唯一原生 id + 明示承载关系的 note + 外层 area shape + 非透明 hex/rgb/hsl fill` 窄契约；namespaced 属性、孤立 note、继承/透明/paint server fill、`decoration` 与自造 role 直接失败。

**生产身份契约（v1.8.9+）**：下游 review / render inventory 以 SVG 根的 `data-figure-id` 绑定跨轮 finding 与渲染证据，不能再依赖“第几张图”或文件遍历顺序。5 个生成器默认从输出文件 stem 取稳定 ID，也支持显式指定：

```bash
python3 scripts/gen-radar.py figures/fig-ch03-s2-01.svg --figure-id fig-ch03-s2-01
```

安全值只允许 1–128 位字母、数字、点、下划线或连字符。写入书稿前必须使用项目内唯一的 `fig-chNN-sN-NN`；默认 stem 只是便捷值，不能替代项目级唯一性检查。`fig-template-*` 只用于模板自身，禁止原样进入书稿。本契约只约束 v1.8.9+ 新生成或新落稿的 SVG，不要求回改历史书稿；历史资产是否迁移由项目单独决策。

仓库内 `.github/workflows/svg-book-producer-contract.yml` 会在本 Skill 或工作流自身发生 PR 改动，以及相关改动推入 `main` 时自动运行同一命令。没有明确通过的 `Source producer contract` check，不应把生产器改动视为可合并。该 CI **只证明源 SVG 生产契约**，不替代受控字体渲染、像素等价验证或多模态视觉目检。

**受控字体渲染（v1.8.9+）**：源 SVG 为保证 Markdown/Obsidian 兼容，不嵌 `<style>` 或字体栈；导出工具统一读取单一权威源 `assets/render-fonts.css`：

```bash
# 快速预览（librsvg；固定外部 CSS + 宽 720，不指定高度）
python3 scripts/render_svg.py input.svg output.png

# 高 DPI（Puppeteer/Chrome；注入同一外部 CSS）
node scripts/svg2png.js input.svg output.png 300

# 修改字体接线、身份元数据或 SVG 生成器后：逐像素比对两类基线
python3 scripts/verify_render_font_equivalence.py
```

禁止用裸 `rsvg-convert` 结果作为验收证据：它会按环境默认字体渲染，已实测产生 serif 退化和像素漂移。浏览器预览可继承宿主字体，但正式导出/验收必须走上述受控入口。像素等价脚本同时比较“旧内嵌字体 vs 外部字体”和“无 ID vs 有 ID”两组基线；它是本地渲染回归证据，需要机器已有 `rsvg-convert` 与 ImageMagick，不属于只校验源码契约的 GitHub Actions check，也不替代逐图视觉目检。

---

## 布局模板

13 种布局模板（11 种基础 + 2 种组合），详见 `references/layout-templates.md`。

| 模板 | 适用场景 | 典型元素数 |
|------|---------|-----------|
| **flow** | 流程图、步骤图、管道图 | 3-5 个节点（水平≤4） |
| **layer** | 层次架构、分层堆叠 | 3-4 层 |
| **matrix** | 前后对比、并排比较 | 2 列 |
| **hub** | 中心辐射、生态关系 | 1 核心 + 4-8 外围 |
| **tree** | 层级结构、组织图、金字塔 | 3 层 |
| **cycle** | 循环流程、迭代闭环 | 4-6 个节点 |
| **radar**（v1.8.0） | 多维度数值对比（理论 vs 实际 / 能力评估 / 国内外 / 模型适配） | 6-12 维，1-2 系列 |
| **skill-card**（v1.8.1） | 单个 Skill 的结构（输入→Skill 三件套+流程→输出） | 1 Skill + 3-5 步 |
| **timeline-lane**（v1.8.2） | 多角色/多主体时间推进（诉讼多角色时间线/案件流程节点） | 3-5 泳道，每道 2-5 事件 |
| **matrix-grid**（v1.8.3） | 两维交叉对照（风险×条款 / 特征×产品 / 能力×模型） | N×M 网格（3-6 × 3-7） |
| **three-col**（v1.8.4） | 三分类/三版本对仗并列（每栏带子卡片） | 3 栏 × 3-4 子卡片 |
| **flow+matrix** | 递进流程附带阶段对比 | 3-4 阶段 + 对比区 |
| **flow+hub** | 编排流程中节点展开 | 主流程 + 展开节点 |

---

## 设计规范

详见 `references/style-guide.md`。核心要点：

- **画布**：**宽 720px 固定（16开 115mm 通栏物理尺寸），高度按内容裁剪**（v1.7.1）——viewBox="0 0 720 H"，H = 内容底边最大 y + 40px；**不再固定 400**（固定 400 会让内容少的图底部留白过大、SVG 下边缘离图注间距忽大忽小）。**透明背景（硬约束）**——不画背景矩形、不设底色；左右 + 顶部安全边距 40px，底部 = H − 内容底（即 40px）。底色由书页/排版提供。
- **元素删除后的画布回收（v1.9.2,设计演进负债纪律）**：删除图内任何可见元素——历史设计的顶部「标记标题」、说明条、废弃节点/分组——时,必须**同步收紧 viewBox 与显式 height**,使留白回归口径(首内容距上缘约 24-40px、四周安全边距 40px)。「删元素不删空间」是多轮修改的技术负债:真实项目实证——早期顶部标记标题设计被整体移除后未回收画布,4 张图在书页上方遗留大片无信息留白,最终需全书统一排查修正(图 7-2/8-4/11-7/13-1)。配套检查口径:成稿 scan `--padding` 只拦「边距不足」;「留白过大」无法与有意分组留白机械区分,由视觉复审兜底——因此本纪律约束的是**删除动作的当下**,不是事后清扫。
- **风格**：简洁、专业、静态（无动画、无渐变、无滤镜、无 emoji）
- **颜色（v1.5.0 透明背景 + 内部模块多色版）**：新生成图**透明底**，配色用于 **SVG 内部不同模块 / 分支 / 方向 / 层级之间的多色柔和区分**——颜色尽量多样（一图 4-6 种甚至更多柔和模块色）。从 8 组预定义调色板（P1 雾蓝系 / P2 浅青系 / P3 嫩绿系 / P4 暖米系 / P5 浅紫系 / P6 浅粉系 / P7 暖灰系 / P8 混合柔和系）选 1 组，组内 5-6 个柔和模块色按"模块 1 取色 1、模块 2 取色 2…"依次分配，相邻模块不同色。文字色统一深灰 `#2D3436`/`#636E72` 保证可读。打印友好约束（文字 vs 所在模块填充色对比 ≥4.5:1 WCAG AA、相邻模块区分度 ≥10%、模块色明度 L*≥80、禁高饱和荧光、CMYK 不偏色、灰度差≥10%）。**仅新生成图用新配色，main 上既有 34 张白底单色 SVG 保持稳定不回改**。
- **颜色语法硬约束**：颜色只用 `fill`/`stroke` 属性内联——**禁 `<style>` 块定义颜色、禁 `<svg>` 开标签写 font-family、禁 CSS 变量/class、禁画背景矩形**（已验证的 Obsidian 渲染 + 透明背景硬约束，详见 `references/style-guide.md` §5.4）。
- **可视友好化配色与渲染禁忌（v1.8.7 硬约束，详见 `references/style-guide.md` §5.5）**：① **深底浅字**——深色填充（L* ≤ 50，如 `#2C5282`/`#1A202C`/G4 深档/项目 canonical 强调色）的模块内 `<text>` 必须用 `#FFFFFF`/`#EDF2F7`，**禁深底深字**；② **字色对比度**——文字 fill 与所在模块 fill 对比 ≥ 4.5:1（AA，大文本 ≥ 3:1）；③ **箭头落点**——marker 单 `id="arrow"` + `markerUnits=userSpaceOnUse` + `orient=auto`，落点 `x2 = 目标框边 − 4px`、方向指向目标节点；④ **文字完整性**——每个有标题语义的节点框都有非空 `<text>`、文字坐标在框内、fill 与模块不同色。源 T134 review 实测：图 7-6 箭头错位 / 图 11-8 字色不可辨 / 图 11-9 深蓝底深字 / 图 7-13/8-3/6-7 框内文字缺失。
- **蓝色焦点 + 文字二档（v1.8.8 通用规则，DEC-020，详见 `references/style-guide.md` §5.0/§5.1）**：① **文字色统一深灰二档**——图内所有文字仅允许 `#2D3436`（主）/`#636E72`（次），深底走 `#FFFFFF`/`#EDF2F7`；**不再用 `#1A202C`/`#4A5568`**（收敛二档消除四档混用）。② **项目 canonical 主色（如 `#2C5282`/`#1A365D` 蓝）只用于焦点节点填充/描边，禁作文字 fill**——以色块承载强调，文字强调改用字重/字号；这是通用纪律，非项目指针（任何项目锁定主色为视觉标识时都适用）。③ **每张结构/流程图 ≥1 焦点节点**——layer/tree/flow/hub/cycle/matrix 应至少有 1 个焦点节点（canonical 主色或更深一档填充/描边）承载层次，反对纯灰平铺；纯并列清单无自然焦点时用灰阶递进 + 边框粗细区分。源法律 AI Skill 实战 DEC-114 方案 A 定调（图 1-6 灰阶 + 唯一蓝色焦点 = 层次标杆、零蓝字）。
- **关系与标签卡语法（v1.8.11，详见 `references/style-guide.md` §六）**：有流程 / 反馈 / 复核 / 状态含义的线不因删繁而删除；同一分叉主干与支线连续；相邻层级箭头优先 16–32px 可见线身、超过 48px 先压缩布局。深色标签 + 浅色正文是一张卡时标题栏只留上圆角；步骤编号占独立上方带；图例只说明读者需要理解的关系。
- **文字**：继承渲染环境默认无衬线字体（PingFang SC / Microsoft YaHei 落在系统层），节点标签 18px 起（16开 115mm 通栏下物理 2.88mm = 8.2pt）
- **形状**：圆角矩形（rx="6"）、简洁箭头、最小 24px 间距
- **形状包含**：默认修复意外重叠；只有真实承载子 shape 的外层 area shape 才声明 `data-overlap-role="container"`，并同时写单图唯一原生 `id`、明示承载关系的 `data-overlap-note` 与非透明 hex/rgb/hsl `fill`。静态契约只审声明，实际几何由 writing-reviewer render gate 审计
- **印刷**：黑白可辨，颜色不是唯一区分手段（黑白降级仍可辨是硬约束）

---

## 插图目录

`references/diagram-catalog.md` 定义插图目录格式和创建方法。

---

## PNG 导出

出版社通常需要位图版本。`scripts/svg2png.js` 会读取 `assets/render-fonts.css`，将 SVG 转为高分辨率 PNG：

```bash
# 单张转换（默认 600 DPI）
node scripts/svg2png.js input.svg

# 指定输出文件和 DPI
node scripts/svg2png.js input.svg output.png 300

# 批量转换目录下所有 SVG
find figures/ -name "*.svg" -exec node scripts/svg2png.js {} \;
```

**依赖**：快速预览 wrapper 需要系统已有 `rsvg-convert`；高 DPI 导出需要 Puppeteer 和 Chrome/Chromium。缺失时脚本会明确报错，不会自动安装。首次使用高 DPI 功能前由用户自行运行：`npm install puppeteer`

**印刷 DPI 建议**：
- 300 DPI：最低印刷要求
- 600 DPI：推荐，清晰锐利
- 1200 DPI：线条图最高质量

---

## 成稿一致性 scan（v1.9.0，对既有书稿）

生成流程之外，对**已成稿书稿**的全部内联 SVG 跑规则巡检（只报告，不改稿；不替代 writing-reviewer render gate 的几何/视觉审计）：

```bash
python3 scripts/scan_consistency.py --book-root <书仓根目录> --report <报告输出.md>
# 阈值可调：--padding 40（安全边距 px）、--arrow-gap 8（箭头悬空 px）
# CI 门禁形态：--fail-on hard（存在 hard finding 时退出码 1）
```

规则覆盖（19 条，每条 finding 带规则 ID / 文件 / SVG 序号 / 位置 / 严重度 hard|soft）：

- **留白**：内容距画布边缘 < 阈值（默认 40px，style-guide §一）
- **箭头落点**：尖端穿入目标框（禁穿框）、离最近目标框 > 阈值且无 `data-arrow-role="axis|annotation"` + 非空 note 声明的悬空箭头（style-guide §5.5.3 / FIGURES-OUTLINE DEC-128）
- **marker 硬约束**：非 `arrow` 的多 marker / 缺 `markerUnits="userSpaceOnUse"`+`orient="auto"` / 悬空 `url(#id)` 引用（v1.6.0）
- **语法**：`<style>` 块、`style=`、`font-family`、整幅画布底色矩形、width/height/viewBox 契约（v1.8.9）
- **身份**：`data-figure-id` 缺失（soft，历史不回填口径）/ 格式不安全 / `fig-template-*` 落稿 / 跨图重复
- **sidecar 同步**：canonical 内联 SVG ↔ `manuscript/**/*_images/<stem>-svg-N.svg` 派生缓存内容一致（T261 口径）

历史口径：对 v1.8.9 前历史书稿的 SYNTAX/IDENTITY 发现只登记不要求回改（与本 skill「不回改历史书稿」既有口径一致）。v1.9.1 新增 `--exemptions <台账.json>`:逐项豁免已裁决历史项(键=file/svg_index/rule_id),命中不计 findings、未命中报警防台账漂移、坏台账 fail-closed;整规则豁免被有意排除——新图违规永远照报。与 BLOCKED Task-001（producer 冲突）/ Task-002（shape containment）互不侵入：本 scan 不改 producer、不做包含几何判定。

---

## 成功标准

- 每张图只表达 1-2 个核心概念
- 架构图层次清晰，流程图逻辑通顺
- 风格简洁专业，无装饰性元素
- SVG 在 Markdown 预览中正确渲染（源契约：开标签严格为 viewBox="0 0 720 H"、width="720"、height="H"，且有项目内唯一安全 `data-figure-id`；无嵌入 font-family、无 `<style>`/`style=`、颜色只用 `fill`/`stroke` 属性内联、**无背景矩形**、xmllint well-formed；受控 wrapper 渲染无警告）
- 图注格式统一：**图 N-X：标题**
- **配图密度达标**：图/节 ≥ 0.7、图/万字 ≥ 0.8
- **图-正文一致**：节点/层级/方向/维度与正文论点吻合，替换 mermaid/ASCII 图信息无损
- **视觉目检通过**：渲染后无溢出/意外重叠/箭头错位，字号可读、黑白可辨、美观；有意的 shape 包含仅走可审计 `container` 窄声明并由 writing-reviewer render gate 留证
- 印刷友好：16开 115mm 通栏下文字 ≥8pt 清晰可读，黑白打印可辨，文字对比度 ≥4.5:1（WCAG AA），CMYK 转换不偏色
- 配色合规（v1.5.0）：新生成图**透明背景**（无画布底色矩形）；从调色板 8 组选 1 组，组内模块色用于内部模块多色柔和区分（一图 4-6 色）、相邻模块不同色；文字色统一深灰；颜色只用 `fill`/`stroke` 属性内联；既有 34 张白底单色图保持稳定不回改
- 可视友好化（v1.8.7）：深底（L* ≤ 50）模块内文字走浅色 `#FFFFFF`/`#EDF2F7`（禁深底深字）；文字 vs 所在模块对比 ≥ 4.5:1；箭头落点 `x2 = 目标框边 − 4px`、方向指向目标；每个有标题语义的节点框都有非空 `<text>`、坐标在框内、fill 与模块不同色（详见 style-guide §5.5）
- 蓝色焦点 + 文字二档（v1.8.8）：文字色仅 `#2D3436`/`#636E72`（+ 深底浅字 `#FFFFFF`/`#EDF2F7`），不再用 `#1A202C`/`#4A5568`；项目 canonical 主色只焦点节点填充/描边、禁作文字 fill；每结构/流程图 ≥1 焦点节点（详见 style-guide §5.0/§5.1）
- 关系与标签卡（v1.8.11）：有含义的关系线完整保留且不压文字；分叉连续、相邻层级连接紧凑；标签卡只标题上圆角，步骤编号在独立上方带，图例面向读者（详见 style-guide §六）

> 源生产契约与受控渲染只是**必要不充分**条件——保证 SVG 可解析、画布与样式受控，不保证图正确美观。密度 + 一致性 + 目检三道审查才是验收依据（`references/review-checklist.md`）。