文档转HTML图片语义命名技能

SKILL.md

---
name: document-html-image-semantic-naming
description: 文档转 HTML 时的图片语义命名技能。用于把 doc/docx/pdf 等文档导出的 `image1`、`image2` 这类无语义图片，结合文档上下文与图片内容重新命名，并同步更新 HTML 引用与映射清单。适用于用户提到“文档转 html”“图片重命名”“导出图片没语义”“根据上下文给图片命名”“doc/pdf 图片预处理”时。
---

# 文档转 HTML 图片语义命名技能

这是一套针对 `doc / docx / pdf -> html` 场景的**图片命名与引用整理方法**。核心不是“把图片导出来”，而是把图片从无语义的 `image1.jpg`、`media/image3.png`，变成后续**一眼可选、一眼可懂、可长期复用**的资产。

## 何时使用

当用户出现以下需求时，立即使用本技能：

- “把这个 docx/ppt/pdf 转成 html，顺便整理图片命名”
- “这些 `image1/image2` 没法看，按内容重命名一下”
- “图片要根据文案上下文命名”
- “导出的 html 能用，但图片文件名没有意义”
- “想让后续选图时不用再靠猜”

## 核心原则

### 一句话原则

**文档型图片的语义，通常不在原文件名里，而在“它在文档中被如何引用”这件事里。**

因此，图片命名必须来自两类信息的联合判断：

1. **引用上下文**
   - 图片前后正文
   - 所在标题 / 小节标题 / 图注
   - 时间节点 / 行程节点 / 模块名称
   - 图片在整篇文档中的角色（封面图、节点图、示意图、住宿图、截图等）

2. **图片自身内容**
   - 实际画面主体（海景、营地、街景、人物、地图、截图、菜单、证件等）
   - 横竖版 / 方图
   - 是否明显与上下文冲突

## 必须遵守

1. **上下文优先，但不能盲信上下文**
2. **图片命名追求可用性，不追求学术级绝对精确**
3. **原始导出图片不直接删除**
4. **重命名后必须同步更新 HTML 引用**
5. **必须保留“原始文件名 -> 新文件名”的映射关系**
6. **若图片内容与上下文明显冲突，以图片内容校正命名**

## 典型问题识别

出现以下任一信号，说明不能直接沿用导出文件名：

- 文件名为 `image1`、`image2`、`media/image3` 这类通用名
- 图片全部位于 `media/`、`assets/`、`tmp/` 等导出目录
- 文档中图片是穿插在正文里的，而不是独立图库
- 用户后续还要继续做选图、改稿、复用或再导出

## 命名来源优先级

命名时按以下优先级取信息：

1. **图注 / 明确图片说明**
2. **最近的章节标题 / 小节标题**
3. **图片前后正文中的高信息量词**
4. **图片视觉内容识别出的主体词**
5. **横图 / 竖图 / 方图**
6. **序号**

## 推荐命名格式

### 通用格式

`[地点或模块]-[场景语义]-[横竖版]-[序号].jpg`

示例：

- `西湾山-四湾连珠全景-横图-01.jpg`
- `浪茄沙滩-果冻海岸-横图-02.jpg`
- `西贡老街-市井烟火补给-横图-01.jpg`
- `行程说明-集合地点示意-截图-01.png`
- `酒店介绍-大堂空间氛围-横图-01.jpg`

### 当无法确定具体地点时

使用“模块名 + 画面语义”命名，而不是继续保留 `image3`：

- `开篇主题-山海意境-横图-01.jpg`
- `产品亮点-亲子互动场景-横图-02.jpg`
- `须知说明-证件示意-截图-01.png`

## 执行流程

### 第一步：抽取文档与图片关系

先建立最基础的关系表：

`原始图片文件 -> HTML 中引用位置 -> 所在段落/标题/模块`

至少要知道每张图：

- 在 HTML 里被哪一个 `<img>` 引用
- 前后相邻的 1-3 段文字是什么
- 所属章节或模块是什么

### 第二步：判断图片角色

每张图至少归入以下一种角色：

- 封面/开篇氛围图
- 行程节点配图
- 景点图
- 酒店/餐食/交通图
- 示意图 / 地图 / 截图
- 活动现场 / 人物氛围图

### 第三步：结合图片内容修正命名

如果上下文与图片画面一致，直接用上下文命名。

如果上下文过泛，例如：

- “沿途风景”
- “活动照片”
- “现场氛围”

则必须看图片内容补上关键信息，如：

- 海景
- 营地
- 城市街景
- 人物合影
- 日落
- 地图
- 菜单
- 截图

### 第四步：批量重命名并更新引用

执行时必须同步完成三件事：

1. 重命名图片文件
2. 更新 HTML 中的 `src`
3. 更新映射清单

### 第五步：交付验证

每次必做：

1. 检查所有 `img src` 是否都能在磁盘上找到
2. 检查是否仍残留 `image1`、`media/image2` 这类无语义引用
3. 检查同一场景多张图是否正确编号
4. 抽查文件名是否一眼能看懂用途
5. 确认原始文件与新文件关系可追溯

## 特别适用的三类场景

### 场景 A：doc/docx 经 pandoc 转 HTML

- 常见问题：图片导出成 `media/image1.png`
- 处理重点：根据 HTML 中文段落与标题重建语义命名

### 场景 B：PDF 拆图转 HTML

- 常见问题：图片来自页块截图或 PDF 内嵌对象
- 处理重点：区分“正文配图”与“页面截图/示意图”

### 场景 C：文档导出图后要继续做图库预处理

- 常见问题：先跑图库脚本会得到 `零散根目录-横图-01`
- 处理重点：应先完成语义命名，再进入常规素材预处理流程

## 与图库预处理技能的衔接

如果后续还要进入 `travel-material-preprocess`：

1. **先用本技能完成语义命名**
2. 再按地点/模块把图片放入更合适的子目录
3. 再运行图库预处理脚本

否则会因为原始文件名无信息，导致输出落入 `零散根目录`，文件名仍然不可用。

## 禁止事项

- 不要直接相信 `image1/image2`
- 不要只看图片、不看上下文就命名
- 不要只看上下文、不核对画面内容就命名
- 不要重命名了图片却忘记更新 HTML 引用
- 不要删除原始导出图后才发现映射关系丢失
- 不要产出 `图片1-横图-01.jpg` 这类伪语义命名

## 交付物建议

完成后至少应产出：

1. 已更新引用的 HTML 文件
2. 语义化命名后的图片目录
3. 一份映射清单，如：

```text
source,image_context,final_name
image4.jpeg,西湾山段落后配图,西湾山-四湾连珠全景-横图-01.jpg
image9.jpeg,西贡老街补给段落后配图,西贡老街-市井烟火补给-横图-01.jpg
```

## 给用户的反馈要点

完成后应明确告诉用户：

1. 共重命名了多少张图片
2. 命名主要依据了哪些上下文模块
3. 哪些图片是靠图片内容修正了上下文
4. HTML 中的引用是否已全部同步
5. 是否还保留了原始图片与映射关系

## 经验沉淀

这项技能的本质不是“批量改文件名”，而是**把文档内的隐式图文关系，转成可复用的显式素材语义**。

只要后续还涉及：

- 再次排版
- 挑图换图
- 迁移到新模板
- 进入素材库
- 交给 AI 继续加工

这一步都非常值。