Imported from liyafly/epub-handbook (
AGENTS.md). Install upstream withnpx skills add liyafly/epub-handbook. Copyright stays with the author.
AGENTS.md
本文件是本仓库给 AI 协作代理使用的通用主入口，也是 AI 工作约束的唯一维护源。 Codex、Claude Code 以及其他代理开始工作前都必须先读取本文件；平台专用入口只做跳转，不复制规则。
普通人或只想做、修一本书的用户请看根 README.md 与 docs/learn/，无需阅读本文件；本文件面向 AI 代理与专业维护者。
启动读取顺序
- 先阅读本文件，判断任务属于「已有 EPUB 清洗」「源材料接入」「阅读器兼容性实测」「实现约束变更」还是「说明增强」。
- 已有 EPUB 清洗：继续阅读
docs/final/SPEC-实现约束.md§10、docs/pipeline/cleanup-flow.md和docs/pipeline/refinement-harnesses.md。 - 源材料接入：继续阅读
skills/epub-source-intake/SKILL.md，先建立可审计的 source bundle。 - 阅读器兼容性实测：继续阅读
templates/epub-style-demo/README.md、templates/epub-style-demo/SCENE_MATRIX.md和docs/final/reader-matrix.yaml。 - 只有在任务需要时才读取对应的
skills/*/SKILL.md；技能索引和推荐顺序见skills/README.md。 - 若模型或客户端不会自动发现本文件，提示词必须显式要求先读取根目录
AGENTS.md。
架构分工
Python 与 Swift 按 capability 并存，不默认删除 Python：
| 层 | 用什么 | 职责 |
|---|---|---|
| AI / agent provider | Python（scripts/ + skills/） |
给 AI agent 调用；CLI 与验证基线的首要 provider |
| 执行核心 | Swift（swift/） |
GUI 能执行的大部分能力，native 首要 provider |
| 字体 / 图片转换 | tools-font/（HTML 工具）+ 独立 Python 项目（uv 管理） |
字体预览、覆盖/子集化、图片转换；Swift/GUI 起子进程调 CLI |
| GUI | Swift，薄（gui/） |
PARKED：当前非焦点，不投入、不作依赖；执行逻辑向 swift/ 收口 |
| 机器契约 | contracts/ + adapters/ |
Python/Swift 按 capability 并存的契约与 agent 适配表面 |
| 规范/证据 | docs/final/ + templates/ + reader-matrix.yaml |
policy/evidence 唯一来源 |
规范来源优先级（三档）
第一档 — 硬约束（违反即事故）：
templates/ → docs/final/ + reader-matrix.yaml → skills/*/SKILL.md
实测 demo 优先于文档推断。遇到冲突以 demo fixture 与 reader-matrix 为准。
第二档 — 指南（提供方法，不设硬规则）：
docs/how-to/、docs/learn/、docs/pipeline/
与 docs/final/ 冲突时以 docs/final/ 为准。
第三档 — 参考（不直接驱动行为）：
archive/ 与 git 历史。已完成的设计、实施计划、实验和早期推导只作背景补充，
不应反向覆盖约束层。
第三方来源记录写入 THIRD_PARTY.md 与 references/；实体 .epub 只在有明确保留理由和许可记录时入 git。tools/ 已于 2026-05-28 移除，人工 diff review 使用 Calibre Editor 或 VS Code。
已有 EPUB 固定流程
已有 EPUB 默认遵循「保留 before → preflight → 必要时格式化和文件名反混淆 → EPUB3 迁移 → 精排建议 → 红线校验 → 人工 diff review」：
-
复制输入文件，保留不可修改的 before 基线。禁止在唯一原件上直接修改。
-
运行
python3 scripts/epub_preflight_harness.py <input.epub>，先判断 DRM、加密标记、文件损坏和结构风险。 -
如果资源目录混乱、文件名明显混淆或需要稳定 diff，先 dry-run：
python3 scripts/epub_structure_tool.py normalize input.epub \ --output normalized.epub \ --dry-run \ --report-format json -
人工确认 dry-run 报告中的两个阶段：先格式化资源目录，再按 OPF manifest id 做文件名反混淆。确认后移除
--dry-run写出 normalized EPUB，并保存 JSON 报告。 -
将 normalized EPUB 作为后续输入。运行迁移 harness、精排 harness 和相关专项 skill。
-
运行
python3 scripts/validate_text_invariance.py before.epub after.epub --path-map <normalize-report.json>，再用 Calibre Editor 或 VS Code 做人工 diff review。 -
把值得复用的人工判断写入
records/typeset-decisions.jsonl；只属于当前书且不含正文的排版判断写入work/<book>/reports/decisions.json。授权正文校订的含文决策另存为work/<book>/reports/text-review-decisions.json，不得改名混入上述两类记录。 -
留下输入、输出、preflight、迁移结果或跳过理由、结构规范化报告、精排建议、红线结果、diff review 结论、阅读器实测或跳过理由、需要回写的文档和 skill 清单。
用户明确授权校订正文时，正文不变 gate 不得被删除、伪造为通过或用宽泛 allow-list 掩盖；应切换到 docs/final/SPEC-实现约束.md §10.1.1 与 docs/pipeline/cleanup-flow.md §7.1 的授权正文校订分支。该分支必须冻结现版与参考版、记录篇章映射和 SHA、逐项导出结构化审阅决策、拒绝待查/缺失手工文本，并在新候选 EPUB 上继续执行 metadata、spine、锚点、封面、DRM、非文字 DOM / 属性、注释和图片红线；篇名与 nav / NCX 标签同步须另列授权。
边界：
scripts/epub_structure_tool.py只使用 Python 标准库，不提供 DRM 解密。- 文件名反混淆只处理 EPUB 内部资源路径，依据 OPF manifest id 生成可读文件名，并同步更新引用。
- 默认遇到加密标记即停止。声明目标在 ZIP 中不存在时，工具可移除 stale encryption 引用；只有工具明确识别为标准字体 obfuscation 且任务得到明确授权时，才可按工具说明单独处理。真实存在的未知加密资源不得猜测或绕过。
阅读器实测闭环
阅读器问题默认遵循「demo 先行，文档后补」：
- 在
templates/epub-style-demo/添加或修改最小但真实的 demo 场景，不直接改手册定论。 - 运行模板 build 脚本，在
templates/epub-style-demo/dist/生成 EPUB。 - 用目标阅读器或转换器验证，保留错误码、截图、日志摘要、阅读器名称和版本。
- 立即更新
docs/final/reader-matrix.yaml，标记pass | warn | fail | na，写明 artifact、现象、处理动作和待复测项。 - 只有 demo 和 reader-matrix 支撑结论后，才将规则写入
docs/final/SPEC-实现约束.md。 - SPEC 变更后，同步检查终极手册、速查表和相关 skills，避免分叉。
如果实测结果与手册冲突，以实测 demo 和 reader-matrix 为准，手册必须被修正。
关键约束
- 修改
docs/final/硬规则时，同步检查：docs/final/EPUB 3 终极实践手册.mddocs/final/EPUB 3 HTML CSS 属性速查表.mddocs/final/SPEC-实现约束.md
- 涉及弹注、字体、A-lite、竖排等规范条目时，优先写入
SPEC-实现约束.md，再在手册解释。 skills/*/SKILL.mdfrontmatter 只保留name和description；字段名不要随意删改。skills/*/agents/openai.yaml只使用扁平字符串 metadata，并与对应SKILL.md用途一致。templates/样本应能独立打包，生成产物放在模板自己的dist/。- Kindle、Apple Books、Thorium、KOReader 等阅读器兼容性问题，不允许只靠手册推断修改。
- demo EPUB 必须覆盖普通正文、中英混排、大字号标题、图片或封面、表格、代码、标准弹注、legacy fallback、A-lite、竖排和字体链。
- 图文环绕主路径使用
figure.img-left/right。float和百分比width放在<figure>，内部<img>使用width:100%; height:auto。 .wavy等带样式下划线必须先写基础text-decoration: underline;，再写text-decoration-style。- 含 MathML 的 XHTML 必须在 OPF manifest 声明
properties="mathml"。 - 修改弹注结构后必须运行
scripts/validate-popup-notes.sh；构建后优先用--epub <artifact>复核产物。 - 任何阅读器实测规则必须能追溯到 demo、artifact、阅读器名称和版本、现象与结论。信息不完整时只能记录为待验证假设。
- 新增第三方 EPUB 参考样本时，必须同步更新
THIRD_PARTY.md，写清来源、作者、许可和链接。
最小验证矩阵
按改动类型运行足够的验证，不要只依赖人工阅读：
| 改动类型 | 至少运行 |
|---|---|
| 任意改动 | git diff --check |
| AI 入口或维护文档 | python3 scripts/validate_ai_entrypoints.py |
| skills | python3 scripts/validate_skills_basic.py |
| 文档、skills、模板或字体规则同步 | python3 scripts/validate_docs_consistency.py |
| Python 脚本 | 对应的 scripts/test_*.py；必要时 python3 -m py_compile <files> |
| 已有 EPUB 清洗 | preflight、结构规范化 dry-run 或跳过理由、validate_text_invariance.py、人工 diff review |
demo、validator 或 docs/final/ |
build demo、scripts/validate-epub-style-demo.sh --epub <artifact>、scripts/validate-popup-notes.sh --epub <artifact> |
| OPF、nav、NCX | 额外运行 xmllint --noout ...；本机没有 xmllint 时记录跳过理由 |
| 任意 EPUB 产物 | python3 scripts/epub_lint.py <artifact>，error 必须清零或逐条给出豁免理由 |
| demo / starter 构建产物 | 本地跑 demo validator、popup note validator 与 scripts/epub_lint.py；EPUBCheck 只在 GitHub Actions 作为 CI gate 运行 |
可选安装 hook 模板：
scripts/install-hooks.sh文档落点
- 对外硬约束写入
docs/final/。 - 某类书的实操方式写入
docs/how-to/。 - 已有 EPUB 的流程、工具和模式写入
docs/pipeline/。 - 当前维护规则和架构总纲写入本文件；任务计划、review 先留在任务或 issue 中。
- 已完成的计划、review、推导和实验记录归档到
archive/或保留在 git 历史中，不直接驱动行为。 - 排版决策记录写入
records/；仓库级文件只保存脱敏、可复用的机器可读判断。 - 新增第三方来源说明写入
THIRD_PARTY.md。
历史计划和实验快照只在任务明确要求时修改。不要为了统一措辞重写 archive/ 中的历史记录。