把 AI 生成的 SVG 改成可维护的¶

为什么要单独讲这一篇¶

AI 画的 SVG 有两个典型通病，值得单独拎出来说：

结构冗余：重复的 <defs>、重复的内联样式、用 <path> 画本该用 <rect>/<circle> 的东西、塞一堆用不上的注释和空分组。不影响显示，但阅读和后续修改非常累。
语义错误：这是更危险的一类。AI 不一定懂你领域的物理 / 工程含义——MOS 管体二极管方向画反、流程图箭头指错、坐标系上下颠倒、正负号写反。这类错误没有任何报错提示，只有懂行的人能看出来。

所以拿到 AI 给的 SVG，第一件事不是"好不好看"，而是"对不对"。本篇给一条从"接手"到"可维护"的固定流程。

总原则：先语义，后样式¶

AI 给图
  │
  ├─ 1. 读懂结构（画布 / 骨架 / 锚点 / 试改）── 见《SVG 入门：读图与制作》第 3 节
  ├─ 2. 清冗余（去重复 defs / 合并样式 / 简化图元）
  ├─ 3. 查语义（领域知识校验方向 / 极性 / 逻辑）── 最花时间、也最重要
  ├─ 4. 改可维护（抽样式 / 双主题 / 参数化 / 加注释）
  └─ 5. 本地预览验证（亮暗都看一遍）── 见《亮暗双主题与 MkDocs 嵌入》

顺序别乱：样式再漂亮，语义错了也是白搭；而一旦语义确认无误，样式是机械活。

1. 读懂：别急着改，先读¶

AI 的图往往几百行、没有缩进规范、分组混乱。照读图四步走：看画布（viewBox / 坐标系）→ 看骨架（折叠 <g> 找模块）→ 找锚点（用 id / 注释 / 坐标搜你关心的元素）→ 无害试改（临时改亮色验证理解对不对）。

读的时候顺手建一张"行号区间表"：哪几行是标题、哪几行是某个模块。后面所有改动都挂在这张表上。

2. 清冗余：把"能跑"变"能读"¶

常见冗余与处理：

冗余	现象	处理
重复 `<defs>` / 重复定义	同一个渐变 / 箭头被定义了多次	合并成一份，别处用 `url(#id)` 引用
重复内联样式	每个元素都写 `fill="#1a73e8" stroke-width="2"`	抽到 `<style>` 或用 class；同色元素统一
用 `<path>` 画矩形 / 圆	一个方框是几十个 path 点	换成 `<rect>` / `<circle>`，坐标一目了然
空分组 / 注释噪声	`<g id="group_3">` 套一层啥也没干	删掉；只保留有语义的分组
看不见的占位元素	`opacity="0"` 或 `display="none"` 的残留	确认无用后删除（删前先 `git commit` 一版）

<!-- 冗余：用 path 画一个方框 -->
<path d="M 10 10 L 110 10 L 110 60 L 10 60 Z" fill="none" stroke="#1a73e8" stroke-width="2"/>

<!-- 改后：一个 rect 说清一切 -->
<rect x="10" y="10" width="100" height="50" fill="none" stroke="#1a73e8" stroke-width="2"/>

原则：SVG 的坐标是绝对的、没有自动重排（见 SVG 动手区入口页）。清理时每删一个元素，要确认没有别的元素依赖它的位置——尤其 <use> / <defs> 引用，删了定义会连累所有引用者。

3. 查语义：这一步 AI 帮不了你¶

样式能自动查，语义只能人查。最容易踩的几类：

3.1 方向 / 极性¶

二极管 / 体二极管：阴极横线在哪一端？AI 经常把三角箭头画反。MOS 管体二极管方向由工艺决定，画反了读图 / 仿真都会错。
变压器 / 线圈同名端：圆点标记不能省，AI 容易漏或乱点。
电流 / 电压参考方向：箭头方向要和标注的参考方向一致。

3.2 坐标系 / 上下¶

SVG 的 y 轴朝下（和数学课相反）。AI 有时按"上正下负"的直觉画，导致箭头 / 标签上下颠倒。用读图第 ① 步的"y 越大越靠下"铁律逐处核对。

3.3 逻辑 / 流程¶

流程图的箭头指向、判断框的"是 / 否"分支、状态机的转移，AI 容易接错线。这类错误显示正常、逻辑却错，必须对照你的真实流程一条条边看。

3.4 数值 / 公式¶

图里标的数值、相位、正负号，是否和正文 / 数据自洽。AI 可能"看起来对"但数值是编的。

没有捷径：逐元素对照领域知识。如果不确定某处对不对，回到原始资料（datasheet / 电路图 / 你自己的草图）核一遍，而不是凭"看着像"放行。

4. 改可维护：让它经得起以后改¶

语义确认无误后，把图整理成"以后你自己或别人改起来不痛苦"的形态：

抽公共样式：颜色 / 线宽用 <style> 里的 class 或 CSS 变量，别散落内联。
双主题适配：写死的颜色在暗色下会糊。优先 currentColor，或内联 + CSS 变量（详见亮暗双主题与 MkDocs 嵌入）。下面是个双主题安全的小例子：

<svg viewBox="0 0 120 60" width="120" height="60" role="img" aria-label="双主题示例">
  <style>
    .box { fill: none; stroke: var(--md-primary-fg-color); stroke-width: 2; }
  </style>
  <rect class="box" x="10" y="10" width="100" height="40" rx="6"/>
</svg>

注意保留 width/height（提供固有尺寸）。本站早期一批 SVG 因为只留 viewBox、删了 width/height，在 <img> 下高度被算成 0、直接不显示——别踩这个坑。

参数化 / 注释锚点：对会经常改的块，用有语义的 <g id="chip1"> 包起来，注释写明"这块是 XX 模块"。以后定位就是搜 id，不是数行号。
保留可回滚的备份：动手前 git commit 一次，或另存 .bak。SVG 是纯文本，回滚成本极低。

5. 预览验证：亮暗都看¶

改完务必本地 mkdocs serve 起一个预览，至少确认两件事： - 图正常显示（不是白屏 / 塌成 0 高度）； - 亮色和暗色主题下颜色都清晰、不糊。

构建告警也会提示链接 / 路径问题，顺手清掉。

检查清单（提交前过一遍）¶

语义逐元素核过（方向 / 极性 / 逻辑 / 数值），并对照了原始资料？
冗余清理了：重复 defs、重复样式、path 画的方框、空分组？
颜色没写死：用了 currentColor 或 CSS 变量，亮暗都看了？
.svg 保留了 width/height（没塌成 0 高度）？
公共块用了有语义的 id / 注释，以后好定位？
相对路径写的是真实文件名（没手动做 URL 编码）？
mkdocs serve 预览过，图正常显示、链接无告警？