engineering-docs:先修文档的决定,再修图
AI 写的技术文档有两个常见问题:一大段一大段地堆字;流程图把节点从头串到尾,看不出重点。
技术文档是给人看的,阅读效率很关键。好好说话能改善语言,结构还需要单独处理:结论放在哪里,细节怎么查,图里哪些关系必须一眼看清。
核心做法:文字分主次,图画清关系。engineering-docs 把这两件事连起来,同时保留可修改的图源,让后续修改能回到具体内容。
这套能力从技术文档标准和稳定、可编辑的工程图需求起步,后来不断补正文格式、图型、布局、配色和交付检查。下面沿着文字和图两条线,拆开说具体怎么做。
文字结构
文字先解决读者看什么。读者不必从头读到尾,也不该自己从参数、背景和过程里找结论。
阅读层级
把信息分成三层,每层回答不同问题。
| 层级 | 放什么 | 读者拿走什么 |
|---|---|---|
| 首屏 | 结论、范围、要确认的决定和一张总览图 | 这件事做什么,为什么要做 |
| 章节 | 按模块或问题展开,第一段先给本章结论 | 主干怎么做,为什么这样选 |
| 实现细节 | 证据、参数、接口、完整规则和测试矩阵 | 需要实现或复查时,能找到依据 |
负责人关心选什么、接受什么代价;实现者需要职责、接口和失败处理。三层结构让他们各取所需,同时沿着同一套结论往下查。
检查方法:只读首屏、章节标题和各章第一段,能否说清做什么、为什么现在、主干怎么做、代价和风险,以及要确认什么。说不清,就先改这一层。
信息的形状
分层之后,再决定每块信息怎么呈现。把一段长文字切成几段,还不能解决并列关系和对比关系难找的问题。
| 内容 | 用什么呈现 | 为什么 |
|---|---|---|
| 结论、前提、待确认的事 | 高亮块或短句 | 先看到判断,再决定是否展开 |
| 并列的职责、约束和理由 | 带标签的列表 | 扫标签就知道有哪些要点 |
| 多个状态、方案或风险 | 表格 | 同一组属性能横向比较 |
| 有先后的操作 | 有序列表 | 操作顺序不埋在句子里 |
| 因果与取舍 | 短段落 | 保住为什么,不拆成互不相干的条目 |
加粗只标关键词,标题只写这一节讲哪块内容。让标题、表头、列表标签和高亮承担不同层次,避免满屏都是重点。
同一内容的对照
以「多端任务执行与验收方案」为例,同一份内容有两种呈现:左边按章节合成大段,右边突出结论,并把并列信息改成列表和表格。

右侧先给结论和待评审事项,再展开设计边界。并列职责放进列表,状态和条件放进表格,读者不用逐句从长段落里提取。
状态规则更适合用表格。Task 表示同一目标,Run 记录每次成功领取后的执行;等待恢复沿用当前 Run,验收退回后再次领取才新建 Run。

读这张表时,可以按「当前状态、允许去向、条件」定位:
- 等待恢复:回到运行中,继续原 Run。
- 验收退回:回到待办,再次成功领取时创建新 Run。
- 取消边界:只有草稿、待办和等待可以取消,两个终态没有出边。
事实与判断
技术方案还要让人分清已知和未定。表达流畅,不能把推测变成事实,也不能把建议写成已经批准的决定。
| 信息 | 写法 |
|---|---|
| 现状事实 | 保留来源、时间与适用范围 |
| 未验证假设 | 写明前提及不成立时的影响 |
| 已作出的决定 | 写清状态、选择理由和接受的代价 |
| 待确认事项 | 写清缺什么证据、如何确认 |
流程图与关系
图要让读者看清谁和谁是什么关系。组成、交接、时序、状态和数据流不同,不能都画成一串同样的方框。
按关系选图
不同关系采用不同图型。下面的总览展示六类图的组织方式,完整文字看对应单图。

图中是用于说明图型的示例。
| 要看清什么 | 合适的图 | 组织重点 |
|---|---|---|
| 哪些模块组成系统,谁调用谁 | 架构图 | 主链、归属与系统边界 |
| 谁负责哪一步,何时交接或分支 | 流程图、泳道图 | 职责、条件、并行与回路 |
| 一次场景中消息按什么顺序发生 | 时序图 | 参与者、发送、返回与等待 |
| 哪个事件让状态发生变化 | 状态图 | 主路径、等待、退回与终态 |
| 数据从哪里来,经过什么转换 | 数据流图 | 来源、变换、存储与消费 |
| 实体有哪些字段,彼此什么关系 | ER 图 | 字段、键和关系基数 |
选图先问读者要回答什么,再确定主路径、分组、边界和条件。图型多只是能力范围,选得对才有用。
主线与分支
一张图先安排核心解释路径,再把分支和异常放到对应位置。正常流程可以连续阅读,等待与回退需要独立走线,关键条件放在连接处。
泳道尤其适合解释跨角色交接。下图把用户界面、Agent 运行、策略与恢复、工具执行分开,规划、审批、阻断和结果回报各有对应位置。

- 泳道:帮助定位动作发生在哪个职责范围。
- 连线:保留真实起点、终点和方向,分支注明触发条件。
- 回路:说明为什么返回、回到哪里,不用一条长链掩盖重试或等待。
节点名称和正文保持一致。图标题给读者一个明确主题;调用线写动作,数据流线写传递的数据,状态迁移线写触发事件或条件。
状态与顺序
状态图能把一个常见误读直接展示出来:执行结束以后,任务还需要验收,才能进入完成状态。

主线从草稿走到已完成;运行中的等待和恢复放在下方,验收退回放在上方。两个终态明确标识,没有出边。读者沿线就能找到条件,不必脑补一整套状态机。
这张图与前面的状态表讲同一组核心规则:表适合逐项查允许去向,图适合追踪路径和回路。对象名称相同不算重复,有没有新的理解帮助才是判断依据。
配色与密度
颜色用来区分角色和状态。前端、后端、存储可以有固定角色色;成功、等待、失败另有状态含义。后端节点是绿色,不代表它已经执行成功。
- 视觉重点:主路径和本次变化更突出,普通关系仍然能看清。
- 标签位置:说明靠近对应的线或对象,不压住箭头、转折和正文。
- 信息密度:放不下时拆成总览和详图,不靠缩小字号塞进去。
- 风格一致:共享字体、颜色含义和标题层级,布局按关系变化。
实体关系图需要保留字段、键和基数。把它缩成几张结论卡,会丢掉技术方案真正需要检查的信息。

图源与修改
图能持续修改,评审意见才能回到具体节点和关系。模块职责、调用方向或条件变了,应当修改图源并重新生成,避免正文更新了,图片还停在旧版本。
| 保留什么 | 用来做什么 |
|---|---|
| JSON 或已有 Python 修改源 | 改对象、关系、条件和标题 |
| scene 场景数据 | 保存对象与连线的语义、稳定 ID 和布局结果 |
| SVG、PNG | 贴进文档阅读,按修改源重新生成 |
| 自包含 HTML | 查找、聚焦和查看已登记的真实关系 |
绘制统一通过 diagram_kit。内部可以用不同布局实现,共享修改源约定、主题、查看器和交付检查。发布到飞书只是最后的承载步骤,不决定图该怎么组织。
使用时保留这些边界:
- 自动布局:处理几何,作者仍要确定职责、主路径和条件。自由对象保留复杂分区及分区端点,不根据视觉位置补未声明的关系。
- 可编辑格式:SVG 保留矢量对象与文字,但不等于完整作者源;draw.io 的真实节点与绑定连线目前只对自由对象图支持。
- 交互:HTML 的查找、聚焦和路径查看不会自动进入飞书正文。
迭代与验证
后续改动对应的是具体使用问题。保留下来的重点,是哪些地方仅靠写作提醒或生成成功还不够。
| 遇到的问题 | 怎么调整 | 留下的检查方法 |
|---|---|---|
| 技能已经存在,细化流程时仍手写 Mermaid 或从画板摆节点 | 明确服务、模块、调用和事件迁移属于工程关系,扩展入口判据 | 工程图任务能走到统一绘图入口 |
| 标题塞整句结论,正文混入对话来源或个人信息 | 补标题、版式与正文检查 | 用 doc_check 定位可枚举问题,再由作者判断内容 |
| 不同图型用法和呈现分散 | 将成熟编译器、专用布局和自由对象收进统一入口 | 图型保留自己的语义,共享源、主题与交付 |
| 树根改成浅色底,原来的白字没有同步 | 修正主题覆盖后的文字规则,不改节点、层级与字号 | 看实际画面,不能只检查角色声明 |
| 组件页通过检查,最终装配或导出却可能改变样式和索引 | 对最终成品重新检查,静态导出先清理临时状态并固化样式 | 以本次生成的源、场景和成品为准 |
每次交付分别检查文字和图。
| 检查对象 | 要回答的问题 |
|---|---|
| 文字速读层 | 只读正文,是否能说清结论、主干、代价和待确认项 |
| 图与正文 | 对象、方向、职责和条件是否一致 |
| 实际画面 | 正常阅读尺寸下,文字、主线、分支和箭头是否清楚 |
| 修改与导出 | 修改源是否保留,成品是否来自同一版本,格式是否真正支持 |
自动检查能拦住格式和部分结构问题,读图仍要看实际成品。生成成功、截图存在,都不能单独证明文档已经讲清楚。
使用与边界
使用时,把材料、读者、目标和范围一起给出。更新已有文档,先读全文和图,再改相关结论,不把新增内容直接挂到末尾。
- 写方案:「基于这些材料写技术方案,给评审会看,重点说明候选、代价和回退。」
- 改文档:「按这些评审意见改这份方案,保留现有事实、图和有效结论。」
- 改工程图:「重画这张架构图,保留节点和条件,突出主链,交付可修改源。」
engineering-docs 主导要评审、要确认决定的方案与工程图。技术分享的叙事由分享技能负责;content-infographic 将抽象内容做成便于理解的信息图;好好说话负责最后的中文表达。它们可以配合,借图不接管正文。
有三件事值得直接带回日常文档:
- 先整理信息的层级,再改句子,完整条件留在能查到的位置。
- 先判断关系,再选图,不能为了版式整齐改掉真实流程。
- 保留修改源,检查最终成品,允许明确说明哪项尚未验证。