🛰️ PaperTrace

📖 项目简介

PaperTrace是一个多 Agent 科研助手——

🤖 自动化下载论文 · 📚 构建论文 + 源代码知识库 · ⏳ 积累得越多越好用

后续你有了自己的研究 idea，一句话从知识库中检索出对应的论文和核心开源代码，配合固定 commit 的代码定位，实验快速复现。

4 个关键词

关键词	含义
🤖 自动化	5 个 Agent 协同完成"检索 → 下载 → 解析 → 入库 → 索引"全流程，零人工
📚 知识库	不只是论文库，还包含对应的源代码索引（每篇论文 → 锁定 commit 的代码仓库）
⏳ 积累效应	知识库是长期资产——每多入一篇，idea 反查越准，越用越值钱
🛠️ 快速复现	每条引用都带 `commit_sha + file:line`，checkout 即可复现，不靠记忆

与同类工具的差异

工具	擅长	不擅长
ChatPDF / 文献 RAG	段落级问答	引用容易合成；不知道代码长啥样
Cursor / Copilot / Code RAG	读代码	没有论文上下文——你问的"attention"是来自哪篇？
Semantic Scholar / Google Scholar	找论文	找到之后还要自己读 + 自己找仓库
PaperTrace	论文 ↔ 代码定位，每条结论带论文出处 + file:line + commit	——

一句话定位

5 个专业 Agent 协同 · 文件式代码索引 · 不杜撰引用 · 不黑盒向量召回 · 全程可追溯

核心能力（30 秒看完）

🔍 3 步找到论文——Semantic Scholar → arXiv → Crossref 三级回退，硬性拒绝绕过付费墙
📄 PDF 解析用 MinerU——正文 + 表格 + 公式（LaTeX 重建），写入本地 Qdrant 论文库
🧠 5 个专业 Agent 协同——1 个研究主管调度 4 个子 Agent：检索 / 下载 / 论文 RAG / 代码定位
🧩 代码检索不用 embedding——原始文件 + LLM 头部摘要就是索引，召回放在 LLM 脑子里（详见为什么不用向量召回）
🔌 实时 WebSocket 推送——每一步推到前端，不轮询、不黑盒
🪶 Claude Code 风格持久化——append-only JSONL 检查点 + 跨进程可恢复 + 跨会话 Markdown 长期记忆

适合谁 / 不适合谁

✅ 适合	❌ 不适合
积累一批 SOTA 论文后提出自己 idea 的研究者——从知识库快速找到"我需要的"论文+代码，快速编码实现（详见核心工作流）	只想要"AI 总结论文摘要"——用 ChatPDF 就行
读论文 / 复现论文 / 跨论文对比实现的研究人员	想要"AI 自动写代码"——这个项目只索引、不生成
研究生 / 博士生 / 论文复现工程师	想要代码的"语义向量召回"——这个项目刻意不做
AI 工程师在调研某方向 SOTA 时

📸 主界面

研究主管正在调度学术检索 → 文献获取 → 知识库 → 科研代码 4 个子 Agent，把一篇 STFDiff 论文从「标题」一路推到「入库状态 + 论文 ↔ 代码定位」，每一步都通过 WebSocket 推到前端。

点击展开：界面里你能看到什么

左侧：历史对话 + 状态条（WebSocket 连接 / 子 Agent 调度计数 / 工具调用 / 异常）
中部：深度研究过程流（每条子 Agent 思考 / 工具调用 / 引用都是一条消息）
右侧：论文信息表（标题 / 作者 / 期刊 / DOI / 机构）+ 研究要点（方法 / 解决的问题 / 效果）+ 知识库入库状态
底部：任务输入框，支持 Enter 发送、Shift+Enter 换行

⚡ 30-second demo

You: "Transformer 论文里的多头注意力是怎么实现的？"

research_supervisor → research_code_agent

正在读 app/data/code_index/<paper_id>/INDEX.md… 模型摘要里提到了缩放点积注意力。打开 src/transformer/attention.py …

MultiHeadAttention.forward() 在第 42 行。Q/K/V 投影各是一个 nn.Linear，缩放点积除以 sqrt(d_k)，然后多头重排为 [batch, h, seq, d_k] 再做矩阵乘。实现对应论文 §3.2.1。

Source: commit a21b1f3 · file tensor2tensor/layers/... · paper Attention Is All You Need (Vaswani et al., 2017).

每一条结论都带 file:line 和固定 commit，不靠"看起来像"。

🤔 它解决什么问题

读论文的痛点不是"读不完"——是读完依然不知道实现细节。

研究人员的真实工作流（以及每一环的痛点）

┌─────────────────────────────────────────────────────────────────────┐
│ ① 找论文    → ② 读论文    → ③ 定位关键实现 → ④ 验证实现            │
│ Google       Abstract+Intro  在论文里找章节     翻 GitHub 仓库      │
│ Scholar      + Method        "本节对应 §X.X"    找"论文版"的实现   │
│ arXiv                                                          │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
              ① ② ③ 都有现成工具，④ 几乎空白

阶段	现有工具	解决了吗
① 找论文	Google Scholar / Semantic Scholar / arXiv	✅ 解决得很成熟
② 读论文	ChatPDF / 文献 RAG / Zotero GPT	⚠️ 段落级，能 cover 摘要但引用容易合成
③ 定位关键实现	自己读 PDF 高亮 + 笔记	⚠️ 慢，章节跳转痛
④ 验证实现	翻 GitHub + 凭记忆 + commit bisect	❌ 几乎纯人工，最痛

PaperTrace 插在 ②③④ 这条链上，尤其是最痛的 ④。

4 个真正的痛点

你以为的痛点	真正的痛点
论文太长读不完	摘要 + introduction 已经能 cover 80% 摘要，真正卡住的是"那 20% 关键实现"
需要读 GitHub 源码对照	论文里写了"我们用 multi-head attention"，仓库里却有一堆 `attention.py`，到底哪个才是论文版本？
拿 ChatPDF / RAG 问论文	引用是合成的——一段"看起来对"的文字，可能来自不相关的段落
用 Copilot / Cursor 读代码	没有论文上下文，它不知道你问的"attention"是来自哪篇论文

PaperTrace 的目标

给你一个"答案 + 论文出处 + 代码 file:line + 固定 commit"的四元组，而不是一段花里胡哨的文字。每一条结论都长这样：

结论：STFDiff 用 DDPM 实现了时空融合，Q/K/V 投影各自独立。 论文出处：STFDiff: Remote Sensing Image Spatiotemporal Fusion with Diffusion Models, He et al., 2024, §3.2, DOI: 10.1016/j.inffus.2024.102505 代码定位：models/stfdiff/diffusion.py:142 · class STFDiff.forward() 固定 commit：a21b1f3 · 仓库：github.com/<org>/STFDiff

✨ 核心特性

🧠 5-Agent 协同架构

不是"一个超长 prompt 把所有事都做了"，而是职责清晰的专业分工：

Agent	角色	触发条件
`research_supervisor`	规划、调度、证据把关	永远在线，是用户对话的唯一入口
`academic_search`	跨源检索 + 交叉验证	用户问"找一篇关于 X 的论文"
`literature_acquisition`	下载 + 解析 PDF	找到目标论文后自动接管
`knowledge_base`	论文库 RAG	用户问"论文里说 X 怎么实现"
`research_code`	论文 ↔ 代码定位	用户问"X 在代码里怎么实现"

主管根据用户意图动态委派，每个子 Agent 自己的 prompt / 工具集 / 输出契约都独立，不互相污染。

📄 PDF 解析用 MinerU（正文 + 表格 + 公式）

跳过图片（图表标题忽略）
公式以 LaTeX 重建（不是 OCR 字符流）
切块按章节 + 段落语义，不按字符数硬切

🗂️ 论文库召回打分透明

final_score = 0.50 · 向量相似度
            + 0.30 · 词典命中度
            + 0.12 · 角色先验（core_method / experiment_config / ...）
            + 0.08 · 论文置信度先验（confirmed / high / medium / low）

向量用 BAAI/bge-large-en-v1.5（英文）
中文查询先自动 CN→EN 再查
角色和置信度在切片入库时手工标注（或 LLM 预标注后人工 review）

🔌 实时 WebSocket 推送

主管的每一步思考 / 工具调用 / 子 Agent 委派都推到 React/AntD 工作台，不轮询、不批量。前端能感知到主管在"等 arXiv 响应"还是"在读代码"。

🪶 持久化

append-only JSONL 检查点：每个 session 独立文件，跨进程可恢复，崩了也不丢
跨会话 Markdown 长期记忆：项目级"我学到了什么"，跨 thread 复用
多 session 隔离：每个 thread_id 独立的虚拟文件根，互不可见

🧱 三阶段上下文压缩

按顺序自动触发：

大结果外置——任何超过 50KB 的工具结果写到 .context_blobs/<id>.bin，LLM 只见 2KB 预览 + 路径
Microcompact——上下文窗口用了 60%，丢掉旧工具结果缓存（保留最近 5 个）
AutoCompact——60% 还不够时，LLM 把最早的 16 条消息压缩成结构化摘要。连续失败 3 次熔断当前任务

🏗️ 架构

📊 全景架构图：从用户前端 → API/WS 层 → DeepAgents 调度层 → 4 子 Agent 工具层 → 数据源与产物层。

5 层架构速览

层	职责	关键模块
用户交互层	对话 / 上传 / 文件列表	React + Vite 前端 · HTTP 命令 · WebSocket 进度
API 与实时通信层	任务调度 + 进度回传	`app/api/server.py` · `ConnectionManager` · `active_tasks[thread_id]`
DeepAgents 调度层	主图编排 + 限流 + 检查点	`main_agent.py` · 限流 middleware · `JsonlCheckpointSaver` · `monitor.py`
子智能体与工具层	4 个 subagent + 主管直连工具	学术检索 / 文献获取 / 知识库 / 科研代码
数据源与产物层	持久化 + 检索后端 + 产物落地	Qdrant · Tavily · Semantic Scholar+arXiv · 论文仓库 · `app/data/{conversations,code_index,memory,output,updated}`

子 Agent 协同

                          research_supervisor (main)
                        规划 + 调度 + 证据把关
                       60 次 LLM 调用 / 16 个子任务上限
                                    │
       ┌────────────────────┬──────┴──────┬──────────────────────┐
       ▼                    ▼             ▼                      ▼
 academic_search    literature_acquisition   knowledge_base    research_code
  • Semantic        • arXiv + OpenAccess     • Qdrant only     • PDF→repo URL→clone
    Scholar         • MinerU 解析            • 角色先验         • tree-sitter 静态分析
  • arXiv           • 下载原始文件           • 论文置信度       • code_manifest.json
  • Crossref                                  • CN→EN 自动翻译  • 自动生成文件式索引

子 Agent	负责什么	主要工具
`academic_search`	论文检索 / 跨源交叉验证	`search_semantic_scholar`, `search_arxiv`, `search_crossref`
`literature_acquisition`	下载 / 解析 PDF	`download_arxiv_paper`, `parse_pdf_with_mineru`
`knowledge_base`	论文库 RAG	`search_paper_kb`, `add_paper_to_kb`
`research_code`	论文 ↔ 代码定位	`read_indexed_code_file`, `find_files_in_paper_repo`
`research_supervisor`	规划 / 委派 / 总结	`task(agent=...)`, `generate_markdown`, `convert_md_to_pdf`

🎬 典型场景

场景 1: 验证一篇新论文的实现细节

你： "找一下 STFDiff 那篇论文，告诉我它怎么把扩散模型用到遥感时空融合里的，并把对应实现指给我看。"

T+0s    你发问
T+2s    academic_search → Semantic Scholar 命中 STFDiff（DOI 10.1016/j.inffus.2024.102505）
T+5s    literature_acquisition → arXiv 下载 PDF
T+18s   literature_acquisition → MinerU 解析完成（正文 + 表格 + 公式）
T+20s   knowledge_base → 切片入库到 Qdrant
T+22s   research_code → 找到 GitHub 仓库 https://github.com/<org>/STFDiff
T+30s   research_code → tree-sitter 静态分析 → code_manifest.json
T+32s   research_code → 生成 app/data/code_index/<paper_id>/INDEX.md
T+45s   research_supervisor → 总结输出：方法 / 解决的问题 / 效果 + 知识库入库状态
T+45s   主管在 WebSocket 推一条"已完成"事件

你看到的输出：

论文信息表（标题 / 作者 / 期刊 / DOI / 机构）
研究要点（方法 / 解决的问题 / 效果）
代码定位（models/stfdiff/diffusion.py:142 · 固定 commit a21b1f3）
知识库入库状态（已入库 / 切片数 / 角色分布）

场景 2: 跨论文对比一个组件

你： "把 Swin Transformer 和 ConvNeXt 里的 LayerNorm 用法对比一下。"

academic_search 拉两篇论文
knowledge_base 各自解析"LayerNorm"相关切片
research_code 在两个仓库里找 norm.py / LayerNorm 的使用方式
主管汇总成对比表

场景 3: 复现一篇论文的实验配置

你： "我要复现 STFDiff，需要什么超参、数据集、训练脚本？"

knowledge_base 搜 §5 (Experiments) 切片
research_code 读 configs/、train.py、data/ 目录
主管整理成可执行清单（commit 锁定，可一键 checkout）

🔄 核心工作流：知识积累 → idea → 代码

这才是 PaperTrace 真正的杀手锏——不是"问单篇论文"，而是长周期的知识积累 + 跨论文检索 + 快速落地自己的 idea。

一句话总结

读 10~20 篇 SOTA → 全部入库 → 提出自己 idea → 跨论文检索实现 → 快速编码

工作流图

┌─────────────────────────────────────────────────────────────────────────┐
│                                                                         │
│  📚 阶段 1: 知识积累（一次性，1~2 周）                                   │
│  ┌──────────────────────────────────────────────────────────┐           │
│  │ 批量拉取 10~20 篇 SOTA 论文                                │           │
│  │   └─ 每篇跑完 5-Agent 流水线                                │           │
│  │   └─ 论文库 + 文件式代码索引自动建立                        │           │
│  │   └─ 每一篇都带：元数据 + §X.X 切片 + commit 锁定的 file:line │           │
│  └──────────────────────────────────────────────────────────┘           │
│                              ↓                                          │
│  💡 阶段 2: 你有了自己的 idea（任意时刻）                                 │
│  ┌──────────────────────────────────────────────────────────┐           │
│  │ "我想做 X 方向，结合 A 论文的 backbone + B 论文的 loss"       │           │
│  │   └─ 不用从零读论文——所有论文已经在知识库里                   │           │
│  └──────────────────────────────────────────────────────────┘           │
│                              ↓                                          │
│  🔍 阶段 3: 跨论文检索（一句话）                                         │
│  ┌──────────────────────────────────────────────────────────┐           │
│  │ "给我找 A 论文的 backbone 实现 + B 论文的 loss 实现            │           │
│  │   + X 方向相关的 3 篇最新工作"                              │           │
│  │                                                            │           │
│  │  PaperTrace 自动：                                          │           │
│  │   1. knowledge_base 命中 A、B、C、D、E 5 篇论文            │           │
│  │   2. 每篇给出 §X.X 章节出处 + file:line + commit             │           │
│  │   3. 主管汇总成 "实现这个 idea 需要 N 个组件" 的清单         │           │
│  └──────────────────────────────────────────────────────────┘           │
│                              ↓                                          │
│  🛠️ 阶段 4: 快速编码落地                                                  │
│  ┌──────────────────────────────────────────────────────────┐           │
│  │ 基于 PaperTrace 给的清单：                                   │           │
│  │   - copy backbone 骨架 → 改 X 方向适配                       │           │
│  │   - copy loss 实现 → 接到自己 pipeline                        │           │
│  │   - 不再是"从零开始读论文"                                   │           │
│  │   - 而是"基于可追溯的清单，copy-paste-改造"                  │           │
│  └──────────────────────────────────────────────────────────┘           │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

和"问单篇论文"工具的对比

维度	ChatPDF / 单论文 RAG	PaperTrace 知识库
使用方式	一次问一篇，用完即弃	持续积累，越用越值钱
检索范围	单论文段落	跨论文——10~20 篇同时检索
检索目标	"段落里有什么"	"我需要的论文和组件在哪"
价值曲线	线性（每问一次消耗一次）	指数（论文越多，问得越准）
适合的工作流	临时问论文	idea 落地前的研究 + 实现

为什么这套工作流能成立

文件式代码索引不漂移——你 6 个月前入的库，今天问还是同一个 commit，引用稳如老狗
跨论文检索有"角色"维度——core_method / experiment_config / entrypoint 等结构化标签，让主管能按"我需要的组件类型"精确召回
主管会规划 + 拆解 + 委派——不是"给我找 A 论文的 backbone"这种字符串匹配，是"分析我的 idea → 拆成 3 个组件 → 分别委派给对应 Agent"
每条结论带 commit + file:line——你写代码时直接 checkout 到那个 commit，不用担心论文仓库改版后实现消失

一个真实场景

你读了 STFDiff、Swin Transformer、ConvNeXt 3 篇论文，全部入库。

你的 idea："在 STFDiff 的扩散过程里，把 Swin 的窗口注意力换成 ConvNeXt 的 depth-wise conv。"

你问 PaperTrace："我需要 STFDiff 的扩散过程 step 实现 + Swin 的 window attention 实现 + ConvNeXt 的 depth-wise conv 实现，给我 file:line 和 commit。"

PaperTrace 在 1 分钟内给你 3 张"定位卡"：

STFDiff diffusion step → models/stfdiff/diffusion.py:217 · commit a21b1f3

Swin window attention → models/swin/window_attention.py:88 · commit 9c2d1e4

ConvNeXt depth-wise conv → models/convnext/blocks.py:46 · commit f81a03b

你用这 3 个锚点，1 周内拼出了自己的 baseline。

🚀 快速开始

1️⃣ 准备

Python 3.12（>=3.12,<3.13，用 uv 管理）
Node 20+（前端用 pnpm 10+）
Docker（跑 Qdrant）
一个 OpenAI-compatible 的 LLM endpoint（自部署 vLLM / OpenRouter / DeepSeek / Qwen 都行）

2️⃣ Windows（一行命令）

git clone <repo> && cd PaperTrace
Copy-Item .env.example .env
# 编辑 .env：设置 OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL
.\start.cmd

启动后打开 **http://localhost:5173**：

服务	端口
Frontend (Vite)	`5173`
Backend (FastAPI)	`8001`
Qdrant Dashboard	`6333`
OpenAPI Docs	`http://localhost:8001/docs`

3️⃣ macOS / Linux

git clone <repo> && cd PaperTrace
cp .env.example .env
# 编辑 .env：设置 OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL
uv sync
docker compose -f docker/docker-compose.yaml up -d qdrant
uv run uvicorn app.api.server:app --host 0.0.0.0 --port 8000
cd frontend && pnpm install && pnpm dev

4️⃣ 最小配置

# 必填
OPENAI_MODEL=qwen-max
OPENAI_API_KEY=replace_me
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1

# 可选
QDRANT_EMBEDDING_DEVICE=cuda   # 有 NVIDIA GPU 时启用
HF_TOKEN=                       # 提高 HF Hub 下载限额
MINERU_MODEL_SOURCE=modelscope  # 模型下载源，可切 huggingface

完整列表见 .env.example（约 20 个键）。

🧠 为什么代码不用向量召回

这是本项目最反直觉的设计决策，必须单独讲清楚。

一句话总结

向量召回擅长"找相似的"，但我们这里要的是"找到这份论文的那份代码"，不是"长得像的所有 attention 实现"。

对比

维度	向量召回（Copilot / Cursor / Code RAG）	文件式索引（PaperTrace）
索引单位	chunk（函数 / 段落）	整个源文件 + 头部 LLM 摘要
召回依据	余弦相似度	LLM 读 INDEX.md 自行决定读哪些文件
精度	容易召回"名字像"的另一篇	召回放在 LLM 脑子里，模型自己知道哪个对
引用粒度	chunk 边界 + embedding drift	固定 commit + file:line
维护成本	改一行代码 → 重新 embed	改一个文件 → 重写一个文件
单次查询成本	1 次向量搜索	2~3 次 LLM 往返
多论文同名冲突	❌ 两篇"attention" 论文召回同一份	✅ 每篇独立 `code_index/<paper_id>/`

实际怎么工作

app/data/code_index/<paper_id>/
  INDEX.md                 # ≤200 字 LLM 摘要 + 文件目录
  <repo_path>/...py       # 原始源码，顶部 LLM 生成的中文描述

用户问"这个模型怎么处理变长序列？"时，LLM 依次做：

读 INDEX.md——看论文模型架构摘要（≤200 字，明确禁止出现性能数字、训练效率、数据集名）
凭摘要匹配自己的知识——挑出 1~3 个候选文件
对每个候选调 read_indexed_code_file——读真正的源文件
带 file:line 引用合成答案——不是 chunk ID，是真正的行号

头部的 LLM 摘要长这样

# ============================================================
# 代码索引元信息 (LLM 自动生成, 请勿手动编辑)
# 文件作用: 多头缩放点积注意力
# 关键符号: MultiHeadAttention, scaled_dot_product_attention
# 角色: core_method
# 论文章节: §3.2.2
# 论文标题: Attention Is All You Need
# 索引时间: 2026-07-31T08:13:27+00:00
# ============================================================

class MultiHeadAttention:
    ...

我们不做什么

不做代码的向量召回——不把 .py 文件切块塞进 Qdrant
不合成代码——只索引论文官方仓库，不让 LLM 编
不基于文件名/函数名做模糊匹配——文件名是噪声（每个仓库命名风格不一样）

Trade-off（诚实声明）

✅ 精度高、可追溯、维护简单
⚠️ 每次查询慢一点（多 2~3 次 LLM 往返）
⚠️ 质量取决于 LLM 的"翻文件能力"——必须用足够聪明的模型（不推荐 7B 以下）

🎯 设计原则

这个项目背后 6 个不可妥协的设计原则：

可追溯 > 简洁——任何结论都带论文出处 + file:line + commit，宁可啰嗦也不让用户去猜
Agent 分工 > 单体智能——把研究流程拆成 4 个专业 Agent，每个有独立 prompt / 工具集 / 输出契约，不混在一个超长 prompt 里
LLM 读 + LLM 决策 > 启发式规则——代码检索放权给 LLM 自己的"翻文件能力"，不写一堆 if "attention" in filename 的硬规则
公开来源 > 灰产数据——只接 arXiv / OpenAccess / 公开仓库，付费墙和未授权数据不碰
本地优先 > 云端优先——所有数据（论文库 / 代码索引 / 会话历史）都落本地，单机可跑，不依赖任何 SaaS
小而美 > 大而全——不试图做"AI 科研助手"，只解决"论文 ↔ 代码定位"这一件事

🧱 技术栈

Backend

Layer	Tech
Runtime	Python 3.12
API	FastAPI 0.135 · Uvicorn
Agent Framework	deepagents 0.5.7 · LangGraph 1.1 · LangChain 1.2
LLM Client	`langchain-openai`（兼容任何 OpenAI-style endpoint）
Vector DB	Qdrant 1.16 (`fastembed` ONNX 推理)
PDF Parsing	MinerU 3.x（pipeline 模式）
Code Analysis	`tree-sitter-language-pack`
Persistence	JSONL append-only checkpointer + Markdown 长期记忆

Frontend

Layer	Tech
Framework	React 19 + TypeScript 5.8
UI Kit	Ant Design 5.26 + Tailwind CSS 4
Build	Vite 7 · pnpm 10
Markdown	`react-markdown` 10 + `remark-gfm`

Infra


Package mgr	uv (backend) · pnpm (frontend)
Container	Docker Compose (Qdrant only)
Tests	`unittest` · 109 个测试，约 5 秒

📁 项目结构

PaperTrace/
├── app/
│   ├── agent/
│   │   ├── main_agent.py              # 研究主管：组装 5 个 Agent
│   │   ├── subagents/                 # 4 个子 Agent
│   │   ├── context_compression.py     # Claude Code 风格压缩
│   │   ├── jsonl_checkpointer.py      # 持久化检查点
│   │   └── project_memory.py          # 跨会话长期记忆
│   ├── api/                           # FastAPI + WebSocket
│   ├── tools/                         # 工具集（论文、PDF、代码、记忆…）
│   ├── prompt/                        # 提示词
│   ├── data/
│   │   ├── code_index/<paper_id>/     # ⭐ 文件式代码索引
│   │   └── ...
│   └── output/<session_id>/           # 每次会话隔离
├── frontend/                          # React 19 + AntD + Vite
├── docs/
│   └── assets/papertrace-ui.png       # README 配图
├── scripts/                           # 调试脚本
├── docker/docker-compose.yaml         # Qdrant
├── start.cmd / start.ps1              # Windows 一键启动
├── pyproject.toml                     # uv 项目定义
└── README.md

🔧 API 速览

GET    /api/health
GET    /api/threads
GET    /api/threads/{id}/history
DELETE /api/threads/{id}/memory

POST   /api/task                   # 启动一个研究任务
POST   /api/task/{id}/cancel       # 取消运行中的任务

POST   /api/upload                 # 上传论文 PDF / MD / DOCX
GET    /api/files
GET    /api/download?path=...

GET    /api/memories               # 跨会话长期记忆
GET    /api/memories/{name}
DELETE /api/memories/{name}

POST   /api/rag/documents          # debug：入库一篇论文
POST   /api/rag/search             # debug：向量检索论文库

WebSocket /ws/{thread_id}          # 实时执行事件

完整 OpenAPI 启动后访问 http://localhost:8001/docs。

🛠️ 开发

uv sync
.\.venv\Scripts\python.exe -m unittest discover -s tests
# 109 个测试，约 5 秒

前端：

cd frontend
pnpm install
pnpm dev

如果这个项目对你读论文有帮助，麻烦点个 ⭐ Star 让我知道有人在用～

Made with 🛰️ by the PaperTrace contributors.

Name		Name	Last commit message	Last commit date
app		app
docker		docker
docs		docs
frontend		frontend
scripts		scripts
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
11-mineru.md		11-mineru.md
README.md		README.md
parsed.md		parsed.md
parsed1.md		parsed1.md
pyproject copy.toml		pyproject copy.toml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
start.cmd		start.cmd
start.ps1		start.ps1
stop-backend.cmd		stop-backend.cmd
stop-backend.ps1		stop-backend.ps1
stop.cmd		stop.cmd
stop.ps1		stop.ps1
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

🛰️ PaperTrace

📖 项目简介

4 个关键词

与同类工具的差异

一句话定位

核心能力（30 秒看完）

适合谁 / 不适合谁

📸 主界面

⚡ 30-second demo

🤔 它解决什么问题

研究人员的真实工作流（以及每一环的痛点）

4 个真正的痛点

PaperTrace 的目标

✨ 核心特性

🧠 5-Agent 协同架构

📄 PDF 解析用 MinerU（正文 + 表格 + 公式）

🗂️ 论文库召回打分透明

🔌 实时 WebSocket 推送

🪶 持久化

🧱 三阶段上下文压缩

🏗️ 架构

5 层架构速览

子 Agent 协同

🎬 典型场景

场景 1: 验证一篇新论文的实现细节

场景 2: 跨论文对比一个组件

场景 3: 复现一篇论文的实验配置

🔄 核心工作流：知识积累 → idea → 代码

一句话总结

工作流图

和"问单篇论文"工具的对比

为什么这套工作流能成立

一个真实场景

🚀 快速开始

1️⃣ 准备

2️⃣ Windows（一行命令）

3️⃣ macOS / Linux

4️⃣ 最小配置

🧠 为什么代码不用向量召回

一句话总结

对比

实际怎么工作

头部的 LLM 摘要长这样

我们不做什么

Trade-off（诚实声明）

🎯 设计原则

🧱 技术栈

📁 项目结构

🔧 API 速览

🛠️ 开发

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages