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

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

Security Scan

The skill's instructions, scope, and requirements are coherent with its stated purpose of renaming exported document images and updating HTML references; it is instruction-only, requests no credentials or installs, and only needs access to the document, HTML, and image files it is meant to operate on.

Purpose & Capability

The name and description match the SKILL.md content: the skill explains how to map exported images (image1, media/image3, etc.) to semantic filenames using document context and image content and to update HTML and mapping lists. No unrelated credentials, binaries, or installs are requested.

Instruction Scope

The instructions require reading document-derived HTML, the surrounding text (titles/paragraphs), and the image files, then renaming images and updating HTML and a mapping file. This is within the task but implies read/write access to the user's document and image files and (optionally) an image-recognition capability. The SKILL.md does not specify how to extract images from PDFs or perform image content recognition—those operational details are left to the agent/environment.

Install Mechanism

Instruction-only skill with no install spec and no code files; nothing is written to disk by an installer and no external packages are pulled in by the skill itself.

Credentials

No environment variables, credentials, or config paths are requested. The only needed access is to the user's document/HTML and image files, which is proportionate to the described purpose.

Persistence & Privilege

always is false and there is no install or persistent agent modification described. The skill does not request permanent platform presence or modify other skills or global settings.

Assessment

This skill is coherent for renaming exported document images and updating HTML, but you should: (1) ensure the agent is only given access to the specific document/HTML/image folders it must operate on (least privilege); (2) keep backups of original exported images and the original HTML before running bulk renames; (3) verify mapping output and that all img src links still resolve; (4) be aware the instructions assume some way to inspect image content (either the agent's vision capability or an external tool)—confirm what the runtime will actually use for image analysis; (5) if you need offline processing or must avoid sending images to external services, verify the runtime will not transmit files externally. If the skill later requests network access, installs, or credentials, re-evaluate because that would change this assessment.

这是一套针对 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 继续加工

这一步都非常值。