| name | figure-table-description |
| description | 图表描述补充(为缺少描述的图/表生成或提示合适的中文描述)。 |
| argument-hint | 可选:指定章节或启用自动占位标记 |
Skill: 图表描述补充(figure-table-description)
适用场景
- 图(
bob/plantuml/mermaid 代码块、<img>、![]())或表(Markdown 管道表格)后缺少描述性段落
**图 X-Y** 或 **表 X-Y** bold 行描述为空或过于笼统
- 新增图表后需要补充有意义的中文描述
audit_chapters.py 报告"图表后缺少描述"时的修复
检测规则
以下情况判定为"缺少描述":
- 代码围栏图(bob/plantuml/mermaid)之后,至 下一个标题或文件末尾之间,无正文段落
- 图片行(
、<img ...>)之后同理
- 管道表格之后同理
**图/表 X-Y** bold 行的描述部分为空(如 **图 1-1** 仅有空格)
排除:以下不算"缺少描述":
- bold/marker 行本身不算正文
- 空行、HTML 注释行不算正文
- 紧接的另一个图/表不算正文
描述撰写规范
通用原则
- 读图/表内容:必须先理解图/表的实际内容(表格数据、图示结构),再撰写描述
- 衔接上下文:描述应与前后段落自然衔接,不是孤立的套话
- 信息量:2-3 句,点明图/表展示的核心信息和读者应关注的要点
- 中文:全部使用中文撰写,术语保留英文原词
- CN-EN 间距:中文与英文/数字之间加一个空格
图描述模式
根据图类型调整描述风格:
| 图类型 | 描述重点 |
|---|
| bob(框图) | 系统架构、模块关系、信号流向 |
| plantuml(时序/流程) | 执行步骤、消息传递、判断逻辑 |
| mermaid(示意图) | 逻辑结构、组件关联、数据流 |
| 图片(照片/截图) | 实物外观、界面操作、实验现象 |
示例(bob 框图):
上图展示了 STM32 最小系统的硬件架构。MCU 核心通过总线连接电源管理、时钟系统、
复位电路和调试接口四大模块,各模块的供电与信号路径在图中清晰标注。
示例(plantuml 时序图):
上图描述了 I2C 通信的完整时序:主机发起起始条件后,依次发送设备地址和寄存器地址,
从机在每个字节后返回 ACK 应答,最终主机以停止条件结束传输。
表描述模式
根据表格内容类型调整:
| 表类型 | 识别特征 | 描述重点 |
|---|
| 对比表 | 列头含"方案/类型/区别",≥3 列 | 各方案在哪些维度有差异,如何选型 |
| 参数表 | 列头含"参数/值/单位" | 关键参数的含义和典型取值 |
| 步骤表 | 列头含"步骤/阶段/顺序" | 流程要点和注意事项 |
| 排障表 | 列头含"问题/错误/解决" | 常见问题的排查思路 |
| 参考表 | 其他 | 表格梳理了哪些核心信息 |
示例(对比表):
上表对比了轮式、履带式和足式三种移动机构的承载能力、地形适应性和控制复杂度,
工程选型时应根据实际工作环境和成本预算综合权衡。
bold 行描述
**图/表 X-Y** 后的描述应为一句话概括,不超过 40 字:
- 好:
**图 3-5** STM32F103 最小系统电路原理框图
- 差:
**图 3-5** 上图以框图形式描绘了系统架构(套话,无信息量)
- 差:
**图 3-5** (空描述)
操作流程
1. 定位缺描述的图/表
使用审计脚本检测:
python scripts/audit_chapters.py
或手动搜索空 bold 行:
grep -n '^\*\*[图表].*\*\*\s*$' docs/*.md
2. 阅读内容
- 打开对应文件,阅读图/表的实际内容
- 阅读所在 section 的标题和前后段落
- 理解图/表在该节中的作用
3. 撰写描述
按上述规范撰写描述,插入到图/表之后(标题之前)。
4. 更新 bold 行
如果 **图/表 X-Y** 的描述为空,同时填入一句话概括。确保同步更新对应的 <!-- fig/tab:chX-Y 描述 --> marker 行。
5. 验证
python scripts/audit_chapters.py
python -m mkdocs build --strict
注意事项
- 禁止模板套话:不要使用"上图展示了……的核心结构"这类不读图就能写出的泛型描述
- 与编号系统配合:描述完成后如需重新编号,运行
python scripts/auto_number_figures_tables.py --toc
- 幂等标记:如果是批量生成的占位描述(后续需人工润色),在行末添加
<!-- desc-auto --> 标记
- 不要删除 marker 注释:
<!-- fig:chX-Y ... --> 和 <!-- tab:chX-Y ... --> 是编号系统的锚点,只修改描述文字,不要删除整行