@taloswork/ose-shared 0.1.8 → 0.1.9

package/skills/cozy-static-svg/references/style-anchor.md

@@ -0,0 +1,271 @@
+# 画风速查（《月亮替你值夜班》标准）
+
+版本：基于 2026-09-10 用户认可的《月亮替你值夜班》；改动本文件前先征得用户确认。
+用法：**每幅开画前通读本文件**；仅在需要复习完整结构时，再打开 `moon_keeps_watch.svg` 与 `approved-preview.png` 对照。速查表 + 自查清单 + artkit 质检，三者照做即可保持原作精细度。
+
+**尺寸定位**：要学的是手法（圆润大形、渐变层次、分层空间、留白、温柔短句），**不是它的夜色**。原作是夜景只是恰好；默认出图应当**明快、明亮，明亮调与中间调为主**，夜景当少数例外。
+
+**文件结构**：画布与技术骨架 → 硬底线（明度 / 对比 / 可读性）→ 题材轮换 → 颜色 → 层序与片段 → 动物配方 → 检查清单。
+
+## 画布与技术骨架
+
+- 默认 1200×900（4:3 横幅）；用户指定尺寸优先。
+- 根节点起手式：
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="900" viewBox="0 0 1200 900" role="img" aria-labelledby="art-title art-desc">
+  <title id="art-title">…</title>
+  <desc id="art-desc">…（与画面一致，不夸大）</desc>
+```
+
+- 全幅圆角由最外层 clipPath 统一裁切（文字也要包含在内），rx≈30：
+
+```svg
+<clipPath id="canvas"><rect width="1200" height="900" rx="30"/></clipPath>
+<g clip-path="url(#canvas)"> …全部内容… </g>
+```
+
+- 纯静态、纯矢量、自包含：无动画 / 脚本 / 外链 / 位图 / foreignObject。
+
+## 硬底线（不可让步）
+
+三条底线，按顺序过：**明度均衡 → 对比度 → 文字可读性**；它们优先于“好不好看”。共同底线：**脸、物件轮廓、文字的对比必须清楚**（亮底尤其别用浅色字）。
+
+### 明度均衡
+
+原作是夜景，但那份深底不是默认值。成批创作时**亮调、中间调要占多数**，深色夜景只当做偶尔的一种。判断标准很简单：
+
+- 每 3–4 张里，至少 2 张是**亮底或中间调**（晨光、米白、浅木、雾面、淡彩）。
+- 连续两张不要都是深底夜景；连续三张深底就算跑偏，第三张必须换亮。
+- 深色只做点缀（主体、轮廓、文字、局部阴影），**不做整幅的默认底色**。
+- 亮底不等于惨白：用米白、奶乳、浅木、雾青、樱粉这类**带暖度的浅色**打底，再以中深色物体压住画面重心。
+
+### 对比度
+
+明快不等于发飘。亮底必须靠**深色锚点**立住，深底必须靠**大面积亮部**立住；整幅要有一处明确的明暗落差，不能到处差不多亮。
+
+- 亮底立住的三类锚点（至少用两类）：**深色主体**（黑猫、深墨绿杯、深蓝书）、**成片的影子**（窗格影、斜射光带、投影）、**深色结构**（深木台面、深色屋档）。
+- 深底立住的亮部：灯 / 发亮的窗是核心，再加上成片的浅色面（浅色石阶、白墙、浅色台面），亮部面积不能只是几个小点。
+- 量化参考：亮底画里，最深处应当接近 `#3A2C22 / #242130`（不是浅褐）；深底画里，最亮处应当接近 `#FFFDF0 / #FFF6E2`。
+- 关键焦点（眼睛、灯芯、窗格中心）用**两端中最强的那一级**：亮底上最深的衬着最亮的，深底上最亮的衬着最深的。
+- 别用低透明黑整层压暗来“造”对比，那是相下去不是对比；对比靠亮部与暗部**各自的纯度**。
+- 对比要做在**有限的几个点点**上（主体、光源、影子），其余区域保持柔和过渡；整幅处处高对比会硬、会吵。
+
+### 文字可读性
+
+文字必须能在它的实际底色上轻松读出来。这是底线，不是风格偏好——好看的配色也要为重。
+
+- **按文字所在区域定色，不按整幅平均色定色**：落在渐变压暗处、光斑上、深色物体上的字，以该处实际背景为准染深或染亮。
+- **先保证对比，再谈协调**：把标题与注脚的明度与背景拉开；相邻明度差不足时，加深文字或给文字加一层轻柔的衬底/暗影，不要靠“整体感觉差不多”蒙过去。
+- **亮底用深字，暗底用亮字**：亮底文字用深褐 / 深墨（如 `#4A3B34 / #2F4B54`），不要反过来，也不要给亮底配奶油色字、给暗底配中灰字。
+- **文字不要横跨明暗交界**：不让句子一半在亮区、一半在暗区；让它整体待在一种背景上，必要时挪位置。
+- **字号越小，对比要求越高**：右下小字最细最易糊，它比标题更需要拉足对比。
+- 仅靠字形描边或很淡的投影来“救”低对比字是不够的；对比不足就直接换色。
+- 四角文字都在圆角裁切内，选色时一并考虑裁切边缘的底色。
+
+## 题材轮换（成批创作尤其重要）
+
+画风固定，题材不能固定。同一批图里反复出现「远山＋月＋一盏灯」就是跑偏，哪怕每张坐标都换了。
+
+- **连续两张不同题材类型**，不要连着两张都是山景（或两张都是室内窗户）。
+- **每 4 张一轮**，至少覆盖三类不同题材：自然风景 / 室内生活 / 季节天气 / 旅途与建筑 / 动物与物件。
+- **同一批里一个母题最多用两次**（母题＝月色、灯火、远山、窗、荷、雪、舟……）；第三次就换。
+- **换的不只是题材名字，还有构图骨架**：不要每张都是“横向分天地”、一个远景加一个主体；俯视、近景特写、斜线分栏都可以用。
+- **主体也可以换**：猫、兔、刺猬、狐狸、鸟、小鸭、鲸都能当主角；不必总用同一只猫换姿势。
+- 用户指定了题材就直接用；没指定时，按上一张的类型主动错开。
+
+## 颜色（自由发挥，不设固定色板）
+
+颜色由你按题材与情绪自由决定、可多变；下表只是原作的参考示例，**不是必用色板**，任何协调的色系都可以用。
+
+| 用途 | 原作示例（仅供参考） |
+| --- | --- |
+| 室内暮紫渐变 | `#252138 → #46334D → #70515F` |
+| 窗外紫粉夜色 | `#343453 → #77627D → #E8AD9B` |
+| 远 / 中 / 近山 | `#97788D / #695776 / #3D364F` |
+| 暖金月光 | `#FFF0C5` |
+| 小灯玻璃 | `#FFE9BB → #FFDAA0 → #ECC18A` |
+| 橘猫毛色 | `#D89462 → #ECAE78 → #F5CA94`（尾 `#C4855F→#EDB783`） |
+| 叶绿 | `#6F9488 / #9BB09B / #B4BD9F` |
+| 灯座灰绿 | `#455D59 / #61746A` |
+| 文字奶油 | `#F5E1CD / #E2C9B6 / #C7AFAD / #A98F98` |
+| 腮红 / 条纹 | `#D08A72（低透明） / #BB7957` |
+
+**亮调底色参考**（不是强制色板，只是把「亮」具象化，避免每次都摸回夜色）：
+
+| 氛围 | 底色示例 | 配文字色 |
+| --- | --- | --- |
+| 晨光米白 | `#FBF3E6 → #F3E3CC` | `#5A4A3E` |
+| 浅木暖调 | `#F1DFC4 → #D9BE9A` | `#4E3A2E` |
+| 雾青淡彩 | `#EAF4F2 → #CBE3E0` | `#2F4B54` |
+| 樱粉霞色 | `#FCEAE4 → #F3CFC4` | `#6A4640` |
+| 岚色雪白 | `#F4F7FA → #D9E4EE` | `#3C4E63` |
+| 苹果园绿 | `#EFF6DC → #D2E3B4` | `#3F5A38` |
+
+- 每幅可换色系：森林绿、海水蓝、晨雾灰、暮紫、樱粉、秋橙、雪青……都行；成批创作尤其鼓励每张不同，避免千篇一律。
+- 保持的是手法而不是色值：渐变过渡自然、层次分明、主光源统一（暖灯 / 冷月 / 落日 / 晨雾 / 日间自然光皆可）。
+
+## 层序总则（从后往前画）
+
+1. 室内底色与氛围 2. 窗外/环境远景（全部收进 clip） 3. 结构（窗框 / 屋檐 / 栏杆）
+4. 远→中→近景 5. 承托面（窗台 / 桌面 / 地面） 6. 道具 7. 主体 8. 细节（纹理 / 表情 / 高光） 9. 文字
+
+- 每个物件：接触阴影（低透明扁椭圆）+ 明确承托；灯、盆、书不得悬空。
+- 只在最后画文字，保证不被压住。
+
+## 可复用片段（照结构改造；色值按当幅色系替换，别照抄坐标）
+
+### 拱窗（框内远景不越界）
+
+```svg
+<path d="M254 707V472C254 284 409 149 600 149S946 284 946 472V707Z" fill="#2B243A"/><!-- 外框底 -->
+<path d="M262 703V472C262 289 412 158 600 158S938 289 938 472V703Z" fill="#A38189"/><!-- 框面 -->
+<clipPath id="window"><path d="M270 698V472C270 294 416 166 600 166S930 294 930 472V698Z"/></clipPath>
+<g clip-path="url(#window)"> …天空 / 山 / 小窗屋… </g>
+<path d="M276 473C276 299 418 173 600 173" fill="none" stroke="#E2BCA5" stroke-width="2" opacity="0.4"/><!-- 内缘高光最后画 -->
+```
+
+### 月牙（mask 切，光晕用 2–3 个低透明同心圆）
+
+```svg
+<mask id="crescent" maskUnits="userSpaceOnUse" x="707" y="250" width="120" height="120">
+  <rect x="707" y="250" width="120" height="120" fill="black"/>
+  <circle cx="767" cy="310" r="48" fill="white"/>
+  <circle cx="786" cy="293" r="43" fill="black"/>
+</mask>
+<circle cx="767" cy="310" r="110" fill="#FFF0C5" opacity="0.025"/>
+<circle cx="767" cy="310" r="48" fill="#FFF0C5" mask="url(#crescent)"/>
+```
+
+### 星光（defs+use 复用，省时省体积）
+
+```svg
+<path id="spark" d="M0-8Q1-1 8 0Q1 1 0 8Q-1 1-8 0Q-1-1 0-8Z"/>
+<use href="#spark" transform="translate(565 332)" opacity="0.8"/>
+<use href="#spark" transform="translate(388 352) scale(0.7)" opacity="0.65"/>
+```
+
+### 暖光晕（径向渐变，不靠模糊滤镜）
+
+```svg
+<radialGradient id="lamp-halo">
+  <stop stop-color="#FFD29A" stop-opacity="0.35"/>
+  <stop offset="0.5" stop-color="#FFC989" stop-opacity="0.12"/>
+  <stop offset="1" stop-color="#FFC989" stop-opacity="0"/>
+</radialGradient>
+<circle cx="824" cy="621" r="183" fill="url(#lamp-halo)"/>
+```
+
+### 动物圆脸（闭眼弧线 / 鼻嘴 / 腮红）
+
+```svg
+<path d="M438 543Q445 551 453 543" fill="none" stroke="#65454A" stroke-width="3" stroke-linecap="round"/>
+<path d="M471 561V566M471 566Q464 572 461 567M471 566Q478 572 481 567" fill="none" stroke="#65454A" stroke-width="1.8" stroke-linecap="round"/>
+<ellipse cx="435" cy="557" rx="8" ry="4.5" fill="#D08A72" opacity="0.55"/>
+```
+
+### 条纹补丁（clip 到身体路径）
+
+```svg
+<clipPath id="cat-body"><path d="M…身体同一路径…"/></clipPath>
+<g clip-path="url(#cat-body)" fill="none" stroke="#BB7957" stroke-width="13" stroke-linecap="round" opacity="0.5">…3 条弧线…</g>
+```
+
+### 文字组（位置与样式照做，字句随画面）
+
+默认版（不带诗词，右下带一句小字）：
+
+```svg
+<g font-family="'PingFang SC','Noto Sans CJK SC','Microsoft YaHei',sans-serif">
+  <text x="86" y="92" fill="#F5E1CD" font-size="27" font-weight="500" letter-spacing="4">标题</text>
+  <text x="1112" y="90" text-anchor="end" fill="#C7AFAD" font-size="15" letter-spacing="3">晚安 · 名字</text>
+  <text x="86" y="840" fill="#E2C9B6" font-size="17" letter-spacing="2">一句注脚</text>
+  <text x="1112" y="841" text-anchor="end" fill="#A98F98" font-size="12" letter-spacing="3">小字</text>
+</g>
+```
+
+（质检脚本会核对字体栈与全部文案。）
+
+### 诗词版：左下角放一首配得上的唐宋诗词
+
+画面相宜时（山水、夜景、四季、雪月、荷塘这类题材尤其合适），左下角题诗词、去掉右下小字；**左上标题、右上落款照旧保留**，全图共五处文字。
+
+```svg
+<g font-family="'PingFang SC','Noto Sans CJK SC','Microsoft YaHei',sans-serif">
+  <text x="86" y="92" fill="#F2EBDC" font-size="27" font-weight="500" letter-spacing="4">今晚山里很静</text>
+  <text x="1112" y="90" text-anchor="end" fill="#8FA6BE" font-size="15" letter-spacing="3">夜 · 名字</text>
+  <text x="86" y="764" fill="#FFFFFF" font-size="28" font-weight="600" letter-spacing="6">月出惊山鸟</text>
+  <text x="86" y="814" fill="#FFF8E4" font-size="28" font-weight="600" letter-spacing="6">时鸣春涧中</text>
+  <text x="88" y="858" fill="#F4EEDC" font-size="14" letter-spacing="3">唐 · 王维《鸟鸣涧》</text>
+</g>
+```
+
+**标题与诗句分工（别写成一句话）**：
+
+- **左上标题**：写自己的话，讲画面的感受或情境（「今晚山里很静」「帐外还下着雪」），口语、短句。
+- **左下诗句**：引原典原文，只选能**与画面互相对上**的句子（画里有鸟有月就选《鸟鸣涧》，有成排灯火就选「夜深千帐灯」）。
+- 两者**不重复、不互相解释**：不拿诗句当标题，也不让标题去翻译诗句。
+
+- **结构**：诗句两行（同字号、同字距、左对齐，行间距 50）＋出处一行（朝代 · 作者《篇名》）。
+- **字号与字重**：标题 27 号 / 字重 500 / 字距 4（与默认版一致）；诗句 28 号 / 字重 600 / 字距 6；出处 14 号 / 字距 3，比诗句小一号且对比不低。
+- **位置**：左上标题 (86, 92)；诗句 x=86、出处 x=88，三行基线 764 / 814 / 858，整体待在左下角、不碰圆角；**右下不放小字**。
+- **出处不省**：朝代与作者写清，字号虽小但对比要够。
+
+**诗词版的对比标准（比普通注脚更严）**：诗句是画面主文字之一，必须一眼看清。
+
+- 诗句与出处都比普通注脚更深/更亮一档：亮底上压到接近墨色（如 `#1E2E24 / #1E3A20`），深底上提到接近纯白（如 `#FFFFFF / #FFF8E4`）。
+- 诗句与出处的对比**不要拉开太多**：出处虽小，也必须在它的底色上看得清，不能发灰发淡。
+- 仍按**文字所在区域**定色：诗句落在深色山影或雪地浅色区上时，以那块背景为准染深或染亮（宁可反向形成强对比，也不要顺着背景走）。
+- 不用透明度、不加投影来“平衡关系”；对比不够就直接换色值或加字重。
+
+### 落款名：按使用者替换，不要照抄
+
+上面片段里的「名字」是占位符，**不是固定文案**——写死就等于把名字串给别人。每张开画前按此决定：
+
+1. **知道对方称呼时**：落款用对方的名字（如「晚安 · 小满」），跟随当前会话的使用者，不要沿用上一张或示例里的名字。
+2. **不确定时**：改用中性落款，只留情境词，如「晚安」「早安」「祝你睡个好觉」，宁可不写名字也不要猜错。
+3. **判断依据（按顺序取第一个可用的）**：当前会话里对方明确的称呼 → 记忆中的使用者姓名 → 中性落款。
+
+- 只有认可原作 `references/moon_keeps_watch.svg` 里的「晚安 · 阿答」属于历史事实，保持原样不动；它是**示例来源**，不是**可复制模板**。
+- 同一批多张图里，落款名要一致；换人做则整批一起换，不要一张一个名。
+- 其余文案（标题、注脚）属于画风，保持克制中文短句即可，无需替换。
+
+## 动物主角配方（坐姿猫为例）
+
+1. 接触阴影椭圆 → 2. 身体大形（圆润梨形）→ 3. 条纹组（clip 到身体）→ 4. 肚皮浅色块 →
+5. 耳朵（先画，含内耳深色）→ 6. 头（盖住耳根）→ 7. 脸（闭眼两段弧、小三角鼻、两小钩嘴、腮红、2–4 根细胡须）→
+8. 前爪（圆头柱状，落在大形下缘）→ 9. 尾巴（最后画：粗圆头 stroke 绕出一侧，可与身体交叠出层次）
+
+- 要点：圆头圆身；闭眼用上拱弧线；耳朵内色深一号。
+- 变体：坐 / 趴 / 躺 / 回头 / 伸爪——改大形与四肢，**不要每张平移同一只猫**。
+
+## 开画前自查清单（过一遍再落盘，能省一轮返工）
+
+**结构与画法**
+- [ ] 月牙用 mask；不用天空色圆"假装"遮挡
+- [ ] 窗 / 框内远景全部被 clip；外框线压在最上
+- [ ] 耳先头后、身先脸后、尾巴最后并压住衔接
+- [ ] 每个物件有影子 + 承托；灯落座、书贴桌
+- [ ] 全幅圆角由 canvas clip 统一（含文字）
+- [ ] 重复小元素（星 / 叶 / 毛簇）用 defs+use
+- [ ] 不复用上一张的同一套坐标；题材与前一张不同类型，母题未超两次，构图骨架换过
+
+**底线三条（明度 / 对比 / 可读性）**
+- [ ] 整幅底色不是默认深色（成批时亮调 / 中间调占多数，无连续夜景）
+- [ ] 整幅有一处明确的明暗落差：亮底有深色锚点（主体 / 影子 / 深色结构）或深底有大面积亮部
+- [ ] 对比集中在主体、光源、影子等少数区域，其余保持柔和过渡
+- [ ] 文字按所在区域选色（不是按整幅平均）：亮底用深、暗底用亮，对比足够，不横跨明暗交界
+- [ ] 小字（如有）在它的底色上能读清楚（最细的字对比要求最高）
+
+**文字与静态底线**
+- [ ] 文字对比足够、字体栈齐全；无动画 / 外链节点
+- [ ] 落款名已按当前使用者替换（或改用中性落款），没有照抄示例里的名字
+- [ ] 若用了诗词版：五处文字齐全——左上标题（27/500，自拟短句）＋右上落款＋左下诗句两行（28/600/字距6）＋出处一行（14），右下无小字
+- [ ] 诗词版的标题与诗句不重复：标题写自己的话，诗句引原典
+- [ ] 诗词诗句与出处的对比足够：亮底近墨色、深底近纯白，出处没有发灰发淡
+
+## 交付前核对（结合 artkit 质检报告）
+
+- 报告无 ✗：结构、圆角裁切（全部内容在框内）、引用、字体栈、静态底线。
+- 调色清单与文案清单逐项核对：整幅用色协调、无错字、句子简短完整。
+- 自查清单（含底线三条、题材轮换、诗词版）已勾完；最终交付 = 质检通过的最新版本，且为零动画原生 SVG。

package/skills/cozy-static-svg/scripts/artkit.py

@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+"""静态 SVG 插画质检：结构校验 + 画风合规报告（秒级，直出 SVG，不转 PNG）。
+
+跨平台：macOS / Linux / Windows 都能跑，只用 Python 标准库（需 Python 3.9+）。
+
+    macOS / Linux   python3 scripts/artkit.py 作品.svg
+    Windows         py -3 scripts\\artkit.py 作品.svg
+
+批量质检（两个平台写法一致：目录和通配符都行，PowerShell 不必自己展开）：
+    python3 scripts/artkit.py .                 # 当前目录下全部 .svg（递归）
+    python3 scripts/artkit.py "out/*.svg"       # 通配符由脚本自己展开
+    py -3 scripts\\artkit.py 作品目录 --strict
+
+- 结构：命名空间 / 尺寸 / viewBox / title·desc / role·aria / 唯一标识 /
+  内部引用 / 禁用动态与外链 / 数值合法。
+- 画风：全部内容位于圆角裁切内（画布圆角约定）/ 字体栈 / 调色清单 /
+  文案清单 / 文案克制。
+- 退出码：0 通过（可含提示）；1 存在不合格项；--strict 时提示也算不合格。
+"""
+from __future__ import annotations
+
+import argparse
+import glob
+import re
+import sys
+import xml.etree.ElementTree as ET
+from collections import Counter
+from pathlib import Path
+
+if sys.version_info < (3, 9):
+    sys.exit(
+        "需要 Python 3.9 或更新版本（当前 %d.%d）；"
+        "Windows 请用 py -3 运行，或到 python.org 安装新版。" % sys.version_info[:2]
+    )
+
+# Windows 控制台默认是 GBK，直接 print 中文可能抛 UnicodeEncodeError → 强制 UTF-8 输出
+if hasattr(sys.stdout, "reconfigure"):
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+SVG_NS = "http://www.w3.org/2000/svg"
+BLOCKED = {
+    "script", "animate", "animatetransform", "animatemotion", "animatecolor",
+    "set", "discard", "foreignobject", "image", "iframe", "audio", "video", "a",
+}
+URL_RE = re.compile(r"url\(\s*(['\"]?)(.*?)\1\s*\)", re.I)
+CSS_MOTION = re.compile(
+    r"@keyframes\b|@import\b|(?:^|[;{\s])(?:-\w+-)?(?:animation|transition)(?:-[\w-]+)?\s*:",
+    re.I,
+)
+SIZE_RE = re.compile(r"(?:\d+(?:\.\d+)?|\.\d+)(?:px)?")
+NAN_RE = re.compile(r"\bNaN\b|\bInfinity\b", re.I)
+CJK_RE = re.compile(r"[\u4e00-\u9fff]")
+CJK_FACES = (
+    "pingfang sc", "noto sans cjk", "microsoft yahei", "heiti sc", "simhei",
+    "source han sans", "wenquanyi",
+)
+COUNT_ORDER = [
+    "g", "path", "circle", "ellipse", "rect", "line", "polygon", "polyline",
+    "text", "tspan", "use", "linearGradient", "radialGradient", "clipPath", "mask",
+]
+CLIP_REF_RE = re.compile(r"url\(\s*#([^)\s]+)\s*\)")
+
+
+def local(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+def local_attr(key: str) -> str:
+    return key.rsplit("}", 1)[-1].lower()
+
+
+def shorten(text: str, limit: int = 26) -> str:
+    return text if len(text) <= limit else text[:limit] + "…"
+
+
+def inspect(source: Path) -> dict:
+    """质检一个 SVG；不合格时抛出 ValueError，通过时返回报告数据。"""
+    raw = source.read_text(encoding="utf-8")
+    if re.search(r"<!DOCTYPE|<!ENTITY|<\?xml-stylesheet", raw, re.I):
+        raise ValueError("不接受 DTD、实体声明或外部样式表。")
+    root = ET.fromstring(raw)
+    if root.tag != f"{{{SVG_NS}}}svg":
+        raise ValueError("根节点必须是含正确命名空间的 SVG。")
+    vb = [float(x) for x in re.split(r"[\s,]+", root.get("viewBox", "").strip()) if x]
+    if len(vb) != 4 or vb[2] <= 0 or vb[3] <= 0:
+        raise ValueError("viewBox 必须包含四个数，宽高须为正数。")
+    for attr in ("width", "height"):
+        value = root.get(attr, "")
+        if not SIZE_RE.fullmatch(value) or float(value.removesuffix("px")) <= 0:
+            raise ValueError(f"请显式填写正数 {attr}（数字或 px）。")
+    canvas_w = float(root.get("width").removesuffix("px"))
+    canvas_h = float(root.get("height").removesuffix("px"))
+    for tag in ("title", "desc"):
+        node = root.find(f"{{{SVG_NS}}}{tag}")
+        if node is None or not "".join(node.itertext()).strip():
+            raise ValueError(f"缺少非空的 {tag}。")
+    if root.get("role") != "img" or not root.get("aria-labelledby", "").strip():
+        raise ValueError("请填写 role=img 和 aria-labelledby。")
+
+    elements = list(root.iter())
+    ids = [e.get("id") for e in elements if e.get("id") is not None]
+    if any(not i for i in ids) or len(ids) != len(set(ids)):
+        raise ValueError("存在空标识或重复标识。")
+    refs = set(root.get("aria-labelledby", "").split())
+    colors = Counter()
+    for node in elements:
+        tag = local(node.tag).lower()
+        if tag in BLOCKED or not node.tag.startswith("{" + SVG_NS + "}"):
+            raise ValueError(f"不接受的节点：{tag}。")
+        for key, value in node.attrib.items():
+            name = local_attr(key)
+            if name.startswith("on") or name == "base":
+                raise ValueError(f"不接受事件处理器或基址属性：{name}。")
+            if NAN_RE.search(value):
+                raise ValueError(f"属性含非法数值（NaN/Infinity）：{name}。")
+            if name == "href":
+                if not value.startswith("#") or len(value) < 2:
+                    raise ValueError("href 只能使用非空的内部 #标识引用。")
+                refs.add(value[1:])
+            if name in {"aria-labelledby", "aria-describedby"}:
+                refs.update(value.split())
+            if name == "style" and CSS_MOTION.search(value):
+                raise ValueError("不接受 CSS 动画、过渡或导入规则。")
+            for _, target in URL_RE.findall(value):
+                if not target.startswith("#") or len(target) < 2:
+                    raise ValueError("url() 只能使用内部 #标识引用。")
+                refs.add(target[1:])
+            if name in {"fill", "stroke", "stop-color"}:
+                plain = value.strip().lower()
+                if plain and not plain.startswith("url(") and plain not in {
+                    "none", "currentcolor", "transparent", "inherit",
+                }:
+                    colors[plain] += 1
+        if tag == "style":
+            css = "".join(node.itertext())
+            if CSS_MOTION.search(css):
+                raise ValueError("不接受 CSS 动画、过渡或导入规则。")
+            for _, target in URL_RE.findall(css):
+                if not target.startswith("#") or len(target) < 2:
+                    raise ValueError("样式只能引用内部资源。")
+                refs.add(target[1:])
+    missing = refs - set(ids)
+    if missing:
+        raise ValueError("未定义的引用：" + "、".join(sorted(missing)))
+
+    # 画风约定：全部内容（含文字）位于圆角裁切分组内
+    rounded_clips = {}
+    for clip in root.iter(f"{{{SVG_NS}}}clipPath"):
+        for child in clip:
+            if local(child.tag) == "rect" and child.get("rx"):
+                try:
+                    rx = float(child.get("rx"))
+                except ValueError:
+                    continue
+                if rx >= 10:
+                    rounded_clips[clip.get("id")] = (rx, child)
+    if not rounded_clips:
+        raise ValueError("缺少全幅圆角裁切：未找到含 rx≥10 矩形的 clipPath（画风约定：全幅统一圆角）。")
+    warns = []
+    frame_rx = None
+    for child in root:
+        tag = local(child.tag)
+        if tag in {"title", "desc", "defs", "metadata", "style"}:
+            continue
+        if tag == "g":
+            match = CLIP_REF_RE.fullmatch((child.get("clip-path") or "").strip())
+            target = match.group(1) if match else None
+            if target in rounded_clips:
+                rx, rect = rounded_clips[target]
+                if frame_rx is None:
+                    frame_rx = rx
+                rw, rh = rect.get("width"), rect.get("height")
+                if rw and rh:
+                    try:
+                        if abs(float(rw) - canvas_w) > 0.5 or abs(float(rh) - canvas_h) > 0.5:
+                            warns.append(
+                                f"圆角裁切 {rw}×{rh} 与画布 {canvas_w:g}×{canvas_h:g} 不完全一致"
+                            )
+                    except ValueError:
+                        pass
+                continue
+        raise ValueError(
+            f"最外层存在未纳入圆角裁切的 {tag}：全部内容（含文字）都应放在"
+            "引用圆角 clipPath 的 <g> 内。"
+        )
+    if frame_rx is None:
+        raise ValueError("找不到包住全部内容的圆角裁切分组。")
+
+    # 字体栈与文案
+    parents = {child: parent for parent in root.iter() for child in parent}
+    texts = []
+    for node in root.iter(f"{{{SVG_NS}}}text"):
+        content = "".join(node.itertext()).strip()
+        if content:
+            texts.append(content)
+        stack = node.get("font-family")
+        cursor = node
+        while stack is None and cursor in parents:
+            cursor = parents[cursor]
+            stack = cursor.get("font-family")
+        if not stack:
+            raise ValueError("有文字缺少 font-family（请在 <g> 或 <text> 上给出系统中文字体栈）。")
+        if CJK_RE.search(content) and not any(face in stack.lower() for face in CJK_FACES):
+            warns.append(f"字体栈可能缺少中文回退：「{shorten(content, 12)}」")
+    if len(texts) > 5:
+        warns.append(f"文案 {len(texts)} 处，注意克制（建议标题＋一句注脚）")
+
+    counts = Counter(local(e.tag) for e in elements)
+    return {
+        "width": canvas_w,
+        "height": canvas_h,
+        "nodes": len(elements),
+        "ids": len(ids),
+        "refs": len(refs),
+        "rx": frame_rx,
+        "texts": texts,
+        "colors": colors,
+        "counts": counts,
+        "warns": warns,
+    }
+
+
+def collect_sources(items: list[str]) -> list[Path]:
+    """把命令行参数展开成 SVG 文件列表：文件 / 目录 / 通配符都接受。
+
+    Windows 的 PowerShell 与 cmd 不会替命令展开 *.svg，所以通配符在这里自己展开，
+    两个平台的命令写法才能真正一致。
+    """
+    found: list[Path] = []
+    for item in items:
+        text = str(item)
+        path = Path(text)
+        if path.is_dir():
+            found.extend(
+                sorted(
+                    p
+                    for p in path.rglob("*")
+                    if p.is_file() and p.suffix.lower() == ".svg"
+                )
+            )
+            continue
+        if any(ch in text for ch in "*?["):
+            found.extend(
+                sorted(
+                    Path(m)
+                    for m in glob.glob(text, recursive=True)
+                    if Path(m).is_file() and Path(m).suffix.lower() == ".svg"
+                )
+            )
+            continue
+        found.append(path)
+
+    unique: list[Path] = []
+    seen: set[str] = set()
+    for p in found:
+        try:
+            key = str(p.resolve())
+        except OSError:
+            key = str(p)
+        if key not in seen:
+            seen.add(key)
+            unique.append(p)
+    return unique
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="静态 SVG 质检：结构校验 + 画风合规报告（跨平台，纯标准库）",
+        epilog="参数可以是文件、目录或通配符；目录会递归查找全部 .svg。",
+    )
+    parser.add_argument("svgs", nargs="+", help="待质检的 SVG（文件 / 目录 / 通配符）")
+    parser.add_argument("--strict", action="store_true", help="提示也视为不合格")
+    args = parser.parse_args()
+
+    sources = collect_sources(args.svgs)
+    if not sources:
+        print("没有找到任何 .svg —— 检查一下路径，或改用目录 / 通配符批量指定。")
+        return 1
+
+    failed = 0
+    warned = 0
+    for index, svg in enumerate(sources, 1):
+        print(f"[{index}/{len(sources)}] {svg.name}")
+        if not svg.is_file():
+            print(f"    ✗ 文件不存在或不是文件：{svg}")
+            failed += 1
+            continue
+        try:
+            report = inspect(svg)
+        except (OSError, ValueError, ET.ParseError) as exc:
+            print(f"    ✗ 检查未通过：{exc}")
+            failed += 1
+            continue
+        counts = report["counts"]
+        parts = " · ".join(f"{tag} {counts[tag]}" for tag in COUNT_ORDER if counts.get(tag))
+        top = " · ".join(f"{color}×{n}" for color, n in report["colors"].most_common(10))
+        print(f"    ✓ 结构：{report['width']:g}×{report['height']:g}；title/desc/role 齐全；无动态与外链")
+        print(f"    ✓ 引用：{report['ids']} 个标识 / {report['refs']} 处引用，全部有效")
+        print(f"    ✓ 裁切：全部内容位于圆角裁切内（rx≈{report['rx']:g}）")
+        print(f"    ✓ 字体：{len(report['texts'])} 处文字字体栈完整")
+        print(f"    元素 {report['nodes']}｜{parts}")
+        print(f"    调色 {len(report['colors'])} 种｜{top}")
+        print("    文案｜" + ("｜".join(shorten(t) for t in report["texts"]) or "无"))
+        if report["warns"]:
+            warned += 1
+            print("    ⚠ 提示｜" + "；".join(report["warns"]))
+        else:
+            print("    提示｜无")
+    passed = len(sources) - failed
+    tail = "；存在提示" if warned and not failed else ""
+    print(f"总计：{passed}/{len(sources)} 通过质检{tail}。")
+    if failed or (args.strict and warned):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())