Thomas-Novato/deepseek-harness-paper-assistant

DeepSeek Harness 论文助手

一个基于 Python 的论文阅读、理解、总结、翻译插件，面向 DeepSeek Harness 设计，并融合了 nature-skills 的论文阅读与学术写作规范。

当前版本：v0.2.0
状态：evidence-grounded / checkpoint-resume / test-inventory ready

功能

- 读取：独立 reader pipeline，输出带源锚点的中英文对照 paper.md
- 理解：生成论文核心结构、研究问题、方法、结论、局限
- 总结：按标准/极简/创造三种模式输出结构化总结
- 翻译：输出中文翻译 translation.md（与 reader 语义分离）
- 问答：paper-assistant ask paper.pdf "问题"，答案必须带 evidence
- 可靠性：429/5xx/超时重试、指数退避、truncated 检测、chunk 级 checkpoint/resume
- 引用校验：reader 输出后自动校验锚点，生成 verification_report.json
- 模式：
- 标准模式（默认，准确优先）
- 极简模式（短摘要，快速阅读）
- 创造模式（发散解读，适合灵感扩展）

快速开始

环境要求

- Python 3.10+
- 安装依赖

pip install -r requirements.txt

使用方式

处理 PDF：默认生成 summary + understanding + reader
python -m paper_assistant run paper.pdf --mode standard

只看总结
python -m paper_assistant run paper.pdf --mode minimal --task summary

完整中英文对照阅读稿
python -m paper_assistant run paper.pdf --mode standard --task reader

仅翻译
python -m paper_assistant run paper.pdf --mode standard --task translate

基于证据问答
python -m paper_assistant ask paper.pdf "作者为什么使用 SST 模型？"

DeepSeek API 配置

插件默认从环境变量读取 DeepSeek API 配置：

export DEEPSEEK_API_KEY="sk-..."
export DEEPSEEK_BASE_URL="https://api.deepseek.com"
export DEEPSEEK_MODEL="deepseek-v4-pro"

支持切换：

deepseek-v4-pro
deepseek-v4-flash

也可以在 config.yaml 中覆盖。

输出目录

运行后会在当前目录生成 output/：

output/
├── paper.md               # reader：中英文对照 + 源锚点
├── translation.md         # translate：纯中文翻译
├── summary.md             # 结构化总结
├── understanding.md       # 理解笔记
├── source_map.json        # 原文块与锚点映射
├── verification_report.json # reader 引用校验报告
├── translation_notes.md   # 术语/不确定/缺失说明
└── assets/                # 从 PDF 中提取的图表（如有）

同时会生成 .cache// 用于 checkpoint/resume。

与 nature-skills 的融合

本项目实现了 nature-reader 的核心约束：

- 默认输出 原文 + 中文 段落级对照，而不是只给摘要
- 保持章节顺序、引用标记、术语一致性
- 建立 source_map.json 稳定锚点
- 图表尽量放在首次实质性引用处
- 记录不确定/缺失内容，不虚构论文信息

上传到 GitHub

本项目默认目标仓库为：

https://github.com/Thomas-Novato/deepseek-harness-paper-assistant

在项目根目录执行：

powershell -ExecutionPolicy Bypass -File scripts/upload_to_github.ps1

脚本会自动：

1. git init
2. 用 GitHub CLI 创建公开仓库（已存在则跳过）
3. 关联远程仓库
4. 提交并推送到 main

注意：请先确保已安装并登录 GitHub CLI：

winget install GitHub.cli
gh auth login

开发计划

- [x] 项目骨架、CLI、三种模式
- [x] DeepSeek API 调用（retry / backoff / truncation detection）
- [x] PDF 文本提取 / 独立 reader 中英文对照阅读稿
- [x] Chunk 级 checkpoint/resume
- [x] Evidence schema + reader 引用校验
- [x] BM25 + RRF retrieval 与 ask 命令
- [x] 测试套件（待真实终端运行）
- [x] GitHub 上传脚本
- [ ] DeepSeek Harness 官方插件描述文件正式接入验证
- [ ] 支持扫描版 PDF（OCR）
- [ ] 支持 HTML / arXiv / DOI 输入
- [ ] 生成 reader.html 预览
- [ ] 多论文 library / compare / literature review
- [ ] 自动安装到插件市场

License

MIT