/svg-book-illustrator

name: svg-book-illustrator
homepage: https://github.com/cat-xierluo/legal-skills
author: 杨卫薪律师（微信ywxlaw）
version: "1.9.2"
license: MIT
description: 书籍/文章 SVG 配图生成工具，专注于架构图、流程图、层次图等专业技术配图。当用户需要为书籍章节或正式文章生成配图、创建架构图/流程图/层次图，或提到"章节配图"、"书籍插图"、"架构图"、"流程图"时使用此技能。

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 到独立文件：

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` 后，必须运行：

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，也支持显式指定：

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`：

# 快速预览（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 子卡