ClawHub

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

v1.0.0

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

0· 110· 1 versions· 0 current· 0 all-time· Updated 1w ago· MIT-0
by@tinglan803-coder

文档转 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. 一份映射清单，如：
source,image_context,final_name
image4.jpeg,西湾山段落后配图,西湾山-四湾连珠全景-横图-01.jpg
image9.jpeg,西贡老街补给段落后配图,西贡老街-市井烟火补给-横图-01.jpg

给用户的反馈要点

完成后应明确告诉用户：

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

经验沉淀

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

只要后续还涉及：

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

这一步都非常值。

Version tags

latestvk970qe7r7jjp7w85gesafaqbhn858zs3