kangwang42 SVG 图解
以原生 SVG 构建内容精确、可编辑的非统计图形。为论文、PPT、报告或网页制作的一般流程图、框架图、机制图和示意图先由 research-visuals 调用 imagegen。只有用户明确要求 SVG、矢量源或完全可编辑图形，编辑现有 SVG，目标格式强制矢量，或只读检查确认当前没有可用 imagegen 路径时才进入本技能。imagegen 已成功返回但关键文字、数字、节点、关系、布局或美学仍不合格时，继续按 research-visuals 的两轮修改与问题披露流程处理，不切换 SVG。默认不调用 R 绘图包生成流程框，也不把 HTML、Mermaid 或 Graphviz 默认主题截图当成品。
进入本技能后先记录改用 SVG 的原因，并沿用 research-visuals 已经确认的图件要求、节点、标签和关系；不得在更换工具时改动信息结构。用户明确调用本技能或直接要求 SVG 时无需先生成位图。
用户提供图片时先判定其角色。待修改原图要求保留其中已确认的视觉特征，只修用户允许的部分；内容来源图只提供事实、文字与关系，先转写为节点表和关系表，再从空白画布重构，不沿用原图的区域、比例、卡片、颜色或阅读路径。用户已经否定原图审美、要求“重构布局”或“重新组织内容”时，必须采用内容来源图路线。
本 skill 内，Q 只解释或只读核对指定内容；L 只修改一个已确认的 SVG、节点、标签、连线或显示项；P 新建图件或重大重绘；R 再按论文、报告、PPT、网页或归档要求检查正式当前版。L 不重新规划整张图，不为一个局部修改执行完整图类清单或重查无关节点。
使用 SVG 的条件
开始绘制前必须满足并记录以下至少一项：
- 用户明确要求 SVG、矢量源、完全可编辑图形或直接调用本技能。
- 任务是编辑现有 SVG。
- 期刊、系统、合同或交付格式明确强制矢量源。
- 已只读检查当前会话的实际图像生成工具，确认没有可用
image_gen或其它已配置生成路径，并记录不可用的证据。
“文字或数字多”“预计 imagegen 可能写错”“已有修改结果不准确或不好看”“SVG 更容易做”“当前可见 skills 清单没有 research-visuals”和“附图调用连续两次 HTTP 524”均不能作为改用 SVG 的理由。HTTP 524 按 research-visuals 保留原图并停止，不自动转用 SVG。
必读资源
- 每次生成或重绘前完整阅读
references/design-system.md。 - 使用层级汇聚、证据谱系或嵌套样本结构时，再读
references/layout-recipes.md对应 A、B、C 章节。 - 内容尚未结构化时，用
references/request-template.md整理，不向图中补写来源没有的信息。 - 生成队列筛选或末端结局分支时，分别从
assets/journal-flow-screening.svg或assets/journal-flow-branching.svg的几何结构起步；替换内容并按实际信息量重算画布和坐标，不原样套用示例数字。
工作流
- 确认内容要求：列出最终用于论文、PPT、报告还是网页，以及图片类型、语言、节点 ID、唯一图内标题、类别、层级和关系。独立科研内容图默认只保留一个标题，不添加副标题、英文眉题、版本状态、来源摘要、实现说明或页脚状态条；页面已有标题时图内不再放标题。用于说明研究内容的图必须包含理解结构所需的准确短标签；hero、封面和氛围图不属于本技能的默认输出。标题、数字和方向均不得擅自生成。
- 选择视觉配置：队列筛选、样本纳排、CONSORT 或病例流转使用
journal-flow；概念机制、技术路线、层级结构、包含关系、时间轴、矩阵和系统架构使用editorial。不得把多色概念卡片用于研究对象筛选流程，也不得把任何固定配色和框形机械套到其它图类。 - 审查模板并确定信息关系：先列出模板必须保留的比例、品牌、字体、色彩、安全区和必要组件，再根据内容选择 A 层级汇聚、B 谱系时间轴、C 嵌套包含、线性流程、矩阵、机制或架构。区域数量、阅读方向、视觉重点、密度和留白按内容重新确定；不得先选好看的模板再硬塞内容。
- 分配语义样式：所有图先采用期刊队列图的共同语法，即白底、细边框、低饱和浅填充、常规正文和几何优先。流程图默认使用两类语义主色：常规路径与辅助或对照；只有真实警示、失败、异常、不良结局或必须单独识别的关键状态才增加第三类。主色相总数不超过三种，黑、白、灰等中性色不计入。不得默认采用蓝白配色，也不得把普通排除步骤自动标红。
- 计算自然几何：先记录各区域适合横向、纵向、近方形、回环还是多输入汇聚，再确定画布、边距、轨道、节点宽高、连线通道和连接点。不同形状不能在一排等宽栏中成立时，改用双行主链、大小不同的编辑分区、分区组合图或总览与详图；不得通过超宽画布、窄字、压扁图元或高窄卡片维持单行。
data-layer只表示语义层，只有应当等尺寸的同类节点才共享data-size-group。 - 生成 SVG：使用原生元素和可编辑文字。节点写入唯一
data-node-id；直接表达事实关系的连线写入data-source、data-target和data-relation；视觉样式元素同时写入data-role、data-category、data-tone和data-layer。避免foreignObject、外部 CSS、网络字体和滤镜。 - 导出预览：SVG 是当前源文件，同时生成同名 PNG。按最终毫米宽度和目标 ppi 计算最低像素宽度，公式为
像素 = 毫米 ÷ 25.4 × ppi；记录实际像素、目标毫米宽度、有效 ppi 和 DPI 元数据。仅改写 DPI 元数据或插值放大不计为达到印刷清晰度。期刊要求 PDF/EMF 时从 SVG 派生，不反向从 PNG 描摹。 - 按范围验证：P/R 按视觉配置运行
scripts/validate_svg.py --profile journal-flow|editorial。内容精确图同时传入全部必需节点、必需边和--require-semantic-graph；独立单标题图加入--single-title；论文或报告 PNG 预览加入--preview-png、--target-width-mm与--target-ppi。L 只使用能够发现本次修改错误的参数，并核对目标变化、未授权文字和关系未变、实际使用该图的论文页、报告、PPT 或网页已更新；不重复与本次修改无关的完整语义图、分辨率或全图样式检查。随后在最终嵌入尺寸检查受影响位置，修复后只重新验证该问题和实际受其影响的成品。
信息关系与版式选择
| 版式 | 适用语义 | 不适用情况 |
|---|---|---|
| A 层级汇聚 | 多因素或多模块汇入核心机制，再指向结局 | 只是时间先后或证据并列 |
| B 谱系/时间轴 | 研究维度、时间顺序、证据分歧或结论分布 | 节点存在明确汇聚因果关系 |
| C 嵌套包含 | 总体、子集、核心分析集、亚组和样本量结构 | 流程步骤或有方向关系 |
| 线性/分支流程 | 明确顺序、决策或处理阶段 | 只有概念归属而无顺序 |
| 矩阵/架构 | 行列比较、模块边界和输入处理输出 | 少量节点可用更简单结构表达 |
队列筛选和样本纳排不是 A 型概念汇聚图。它们采用一条居中的纵向主路径，排除项在侧栏以灰框接出，末端按结局或分析集分支。
图类选择
| 图类 | 默认结构 | 主要视觉线索 |
|---|---|---|
| 队列筛选、CONSORT | journal-flow 纵向主线或末端分支 |
常规路径色、辅助排除色、近直角；不良结局可用警示色 |
| 概念框架、机制图 | A 汇聚或左中右机制轨道 | 语义淡色、位置主次、共享母线 |
| 技术路线、处理流程 | 线性或分阶段流程 | 阶段分组、统一步骤框、正交箭头 |
| 层级图、组织结构 | 树形或分层容器 | 层级缩进、父子边界、同级共线 |
| 包含关系、样本结构 | C 嵌套包含 | 共同中心、等差内边距，不用箭头 |
| 时间轴、证据谱系 | B 水平主轴 | 等距刻度、短垂线、上下分布 |
| 矩阵、二维分类 | 行列网格 | 行列标题、共享边界、有限强调 |
| 系统架构、模块关系 | 容器加通道 | 模块边界、输入处理输出、边缘走线 |
先写清结构命题再选图类。不同图类共享字体、留白、对齐和克制配色原则，但不共享固定框形、固定方向或固定节点数量。
画布与使用位置
- PPT 全页图：默认
viewBox="0 0 1600 900"，16:9；嵌入半页或栏位时按实际占位比例生成，不把方图硬塞进宽框。 - 论文图：按最终单栏约 85 mm 或双栏约 170–180 mm 设计；图注默认交给正文或投稿系统，只有目标格式明确要求时才嵌入 SVG。
- 报告图：按 Word 版心宽度设计，通常 140–165 mm；保留同名 PNG，供 python-docx 无法直接使用 SVG 时嵌入。
- README 与技术文档：按实际内容列宽设计；正文内容图直接包含必要标签，并在桌面与窄屏渲染下检查字号、箭头、替代文本和文件体积。
- 所有使用位置：内容决定高度，避免为了填满固定比例制造大面积空白。
默认视觉规则
- 只保留一个视觉主张。无用户要求时，不添加英文眉题、画布副标题、装饰圆点、无语义图标或背景大色块。
- 独立科研内容图使用一个
data-role="figure-title"标题；不设置画布副标题、眉题或页脚状态。所在页面已有标题时，SVG 内不重复放标题；PPT 页标题、论文图注或报告小节标题与 SVG 内标题二选一。 - 概念图的节点副标题是可选信息层，不是固定装饰。只有来源确有次级说明时才生成；不得为了凑两行虚构解释。
- 所有图默认白底、1 至 1.5 px 细边框、低饱和浅填充和常规正文。
editorial框通常使用 2 至 8 px 小圆角；只有明确的柔和概念图才可到 10 px。journal-flow使用 0 至 2 px 近直角框和更紧凑的内容框。 - 强调靠字重、位置、边界和留白，不靠高饱和色。全图只启用实际存在的语义类别。
editorial默认使用两类低饱和语义主色，必要时增加一类警示或关键状态色；主色相总数不超过三种。即使存在多个语义类别，也先用标题、位置、边界和连线区分，不按变量类别逐框随机换色。目标文档或网页有既有视觉系统时，在保持语义角色不变的前提下适配其颜色。- 同层节点等宽等高；同一行列使用共同的对齐基准；相邻间距一致；分支使用正交或短曲线连接，避免长斜虚线跨越大片空白。
- 序号标记与标题第一行的视觉中心在同一水平线上。序号、标题和副文字不能各自漂浮在不同基线。
- 分支标题、组标题和说明文字不得小于同图正文；小字不能承担结构层级。
- 包含关系图按共同中心或共同基线嵌套，各层内边距递进一致；层标题与样本量在同一基线，底部说明居中且与边框保持安全距离。
- 中文字体统一使用思源黑体、苹方或微软雅黑之一；英文使用 Arial/Helvetica。SVG 中按顺序列出可替代字体，不依赖某一台电脑上的单一字体。
语义元数据
对新生成图使用以下属性：
- 画布：
data-role="canvas" - 图内唯一标题：
data-role="figure-title" - 卡片或嵌套层：
data-role="card|nested-layer" data-node-id="..." data-category="..." data-tone="primary|secondary|critical|neutral" data-layer="..."；只有确实应等尺寸的同类节点再使用相同data-size-group - 期刊研究流程：
data-role="flow-main|flow-exclusion|flow-terminal" data-layer="..." - 标题与副标题：
data-role="node-title|node-subtitle" data-category="..." data-tone="primary|secondary|critical|neutral" - 事实关系连线：
data-role="connector" data-source="..." data-target="..." data-relation="..." data-arrow="true|false" - 主轴与刻度：
data-role="axis|axis-tick" - 可选 PPT 装饰：
data-role="decoration"；论文图禁止该角色。
语义类别固定为 biology、exposure、covariate、risk、outcome、nonlinear，用于机器识别内容类别；外观颜色由 data-tone 的阅读角色决定，不按类别自动分色。具体颜色见设计系统。
与论文、报告和 PPT 的衔接
- 统计图、森林图、生存曲线、热图等仍由
publication-figures生成；本技能不处理数据映射图。 - 为论文、PPT、报告或网页制作的流程、结构、机制、路线和包含关系图默认由
research-visuals调用 imagegen；本技能只处理明确矢量需求、现有 SVG 编辑、强制矢量格式或 imagegen 实际不可用的任务。普通图解和 imagegen 质量修正不使用本技能。 - 论文和报告保留 SVG 源文件与同名 PNG；Word 不直接支持时嵌入 PNG，但不得丢失 SVG 源。
- PPT 优先直接嵌入 SVG；若当前生成库不能嵌入，则使用同名 PNG，并在源目录保留 SVG。
- 混合图先分别生成统计子图和 SVG 图解子图，再按共同字体、配色和边距组合。
新图、重大重绘与正式发布自检
以下项目只选择与图类、使用位置和本次变化实际有关的内容；它们适用于 P 新图、重大重绘和 R 正式发布，不是 L 局部修改的固定清单。每项检查必须能指出可能发现的具体内容、关系、显示或文件错误，否则不执行。
- 文字、数字和关系与来源逐项一致，无擅自新增内容
- 内容来源图已先转写事实和拓扑，未保留被否定的原布局与审美
- 独立内容图只有一个图内标题，无副标题、眉题、版本状态、实现说明或页脚状态条
- 画布比例匹配最终页面或图位，无明显空边或压缩变形
- 区域按自然形状排布，没有用高窄卡片、窄字或失真图元强行维持单行
- 同行、同列、同层、嵌套框和连接点严格对齐
- 序号与标题第一行垂直居中对齐
- 字号层级清楚，分支标题不小于正文
- 无英文眉题、虚构副标题、深色顶条、装饰圆点和无语义图标
- 连接线不穿字、不穿框、不交叉，箭头方向明确
- 同类节点配色一致；颜色不是唯一的类别线索
- 默认使用两类语义主色，必要时才增加第三类；主色相总数不超过三种，未默认套用蓝白配色
- 警示色只对应真实警示、失败、异常、不良结局或关键状态，普通排除步骤未自动标红
- 图内标签来自来源、方案或规范术语，无内部流程词、生硬直译、自造缩略语或临时拼接短语
- 已记录使用 SVG 的合法原因：明确矢量要求、编辑现有 SVG、强制矢量格式或 imagegen 实际不可用；未因 imagegen 内容或美学不合格而切换
- 没有无意义的卡片墙、彩色徽章、胶囊标签或每框一个图标
- SVG XML 有效，文字未裁切，PNG 预览与 SVG 一致
- 必需节点与必需边已由语义图校验逐项确认，连线端点均引用真实节点
- PNG 实际像素、目标毫米宽度、有效 ppi 与 DPI 元数据同时达到约定；未以改元数据或插值冒充清晰度
- 正式项目当前版使用稳定文件名；确有需要恢复的旧正式版已整组归档，轻量任务不建立项目归档
L 完成时只确认：指定节点、标签、连线或显示项已经按要求修改；其它文字、数字、关系和样式未被误改；SVG 可重新打开；实际使用该图的论文、报告、PPT 或网页已更新。只有共享样式、画布比例、语义图结构、输出尺寸或正式用途发生变化时，才扩大检查。
验证示例：
python skills/svg-diagrams/scripts/validate_svg.py output.svg \
--profile editorial --purpose ppt --expected-ratio 1.777778 \
--require-text "主流程" --forbid-text "RESEARCH WORKFLOW" \
--single-title --require-semantic-graph \
--require-node input --require-node output \
--require-edge "input->output"
python skills/svg-diagrams/scripts/validate_svg.py cohort_flow.svg \
--profile journal-flow --purpose paper --max-circles 0
python skills/svg-diagrams/scripts/validate_svg.py architecture.svg \
--profile editorial --purpose paper --single-title \
--preview-png architecture.png --target-width-mm 180 --target-ppi 300