svg-article-illustrator · diff

v1.0.4 to v1.2.0

44 added, 179 removed. Audit A to A.

---

name: svg-article-illustrator

homepage: https://github.com/cat-xierluo/legal-skills

author: 杨卫薪律师（微信ywxlaw）

- version: "1.0.4"

+ version: "1.2.0"

license: MIT

- description: AI驱动的SVG文章配图生成工具，支持动态SVG、静态SVG和PNG导出三种输出模式。当用户需要为文章生成配图、创建SVG插图、将SVG转换为PNG，或提到"为文章配图"、"生成插图"时使用此技能。

+ description: 根据文章内容创作动态 SVG 文章配图，以构图、图形关系和状态变化解释内容；默认输出3–5秒原生SMIL动画，静态图仅作为明确例外。支持时间轴编译、布局检查与PNG导出；不用于完整视频制作或自动发布。

---

# SVG Article Illustrator

- AI 驱动的文章配图生成工具，使用 SVG 技术为公众号文章生成高质量配图。

- > **重要说明**：默认模式（dynamic-svg 和 static-svg）将 **SVG 代码直接嵌入**到 Markdown 文件中，而不是使用 `![](path.svg)` 的图片引用语法。这确保了动画效果和最佳兼容性。

- ## 快速开始

- ```

- /svg-article-illustrator @path/to/article.md

- ```

- ## 依赖说明

- - **dynamic-svg / static-svg 模式**：无需安装任何依赖

- - **png-export 模式**：需要安装 Node.js 和 puppeteer，详见 [references/png-export.md](references/png-export.md#依赖)

- ---

- ## 选择输出模式

- 根据用户需求和发布平台选择合适的输出模式：

- | 用户场景 | 使用模式 | 加载参考文件 |

- | ------------------ | --------------------- | ------------------------- |

- | 默认/未指定 | **dynamic-svg** | references/dynamic-svg.md |

- | 需要动画效果 | **dynamic-svg** | references/dynamic-svg.md |

- | 需要 PNG 兼容性 | **png-export** | references/png-export.md |

- | 不知道如何使用 SVG | **png-export** | references/png-export.md |

- | 明确要求静态效果 | **static-svg** | references/static-svg.md |

- | 需要静态 SVG 代码 | **static-svg** | references/static-svg.md |

- **默认模式**：当用户未明确指定时，使用 **dynamic-svg** 模式。

- ---

- ## 并行生成模式

- 当配图数量 ≥ 8 张时，自动启用多 Agent 并行生成以提升效率。

- 详见：[references/multi-agent-generation.md](references/multi-agent-generation.md)

- **核心思路**：

- 1. 主 Agent 分析文章内容并规划配图

- 2. 插入占位符 `[[ILLUSTRATION:ID:简短描述]]` 到文章

- 3. 解析占位符，按批次分发（每批 3-5 张）

- 4. 并行启动多个 Task Agent 生成

- 5. 主 Agent 按 ID 顺序收集并替换占位符

- **启用条件**：

- - 规划的配图数量 ≥ 8 张

- ---

- ## 核心工作流程

- ### 第一阶段：内容分析

- 1. 读取源文章 Markdown 文件

- 2. 识别核心概念和关键信息点

- 3. 规划配图位置：

- - 每个二级标题（##）后至少 1 张图

- - 每 2-3 个重要段落 1 张图

- - 重要概念转折点额外配图

- - 在规划位置插入占位符 `[[ILLUSTRATION:ID:简短描述]]`

- 4. 评估并选择生成模式：

- - ≥ 8 张 → 并行生成（多 Task Agent）

- - < 8 张 → 顺序生成

- ### 第二阶段：设计 SVG

- 1. 根据选择的输出模式应用相应规范

- - **dynamic-svg**：添加 SMIL 动画效果

- - **static-svg**：生成静态 SVG 代码

- - **png-export**：生成 SVG 文件

- 2. 遵循共享设计原则：[references/core-principles.md](references/core-principles.md)

- ### 第三阶段：生成与输出

- 1. **解析占位符**：提取所有 `[[ILLUSTRATION:ID:描述]]`

- 2. **并行/顺序生成**：

- - ≥ 8 张：并行生成（多 Task Agent）

- - < 8 张：顺序生成

- 3. **替换占位符**：将生成的 SVG 代码替换占位符

- > **默认行为**：除非用户明确要求 PNG 格式或图片文件引用，否则**必须直接将 SVG 代码嵌入**到 Markdown 文件中。

- - **dynamic-svg**：将 SVG 代码直接嵌入 Markdown 文件（使用 `<svg>` 标签）

- - **static-svg**：将 SVG 代码直接嵌入 Markdown 文件（使用 `<svg>` 标签）

- - **png-export**（仅当用户明确要求时）：

- 1. 保存 SVG 文件到源文章目录

- 2. 使用 `scripts/svg2png.js` 转换为 PNG

- 3. 在 Markdown 中插入图片引用 `![](path.png)`

- ### 第四阶段：归档

- 每次完成配图生成后，将文章中的 SVG 代码提取并归档到 Skill 内部：

- ```bash

- # 归档目录结构

- .claude/skills/svg-article-illustrator/archive/YYYYMMDD_HHMMSS_文章名/

- ├── 1_配图名称.svg # 提取的 SVG 文件

- ├── 2_配图名称.svg

- └── ...

- ```

- **归档命名规则**：

- - 格式：`YYYYMMDD_HHMMSS_文章标题`

- - 文章标题取自 Markdown 的第一个一级标题（`# 标题`），去除特殊字符

- - SVG 文件命名：`序号_配图名称.svg`

- - 示例：`20260209_163045_AI_Agent法律工作流未来范式/`

- - `1_AI_Agent_演进概览.svg`

- - `2_提示词设计.svg`

- - ...

- ---

- ## 共享设计原则

- 所有输出模式都遵循相同的核心设计原则，详见：[references/core-principles.md](references/core-principles.md)

- 核心要点：

- - 概念聚焦：每张图只表达 1-2 个核心概念

- - 极简设计：浅色主题，大图形，少文字

- - 画布尺寸：800x450（16:9 比例）

- - 边界控制：所有元素在有效区域内（60px 安全边距）

- ---

- ## 模式特定规范

- ### Dynamic SVG 模式

- **默认模式**，支持 SMIL 动画效果。

- 详见：[references/dynamic-svg.md](references/dynamic-svg.md)

- 核心特性：

- - SMIL 动画：浮动、虚线流动、箭头绘制

- - Emoji 动画：浮动、脉冲效果

- - 逻辑性动画优先：箭头和虚线框必须有动画

- - SVG 代码直接嵌入 Markdown

- ### Static SVG 模式

- 静态 SVG 代码直接嵌入 Markdown。

- 详见：[references/static-svg.md](references/static-svg.md)

- 核心特性：

+ 读取全文与调用项目的视觉、画幅、嵌入、归档约定，再做配图。先定阅读任务，再定视觉形态；从参考作品提炼表达方法，示例仅说明方法或技术用法。文章 SVG 插图默认动态：每张图至少安排一组解释对象关系或状态变化的原生 SMIL 动画，动画是交付口径，不是可选加分项。

- - 无动画效果

- - SVG 代码直接嵌入 Markdown

- - 公众号完美支持

+ 常规循环时长目标为 **3–5 秒**，其中 3 秒左右优先用于单一、清楚的状态变化，5 秒是文章插图上限。内容更多时先拆图、删掉无信息动作或提高关键状态密度；不得靠延长周期换取完整。任何 3–5 秒方案都要保留关键结果的可读停留，不能让形成、拆分、替换或接续变成一闪而过。

- ### PNG Export 模式

+ 静态只用于调用方明确要求静态、目标平台拒绝动画，或动画确实无解释增益的总结图。选择静态必须在配图计划和交付说明中逐图写明理由；不得因为关系图、分类图或制作方便而静默降级为静态。

- 生成独立的 SVG 和 PNG 文件。

+ 最终交付前用 `validate` 或 `publish` 验收，命令默认拒绝没有原生 SMIL、全部轨道恒定或所有变化轨道均可确定永久隐藏的 SVG。只有已记录逐图理由的静态例外才可显式加 `--allow-static`；不得为通过门禁改写例外理由。Markdown 内联交付也要先把每段 SVG 单独通过该门禁。

- 详见：[references/png-export.md](references/png-export.md)

+ ## 工作方法

- 核心特性：

+ 1. **内容 → 配图计划**：为每张图记录对应段落、读者需要理解的关系/变化、图的作用、插入点、输出模式。按信息增益决定数量，不按标题数或固定张数配图。

+ 2. **计划 → 视觉表达**：用一句话说清读者将看到哪些对象、它们有什么关系或变化，再选择画面形态。在计划中说明哪些关系需要突出、比较或同时保留，以及图形与变化怎样帮助理解；同时记录必须保留的事实与对象辨识细节，见[阅读编排](references/reading-sequence.md)和[视觉设计](references/visual-design.md)。创意从本次内容出发，不按示例外观或固定类型映射套版。已有插图先按上述方法审旧基线：旧图已讲清内容时沿用，不用“换成动画”或“重新设计”替代比较。沿用表示不重画，不绕过交付门禁；动态旧图按原样验证，静态旧图仍按逐图静态例外记录并显式放行。

+ 3. **对象/状态 → 时间轴**：列出对象、标签、容器、坐标系、初末状态和互斥关系。让运动说明对象如何变化、为何变化；在 3–5 秒内组织需要的变化与可读停留，结合关键状态和过渡共同安排空间与节奏。过程复杂就拆图或压缩无关动作。确认为静态例外时，仍记录该图缺少动效的解释理由。

+ 4. **骨架 + 时间轴 → SVG**：使用唯一 `data-cue` 定位实际图形；通过 [时间轴工具](references/timeline-tools.md) 编译，不手算大量 keyTimes。静态例外直接输出可读 SVG。变换坐标合同和修正示例见 [动态规范](references/dynamic-svg.md)。

+ 5. **SVG → 实测与整图审阅**：运行结构校验；打开自包含 HTML，在桌面与 375 CSS px 宽度测量真实文字与对象，检查截图。覆盖初态、停留、运动中段、循环末与下一轮；实际播放两个完整周期。按[阅读编排](references/reading-sequence.md)审内容理解、观看顺序、最终布局和文字疏密；返修后回查此前反馈是否仍落实，记录具体画面与所见。动画存在、字数减少或无碰撞均不能单独代替这一层；还要说明运动是否让对象关系、结构、数量或因果比基线更容易理解，不能只比较质感或节奏。多图先审有代表性的一张，再扩展。测量方法及边界见 [布局验收](references/layout-verification.md)。

+ 6. **实测 → 交付**：按调用项目要求内联 SVG、保存文件或插入 PNG；回读实际交付内容，确认动画、ID 引用和文本仍完整。通过 publish 剥离制作标记，保留原生 SMIL；预览 HTML 的 JS 不进入发布 SVG。本地 HTML 片段交接见工具参考。提供源骨架、时间轴和验证记录以便修改。

- - 文件命名：短名-序号.svg（≤15 字符）

- - 保存位置：与源文章同目录

- - PNG 转换：使用 `scripts/svg2png.js`

- - 跨平台兼容性最佳

+ ## 按需加载

- ---

+ | 任务 | 参考 |

+ |---|---|

+ | 选画幅、安排文字与对象 | [共享原则](references/core-principles.md) |

+ | 提升设计感、选择构图与图形语言、避免套模板 | [视觉设计](references/visual-design.md) |

+ | 设计读者观看顺序、动作接续及新旧版本对照 | [阅读编排](references/reading-sequence.md) |

+ | 操作演示、机制或状态变化 | [动态 SVG](references/dynamic-svg.md) |

+ | 编译 JSON、校验与预览 CLI | [时间轴工具](references/timeline-tools.md) |

+ | DOM 测量、长文本、重叠反馈 | [布局验收](references/layout-verification.md) |

+ | 明确静态例外与静态后备 | [静态 SVG](references/static-svg.md) |

+ | 已选表达确实涉及界面操作或控件状态 | [UI 与微交互](references/ui-interaction.md) |

+ | 输出 PNG | [PNG 导出](references/png-export.md) |

+ | 多图有界委派 | [并行协作](references/multi-agent-generation.md) |

+ | 维护与回归、独立复验 | [验证设计](references/verification.md) |

+ | 借鉴来源与评估边界 | [来源记录](references/provenance.md) |

- ## PNG 转换脚本

+ ## 工具入口

- 使用 `scripts/svg2png.js` 进行高保真转换：

+ 以下以材料归拢样例演示命令，在 Skill 目录运行，输出路径可指定；已有文件默认拒绝覆盖，确认替换时加 `--force`。Python 工具仅使用标准库，不安装第三方套件。

```bash

- node scripts/svg2png.js input.svg [output.png] [dpi]

+ python3 scripts/svg_motion.py compile assets/materials-demo.skeleton.svg assets/materials-demo.timeline.json -o /tmp/materials-demo.svg

+ python3 scripts/svg_motion.py validate /tmp/materials-demo.svg

+ python3 scripts/svg_motion.py preview /tmp/materials-demo.svg -o /tmp/materials-demo.html

+ python3 scripts/svg_motion.py publish /tmp/materials-demo.svg -o /tmp/materials-demo.publish.svg

+ # 仅用于已在计划和交付说明中写明理由的静态例外：

+ python3 scripts/svg_motion.py validate /tmp/static-exception.svg --allow-static

```

- - **默认 DPI**：600

- - **支持**：emoji、中文、CSS

- - **输出位置**：总是生成到 SVG 源文件所在目录

+ 在浏览器打开生成的 HTML；播放、暂停、重置、逐秒步进与时间滑杆只服务于制作预览。其测量函数 `window.measureSvgLayout(svg)` 也可由浏览器自动化调用。此处只演示工具的输入输出，实际创作自行选择画面形态、风格、尺寸与节奏。

- ---

+ PNG 路径保留 `node scripts/svg2png.js input.svg [output.png] [dpi]`，需要既有 Node.js、Puppeteer和浏览器；缺少时按环境约定准备项目本地依赖，不自动做全局安装。

- ## 成功标准

+ ## 交付边界

- - 配图密度 10-15 张，有效增强视觉吸引力

- - 每张配图概念聚焦准确

- - 极简风格贯穿始终

- - 公众号显示正常

- - 跨平台兼容性良好

+ - XML/时序检查通过仅代表本工具支持的保守 SVG 子集通过；未知语法会拒绝，检查边界见工具参考。

+ - 动态交付必须回读每段 SVG 中的 `animate` / `animateTransform`；`validate` / `publish` 默认拒绝无动画文件。发现仅有装饰性浮动时，先修订时间轴，不得将其称为解释性动态配图。

+ - 布局测量基于实际 DOM，可发现边界问题与碰撞候选；不能仅凭字符估宽、一个时点或文字边界交集断言画面正确。容器、互斥状态与有意遮挡都保留可观察证据。

+ - 浏览器成功不证明公众号编辑器、保存后预览或手机 WebView 成功。逐环境记录实测时间、入口与结果；未测项写 `NOT_VERIFIED`。静态 SVG 与 PNG 也要核对实际字体、裁切和发布入口。

+ - 默认交回计划、源码和本地验证结果；内容发布、外部上传和安装不包含在本 Skill 的默认动作内。