前言¶

在 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)¶

只读不写，不解包到磁盘即可返回：

warnings 会明确列出例如：mimetype 被压缩或不在首位；spine 声明的文件不在 ZIP 内；nav href 悬空；spine 文档在目录中不可达；linear="no"；缺少 properties="nav" 等。

epub_build(outputName, …)¶

生成 EPUB 3，两条路径二选一：

outputName 必填（如 my-book.epub）。可选 title、language、author、identifier（未给则按内容生成稳定 URN）、splitLevel（默认 auto 或 h1–h6）、coverImagePath。返回含 splitRule，说明边界如何切出；build 与 inspect 的字数统计口径一致（含注入的 <h1>）。

epub_split(path, …)¶

将 EPUB 按 spine 顺序拆成逐章文件并写清单。

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

典型用法思路¶

1. 对已有书：epub_inspect(path="book.epub")，根据 warnings 与 chapters[]、toc[] 决定是否改 spine/nav 或重打包。
2. 从已知章节列表：epub_build(outputName="my-book.epub", title="…", chapters=[{title, html}, …])。
3. 从整页 HTML：epub_build(..., html="…", splitLevel="auto")，检查返回的 splitRule 是否符合预期。
4. 导出编辑：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 电子书依赖的场景。

• 目录页：https://www.skillhub.cn/plugins/yuehancn/dsh-tool-epub
• GitHub：https://github.com/yuehancn/dsh-tool-epub