svg-diagrams

# 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` 的几何结构起步；替换内容并按实际信息量重算画布和坐标，不原样套用示例数字。 ## 工作流 1. 确认内容要求：列出最终用于论文、PPT、报告还是网页，以及图片类型、语言、节点 ID、唯一图内标题、类别、层级和关系。独立科研内容图默认只保留一个标题，不添加副标题、英文眉题、版本状态、来源摘要、实现说明或页脚状态条；页面已有标题时图内不再放标题。用于说明研究内容的图必须包含理解结构所需的准确短标签；hero、封面和氛围图不属于本技能的默认输出。标题、数字和方向均不得擅自生成。 2. 选择视觉配置：队列筛选、样本纳排、CONSORT 或病例流转使用 `journal-flow`；概念机制、技术路线、层级结构、包含关系、时间轴、矩阵和系统架构使用 `editorial`。不得把多色概念卡片用于研究对象筛选流程，也不得把任何固定配色和框形机械套到其它图类。 3. 审查模板并确定信息关系：先列出模板必须保留的比例、品牌、字体、色彩、安全区和必要组件，再根据内容选择 A 层级汇聚、B 谱系时间轴、C 嵌套包含、线性流程、矩阵、机制或架构。区域数量、阅读方向、视觉重点、密度和留白按内容重新确定；不得先选好看的模板再硬塞内容。 4. 分配语义样式：所有图先采用期刊队列图的共同语法，即白底、细边框、低饱和浅填充、常规正文和几何优先。流程图默认使用两类语义主色：常规路径与辅助或对照；只有真实警示、失败、异常、不良结局或必须单独识别的关键状态才增加第三类。主色相总数不超过三种，黑、白、灰等中性色不计入。不得默认采用蓝白配色，也不得把普通排除步骤自动标红。 5. 计算自然几何：先记录各区域适合横向、纵向、近方形、回环还是多输入汇聚，再确定画布、边距、轨道、节点宽高、连线通道和连接点。不同形状不能在一排等宽栏中成立时，改用双行主链、大小不同的编辑分区、分区组合图或总览与详图；不得通过超宽画布、窄字、压扁图元或高窄卡片维持单行。`data-layer` 只表示语义层，只有应当等尺寸的同类节点才共享 `data-size-group`。 6. 生成 SVG：使用原生元素和可编辑文字。节点写入唯一 `data-node-id`；直接表达事实关系的连线写入 `data-source`、`data-target` 和 `data-relation`；视觉样式元素同时写入 `data-role`、`data-category`、`data-tone` 和 `data-layer`。避免 `foreignObject`、外部 CSS、网络字体和滤镜。 7. 导出预览：SVG 是当前源文件，同时生成同名 PNG。按最终毫米宽度和目标 ppi 计算最低像素宽度，公式为 `像素 = 毫米 ÷ 25.4 × ppi`；记录实际像素、目标毫米宽度、有效 ppi 和 DPI 元数据。仅改写 DPI 元数据或插值放大不计为达到印刷清晰度。期刊要求 PDF/EMF 时从 SVG 派生，不反向从 PNG 描摹。 8. 按范围验证：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 或网页已更新。只有共享样式、画布比例、语义图结构、输出尺寸或正式用途发生变化时，才扩大检查。 验证示例： ```bash 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 ```