svg-diagrams

name	svg-diagrams
description	创建、审校或修改可编辑且内容精确的 SVG 非统计图解。仅在用户明确要求 SVG/矢量源、编辑现有 SVG，或 research-visuals 已实际耗尽适用 imagegen 路径且仍无法保证文字和关系准确时使用。HTTP 524、文字密集或预测生成会失败均不是回退凭证；普通非统计视觉先走 research-visuals，统计图走 publication-figures。

SVG 图解回退

以原生 SVG 构建内容精确、可编辑的非统计图形。泛化的流程图、框架图、机制图、示意图和跨载体配图由 research-visuals 先调用 imagegen；除用户明确要求矢量或当前会话没有可用图像生成工具外，只有全部适用的 imagegen 路径实际耗尽后才进入本技能。适用的 Image 2 优先于 SVG。默认不调用 R 绘图包生成流程框，也不把 HTML、Mermaid 或 Graphviz 默认主题截图当成品。

进入本技能后先记录回退原因，并沿用 research-visuals 已锁定的视觉简报、节点、标签和关系契约；不得在工具切换时改动信息结构。用户显式调用本技能或直接要求 SVG 时无需先生成位图。

回退凭证

除用户显式要求 SVG、直接调用本技能或编辑现有 SVG 外，开始绘制前必须满足并记录以下至少一项：

• 已检查当前会话的实际图像生成工具，确认没有可用 image_gen 或其它已配置生成路径。
• 已真实调用 imagegen，发生非 HTTP 524 的失败，且其允许的重试或内置路径均不可用。
• imagegen 已成功返回并查看完整原图，经过 Image 1 定向修正、适用的 Image 2 辅助修正和允许的整图重生成后，关键文字、数字、节点或关系仍不准确；如无适用 Image 2，已记录其不适用原因。

“文字或数字多”“预计 imagegen 可能写错”“已有候选图不准确”“SVG 更容易做”“当前可见 skills 清单没有 research-visuals”“存在适用 Image 2 但尚未尝试”和“携图调用连续两次 HTTP 524”均为无效凭证，不得据此提前进入本技能。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 的几何结构起步；替换内容并按实际信息量重算画布和坐标，不原样套用示例数字。

工作流

1. 锁定内容契约：列出用途、载体、信息角色、语言、节点 ID、标题、可选副标题、语义类别、层级和关系。正文内容图必须包含理解结构所需的准确短标签；hero、封面和氛围图不属于本技能的默认输出。标题、副标题、数字和方向均不得擅自生成。
2. 选择视觉配置：队列筛选、样本纳排、CONSORT 或病例流转使用 journal-flow；概念机制、技术路线、层级结构、包含关系、时间轴、矩阵和系统架构使用 editorial。不得把多色概念卡片用于研究对象筛选流程，也不得把任何固定配色和框形机械套到其它图类。
3. 审查模板与选择拓扑：先列出模板必须保留的比例、品牌、字体、色彩、安全区和必要组件，再按内容从 A 层级汇聚、B 谱系时间轴、C 嵌套包含、线性流程、矩阵、机制或架构中选择。区域数量、阅读方向、视觉权重、密度和留白按内容重算；不得先选好看的模板再硬塞内容。
4. 分配语义样式：所有图先采用期刊队列图的共同语法，即白底、细边框、低饱和浅填充、常规正文和几何优先。流程图默认使用两类语义主色：常规路径与辅助或对照；只有真实警示、失败、异常、不良结局或必须单独识别的关键状态才增加第三类。主色相总数不超过三种，黑、白、灰等中性色不计入。不得默认采用蓝白配色，也不得把普通排除步骤自动标红。
5. 计算几何：先确定画布、边距、轨道、节点宽高、锚点、间距和连接线坐标，再写 SVG。禁止凭目测逐个拖位置。
6. 生成 SVG：使用原生元素和可编辑文字；语义元素写入 data-role、data-category、data-layer，供自动校验。避免 foreignObject、外部 CSS、网络字体和滤镜。
7. 导出预览：SVG 是当前源文件，同时生成同名 PNG。期刊要求 PDF/EMF 时从 SVG 派生，不反向从 PNG 描摹。
8. 双重验证：按视觉配置运行 scripts/validate_svg.py --profile journal-flow|editorial，再按最终嵌入尺寸渲染并目视检查；修复后重新验证受影响图件。

拓扑选择

版式	适用语义	不适用情况
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 的嵌入回退。
• README 与技术文档：按实际内容列宽设计；正文内容图直接包含必要标签，并在桌面与窄屏渲染下检查字号、箭头、替代文本和文件体积。
• 所有载体：内容决定高度，避免为了填满固定比例制造大面积空白。

默认视觉规则

• 只保留一个视觉主张。无用户要求时，不添加英文眉题、画布副标题、装饰圆点、无语义图标或背景大色块。
• 载体已有标题时，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="card|nested-layer" data-category="..." data-tone="primary|secondary|critical|neutral" data-layer="..."
• 期刊研究流程：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|axis|axis-tick"
• 可选 PPT 装饰：data-role="decoration"；论文图禁止该角色。

语义类别固定为 biology、exposure、covariate、risk、outcome、nonlinear，用于机器识别内容类别；外观颜色由 data-tone 的阅读角色决定，不按类别自动分色。具体颜色见设计系统。

与论文、报告和 PPT 的衔接

• 统计图、森林图、生存曲线、热图等仍由 publication-figures 生成；本技能不处理数据映射图。
• 流程、结构、机制、路线、包含关系和跨载体非统计视觉默认由 research-visuals 调用 imagegen；本技能只承担显式矢量需求和全部适用 imagegen 路径耗尽后的最终回退，不再作为泛化图解的默认入口。
• 论文和报告保留 SVG 源文件与同名 PNG；Word 不直接支持时嵌入 PNG，但不得丢失 SVG 源。
• PPT 优先直接嵌入 SVG；若当前生成库不能嵌入，才使用同名 PNG 回退，并在源目录保留 SVG。
• 混合图先分别生成统计面板和 SVG 图解面板，再按共同字体、配色和边距拼装。

强制自检

• 文字、数字和关系与来源逐项一致，无擅自新增内容
• 画布比例匹配最终载体，无明显空边或压缩变形
• 同行、同列、同层、嵌套框和连接锚点严格对齐
• 序号与标题第一行垂直居中对齐
• 字号层级清楚，分支标题不小于正文
• 无英文眉题、虚构副标题、深色顶条、装饰圆点和无语义图标
• 连接线不穿字、不穿框、不交叉，箭头方向明确
• 同类节点配色一致；颜色不是唯一的类别线索
• 默认使用两类语义主色，必要时才增加第三类；主色相总数不超过三种，未默认套用蓝白配色
• 警示色只对应真实警示、失败、异常、不良结局或关键状态，普通排除步骤未自动标红
• 图内标签来自来源、方案或规范术语，无内部流程词、生硬直译、自造缩略语或临时拼接短语
• 非显式矢量任务已记录 imagegen 回退凭证；适用的 Image 2 已先于 SVG 尝试
• 没有无意义的卡片墙、彩色徽章、胶囊标签或每框一个图标
• SVG XML 有效，文字未裁切，PNG 预览与 SVG 一致
• 当前版使用稳定文件名，旧版已整组归档

验证示例：

python skills/svg-diagrams/scripts/validate_svg.py output.svg \
  --profile editorial --purpose ppt --expected-ratio 1.777778 \
  --require-text "主流程" --forbid-text "RESEARCH WORKFLOW"

python skills/svg-diagrams/scripts/validate_svg.py cohort_flow.svg \
  --profile journal-flow --purpose paper --max-circles 0