前言¶

在 DeepSeek Harness（DSH）里读论文，常见做法是打开原始 PDF，或在对话里让模型概括全文。前者版式固定、长文翻页成本高；后者快，但缺少可跳转目录、内嵌图表和可反复标注的阅读界面。若你希望「一条链路」从 PDF 或 arXiv 链接得到单文件 HTML，并在 DSH Web 里预览、批注、再让 agent 读你的高亮，客户端插件 dsh-paper2html（维护者 rubyzhao666）就是围绕这条路径做的。它由上游 paper2html（MIT）改造而来，归类为 DSH 社区目录中的客户端插件。

这是什么¶

dsh-paper2html 是 DSH 插件：把本地 PDF 或 arXiv 论文转成精美、可分享、可交互的 HTML 阅读页。默认不需要任何 API key——内置本地解析（PyMuPDF）抽取标题、正文与图片，再由渲染层排版。配置 DeepSeek key 后可选用 AI 摘要；配置 Doc2X / PDF2X key 后可走云端高保真解析（公式、表格、扫描件 OCR）。

• 目录页：rubyzhao666/dsh-paper2html
• 源码：GitHub
• 当前包版本（package.json）：0.5.2，许可证 MIT

核心能力¶

下面按「转换 → 阅读 → 批注 → 与 agent 协作」说明已文档记载的能力。

转换与输出¶

paper2html_convert 主要参数如下（供排查与二次开发参考）：

paper2html_convert({
  input: "/abs/path/paper.pdf" | "https://arxiv.org/abs/1706.03762" | "1706.03762",
  outputDir?: "/abs/out/dir",
  style?: "dark_lab" | "clean_paper" | "neon_tech",
  understand?: false   // true 需要已配置 DeepSeek key
})

返回中包含 htmlPath、previewUrl、title、engine（local | doc2x | pdf2x）、pages、bytes、understand、warnings 等字段。

交互阅读器¶

生成页提供左侧目录、⌘K 搜索、速读/标准/精读三种阅读模式、阅读进度与锚点复制。公式与图表方面：KaTeX 渲染公式（云端解析时最完整）、Mermaid 架构图、论文插图内嵌。公式/图表依赖 CDN 加载 KaTeX/Mermaid 时，联网打开渲染最完整；离线时正文仍可读。

DSH Web 集成¶

安装后会自动具备：

• 工具：paper2html_convert、paper2html_status、paper2html_annotations
• skill：paper2html
• 只读预览路由：/paper2html/
• DSH Web 左侧栏「Paper2HTML」入口：打开论文库单页，展示已转换论文、批注统计、搜索/主题筛选/排序，以及「转换新论文」等操作

左侧栏入口属于浏览器 client 半边：安装或更新插件后需重启 DSH（或重载 Web 界面） 才会出现；重启前工具、skill、预览路由仍可用。

批注、导出与 agent 读取¶

阅读页右下角提供「批注」能力：划词高亮（四色）或文字批注，侧栏按文档顺序列出；数据保存在浏览器 localStorage，并可「导出带批注版」得到 <原名>-annotated.html。

在 DSH Web 预览页（http://127.0.0.1:<端口>/paper2html/…）打开时，批注会防抖同步到 Host：$DSH_HOME/paper2html/annotations/<docId>.json。对话里可说「把我标的部分总结一下」，由模型调用 paper2html_annotations 读取同步后的批注。注意：仅用 file:// 打开 HTML 时批注不 sync 到 Host，agent 读不到，但仍可用「导出带批注版」分享。

有没有 API key 的差别¶

插件不会使用作者提供的 key；本地解析时论文内容不出网。云端解析直连 Doc2X/PDF2X，AI 摘要直连你配置的模型地址。

可选配置（勿把 key 贴在对话里）：

export DEEPSEEK_APIKEY="sk-..."
export DOC2X_APIKEY="sk-..."
# 或 PDF2X_APIKEY

或写入 ~/.dsh/paper2html/config.json：

{
  "deepseekKey": "sk-...",
  "doc2xKey": "sk-..."
}

可选字段包括 deepseekBaseUrl（默认 https://api.deepseek.com/v1）、llmModel（默认 deepseek-chat）。插件只读该文件，不会自动写入 key。

安装与启用¶

README 记载：插件由 DeepSeek Harness 安装，方式包括 plugin_manager 或本地目录安装。安装完成后，上述工具、skill、预览路由即注册；首次成功转换时会自动准备 Python 环境：优先使用本机已安装 pymupdf / markdown 的解释器；否则在 ~/.dsh/paper2html/venv 懒建 venv 并联网安装最小依赖（约 50 MB，仅一次）。可通过环境变量 PAPER2HTML_PYTHON=/path/to/python3 指定解释器。

环境要求（摘自 package.json / README）：

• DeepSeek Harness >=0.2.1-rc.2 <0.3.0
• Node ^22.19.0 || >=24.0.0
• Python 3.9+

安装前请自行查看 GitHub 仓库 源码与 MIT 许可证；插件以当前 DSH 进程权限访问本机文件与网络（首次装依赖、可选云端解析与 AI 摘要时才会出网）。

典型用法¶

论文库（左侧栏）¶

在 DSH Web 左侧点 Paper2HTML：顶栏显示篇数与批注总数，「＋ 转换新论文」会在新会话填入提示词，补上 PDF 路径或 arXiv 链接即可。卡片上可「打开阅读页」「复制链接」「复制文件路径」。数据来自本机 $DSH_HOME/paper2html/exports 与批注 store，页面本身不发外网请求。

直接对话¶

不必记忆工具名，例如：

• 「把这个 PDF 变成能看的网页」
• 「这篇 arXiv 帮我转成网页，用 clean_paper 主题」
• 「根据我在预览里标的批注整理成笔记」
• 「怎么把带批注的版本发给同事」

预览与分享¶

转换完成后打开返回的 previewUrl（形如 http://127.0.0.1:<端口>/paper2html/p/<id>）；分享则发送 htmlPath 指向的单文件 HTML 即可。

手动排查（可选）¶

node scripts/smoke.mjs https://arxiv.org/abs/1706.03762 --style clean_paper

python3 python/paper2html.py --input /abs/paper.pdf --style clean_paper --no-understand

数据目录与已知限制¶

本机数据布局：

$DSH_HOME/paper2html/
├── config.json
├── venv/
├── cache/              # arXiv PDF 缓存
├── exports/            # 默认 HTML 输出
├── annotations/        # Web 预览同步的批注 JSON
└── preview-registry.json

使用前需心里有数的几点：

• 本地解析对复杂公式、表格、版式还原有限；扫描件无文本层时需 OCR 或 Doc2X/PDF2X。
• 插图上限：单篇 80 张、单张 ≤4 MB、总原始图 ≤20 MB，超出会在 warnings 中提示。
• 批注同步单文档上限 500 条 / 512KB；file:// 与 Web 预览的 Host 批注不互通，分享批注依赖「导出带批注版」。

结尾¶

dsh-paper2html 把「PDF / arXiv → 交互 HTML → DSH Web 预览与论文库 → 批注同步给 agent」串成一条默认无 key 可跑的客户端链路，适合在 Harness 里长期囤积、标注和复述论文的场景。安装与能力细节以仓库 README 为准。

• 社区目录：https://www.skillhub.cn/plugins/rubyzhao666/dsh-paper2html
• 源码与许可：https://github.com/rubyzhao666/dsh-paper2html