Menu
将 EPUB 普通注释、尾注、旧式注释或纯文本注释标记转换为项目标准 popup footnote 结构：图片注释图标触发、同文件 grouped note body、◎ 回跳，并保留注释内容。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | epub-popup-footnote-converter |
| description | 将 EPUB 普通注释、尾注、旧式注释或纯文本注释标记转换为项目标准 popup footnote 结构：图片注释图标触发、同文件 grouped note body、◎ 回跳，并保留注释内容。 |
当需要把普通脚注、尾注、旧多看注释或纯文本 noteref 标记转换为项目最终 popup footnote 模式时使用这个 skill。
权威结构源是 docs/final/SPEC-实现约束.md §1；以下内容保持 skill 可独立执行，并不得与该节分叉。
使用这个结构：
epub:type 的 XHTML 根 <html> 都声明 xmlns:epub="http://www.idpf.org/2007/ops"。epub:type="noteref" 和 role="doc-noteref" 的 <a>。../Images/note.png；已有本地图标资源时保留原 img src，本 skill 的 assets/note.png 只作为纯文本标记转换时的默认图标。<aside epub:type="footnote" role="doc-footnote">。ol.footnote-list。id 的 li.footnote-item。href 指向对应 li.footnote-item id，不指向独立 per-note aside。◎。li 和包含它的 aside 位于同一 XHTML 文件。<html> 声明 xmlns:epub="http://www.idpf.org/2007/ops"。已有声明则保留，不重复添加。section[epub:type="footnotes"] 内含多个 aside#footnote_N，正文引用为 a#noteref_N。仅当该 section 的所有 aside 都能匹配时，保留原 ID 并合并为一个 grouped aside/ol/li；有任何无法识别的 aside 或附加内容时不做部分转换，改为人工 review。[1]、*、注 等文本标记替换为图片 noteref；如果原 noteref 已经包含图片图标，保留原 img src 和 alt，不替换为默认图标。href 必须指向最终 li.footnote-item target id：<sup class="note-marker">
<a id="note-1"
class="noteref-icon"
epub:type="noteref"
role="doc-noteref"
href="#footnote-1">
<img alt="注" src="../Images/note.png"/>
</a>
</sup>
<aside epub:type="footnote" role="doc-footnote">
<div><hr class="footnote-line xian"/></div>
<ol class="footnote-list">
<li class="footnote-item" id="footnote-1">
<p class="footnote">
<a class="footnote-back"
epub:type="backlink"
role="doc-backlink"
href="#note-1">◎</a>
注释内容。
</p>
</li>
</ol>
</aside>
duokan-* note 类时，保留 grouped ol/li 结构，但改成 footnote-list、footnote-item 等中性类。不要把 duokan-* 类作为主输出。assets/note.png 复制进 EPUB 的 Images/ 目录并补 manifest。href="#footnote-x" 都指向 li.footnote-item，每个 backlink 都能回跳，每个有 notes 的文件只有一个 grouped footnote aside，且每条 note 都留在同一 XHTML 文件。sup.note-marker {
font-size: 1em;
line-height: 0;
vertical-align: baseline;
}
sup.note-marker > .noteref-icon {
display: inline-block;
line-height: 0;
position: relative;
top: -0.14em;
text-decoration: none;
}
sup.note-marker > .noteref-icon > img {
display: block;
width: auto;
height: 0.72em;
max-width: none;
}
.footnote-line {
width: 60%;
height: 1px;
margin: 1.5em 0 1em -0.5em;
border: none;
border-top: 1px solid #777;
}
.footnote-list {
margin: 0;
padding: 0;
list-style-type: none;
text-align: left;
}
.footnote-item {
margin: 0.4em 0;
padding: 0;
list-style-type: none;
}
.footnote {
margin: 0.4em 0;
text-indent: 0;
font-size: 0.9em;
line-height: 1.35;
text-align: left;
}
.footnote-back {
margin-right: 0.25em;
text-decoration: none;
}
Styles/notes.css。poster.css。@font-face 和字体工具类属于 Styles/fonts.css。Images/note.png；默认图标只用于纯文本/数字上标标记转换。sup img 或裸 sup 图标规则；只给图片 noteref 的 sup.note-marker 设置零行高和相对上移，普通文字上标保持原样。display:none。ol/li 分组。duokan-wavyline、多看专属 notes 或 JS 作为主机制。epub-legacy-footnote-fallback。使用 templates/epub-style-demo/OEBPS/Text/02-ruby-note.xhtml 作为本地 popup footnote 参考。转换文件应满足：
href 指向同一 XHTML 内的 li.footnote-item。<html> 声明 xmlns:epub="http://www.idpf.org/2007/ops"。aside epub:type="footnote" 容纳所有本地 notes。epub:type="backlink" 和 role="doc-backlink"。转换后运行：
scripts/validate-popup-notes.sh
python3 scripts/validate_text_invariance.py before.epub after.epub --check all
validate_text_invariance.py 只将 noteref/backlink 的数字、图标和 ◎ 当作表示控件；所有 li.footnote-item 的注释正文仍必须逐字相同。
验证已构建产物：
scripts/validate-popup-notes.sh --epub templates/epub-style-demo/dist/<artifact>.epub
本 skill 默认 dry-run。直接调用只输出预期改动 JSON；加 --commit 才真正改。
代理协议示例（注释说明代理动作，不是独立 shell 命令）：
# 代理调用当前 skill，并将 dry-run JSON 写入 work/dry-run.json
# 人工审查
cat work/dry-run.json | jq
# 用户确认后，由映射 provider 写出新的 EPUB 产物
dry-run 输出格式见 docs/pipeline/cleanup-flow.md。
用于 EPUB 出现生僻字、方块字、跨阅读器字形不一致、Kindle 字体回退失败，或需要验证嵌入字体、子集字体和候选大字库是否覆盖全书字符时。
优化中文/CJK EPUB 排版，包括正文节奏、font-family 链、嵌入字体、生僻字 fallback、标题字体、中西文混排和阅读器安全段落间距。用于文字拥挤、裁切、跨阅读器字体不一致或字体规则需要清理时。
将 EPUB 封面式页面、卷首、章首或海报页转换为项目的 A-lite 可重排全页方案，同时保留原有图文叠加构图、文字、图片和资源。
重构和维护 EPUB CSS 分层。用于 CSS 规则重复、放错文件、层级边界不清，或新增正文、弹注、文字效果、文学结构、图片混排、竖排、A-lite 海报等样式时。
优化英文 EPUB 书籍排版，包括书籍类型判断、英语语言标记、serif 字体链、段落缩进、标题层级、插图、断字、引用/诗歌/信件、Kindle/Readest/Apple Books 大字号回归。用于英文小说、散文、非虚构或英文为主的 EPUB 需要形成可重排、可验证的排版方案时。
优化 EPUB 图片版式、figure 环绕、图注、栅格格式、封面声明与阅读器兼容性。用于图片过小、裁切、Kindle 空白、图文环绕差、缺图注，或封面/海报图片处理需要 EPUB 安全规则时。