Skip to content
BranchesTags

Repository files navigation

PaperAgent：AI 论文辅助系统

这是一个面向 Agent 开发求职的实战项目。我们会从一个最小可运行 Agent 开始，逐步加入论文检索、引用核验、多 Agent 协作、记忆、流式输出、评测和 Web 界面。

v0.1.0 当前能力

  • 在本地 Web 工作台选择示例论文或上传 PDF；刷新后可从默认项目勾选 1–8 篇历史文档。
  • 对文本型 PDF 直接建立索引；对扫描型或混合型 PDF 生成逐页 OCR 候选，人工检查或编辑后再建立索引。
  • 使用 BM25、Vector、Hybrid 或 Rerank 检索并展示原文证据、文件名和页码。
  • 配置 DEEPSEEK_API_KEY 后生成带引用且经过引用范围校验的回答。
  • 对显式选中的文档版本执行公平的 document_round_robin_v1 检索；回答使用 D1/D2 页级引用， 并映射回精确文档、版本和 chunk，避免同名文件串证。
  • 上传文件只在请求期间临时保存，索引成功或失败后都会删除。
  • 默认本地 SQLite 数据库与 output/data/blobs/ 会持久化本地 PDF、逐页文本和 chunk 正文； 这是单用户本地存储，不提供多实例、权限或云端数据隔离。
  • React/TypeScript 工作台位于 /app，提供历史文档分页、显式 D1/D2 范围、证据检查器、quick/reviewed 回答和 OCR 人工复核；旧 / 页面、/static/ux_state.js、API 和 CLI 继续保留。

业务数据库使用 Alembic 前向迁移，首次启动空数据库会自动执行：

uv run alembic upgrade head

可用 PAPER_AGENT_DATABASE（路径）、PAPER_AGENT_DATABASE_URL（SQLite URL）和 PAPER_AGENT_DATA_ROOT 配置路径。LangGraph 检查点使用独立的 SQLite 文件，不能与业务 数据库混用。

多论文路由保持旧单篇 API 不变，并新增：

  • GET /api/projects/default/documents
  • POST /api/projects/default/search
  • POST /api/projects/default/answer

请求必须显式提交 1–8 个 document_id + index_version_id，不会把空范围解释为“全部论文”。 离线评测和浏览器验收均使用本地 BM25 fixture 与固定模型：

uv run python -m scripts.multi001_evaluate
uv run python -m scripts.multi001_browser_acceptance

完整合同、版本和引用边界见 docs/tasks/MULTI-001-LITE.md。

最终用户流程

  1. 用户建立一个论文项目并上传 PDF。
  2. 系统解析论文，建立可检索的知识库。
  3. 用户提出研究问题，系统给出带来源的回答。
  4. 用户生成大纲，写作 Agent 根据证据起草章节。
  5. 审稿 Agent 检查论证、引用和格式，用户确认后再修改。
  6. 系统保存每次运行轨迹、引用依据和评测结果。

我们真正要证明的能力

  • 会设计 Agent 的状态、工具和执行循环，而不只是调用聊天 API。
  • 会做有出处的 RAG，并能检查回答是否真的被原文支持。
  • 会用工作流约束多 Agent 协作，处理失败、重试和人工确认。
  • 会通过测试集量化检索质量、引用正确率、延迟和成本。
  • 会把后端、数据库和前端组合成一个可演示的完整产品。

开发原则

  • 每次只增加一个概念，并先做出能运行、能测试的小版本。
  • 不伪造效果数字；所有简历指标都必须来自项目内的评测结果。
  • API 密钥只放本机 .env，绝不提交到 Git。
  • Redis、多 Agent、复杂记忆等能力等到真正需要时再加入。

详细路线见 docs/ROADMAP.md。

运行第一个 Agent

uv sync
uv run python -m paper_agent

输入：

计算 (12 + 8) * 3

运行测试与代码检查：

uv run pytest
uv run ruff check .
uv run ruff format --check .

当前测试基线：221 项 Python 测试、19 项旧 Node 状态测试、17 项 React/Vitest 测试通过。

Web 工作台开发与离线浏览器验收：

npm --prefix web ci
npm --prefix web run generate:api:check
npm --prefix web run typecheck
npm --prefix web run test
npm --prefix web run build
uv run python -m scripts.web001_browser_acceptance

验收脚本使用临时 SQLite/data root 和固定本地 fixture，不调用真实 DeepSeek、云 OCR 或网络模型。 完整范围与限制见 docs/tasks/WEB-001-LITE.md 和 docs/evidence/WEB-001-LITE-ACCEPTANCE.md。

第 1 课的逐步解释见 docs/LESSON_01_MINIMAL_AGENT.md。

第 2 课的 DeepSeek 模型适配见 docs/LESSON_02_REAL_LLM.md。

第 2 课真实调用的脱敏证据见 docs/evidence/LESSON_02_DEEPSEEK_LIVE_RUN.md。

第 3 课的 PDF 检索基线见 docs/LESSON_03_PDF_RETRIEVAL.md。

第 3 课的测试、运行和视觉验收证据见 docs/evidence/LESSON_03_RETRIEVAL_RUN.md。

完整的单篇论文问答：

uv run python -m paper_agent.ask \
  output/pdf/paperagent_rag_sample.pdf \
  "这篇文档建议如何评估检索质量？"

第 4 课的页级 Recall@K 评测见 docs/LESSON_04_RETRIEVAL_EVALUATION.md。

uv run python -m paper_agent.evaluate \
  output/pdf/paperagent_rag_sample.pdf \
  evals/retrieval_questions.json

第 5 课用困难同义改写题暴露 BM25 的弱点，见 docs/LESSON_05_BM25_FAILURE_CASES.md。

uv run python -m paper_agent.evaluate \
  output/pdf/paperagent_rag_sample.pdf \
  evals/retrieval_hard_questions.json

第 6 课加入免费的本地向量检索，并与 BM25 使用同一题集对比，见 docs/LESSON_06_VECTOR_RETRIEVAL.md。

uv run python -m paper_agent.evaluate \
  output/pdf/paperagent_rag_sample.pdf \
  evals/retrieval_hard_questions.json \
  --retriever vector

第 7 课使用 RRF 融合 BM25 与向量排名，并保留未超过纯向量检索的真实负面结果，见 docs/LESSON_07_HYBRID_RETRIEVAL.md。

uv run python -m paper_agent.evaluate \
  output/pdf/paperagent_rag_sample.pdf \
  evals/retrieval_hard_questions.json \
  --retriever hybrid

第 8 课在 RRF 候选上使用本地交叉编码器精排，见 docs/LESSON_08_CROSS_ENCODER_RERANKING.md。

uv run python -m paper_agent.evaluate \
  output/pdf/paperagent_rag_sample.pdf \
  evals/retrieval_hard_questions.json \
  --retriever rerank

第 9 课比较四种策略的 Recall 与预热后查询延迟，见 docs/LESSON_09_QUALITY_LATENCY_BENCHMARK.md。

uv run python -m paper_agent.benchmark \
  output/pdf/paperagent_rag_sample.pdf \
  evals/retrieval_hard_questions.json

第 10 课建立无法回答问题与相似度阈值拒答基线，见 docs/LESSON_10_UNANSWERABLE_ABSTENTION.md。

uv run python -m paper_agent.abstention \
  output/pdf/paperagent_rag_sample.pdf \
  evals/answerability_questions.json

第 11 课区分引用目标有效率、引用精确率和事实忠实度，见 docs/LESSON_11_CITATION_FAITHFULNESS.md。

uv run python -m paper_agent.answer_eval \
  output/pdf/paperagent_rag_sample.pdf \
  evals/answer_quality_claims.json

第 12 课使用真实 ReAct 论文检查 PDF 文本层和视觉版式，见 docs/LESSON_12_REAL_PDF_QUALITY_GATE.md。

uv run python -m paper_agent.pdf_inspect \
  output/pdf/react_2210.03629v3.pdf

第 13 课把文本质量门接入知识库，并建立显式排除风险页的降级索引，见 docs/LESSON_13_SAFE_PDF_INDEX.md。

uv run python -m paper_agent.safe_index \
  output/pdf/react_2210.03629v3.pdf

第 14 课使用本地 Tesseract、SHA-256 和人工锚点恢复风险页，见 docs/LESSON_14_OCR_RECOVERY.md。

uv run python -m paper_agent.ocr_recover \
  output/pdf/react_2210.03629v3.pdf \
  evals/react_ocr_anchors.json \
  output/ocr/react_2210.03629v3_ocr.json

第 15 课用固定人工标注题集对比风险页隔离前后检索能力，见 docs/LESSON_15_OCR_RETRIEVAL_EVALUATION.md。

uv run python -m paper_agent.ocr_retrieval_eval \
  output/pdf/react_2210.03629v3.pdf \
  output/ocr/react_2210.03629v3_ocr.json \
  evals/react_ocr_retrieval_questions.json

第 16 课建立覆盖原生文本页和 OCR 页的真实论文 20 题 BM25 基线，见 docs/LESSON_16_REAL_PAPER_BM25_BASELINE.md。

uv run python -m paper_agent.evaluate \
  output/pdf/react_2210.03629v3.pdf \
  evals/react_full_retrieval_questions.json \
  --ocr-overrides output/ocr/react_2210.03629v3_ocr.json

第 17 课在同一份 20 题考卷上测试本地 BGE 向量检索，并记录低于 BM25 但存在互补命中的负面结果，见 docs/LESSON_17_REAL_PAPER_VECTOR_BASELINE.md。

uv run python -m paper_agent.evaluate \
  output/pdf/react_2210.03629v3.pdf \
  evals/react_full_retrieval_questions.json \
  --ocr-overrides output/ocr/react_2210.03629v3_ocr.json \
  --retriever vector

第 18 课使用默认 RRF 融合 BM25 与向量排名，并记录 Top-3 与 BM25 持平的结果，见 docs/LESSON_18_REAL_PAPER_HYBRID_RETRIEVAL.md。

uv run python -m paper_agent.evaluate \
  output/pdf/react_2210.03629v3.pdf \
  evals/react_full_retrieval_questions.json \
  --ocr-overrides output/ocr/react_2210.03629v3_ocr.json \
  --retriever hybrid

第 19 课用本地交叉编码器精排 Hybrid 的 20 个候选，在固定题集上达到 90% Recall@1 和 100% Recall@3，见 docs/LESSON_19_REAL_PAPER_RERANKING.md。

uv run python -m paper_agent.evaluate \
  output/pdf/react_2210.03629v3.pdf \
  evals/react_full_retrieval_questions.json \
  --ocr-overrides output/ocr/react_2210.03629v3_ocr.json \
  --retriever rerank

第 20 课在真实 20 题上比较四种检索流程的 Recall、中位热查询延迟和 P95，见 docs/LESSON_20_REAL_PAPER_QUALITY_LATENCY.md。

uv run python -m paper_agent.benchmark \
  output/pdf/react_2210.03629v3.pdf \
  evals/react_full_retrieval_questions.json \
  --ocr-overrides output/ocr/react_2210.03629v3_ocr.json \
  --repeat 10

第 21 课把 OCR、Rerank、DeepSeek 和“引用必须来自本次检索证据”的校验串成真实论文问答，见 docs/LESSON_21_REAL_PAPER_GROUNDED_QA.md。

uv run python -m paper_agent.ask \
  output/pdf/react_2210.03629v3.pdf \
  "Figure 5 中，人类修改了哪两个 Act 的 thought？修改后为什么能够成功？" \
  --ocr-overrides output/ocr/react_2210.03629v3_ocr.json \
  --retriever rerank

第 22 课冻结一次真实 DeepSeek 回答，用人工支持页评测 6 条主张的引用精确率和事实忠实度，见 docs/LESSON_22_REAL_ANSWER_FAITHFULNESS.md。

uv run python -m paper_agent.answer_eval \
  output/pdf/react_2210.03629v3.pdf \
  evals/react_live_answer_claims.json \
  --ocr-overrides output/ocr/react_2210.03629v3_ocr.json

第 23 课批量运行 5 道代表性问题，并保存包含检索证据、回答、引用、模型版本和失败状态的不可覆盖快照，见 docs/LESSON_23_BATCH_ANSWER_SNAPSHOT.md。

uv run python -m paper_agent.answer_snapshot \
  output/pdf/react_2210.03629v3.pdf \
  evals/react_answer_snapshot_questions.json \
  output/evals/react_answer_snapshot_v1.json \
  --ocr-overrides output/ocr/react_2210.03629v3_ocr.json

MVP 本地 Web 工作台

把现有检索、OCR、Rerank、DeepSeek 问答与引用校验能力打包成一个本地可运行的单篇论文问答入口。

uv run python -m paper_agent.mvp

默认监听 http://127.0.0.1:8000，React 工作台入口为 /app/；旧原生页面仍在 /。端口被占用时可用 --port 指定：

uv run python -m paper_agent.mvp --port 9000

功能：

  • 选择仓库内示例 PDF 或上传本地 PDF 建立索引。
  • 扫描型或混合型 PDF 会先展示页面图片和 OCR 文本；确认前不会进入索引。
  • 选择检索算法（默认 bm25；vector/hybrid/rerank 会加载本地模型）。
  • 离线检索证据，不依赖 API key。中文问题对英文论文的查询改写属于配置 DeepSeek 后的端到端问答能力，不在离线检索范围内。
  • 配置 DEEPSEEK_API_KEY 后生成带 [文件名, p.页码] 引用、经过 validate_citations 校验的回答。

旧页面人工验收路径：

  1. 打开 http://127.0.0.1:8000。
  2. 选择 paperagent_rag_sample.pdf 并建立索引。
  3. 输入英文问题 How should retrieval quality be evaluated?，点击「检索证据」，确认至少 1 条证据。
  4. 未配置 DeepSeek 时点击「生成回答」，确认页面提示缺少 API key。
  5. 配置 DeepSeek 后将问题改为中文 这篇文档建议如何评估检索质量？，点击「生成回答」，确认回答带引用且引用校验通过。

ReAct 示例 react_2210.03629v3.pdf 存在文本质量风险页，选择后页面会自动填入 output/ocr/react_2210.03629v3_ocr.json 作为 OCR 覆盖文件。

已验证基线：221 项 Python 测试、19 项旧 Node 状态测试和 17 项 React/Vitest 测试；WEB-001 Lite 真实本地浏览器验收通过，覆盖 /app 资源、历史同名文档、sample、文本上传、OCR 编辑确认、D1/D2 检索、quick/reviewed/trace、失败恢复、XSS、键盘和 1280/390 布局。

已知限制：工作台仍是默认项目单用户本地功能；索引、OCR 和回答为同步请求，不提供后台任务、权限、项目 CRUD、回答历史或云部署；离线 fixture 不证明真实模型/OCR 质量；回答仍需要 DeepSeek API key。

详细规格见 docs/MVP_REQUIREMENTS.md。

About

AI-assisted research paper workbench with FastAPI, LangGraph, RAG, OCR, React and TypeScript

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages