| name | epub-image-layout-optimizer |
| description | 优化 EPUB 图片版式、figure 环绕、图注、栅格格式、封面声明与阅读器兼容性。用于图片过小、裁切、Kindle 空白、图文环绕差、缺图注，或封面/海报图片处理需要 EPUB 安全规则时。 |
EPUB 图片版式优化
这个 skill 用于可重排 EPUB 正文中的图片。封面式全页海报布局使用 epub-alite-converter。
固定目标
生产图片版式应使用：
- JPEG / PNG 作为主要交付格式。
figure 包裹浮动图片和图注。- 百分比宽度挂在
figure 上，不直接 float img。
- wrapped figure 内部使用
img { width: 100%; height: auto; }。
- 封面图在 OPF 中完整声明。
- 周围有足够正文来证明环绕行为。
Figure 模式
左/右环绕：
<figure class="img-left">
<img src="../Images/example.png" alt="图示说明"/>
<figcaption>图注文字。</figcaption>
</figure>
.img-left {
float: left;
width: 30%;
margin: 0.2em 1em 0.6em 0;
}
.img-left img,
.img-right img {
display: block;
width: 100%;
height: auto;
}
工作流
机器判断入口是 scripts/epub_image_layout_advisor.py：它只读扫描 EPUB，列出逐图候选和可追溯风险，不直接修改文件。
- 先运行图片布局 advisor，读取目标 XHTML、
media.css、base.css、OPF manifest 和图片资源；祖先为 .noteref-icon 或 a[epub:type~=noteref] 的图片是注释交互控件，必须排除，不生成 figure / 浮动 / 图注 / alt 候选。
- 分类图片：
- 封面图。
- 正文内联图。
- 浮动 figure。
- 通栏 figure。
- 图标 / 注释标记。
- 海报背景。
- 公式或图表 fallback。
- 把 direct floated
img 转成 figure.img-left 或 figure.img-right。
对尚未人工确认图文关系的插图，只规范为居中的 figure.illustration，不自动分配左/右浮动类；把候选写入决策记录，留待逐图 review。
- figure 宽度从
30% 起步；正式默认保持在 25% 到 35%，除非阅读器测试证明需要调整。
- 保留图注和 alt。只有图片角色明确时才补 alt。
- 图片环绕规则写进
media.css；通用 figure/img 默认写进 base.css。
- 新增或删除图片时同步 OPF。
- 面向 Kindle 时，用 JPEG / PNG 替换 WebP 主路径；必要时预栅格化风险 SVG。
封面规则
包封面应满足：
- manifest 中封面图片 item 带
properties="cover-image"。
- metadata 同步提供
<meta name="cover" content="..."/>，兼容 Kindle。
- Kindle 交付优先使用 JPEG / PNG 封面资源。
- Kindle 生产包不依赖 SVG-only 封面声明。
图片压缩边界
图片压缩、色彩空间转换和有损质量参数不在本仓实现。本 skill 只负责：
- 判断图片是否适合 EPUB/Kindle 主路径。
- 检查 OPF manifest、封面声明、figure 包装、图注和 alt。
- 在外部压缩/转码后复查路径、格式和阅读器风险。
如果用户要求压缩图片，先说明需要外部工具完成压缩，再把压缩后的资源带回本 skill 做 EPUB 结构与版式校验。
禁止事项
- 不在可重排主路径固定图片高度。
- 不依赖
aspect-ratio 作为 EPUB 图片环绕主路径。
- Kindle 主路径不使用
em 宽度控制 figure float。
- 不为了视觉整齐删除图注或 alt。
- 除非用户明确选择，不用截图替代真实文本。
- 不用短段落直接判定 float 失败；需要长正文 fixture，或标记为阈值反例。
验证 fixture
Text/01-body.xhtml：基础 figure。Text/03c-poster-contain.xhtml：单图卷封 contain + fallback。Text/09-kindle-risk.xhtml：Kindle 图片风险页。Text/17-image-layout.xhtml：figure 环绕和大字号回归。
运行：
sh templates/epub-style-demo/build.sh
scripts/validate-epub-style-demo.sh --epub templates/epub-style-demo/dist/<artifact>.epub
Dry-run 约定
本 skill 默认 dry-run。直接调用只输出预期改动 JSON；加 --commit 才真正改。
代理协议示例（注释说明代理动作，不是独立 shell 命令）：
cat work/dry-run.json | jq
dry-run 输出格式见 docs/pipeline/cleanup-flow.md。
