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