dsh-paper-reader

v1.5.0

Published

2 months ago

英文文献精读插件：注册 paper_ingest 工具（按 URL 抓取论文网页文本），并内置 paper-reader skill（PDF 提取 / 句子切分 / 全文逐段翻译、解析、逻辑链条梳理与方法论/亮点提炼工作流，含环境自检）。

0High
0Medium
0Low

rantz

dsh deepseek-harness paper pdf translation literature-review skill

dsh-paper-reader — 英文文献全文逐段翻译与解析插件

给一篇英文文献的 PDF 文件 或 网页链接，自动完成：全文逐段翻译（原文/译文）与逐段解析（每段在论证中的作用与逻辑关系），并理清全文逻辑链条、提炼方法论与亮点创新，输出结构化精读报告。

安装本插件后，DSH agent 会获得两样能力：

paper_ingest 工具 — 按 URL 抓取论文网页（HTML 文章页/摘要页）并转为纯文本；
paper-reader skill — 内置精读工作流与脚本：PDF 文本提取（PyMuPDF）、句子切分、URL 抓取，以及"全文逐段翻译+解析+逻辑链条+方法论/创新提炼"的完整流程规范。最终报告 analysis.md + analysis.pdf 双格式交付。

一、安装

方式 A：一键安装（推荐）

# 在插件目录内运行
cd dsh-paper-reader
.\install.ps1

脚本会自动：① 用 dsh plugin 把插件注册到 web profile；② 向 cordis.patch.yml 写入 insert 条目（幂等）。

方式 B：手动安装

# 1) 注册依赖（在任意目录，把路径换成你的插件路径）
dsh plugin --profile web add "file:D:/path/to/dsh-paper-reader"

# 2) 编辑 C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml，追加：
#    - insert:
#        - id: paper-reader
#          name: dsh-paper-reader

激活

插件集合变更需要重启：停止当前 dsh web 进程，重新运行 dsh web，刷新页面。

环境依赖

| 依赖 | 用途 | 说明 | |---|---|---| | Node.js ≥ 18 | URL 抓取 / 插件运行 | DSH 本身就需要 | | Python 3 + PyMuPDF | PDF 文本提取 | 缺失时：pip install pymupdf | | python-markdown | 生成 PDF 报告 | 缺失时：pip install markdown | | dsh + pnpm | 插件安装 | DSH 自带 |

环境自检：安装脚本会在结束时自动检查依赖；也可以随时手动运行：

python "<插件目录>\skill\scripts\check_env.py"

全部显示 [OK] 即就绪；显示 [缺失] 的项按提示安装（pip install pymupdf markdown）后重跑自检。缺少 PyMuPDF 是新手最常见的报错来源——pip install pymupdf 即可解决，插件内的脚本与启动日志也会在依赖缺失时给出同样的安装提示。

安装后可快速自检：node test\test-standalone.mjs https://arxiv.org/abs/1706.03762（无需重启 GUI）。

二、使用

在 DSH Web GUI 对话框里直接说：

本地 PDF：把 C:\...\paper.pdf 这篇文献逐段翻译并解析，理清逻辑链条
网页链接（HTML 文章页/摘要页）：解析这个链接的论文：https://arxiv.org/abs/xxxx.xxxxx
网页链接（PDF 文件）：分析这篇 PDF 文献：https://arxiv.org/pdf/xxxx.xxxxx

agent 会：抓取/提取全文 → 句子切分编号（连续的编号列表项自动合并为同一部分）→ 分块逐段翻译解析（图表引用高亮标注：原文/译文图号加粗、解析标注"本段讲的是哪张图/表"、报告末尾附图表引用索引）→ 梳理逻辑链条 → 提炼方法论与亮点 → 输出 analysis.md 报告 + analysis.pdf。

报告结构：文献信息 → 一句话概括 → 逻辑链条（章节地图 + 纯文本论证流程图）→ 逐段翻译与解析（原文/译文/论证作用/逻辑关系/图表引用）→ 方法论提炼 → 亮点创新 → 图表引用索引 → 术语表 → 批判性思考。

三、个性化：用户领域配置（可选，推荐）

不同用户研究的领域不同。本插件支持用户档案（profile） 与 术语表（glossary） 两种个性化输入：存在时每次精读前强制加载，翻译与解析必须遵守；不存在时也不影响使用。

两种配置方式

方式 A：对话式（推荐，无需手动编辑）

配置缺失时，agent 会在开始翻译前主动询问：研究领域、翻译风格、希望固定译法的术语（可选）、固定规则（可选）。回答后 agent 自动把结果写入配置文件，之后每次精读自动加载，不再重复询问（随时说"更新我的领域配置"可重新配置）。

方式 B：手动编辑文件

python "<插件目录>\skill\scripts\user_config.py" init    # 首次创建模板（绝不覆盖已有文件）
python "<插件目录>\skill\scripts\user_config.py" status   # 随时查看状态

用任意文本编辑器打开下面的文件修改，保存即生效（下次精读自动加载，无需重启）。

存放位置（用户主目录，独立于插件）

~/.dsh/paper-reader/            # Windows: C:\Users\<你>\.dsh\paper-reader\
├── profile.md                  # 用户档案：领域 / 风格 / 固定规则
├── glossary.md                 # 术语表：英文术语 → 指定译法
├── corrections/                # 纠错记忆（预留，开发中）
└── corpus/                     # 用户语料（预留，可选）

与插件安装目录完全隔离：npm pack / npm publish / 插件更新绝不会包含或覆盖这些文件；
每个系统用户各自独立一份（多用户天然隔离）；
服务器部署可用环境变量 DSH_PAPER_READER_USER_DIR 指定其他位置。

首次创建（一条命令，绝不覆盖已有文件）

python "<插件目录>\skill\scripts\user_config.py" init
python "<插件目录>\skill\scripts\user_config.py" status   # 随时查看状态

日常编辑

直接用任意文本编辑器打开 profile.md / glossary.md 修改，保存即生效（下次精读自动加载，无需重启）。

profile.md：填你的研究领域、翻译风格、固定规则（如"机构名保留英文""公式原样保留"）
glossary.md：维护术语表（表格：英文术语 / 指定译法 / 语境说明），精读时强制采用表中译法

四、工作原理

输入（PDF 路径 | 网页 URL | 粘贴全文）
  ├─ PDF      → skill/scripts/extract_pdf.py（PyMuPDF：页标记 + 阅读顺序）
  ├─ URL(HTML)→ paper_ingest 工具 / skill/scripts/fetch_url.mjs
  └─ URL(PDF) → fetch_url.mjs 下载 → 再走 PDF 流程
  ▼
skill/scripts/split_sentences.py（缩写感知切句 → sentences.json，含页码/章节/段落；
   连续的列表项段落 (1)(2)(3) / 1.2.3 / • 自动合并为同一段落）
  ▼
agent 分块（≤3–4 段/块）逐段翻译与解析（图表引用高亮：图号加粗 + 解析标注 +
   图表引用索引）→ 逻辑链条 → 方法论/亮点提炼 → analysis.md
  ▼
skill/scripts/md_to_pdf.py（Markdown → PDF，Chrome/Edge 或 PyMuPDF 引擎）

四、目录结构

dsh-paper-reader/
├── lib/
│   ├── index.js          # 插件入口：注册 paper_ingest 工具 + 内置 skill
│   └── fetch-text.js     # URL 抓取核心逻辑（可独立测试）
├── skill/                # 内置 paper-reader skill（skill 内容的唯一数据源）
│   ├── SKILL.md          # 精读工作流指令（frontmatter + 完整流程，含环境自检与用户配置加载）
│   ├── scripts/
│   │   ├── check_env.py        # 环境自检（Python/PyMuPDF/markdown/Node，给出安装指引）
│   │   ├── extract_pdf.py      # PDF → 全文文本（PyMuPDF）
│   │   ├── split_sentences.py  # 全文 → 编号句子（列表项段落自动合并）
│   │   ├── fetch_url.mjs       # URL → 纯文本 / 下载 PDF
│   │   ├── md_to_pdf.py        # analysis.md → PDF（Chrome/Edge 或 PyMuPDF 引擎）
│   │   └── user_config.py      # 用户领域配置管理（path/status/init，绝不覆盖用户数据）
│   ├── templates/              # 用户档案/术语表示例模板（init 的拷贝来源）
│   │   ├── profile.example.md
│   │   └── glossary.example.md
│   └── README.md
├── examples/sample-analysis.md # 示例精读报告（输出格式参考）
├── test/test-standalone.mjs    # 工具逻辑独立测试
├── install.ps1                 # 一键安装脚本
├── package.json / LICENSE / README.md

五、示例输出

examples/sample-analysis.md 是一份完整精读报告（全文逐段翻译与解析 + 纯文本论证流程图 + 方法论提炼/亮点创新），可直接打开查看输出格式与质量。

六、已知限制

环境依赖：PDF 精读需要本机 Python 3 + PyMuPDF（pip install pymupdf）、生成 PDF 报告需要 python-markdown（pip install markdown）。缺失时插件安装脚本、启动日志、skill 工作流与脚本报错都会给出安装提示；也可随时运行 skill/scripts/check_env.py 自检。
付费墙：订阅制期刊（如 Nature 系列）的正文全文无法从公开网页获取，只能解析公开的摘要与图注；有全文 PDF 时直接给本地路径即可完整逐段讲解。
扫描版 PDF：纯图片 PDF 无法直接提取文字，需先 OCR（不内置）。
网页正文提取为启发式实现，导航/广告噪声多的页面由 agent 剔除后使用。

七、发布与更新（npm 分发模式）

本插件是标准 npm 包，并声明了 dsh.bundle——安装/更新/卸载都是一条命令，自动进出 profile 层栈，无需手动改配置。

发布新版本（插件作者）

# 1. 修改 package.json 的 version（semver：修复=patch，新功能=minor，破坏性= major）
# 2. 登录并发布（需 npmjs.com 账号）
npm login
npm publish
# 3. 可选：本地预检发布内容
npm pack --dry-run

用户数据安全：用户档案/术语表/语料存放在用户主目录 ~/.dsh/paper-reader/（见"三、个性化"），不在插件目录内——打包与发布天然不会包含，插件更新也不会覆盖。发布脚本 publish.ps1 内置防泄漏检查：若 tarball 中出现 profile.md / glossary.md / corpus / corrections 等用户数据路径，会中止发布。

用户侧安装（一条命令）

dsh plugin --profile web add dsh-paper-reader
# 重启 dsh web 生效

用户侧更新（像软件更新一样）

dsh plugin --profile web update dsh-paper-reader   # 更新到当前锁定的最新兼容版本
dsh plugin --profile web update dsh-paper-reader --latest   # 强制更新到最新版
# 重启 dsh web 生效

dsh plugin update 会刷新安装副本并重新校验 bundle，新版本的 skill 指令与脚本自动生效。

其他分发方式

| 方式 | 安装命令 | 说明 | |---|---|---| | npm 公共源 | dsh plugin add dsh-paper-reader | 推荐，更新最顺滑 | | 私有 npm 源（Verdaccio/GitHub Packages） | dsh plugin add dsh-paper-reader（配置好 registry 后） | 不想公开时使用 | | Git 仓库 | dsh plugin add git+https://github.com/<你>/dsh-paper-reader.git | 无需 npm 账号 | | 本地离线 | dsh plugin add file:<路径> 或 install.ps1 | 分享 zip 解压后使用 |

版本规范建议

用 semver 管理：1.5.1（修复）、1.6.0（新功能）、2.0.0（破坏性变更）。
每次发布前：更新 version → npm pack --dry-run 检查内容 → npm publish。

八、卸载

dsh plugin --profile web remove dsh-paper-reader
# bundle 模式会自动从 dsh.profile.bundles 移除；重启 dsh web 生效

九、许可

MIT License。工具本身开源；使用时应遵守所分析文献的版权（输出仅用于学习研究）。