content-infographic 的来路:图本身讲清一件事,和正文咬在一起
长文里的关系、顺序和主次,经常要读者自己在脑中重排。随手配一张好看的图,又可能只是氛围图;图里换了术语或比喻,读者以为在看解释,实际看的是另一套内容。
content-infographic 把配图做成写作的下游步骤:正文先有判断,图再帮助解释。它来自技术文章配图实践,后来把方法和平台能力分开,保留可迁移的出图与核对流程。
先决定画什么
先问读者看完这张图应该理解哪件事,再找支持它的段落。不能先画好,再给它找一节正文安放。
| 要决定的事 | 判断方法 |
|---|---|
| 是否需要图 | 一句话已经讲清就不画;关系要读者反复重排,才用图承载 |
| 这张图的主题 | 只保留一个判断,主次、顺序、条件围绕它组织 |
| 文字从哪里来 | 先列上屏文字,沿用正文术语和作者已有比喻 |
| 能否放进一张 | 信息过多按判断拆分,不靠缩字号塞满,也不按章节数量凑图 |
下面的流程图从正文定位开始,经过选后端、渲染和图文核对。侧边是文生图与比喻的限制,目的都是让图仍在解释同一段内容。
默认阅读经验:本技能对超过7步或4列的密集图要求拆分。先确定各图要表达的判断,再安排总览与详图;数量线不替代图义。具体布局的 Schema 上限另查。

按内容选后端
多标签图与具象场景图需要不同能力。默认先保住文字和关系的准确性,再选择表现方式。
| 后端 | 适合什么 | 怎么检查 |
|---|---|---|
| 确定性渲染器 | 步骤链、分类、对照和多标签;结构化内容生成 SVG,文字可改可复核 | 既检查内容,也看实际折行、间距和连接关系 |
| 文生图 | 标签少、靠体量与动作把判断演出来的场景或封面 | 逐项检查错字、漏项、误连线和多余内容 |
用户指定既有立体风格,就继承那种表现方式,不能静默换成几何流程图,也不能以精简为由删掉标题、节点用途和关键关系。精确架构、时序和可评审工程关系则交给 engineering-docs。
渲染器用 Python 标准库生成 SVG;PNG 导出需要环境里可用的转换器。文生图按宿主原生能力、MCP 或 HTTP 适配,不具备时说明缺口并降级,不把没出图说成已经完成。
图与正文对账
一张正文图按“锚定段落 → 指图过渡句 → 图 → 图注”放置。过渡句要点出图里的具体对象,而不只写“见下图”。
| 检查对象 | 要回答的问题 |
|---|---|
| 术语与数字 | 正文能否找到出处,是否换了名字或新增数据 |
| 关系 | 先后、方向、条件和阶段与正文是否一致 |
| 比喻 | 是否沿用作者已有比喻,新增比喻有没有先确认并同步正文 |
| 实际画面 | 标签有没有挤在一起,箭头和分界是否能看清 |
check_linkage.py 能提示文字脱锚、自造术语、另起比喻和过渡句缺失;它不能替代实际读图,也不能证明图已经提升理解。
原稿样例与反例
原稿用七张卡片呈现 API 调用说明:Tokenizer 分词、Embedding 查表、加位置编码、N 层 Transformer、Softmax 采样、自回归循环、De-tokenize。阶段括号补出 Prefill 与 Decode 的分界,让读者同时看到顺序和分组。
下图保留这张原样例。它也提供了一个检查反例:术语能够对账,但卡片标题与说明仍有可见重叠,不能因为机器放行,就说画面已经合格。

文字层的另一种反例是把某个标题改成正文没有的 Pretraining,或把作者的阶段比喻换成读书、实习、工作。即便新图好看,也要回到原文改正,不能靠新图注把不同内容补成合法。
使用与交付
把已成型的段落交给 Agent,说“把这节画出来”。先确定该不该出图和上屏文字,再做环境自检、选后端、生成和核对。
python3 scripts/doctor.py
python3 scripts/render_infographic.py spec.json -o out.svg --png
python3 scripts/check_linkage.py figure.json
最终交图、可修改源、锚定段落、过渡句和图注。原文和公开版文章可查看完整实践;实践总结补充了文字结构与视觉评审的取舍。
本技能不写正文,不把代码、API 签名、公式和精确参数塞进信息图。它帮助读者看清道理,工程图帮助评审精确关系,两者可以配合,不互相替代。