论文与研究示意图（draw.io）
scibox-diagram 用于制作与修改可编辑的 draw.io / diagrams.net 示意图（.drawio XML）。主产物是可编辑的 .drawio 文件，PNG/PDF 为附带导出。模板、手写、复刻、校验、预览、导出等环节都在同一目录内完成。
一、三条使用路径
使用前需先判断走哪条路：
路径 A 套用模板：适用于全文脉络、研究框架、执行流程，或课题的任务分解，入口是下方模板索引。 路径 B 从零手写 XML：适用于其他示意图，如算法流程、模型架构、实验设计、机制示意等，入口是 references/authoring.md。 路径 C 高保真复刻：适用于给出参考图、需要照着重画成可编辑矢量图的情况，入口是 references/replication.md。
三条路的 XML 写法一致，产物可互相接着改，区别只在流程纪律的严格程度。
二、路径 A：套用模板
内置模板及适用表达：
roadmap-5band：954×1296 竖版，五条点线带 + 左旗标 + 右竖排标签，适合表达“提出问题 → 数据与指标 → 方法与机制 → 结果对比 → 评价推广”。说明见 references/roadmap-5band.md。 framework-3col：1026 宽三栏，左阶段链 / 中内容块 / 右方法清单，高度自适应，适合研究内容全景，即每个阶段对应哪些研究内容、用什么方法。说明见 references/framework-3col.md。 stageflow-3col：1000 宽三栏，中栏每块实色标题条 + 独立色系，高度自适应，适合研究/系统的执行流程，即阶段推进、决策分支、成果分发。说明见 references/stageflow-3col.md。 taskflow-land：横版 1360 宽，若干任务块，块内流水线 + 每步挂做法细节，适合把课题拆成“任务一…任务四”，每步要写清方法与结论，适合 16:9。说明见 references/taskflow-land.md。
使用模板时的要点：需读模板说明的两节——语义约定（哪些槽位并列、哪些汇流、哪两组必须可对比）与字数预算，语义放错比字数超框更严重；从用户材料中抽取内容，不要编造，有源文件（.tex/.md/代码）时逐个核对数值，术语用原文；复制 assets/<template_id>/example.json 改写，"\n" 手动断行。
渲染命令（写文件前逐槽校验字数，超框报出具体预算）：
python3 scripts/roadmap_5band.py content.json -o out.drawio # 模板 roadmap-5band python3 scripts/framework_3col.py content.json -o out.drawio # 模板 framework-3col python3 scripts/stageflow_3col.py content.json -o out.drawio # 模板 stageflow-3col python3 scripts/taskflow_land.py content.json -o out.drawio # 模板 taskflow-land（横版）
新增模板见 references/adding-templates.md。
三、路径 B：从零手写 XML
需读 references/authoring.md，内容包括骨架、样式速查、中文字宽预算、连接器写法、四个必踩的坑。图标与特殊图元见 references/icons.md。
三条最容易翻车的点：
- 先排栅格再写图元：定死画布、列基线、步距；同族同宽同步距，数量可变的组用等分公式。
- 中文手动断行：全角≈字号、半角≈字号/2、行高≈字号+3；16px 字号下 160px 宽的盒子每行最多 9 个汉字。竖排逐字 <br> 堆叠，不要用 horizontal=0（中文会躺倒）。
- 连接器端点离盒边 1px；一分多/多合一画成“竖线+横母线+分支”，不要画成 N 条独立斜线。
画之前想清楚每根箭头的语义（谁到谁、单向还是双向、扇入还是扇出）；说不出含义的箭头不要画。
四、路径 C：高保真复刻参考图
比路径 B 多一套证据链，照 references/replication.md 执行，要点：
先标定再动笔：连通域抠盒子坐标与填充色、行列扫描找框线、颜色普查取配色、量字宽反推字号。不要目测，也不要假设“标题一定比正文大”。 四件中间产物：visual-spec.md（看到了什么）、layout-grid.md（坐标计划）、asset-ledger.md（哪些是近似的，防止悄悄丢元素）、defect-log.md（首次截图后只增不改）。 ≥3 轮“截图 → 九区盘点 → 修完所有 P0/P1 → 重渲 → 逐条核销”；截图必须是画布本身。 红队复审 + 自评分卡（见 references/self-check.md）：总分 <40 或任一维 ≤4 不交付。 像素差分定位残留差异，逐条写进 defect-log.md，不写“已完美还原”。
五、通用：校验、预览、导出
python3 scripts/check_layout.py fig.drawio # 溢出/越界/重复 id/重叠/穿盒/位图（--strict 作门禁） python3 scripts/export_figure.py fig.drawio # 1:1 PNG + 矢量 PDF（需 drawio 命令行） python3 scripts/preview_html.py fig.drawio # 浏览器预览，无需 drawio 命令行
check_layout 用中文字宽模型、噪声低，正常的图应当 FAIL 0 / WARN 0；报警就值得认真看。它刻意不查紧密堆叠的行列间距和同族尺寸对齐（前者是刻意排版，后者机器判族必然误报）——这两项交给眼睛。规则详解与四个规避手法见 references/preflight-rules.md。
不看渲染图不算画完：XML 里看不出文字溢出、箭头压字、盒子挤扁。打开 PNG 至少过两轮：① 文字溢出/压线；② 箭头方向与语义；③ 同族元素对齐同宽；④ 数值有没有抄错。完整的九区盘点与交付清单见 references/self-check.md。
六、交付与尺寸提醒
交付物为 .drawio + PNG/PDF；走模板路径时保留 content JSON 作为可复现源。尺寸提醒：954px 宽、16px 字号的图压到 A4 正文 0.97\textwidth 约 6.5pt，建议整页横排或答辩使用，正文小图另做精简版。
七、参考索引
authoring.md：手写示意图——骨架、样式串、字宽预算、连接器 icons.md：需要图标、旗标、块箭头、弯箭头等特殊图元 roadmap-5band.md：用五带路线图模板 framework-3col.md：用三栏研究框架模板（内容全景） stageflow-3col.md：用三栏阶段流程模板（执行流程） taskflow-land.md：用横版任务流水线模板 adding-templates.md：新增一个模板 replication.md：复刻参考图——标定方法、四件产物、迭代闭环 self-check.md：九区盘点、红队复审、自评分卡、交付清单 preflight-rules.md：静态检查在查什么、误报如何绕开
八、不适用
折线图、热图、统计图等数据图表，应使用 scibox-figure 技能；需要 LaTeX 排版的公式推导链，应使用 TikZ 或写进正文。