document-html-image-semantic-naming（document HTML 图像 semantic naming）

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

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

何时使用

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

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

核心原则

一句话原则

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

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

1. 引用上下文

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

1. 图片自身内容

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

必须遵守

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. 一份映射清单，如：

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

给用户的反馈要点

完成后应明确告诉用户：

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

经验沉淀

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

只要后续还涉及：

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

这一步都非常值。