auto-figure-table-numbering

name	auto-figure-table-numbering
description	图表自动编号（为 Markdown 文档中的图与表生成统一编号并同步交叉引用）。
argument-hint	可选：--toc/--dry-run/--refs-only

Skill: 图表自动编号（auto-figure-table-numbering）

适用场景

• 全书 Markdown 文档中的图（bob/plantuml/mermaid 代码块、<img> 标签、![]()）和表（Markdown 管道表格）需要统一编号
• 新增或删除图/表后需要全局重排编号
• 需要生成图目录或表目录
• 需要在正文中自动更新交叉引用（如"如图 1-5 所示"、"参见表 2-3"）

编号规则

图编号

• 格式：图 X-Y，其中 X 为章号，Y 为该章内图的顺序号（从 1 开始）
• 附录用字母：图 A-1、图 B-2
• 图说（caption）放在图的下方，格式：

<!-- fig:chX-Y 描述文字 -->

渲染后显示为：

**图 X-Y** 描述文字

表编号

• 格式：表 X-Y，其中 X 为章号，Y 为该章内表的顺序号（从 1 开始）
• 附录同理：表 A-1
• 表说（caption）放在表的上方，格式：

<!-- tab:chX-Y 描述文字 -->

渲染后显示为：

**表 X-Y** 描述文字

正文交叉引用

• 引用图：如图 1-5 所示、见图 A-2
• 引用表：参见表 2-3、如表 B-1 所列
• 脚本会自动更新这些引用中的编号

标记约定

图标记

在图（代码块或图片）下方添加标记行：

<!-- fig: 描述文字 -->

脚本运行后会自动替换为带编号的图说：

**图 1-3** 描述文字
<!-- fig:ch1-3 描述文字 -->

表标记

在表 上方添加标记行：

<!-- tab: 描述文字 -->

脚本运行后会自动替换为带编号的表说：

**表 2-1** 描述文字
<!-- tab:ch2-1 描述文字 -->

自动占位标记

之前由 insert_placeholders_after_tables.py 插入的 <!-- autoplaceholder --> 会被本脚本识别，并根据上下文自动转换为 <!-- fig: ... --> 或 <!-- tab: ... -->，需要人工补充描述文字。

使用方法

# 预览模式（只报告，不修改文件）
python scripts/auto_number_figures_tables.py --dry-run

# 执行编号（修改文件）
python scripts/auto_number_figures_tables.py

# 生成图目录和表目录
python scripts/auto_number_figures_tables.py --toc

# 仅更新交叉引用（不重新编号）
python scripts/auto_number_figures_tables.py --refs-only

注意事项

1. bob 代码块内部的 | 字符不是表格，脚本已做区分
2. 章号从文件名或 frontmatter start-at 提取
3. 附录文件（appendix_*.md）使用大写字母作为章号
4. 脚本幂等：多次运行结果一致
5. 运行前建议 git diff 确认变更范围
6. 重编号时保留描述：若 bold 行已有描述（如 **图 10-1** 高级运动控制方法总览图），重新编号后描述文字会被保留，不会丢失。编辑者可直接修改 bold 行中的描述文字，脚本会以 bold 行的描述为准。
7. 交叉引用自动同步：正文中自然语言引用（如"如图 1-5 所示""参见表 2-3"）会在编号变更时自动更新。脚本采用两遍架构——Pass 1 完成编号并收集旧→新映射，Pass 2 在所有文件中替换引用。代码围栏、bold 图/表说行、HTML 注释 marker 行内的编号不会被误替换。

交叉引用书写指南

推荐写法

在正文中用自然中文引用图表，脚本能自动识别并更新编号：

如图 1-3 所示，最小系统由电源、时钟、复位等电路组成。
具体参数见表 2-1 中的层次说明。
有关引脚布局的详细信息，参见图 A-2。

识别模式

脚本识别以下模式（前缀 + 编号）：

• 图引用：图 X-Y 形式，如 图 1-3、图 A-2（X 为章号/字母，Y 为序号）
• 表引用：表 X-Y 形式，如 表 2-1、表 B-3

常见自然写法均可识别：如图 1-3 所示、见图 1-3、参见表 2-1、如表 2-1 所列、（图 1-3）等。

排除规则

以下位置的编号不会被替换：

1. 代码围栏（``` 内部）——避免修改示例代码
2. **图 X-Y** / **表 X-Y** bold 标题行——由 Pass 1 管理
3. <!-- fig:chX-Y --> / <!-- tab:chX-Y --> HTML 注释标记行——由 Pass 1 管理
4. 悬空引用（引用的编号不在旧编号列表中）——保持原样并在终端显示警告