Skill: tinglan803-coder/document-html-image-semantic-naming (version 1.0.0)

--- 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 继续加工 这一步都非常值。


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)