EPUB 电子书工具 yuehancn/dsh-tool-epub

dsh-tool-epub

在 dsh 里读、造、拆 EPUB 电子书 —— 先把一本书拆开看清楚它的元数据、阅读顺序和目录到底对不对，再从章节拼出一本合规的书，或者把一本已有的书拆回逐章的 HTML。

给 DeepSeek Harness 用的自建工具插件：ZIP 读写器和 XML 扫描器都是自己写的，不装 epubjs、不装 jszip，在一台干净的机器上就能用。

Compatibility: built and tested against dsh 0.2.0-rc.2 (preview).
The apply(ctx) plugin spec is stable; verify against your own dsh version if newer.

一行安装

dsh plugin --profile desktop add github:yuehancn/dsh-tool-epub

支持的 profile：desktop（桌面版）/ web（Web 版）。装完重启 dsh 即可用。

为什么需要它

EPUB 不是「一个 Word 文档换个后缀」，它是一个有强制骨架的 ZIP： mimetype 必须是第一个条目且不压缩存储，META-INF/container.xml 指向一个 OPF 包文档，包文档里再声明 spine（阅读顺序）和 nav（目录）。
缺一环，阅读器就直接拒收。

真正容易出错的是判断而不是管道：

- 一本书的章节被声明了两次 —— spine 一次、nav 一次。它们比你想的更常不一致，而「书坏了」绝大多数时候就是这两处对不上。
- 把一个大 HTML 拆成章节要靠标题层级猜边界。猜错了是静默的：书还是能打开，只是内容错位了。
- mimetype 要是被压缩了（绝大多数 ZIP 库的默认行为），严格的阅读器直接拒绝整本书。

这个插件把「看清楚」和「动手」分开：

epub_inspect(path="book.epub") → 元数据 / 阅读顺序 / 目录 / 逐章字数 / 结构问题
epub_build(title="…", html="…") → 合规的 EPUB 3，并告诉你用了哪条拆分规则

关键设计：epub_inspect 是独立的工具，不是 epub_build 的前置步骤。
因为「这本书现在长什么样」和「我要造一本什么样的书」是两件事 ——先拿到体检报告，再决定动不动手。

四个工具

epub_status

报这里有哪些能力：读、造、拆都内置，externalDependency 一栏明确写着 none。另外报出章节数上限和单次调用预算。
长任务前先问一句，避免做到一半才发现超限。

epub_inspect(path)

只读不写。不解包就能拿到：

| 返回项 | 说明 |
| title / creator / language / identifier | OPF 里的元数据 |
| epubVersion | 从 package 元素的 version 属性读，通常是 3.0 |
| entryCount | ZIP 里的条目数 |
| chapters[] | 按 spine 顺序（不是文件名顺序）排好的逐章记录，含 words 和 bytes |
| toc[] | nav 文档里的目录树 |
| totalWords | 全书字数 |
| images[] | 书里引用的图片资源 |
| warnings[] | 结构问题清单 |

warnings 是重点，它会把下面这些明确点出来而不是含糊带过：

- mimetype 被压缩了，或者不是第一个条目
- spine 里声明了某个文件，但 ZIP 里没有这个文件
- 目录（nav）里的 href 指向一个不存在的路径
- 某个 spine 文档从目录里根本走不到（读者会看得见但翻不到）
- linear="no" 的文档（不算正文顺序）
- manifest 里没有 properties="nav" 的条目 → 这本书没有目录

epub_build(outputName, …)

造一本书。两条路径，二选一：

| 方式 | 参数 | 用途 |
| 显式章节 | chapters: [{title, html}, …] | 边界已经知道了 |
| 自动推断 | html: "<一个大 HTML>" + splitLevel | 边界要从标题层级推 |

| 参数 | 说明 |
| outputName | 必填，产出文件名，如 my-book.epub |
| title / language / author / identifier | 元数据；identifier 不给就按内容生成一个稳定的 URN |
| splitLevel | auto（默认，取最浅的标题层级）或 h1–h6 |
| coverImagePath | 封面图路径 |

返回里带 splitRule 字段 —— 明确告诉你边界是怎么切出来的 （例如 split on 3 h2 headings）。推断出来的东西必须可解释，否则错了没人知道。第 0 章以外每一章的字数都从生成的 XHTML 里数（包含注入的 ），所以 build 和 inspect 数出来的字数是对得上的。

epub_split(path, …)

把一本书拆回逐章文件，再写一份清单。

| 参数 | 说明 |
| path | 必填，.epub 路径 |
| outputDir | 输出目录，默认走配置 |
| format | html（保真）或 txt（纯文本），默认 html |
| prefix | 文件名前缀，默认用书名/文件名生成的 slug（支持中文） |
| includeToc | 是否额外写一份 index.html 目录页 |

txt 模式和字数统计走的是同一个标签剥离器，所以两者对「正文是什么」永远不会打架。章节序号按 spine 顺序补零到三位（-001、-002），保证文件名的字典序和阅读顺序一致。

配置

~/.dsh/profiles/<profile>/cordis.patch.yml
- id: tool-epub
config:
outputDir: C:/Users/you/Documents/epub-output
defaultTitle: Untitled
defaultLanguage: zh-CN
defaultAuthor: 你的名字 maxChapters: 500 timeoutMs: 60000

| 字段 | 默认 | 说明 |
| outputDir | epub-output | 产物目录 |
| defaultTitle | Untitled | 调用方不给标题时的兜底 |
| defaultLanguage | en | BCP 47 语言标签，中文书改成 zh-CN |
| defaultAuthor | "" | 写进生成书的作者 |
| maxChapters | 500 | 超过就拒绝构建（防止一次请求把内存吃光） |
| timeoutMs | 60000 | 单次调用预算 |
| status/inspect/build/split | true | 按需关掉某个工具 |

安全说明

- Zip-slip 防护：书里的 href 一律过 resolvePath 归一化， ../../etc/passwd 这类路径会被夹在压缩包根目录内，逃不出去。
- 产物文件名同样净化：outputName 里的 ../ 会被剥掉再做替换，不会往产物目录外面写文件。
- 不联网、不执行书里的任何东西 —— 只解析文本和 XML。
- 确定性：固定 DOS 时间戳 + 按内容推导的 identifier + 固定的 dcterms:modified。同一份输入永远产出字节一致的书，所以两次构建可以直接 diff。

实现说明：两个必须自己写的地方

EPUB 是 ZIP + OCF + OPF + XHTML，全是开放标准，但细节全是坑。
这里没有引第三方库，所以下面这几件事必须做对：

1. mimetype 必须是第一个条目，且 STORED（不压缩）。
大多数 ZIP 库默认压缩所有条目 —— 那是错的，严格的阅读器会直接拒收整本书。
所以 writeZip 里 store: true 走的是方法 0 的独立分支。

2. 读 ZIP 时必须用「本地头」的长度，不能用目录里的。
中央目录和本地头各自记录了自己的 name/extra 长度，两者可以不一样。
用目录里的长度去算数据偏移，遇到带额外字段的条目就会读出乱码。

3. EOCD 签名要从后往前扫，且窗口要留出 65535 字节的注释空间。
因为 ZIP 注释里可以包含 0x06054b50 这四个字节，从前往后扫会命中假签名。

4. 目录里指向的 href 是相对路径，要相对nav 文档自己的位置解析，不是相对包根、也不是相对当前工作目录。

验证方式：_test/verify-epub.py 用两条独立路径校验 —— Python 标准库 zipfile 检查容器合法性（mimetype 首位、STORED、CRC 全对，
testzip() 能跑通），再用 ebooklib 做一次真正的 EPUB 解析
（元数据、spine、目录）。

这个双路校验当场抓到了一个我自己的 bug：我的校验脚本没做 HTML 实体解码，把书里的 & 和 & 当成不相等，误报标题错误 —— 书是对的，校验器是错的。
自己写的校验器犯的错，只有另一个实现才能发现。

当前结果：4/4 本书通过校验（含中文书、实体转义书、单章书、多章书）。

跑测试

mkdir -p node_modules/@deepseek-ai
cp -r "$HOME/.dsh/profiles/desktop/node_modules/@deepseek-ai/." node_modules/@deepseek-ai/
node _test/run-all.mjs

三个套件，356 条断言全绿（对着真实 @deepseek-ai/dsh-tools 跑，不 mock）：

| 套件 | 断言 | 内容 |
| test-logic.mjs | 168 | Config 默认值与覆盖、注册开关、schema 归一化、XML 转义、标签剥离（含多行 ）、路径解析（含 zip-slip 夹取）、标题推断、字数统计（CJK 逐字计）、字节嗅探、CRC-32 已知向量（"123456789" = 0xcbf43926）、ZIP 写出布局与确定性、ZIP 读入健壮性、OPF/nav 解析 |
| test-integration.mjs | 125 | status、显式章节构建、自动推断构建、8 条构建错误路径、章节上限、封面嵌入、真书 inspect、4 条 inspect 错误路径、5 个结构问题 fixture（mimetype 被压缩 / spine 文件缺失 / 目录悬空 / 孤儿章节 / linear="no"）、split 的 html 与 txt 两种模式、自定义输出目录 + 中文 slug、split 错误路径、确定性、注册开关 |
| test-e2e.mjs | 63 | 构建真书 → 断言结构自洽（assertCoherent）→ XHTML 良构性 → 中文往返 → 实体转义 → 产物文件名净化（zip-slip）→ 封面 → split 能还原正文 → build 与 split 对字数的口径一致 |

再跑一次独立校验（需要 Python + ebooklib）：

python _test/verify-epub.py _test/samples

test-e2e.mjs 会把样本写到 _test/samples/，正是给这个脚本消费的 ——所以 e2e 是「自己验自己」，而这个脚本是「别人验自己」。

许可

MIT