附录 F：图像与可视化规范

本附录规定教程中主图、机制图和实验图的职责、存放位置、图注与验证方式。目标是让图帮助读者建立判断链路，而不是成为装饰或重复正文。

三类图与最低标准

类型	回答的问题	推荐格式	维护位置
章节主图	本章解决什么问题、与前后章如何衔接？	SVG	docs/public/diagrams/
机制图	一个方法的输入、变换、输出和边界是什么？	SVG 优先	docs/public/diagrams/
实验/项目图	在什么条件下有效、代价和失败案例是什么？	PNG（必要时 SVG）	assets/，由代码生成

每个核心章节应有一张章节主图；并非每个小节都需要配图。只有出现新的机制、容易混淆的比较，或需要解释实验结果时，才增加机制图或实验图。

编号与图注

章节主图不使用数字图号

章节入口处的全局路线图统一使用以下形式，避免与正文小节图号冲突：

![简短替代文本](/diagrams/ch05-llm-prediction-generation.svg)

*章节主图：一句话说明这张图连接了哪些概念，以及读者应如何使用它。*

小节图按“章节.小节-序号”编号

新增加的机制图或实验图使用 图<章号>.<小节号>-<序号>，例如 图4.1-1、图5.4-2。同一张图在章节 README 的实验索引和小节正文中重复展示时，必须使用同一编号和同一含义。

图注必须包含：

1. 图展示的对象或变量；
2. 读者应观察的关系；
3. 该关系对方法选择、边界或下一节的意义。

实验图还应说明关键条件，例如数据、SNR、阈值、模型版本或评价指标；不得把示意数据包装为真实 benchmark 结果。

文件与单一源头

docs/public/diagrams/       # 手工维护的 SVG：章节主图、流程、机制、决策图
assets/                     # 代码自动生成的 PNG/SVG：实验和项目结果的唯一源头
docs/public/assets/         # assets/ 的构建镜像，不手动修改
projects/<name>/outputs/    # 本地项目输出，不提交

命名规则：

ch04-transformer-information-flow.svg
ch06-solution-selection.svg
ch01_detection_performance.png

使用小写连字符，包含章节或作用域与图的职责；避免 final.svg、new.png、figure1.png 等不可维护名称。

SVG 要求

• 使用 viewBox，不依赖固定像素宽高；
• 包含 <title> 和 <desc>，并使用 role="img"；
• 颜色不是唯一的信息通道，关键关系同时用文字、位置或线型表达；
• 文字应简短，优先让图表达结构，把完整解释放到图注；
• 一张图只表达一个主要判断，不塞入完整课程内容；
• 修改 SVG 后必须执行 npm run docs:build，检查资源路径和页面渲染。
• make test 会验证每个核心章节都有章节主图，且引用的 SVG 具有 viewBox、title 和 desc。

新增或修改图片的检查清单

1. 这张图属于章节主图、机制图还是实验图？
2. 它是否回答了正文中一个明确的问题？
3. 图中的术语、颜色和箭头方向是否与正文一致？
4. 图注是否说明读者应该观察什么，以及该观察意味着什么？
5. 它是否与既有图重复，或造成图号冲突？
6. 实验图能否由对应脚本复现，且输出路径是否仍在 assets/ 或项目 outputs/？
7. npm run docs:build 是否通过？

历史图的处理原则

历史图不做为统一格式而统一格式的全量重命名。优先修复读者会在同一阅读路径中遇到的冲突；其余图片在对应小节重写或图重新生成时，迁移到本规范。章节主图采用非数字标题，正是为了与既有历史图号安全共存。