figure-table-description

name	figure-table-description
description	图表描述补充（为缺少描述的图/表生成或提示合适的中文描述）。
argument-hint	可选：指定章节或启用自动占位标记

Skill: 图表描述补充（figure-table-description）

适用场景

• 图（bob/plantuml/mermaid 代码块、<img>、![]()）或表（Markdown 管道表格）后缺少描述性段落
• **图 X-Y** 或 **表 X-Y** bold 行描述为空或过于笼统
• 新增图表后需要补充有意义的中文描述
• audit_chapters.py 报告"图表后缺少描述"时的修复

检测规则

以下情况判定为"缺少描述"：

1. 代码围栏图（bob/plantuml/mermaid）之后，至 下一个标题或文件末尾之间，无正文段落
2. 图片行（![...](...)、<img ...>）之后同理
3. 管道表格之后同理
4. **图/表 X-Y** bold 行的描述部分为空（如 **图 1-1** 仅有空格）

排除：以下不算"缺少描述"：

• bold/marker 行本身不算正文
• 空行、HTML 注释行不算正文
• 紧接的另一个图/表不算正文

描述撰写规范

通用原则

1. 读图/表内容：必须先理解图/表的实际内容（表格数据、图示结构），再撰写描述
2. 衔接上下文：描述应与前后段落自然衔接，不是孤立的套话
3. 信息量：2-3 句，点明图/表展示的核心信息和读者应关注的要点
4. 中文：全部使用中文撰写，术语保留英文原词
5. 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

注意事项

1. 禁止模板套话：不要使用"上图展示了……的核心结构"这类不读图就能写出的泛型描述
2. 与编号系统配合：描述完成后如需重新编号，运行 python scripts/auto_number_figures_tables.py --toc
3. 幂等标记：如果是批量生成的占位描述（后续需人工润色），在行末添加 <!-- desc-auto --> 标记
4. 不要删除 marker 注释：<!-- fig:chX-Y ... --> 和 <!-- tab:chX-Y ... --> 是编号系统的锚点，只修改描述文字，不要删除整行