dsh-paper-tutor

面向中文读者的英文论文精读 Agent 预设插件，为 DeepSeek Harness 提供：

• paper-tutor Agent 预设（论文精读）：中文讲解型人格 + 精读工作流提示词 + 随附 paper-reading skill。启动时自动安装到 $DSH_HOME/.agent-presets/paper-tutor/，在会话预设选择器中直接可选。
• 4 个论文工具（仅对选用该预设的会话生效）：

  工具	作用
  paper_scan	盘点工作区论文资产：PDF / LaTeX / 图表图片 / 论文代码 / 数据
  pdf_extract	纯 JS 提取 PDF 全文（按页、保留版式与双栏顺序）与内嵌图表（自动匹配 caption）
  tex_structure	解析 LaTeX 结构：章节大纲、图表浮动体、公式、定理、引用键、\input 包含关系
  paper_figure	从 PDF 提取图表并（可选）调用视觉端点解读图表内容

面向的用户：以中文为母语、可能对英文论文/术语/数学推导感到吃力的学习者。预设默认按"零基础也能听懂"讲解，支持速览/精读/溯源（对照代码）/批判四层深度，输出论文卡片、术语表与论文↔代码对照表。

特性

• 零 npm 运行时依赖：PDF 文本/图片提取为纯 JS 实现（node 内置 zlib），跨平台开箱即用；检测到 pdftotext（poppler-utils）时自动使用它加速并提升版式质量（config.pdftotext: "auto"，可关）。
• 图表提取：从 PDF 页面提取内嵌图片（Flate/DCT/Indexed/CMYK/1-16bit），写为 PNG/JPEG 到 .paper-figures/，并启发式匹配 "Fig. 1: …" 标题。
• 图表解读：可选 OpenAI 兼容视觉端点（与 dsh-tool-vision 同款配置约定），未配置时优雅降级为返回图片路径供多模态模型/用户查看。
• 幂等安装：预设安装器只在版本变化时升级（旧版自动备份为 .bak-<ts>），从不覆盖未标记的用户自建目录。

一键安装

方式 A：远程安装（推荐，无需克隆仓库）

curl -fsSL https://raw.githubusercontent.com/ASAKAFENG/dsh-paper-tutor/main/scripts/install.sh | bash -s -- --github

脚本会自动：下载最新 Release → 解压装配进 profile（$DSH_HOME/profiles/<profile>/node_modules/ + dsh.profile.bundles 注册，默认 profile 为 web，可用 --profile <name> 指定）→ 安装预设到 $DSH_HOME/.agent-presets/paper-tutor/。幂等，重复执行安全。

Windows（PowerShell 5.1+/7）：

irm https://raw.githubusercontent.com/ASAKAFENG/dsh-paper-tutor/main/scripts/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File scripts/install.ps1 -Github

方式 B：本地安装（克隆仓库后）

git clone https://github.com/ASAKAFENG/dsh-paper-tutor.git
bash dsh-paper-tutor/scripts/install.sh            # 本地装配（link: 指向克隆目录，便于开发）

方式 C：作为 profile bundle（手动）

# 在插件仓库目录构建
bash scripts/build.sh

# 装配进 profile（web profile 示例）——加入 dependencies link: + bundles 列表，
# 建 node_modules junction
# （在 DSH 内使用 dev_install_package 注入器，或手动编辑 profile package.json：
#   "dependencies": { "@dsh-external/dsh-paper-tutor": "link:<本目录>" },
#   "dsh": { "profile": { "bundles": [ ..., "@dsh-external/dsh-paper-tutor" ] } }
#   然后重启 dsh）

三种方式任选其一，然后重启 DSH：bundle 层装配后，安装器把 paper-tutor 预设写入 $DSH_HOME/.agent-presets/，新开会话即可在预设选择器中选择「论文精读 · Paper Tutor」。

卸载：从 profile 的 package.json 移除 dependencies/dsh.profile.bundles 条目，删除 node_modules/@dsh-external/dsh-paper-tutor 与 $DSH_HOME/.agent-presets/paper-tutor。

发布为 marketplace 插件

npm pack 产出 tgz 后按 DSH marketplace 规范发布；包内 cordis.patch.yml 会在装配时自动注册安装器（安装器同时把预设装入 $DSH_HOME/.agent-presets/）。

配置

插件行（cordis.patch.yml 或预设 agent.cordis.yml 的 config）：

视觉端点也可用环境变量配置：PAPER_TUTOR_VISION_BASE_URL、PAPER_TUTOR_VISION_API_KEY、PAPER_TUTOR_VISION_MODEL。未配置时 paper_figure 返回图片路径并给出引导，不报错。

使用示例

1. 开一个「论文精读 · Paper Tutor」会话，工作区放好论文 PDF（或 LaTeX 源码 + 代码）。
2. 说："精读这篇论文" 或 "帮我看一下 xxx.pdf，讲清楚方法部分"。
3. Agent 会：paper_scan 盘点 → pdf_extract 建卡片 → 逐节讲解 → paper_figure 读图 → 对照工作区代码 → 输出精读笔记。

建议把论文配套代码放在同一工作区（或子目录），溯源讲解效果最佳。

插件市场

本插件已关联 DSH 插件市场（索引：bradeGithub/DSH-Plugins-Marketplace，按 topic:dsh-plugin 聚合、每 2 小时自动刷新）：

• 仓库 topics：dsh-plugin deepseek-harness dsh paper-reading pdf latex academic agent-preset llm
• 市场页搜索 paper-tutor（或 dsh-paper-tutor）即可找到；市场按 cordis-plugin 管线安装（根目录刻意不放 install 脚本以避免误判为脚本型；包声明 dsh.plugin + bundle.patch + scripts.build，市场会克隆仓库 → 检测到未构建的 lib/ 自动执行 npm run build → 注册 bundle → 重启生效），预设由插件运行时自动安装到 $DSH_HOME/.agent-presets/，卸载可回滚
• 市场安装同样会触发包内安装器：$DSH_HOME/.agent-presets/paper-tutor/ 自动就位

若刚发布/刚加 topic 暂时搜不到，等市场索引刷新（≤2 小时）或先用上方一键安装命令。

环境依赖与配套插件

系统依赖（本机）

poppler-utils 安装（一行命令）：

# Debian / Ubuntu
sudo apt install -y poppler-utils
# RHEL / Fedora
sudo dnf install -y poppler-utils
# macOS（Homebrew）
brew install poppler
# Windows（Scoop / Chocolatey）
scoop install poppler
choco install poppler

验证：pdftotext -v。不装也不影响使用——pdf_extract 自动检测并降级为内置引擎（config.pdftotext 可强制 on/off）。

配套 DSH 插件（可选，推荐）

以上均为可选。不装任何配套插件，paper-tutor 也能独立工作（PDF/LaTeX/图表提取全内置；图表解读降级为返回图片路径）。

视觉端点（可选）配置对照

paper_figure 与 dsh-tool-vision 共用同一套约定，任选一种配置方式：

常见免费/低门槛端点：DashScope（阿里云百炼，qwen-vl 系列）、智谱 GLM-4V、Ollama 本地（llava/qwen2.5vl 等）。

开发

bash scripts/build.sh   # 装配 lib/ + 链接运行时依赖（Windows 用 Git Bash/WSL）
node test/pdf-smoke.mjs # PDF 引擎冒烟测试（生成合成 PDF 验证提取）

许可证

MIT