AGENT

图文文档写作规范

2026/04/20 8 min read AGENT 图文文档写作规范

图文文档写作规范

适用范围

适用于需要输出以下任一类型内容的任务：

  • 图文并茂说明文档
  • 带截图的操作手册、排障记录、上线说明
  • 带结构图、流程图、示意图的方案文档
  • 需要导出 PDF / DOCX / 对外分发的说明材料
  • 需要把“看得见的界面、状态、结果”讲清楚的汇报文档

这份文档管的是“图文如何共同表达”，不是替代全局文档基线。文档创建、整合、合并、删旧、修引用等通用规则，仍以 C:\Users\ASUS-KL\.codex\AGENTS.md 和 C:\Users\ASUS-KL\.codex\AGENTS.annotated.md 为入口约束。

一、总原则

  1. 先定主文档，再组织图片，不要先堆截图再拼文字。
  2. 图片必须服务事实，不服务装饰。
  3. 一张图只承担一个主结论，不要让一张图同时解释五件事。
  4. 文字必须能说明图里“为什么值得看”，图片必须能补足文字“看了才更快懂”的部分。
  5. 如果纯文字已经最清楚，就不要硬塞图片；如果图片能显著降低理解成本，就不要只写字墙。

一句话：图不是点缀，图是证据、结构、定位或对比工具。

二、写前预检

开始写图文文档前，先明确 5 件事：

  1. 这份文档的主读者是谁
  2. 读者看完后要完成什么动作
  3. 这份文档的 canonical 文件是哪一份
  4. 哪些截图 / 示意图 / 配图是必须保留的证据
  5. 哪些内容只能文字说明，哪些内容必须靠图来讲清

没有回答清楚这 5 件事之前，不要先进入截图堆积或排版微调。

三、文图分工

1. 文字负责什么

文字默认负责：

  • 交代背景、目标、边界
  • 说明步骤顺序
  • 解释图里应该看哪里
  • 给出结论、限制、注意事项
  • 补足图中看不到的上下文

2. 图片负责什么

图片默认负责：

  • 证明某个界面 / 状态 / 结果真实存在
  • 帮读者快速定位按钮、区域、层级、异常点
  • 展示结构关系、流程关系、前后对比
  • 压缩重复说明，减少大段抽象文字

3. 不要混用职责

不要让：

  • 图片承担全部步骤说明，正文只剩“见下图”
  • 文字重复逐句朗读图片里已经明显可见的信息
  • 一堆截图并排出现，但没有说明每张图的结论

默认要求是：读者扫标题与图注，就应知道每张图为什么在这里。

四、截图规范

1. 何时必须截图

以下场景默认应提供截图或等价可视证据：

  • 页面改版、UI 变更、可见结果验证
  • 控制台 / 运维页状态变化
  • 关键操作路径说明
  • 报错界面、异常状态、修复前后对比
  • 需要向别人证明“现在就是这样”的现场结果

2. 截图选择规则

优先顺序默认是：

  1. 能证明目标结果的最小可见区域
  2. 必要时补一张全页上下文图
  3. 如果有前后对比，再补“前 / 后”配对图

不要默认每次都贴整页长截图。整页只有在“页面结构本身”是结论的一部分时才值得保留。

3. 截图内容要求

截图应尽量满足：

  • 主体明确，不把结论淹没在无关区域里
  • 保留必要上下文，避免只截一个按钮导致无法判断它在哪里
  • 如果结论依赖状态文字、数字、Badge、表头、路径、时间戳，应确保这些信息可读
  • 如果要证明“无报错 / 无告警”，不要只截局部，至少保留能看出整体状态的区域

4. 截图文件落点

图文文档所需的本地图片、截图、示意图，默认统一落到：

  • E:\My Project\Atramenti-Console\codex\plugins\obsidian\data\image

不要在 docs 下为单篇文档临时再建一套 assets、images、xxx.images、同级图片副本。

5. 截图命名

截图文件名默认应包含：

  • 主题
  • 页面或对象
  • 关键状态
  • 日期

例如：

  • mortis-overview-status-filter-active-20260420.png
  • deploy-center-heartbeat-healthy-20260420.png

不要使用 图片1.png、截图(3).png、最终版.png 这类不可维护命名。

五、示意图 / 结构图规范

1. 何时画图

以下内容默认优先考虑结构图、流程图或关系图，而不是截图：

  • 架构关系
  • 部署拓扑
  • 数据流 / 调用链
  • 分层职责
  • 多步骤流程

2. 画图规则

图要尽量做到：

  • 一个图只讲一条主线
  • 节点名称与正文术语一致
  • 先有结构层级，再谈样式
  • 颜色只辅助分组，不额外发明复杂语义
  • 不为“看起来高级”添加无意义图标、渐变、装饰线

3. 什么时候不要画图

以下情况默认不要画图：

  • 纯粹为了让文档“看起来更丰富”
  • 文本本来两三行就能说清
  • 没有稳定结构，只能画出临时想象图
  • 图会比文字更难维护

六、推荐写法

图文文档默认优先采用下面的结构：

  1. 这份文档解决什么问题
  2. 当前状态 / 目标状态
  3. 主步骤或主结构
  4. 关键截图 / 关键示意图
  5. 风险、限制、回滚或注意事项
  6. 相关文件、相关入口、后续动作

如果文档是操作类或排障类，优先使用：

  • 小节标题
  • 短段说明
  • 紧跟的截图或示意图
  • 图后一句结论

而不是：

  • 先放十几张图，最后再统一解释
  • 一整页长文字后再把所有图堆在末尾

七、图注与结论

每张图附近默认至少交代一件事：

  • 这张图证明了什么
  • 这张图应重点看哪里
  • 这张图和上一张图相比变化了什么

推荐表达：

  • “这里重点看页头下的资源状态条，说明 overview 已经切到共享分布条方案。”
  • “这张图证明筛选交互没有跳页，结果区直接出现在同页状态条下方。”

不推荐表达：

  • “如下图”
  • “界面如图所示”
  • “效果见截图”

八、导出与分发

如果文档后续要导出 PDF / DOCX / 对外发送，默认额外检查：

  • 图片是否在导出后仍然清晰可读
  • 图片前后的文字是否仍能独立成段
  • 是否存在只靠 hover、折叠态、动态交互才能看懂的内容
  • 路径、标题、编号、图注在导出后是否仍能对齐

对外版本不要保留本地临时口语、未清理备注、无意义截图堆叠。

九、禁止项

以下做法默认判为不合格：

  • 纯装饰配图，没有承载事实
  • 用很多截图替代本应明确写出的步骤
  • 同一事实在正文、图注、截图标记里重复三次
  • 截图只截到局部，导致读者不知道对象在哪里
  • 图文顺序混乱，读者需要反复上下翻找
  • 只保留图片，不写结论
  • 只写“见图”，不说明图证明什么

十、完成标准

图文文档完成前，至少确认：

  • 主文档已明确，未制造并行薄导航页
  • 所有保留的图都有明确职责
  • 关键可视证据没有缺失
  • 图与文的顺序按理解路径组织，而不是按采集顺序堆放
  • 图片落点、命名、引用路径都可持续维护
  • 如果文档引用了旧路径、旧截图、旧说法，已同步清理或改写

一句话：图文文档的完成标准不是“有图了”，而是“图文一起把事实讲清楚了”。