前言¶

在 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