name	epub-popup-footnote-converter
description	将 EPUB 普通注释、尾注、旧式注释或纯文本注释标记转换为项目标准 popup footnote 结构：图片注释图标触发、同文件 grouped note body、◎ 回跳，并保留注释内容。

EPUB Popup Footnote 转换

当需要把普通脚注、尾注、旧多看注释或纯文本 noteref 标记转换为项目最终 popup footnote 模式时使用这个 skill。

固定目标

权威结构源是 docs/final/SPEC-实现约束.md §1；以下内容保持 skill 可独立执行，并不得与该节分叉。

使用这个结构：

任何使用 epub:type 的 XHTML 根 <html> 都声明 xmlns:epub="http://www.idpf.org/2007/ops"。
noteref 是带 epub:type="noteref" 和 role="doc-noteref" 的 <a>。
noteref 内容是图片图标，通常为 ../Images/note.png；已有本地图标资源时保留原 img src，本 skill 的 assets/note.png 只作为纯文本标记转换时的默认图标。
每个 XHTML 文件最多一个 grouped note body：<aside epub:type="footnote" role="doc-footnote">。
该 XHTML 文件内所有 notes 放进 ol.footnote-list。
每条 note target 是带目标 id 的 li.footnote-item。
noteref href 指向对应 li.footnote-item id，不指向独立 per-note aside。
回跳符号是 ◎。
noteref、target li 和包含它的 aside 位于同一 XHTML 文件。
注释正文精确保留。
私有 note 机制不能作为主路径。

转换流程

读取包含 note reference 和 note body 的 XHTML 文件。
确保 XHTML 根 <html> 声明 xmlns:epub="http://www.idpf.org/2007/ops"。已有声明则保留，不重复添加。
尽量保留已有 note id。只有缺失或冲突时才规范化。
识别 Sigil 旧结构：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>

把同一 XHTML 文件内所有 note body 转成一个 grouped aside：

<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-* 类作为主输出。
校验每个 noteref 图标都在 OPF manifest 中声明且文件存在。只有 EPUB 还没有可用注释图标、且需要从纯文本标记生成图片触发器时，才把本 skill 的 assets/note.png 复制进 EPUB 的 Images/ 目录并补 manifest。
把下面 CSS 加入活动 stylesheet，或合并进已有 note section。
验证每个 noteref href="#footnote-x" 都指向 li.footnote-item，每个 backlink 都能回跳，每个有 notes 的文件只有一个 grouped footnote aside，且每条 note 都留在同一 XHTML 文件。

CSS

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;
}

CSS 放置

在本仓库 layered demo 中，footnote CSS 必须写进 Styles/notes.css。
不把 footnote CSS 写进 poster.css。
@font-face 和字体工具类属于 Styles/fonts.css。

禁止事项

除非没有图标资源且用户同意，不把图片图标替换为纯文本。
已有图片图标不得无差别替换为默认 Images/note.png；默认图标只用于纯文本/数字上标标记转换。
不使用无作用域的 sup img 或裸 sup 图标规则；只给图片 noteref 的 sup.note-marker 设置零行高和相对上移，普通文字上标保持原样。
不对 footnote body 使用 display:none。
不把 notes 移到另一个 XHTML 文件。
同一文件包含多条 notes 时，不输出每条一个 aside；必须用一个 aside + ol/li 分组。
不改写注释正文。
不把 duokan-wavyline、多看专属 notes 或 JS 作为主机制。
如果目标 EPUB 需要多看旧版兼容，先做本转换，再应用 epub-legacy-footnote-fallback。

验证 fixture

使用 templates/epub-style-demo/OEBPS/Text/02-ruby-note.xhtml 作为本地 popup footnote 参考。转换文件应满足：

noteref href 指向同一 XHTML 内的 li.footnote-item。
XHTML 根 <html> 声明 xmlns:epub="http://www.idpf.org/2007/ops"。
每个文件用一个 grouped aside epub:type="footnote" 容纳所有本地 notes。
backlinks 使用 epub:type="backlink" 和 role="doc-backlink"。
EPUB 有或能接收图标资源时，note trigger 使用图片图标。

转换后运行：

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

Dry-run 约定

本 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。