前言¶
在 DeepSeek Harness（DSH）里做长文或电子书相关任务时，模型往往只能处理「一段 HTML」或「几个章节文件」，而 EPUB 本身是一套带强制约束的容器：ZIP 里 mimetype 必须首位且不压缩，OPF 里 spine 与 nav 还要彼此一致。用通用 ZIP 库随手打包，常见问题不是立刻报错，而是阅读器拒收，或章节边界猜错却仍能打开——排查成本高。
下面介绍社区插件 dsh-tool-epub（维护者 yuehancn，GitHub：yuehancn/dsh-tool-epub）。它在 DSH 进程内提供四个工具，把「先看清结构」和「再动手改/造」分开；ZIP 读写与 XML 解析为自实现，不依赖 epubjs、jszip，externalDependency 为 none。插件在 SkillHub 目录分类为「模型推理」，本质是供智能体调用的 EPUB 工具集，而非单独的推理模型。
这是什么¶
dsh-tool-epub 是面向 DeepSeek Harness 的自建工具插件：只读体检现有 .epub，从章节或单一大 HTML 组装合规 EPUB 3，或按 spine 顺序拆回逐章文件。README 写明在 dsh 0.2.0-rc.2（preview）上构建测试；apply(ctx) 插件规范稳定，若你使用更新版本 dsh，需自行核对兼容性。package.json 中版本为 1.0.0，许可证 MIT。
为什么 EPUB 需要专门工具¶
EPUB 不是改后缀的 Word，而是 ZIP + OCF + OPF + XHTML 的组合。容易出错的往往是判断环节：
- spine（阅读顺序）与 nav（目录）各声明一遍章节，两者不一致时，多数「书坏了」来自此处。
- 从大 HTML 拆章依赖标题层级推断，猜错时可能静默错位。
- 多数 ZIP 库默认压缩所有条目；
mimetype被压缩后，严格阅读器会直接拒收。
插件设计把 epub_inspect 独立成只读工具，不强制作为 epub_build 的前置步骤：「这本书现在长什么样」与「我要造一本什么样的书」是两件独立决策。
四个工具¶
epub_status¶
长任务前先调用，查看本插件支持读、造、拆，以及 externalDependency: none；同时返回章节数上限与单次调用时间预算，避免做到一半才触顶。
epub_inspect(path)¶
只读不写，不解包到磁盘即可返回：
| 返回项 | 说明 |
|---|---|
title / creator / language / identifier |
OPF 元数据 |
epubVersion |
通常 3.0 |
entryCount |
ZIP 条目数 |
chapters[] |
按 spine 顺序的逐章记录，含 words、bytes |
toc[] |
nav 目录树 |
totalWords |
全书字数 |
images[] |
引用的图片 |
warnings[] |
结构问题清单 |
warnings 会明确列出例如：mimetype 被压缩或不在首位；spine 声明的文件不在 ZIP 内；nav href 悬空；spine 文档在目录中不可达；linear="no"；缺少 properties="nav" 等。
epub_build(outputName, …)¶
生成 EPUB 3，两条路径二选一：
| 方式 | 参数 | 用途 |
|---|---|---|
| 显式章节 | chapters: [{title, html}, …] |
边界已知 |
| 自动推断 | html: "<一个大 HTML>" + splitLevel |
按标题层级切分 |
outputName 必填（如 my-book.epub）。可选 title、language、author、identifier（未给则按内容生成稳定 URN）、splitLevel（默认 auto 或 h1–h6）、coverImagePath。返回含 splitRule，说明边界如何切出；build 与 inspect 的字数统计口径一致（含注入的 <h1>）。
epub_split(path, …)¶
将 EPUB 按 spine 顺序拆成逐章文件并写清单。
| 参数 | 说明 |
|---|---|
path |
必填，.epub 路径 |
outputDir |
默认走配置 |
format |
html（默认）或 txt |
prefix |
文件名前缀，默认 slug，支持中文 |
includeToc |
是否额外写 index.html 目录页 |
txt 与字数统计共用同一标签剥离逻辑；章节文件名按 spine 补零三位（-001、-002），字典序与阅读顺序一致。
安装与启用¶
一行安装（命令来自项目 README）：
dsh plugin --profile desktop add github:yuehancn/dsh-tool-epub
支持的 profile：desktop（桌面版）、web（Web 版）。安装后重启 dsh 即可在工具列表中看到上述能力。
配置¶
在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中可覆盖插件配置，例如：
# ~/.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 |
可按需关闭单个工具 |
典型用法思路¶
- 对已有书：
epub_inspect(path="book.epub")，根据warnings与chapters[]、toc[]决定是否改 spine/nav 或重打包。 - 从已知章节列表：
epub_build(outputName="my-book.epub", title="…", chapters=[{title, html}, …])。 - 从整页 HTML：
epub_build(..., html="…", splitLevel="auto")，检查返回的splitRule是否符合预期。 - 导出编辑：
epub_split(path="book.epub", format="html")，在配置的outputDir下得到按 spine 命名的章节文件。
长任务前可先 epub_status 确认章节上限与超时预算。
安全与运行环境¶
README 说明：href 经 resolvePath 归一化，带 zip-slip 防护；outputName 中的 ../ 会被净化；不联网、不执行书内脚本，仅解析文本与 XML；同输入可得到字节一致的 EPUB（固定时间戳与 identifier 策略），便于 diff 对比。
适用与注意：插件在 当前 dsh 进程权限 下读写你指定的路径；安装前建议阅读 源码仓库 与 MIT 许可证。DSH 生态强调「一切皆插件」；SkillHub 插件目录 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-tool-epub 把 EPUB 的「体检、组装、拆解」收进 DSH 工具面，强调 spine/nav 一致性与可解释的拆章规则，适合需要在智能体工作流里处理 EPUB 3、且希望零额外 npm 电子书依赖的场景。
