Paper Atlas 把一个 PDF 文件夹变成科研工作空间的工具，检索 arXiv 和期刊论文，以科研课题为单位组织文献，用结构化 AI 分析辅助阅读，并在左右分栏的 PDF 阅读器中把结论、证据、页码和原文对应起来。
所有数据都保存在本机。论文、笔记、批注、分析结果和设置都在本地 data/ 目录，不需要账号、云同步或外部数据库。
开源地址在文章末尾。
为什么是 Paper Atlas
多数文献工具停在"下载 + 预览"。真正的研究工作还需要回答：
- 这篇论文属于哪个课题？
- 它在回答什么科学问题？
- 哪一句原文支撑了这个结论？
- 我读过什么、标记了什么、写了什么？
- 能否在不上传整个文献库的情况下向 AI 提问？
Paper Atlas 以科研课题 组织工作流，把 PDF 与 AI 分析并排展示 ，并保存带页码和原文引用的证据。
文献发现
- arXiv 检索：关键词或 AI 生成检索式。
- 期刊检索：Elsevier 优先，OpenAlex / Crossref 回退。
- 相关性筛选、处理队列、持久化任务状态。
- PDF 下载：断点续传、镜像回退、大小校验、可选 Playwright 兜底。
- 需要验证码/登录/订阅的出版商页面：打开真实 Firefox 由用户人工完成，不绕过访问控制。
- 本地论文库：搜索、筛选、收藏、分析历史。
科研课题工作空间
- 多个课题，各自拥有简介、研究背景、研究目标、研究方向和关键词。
- 课题文献集合：重点/待读标记、阅读状态、个人评价、评分、标签。
- 研究问题：问题描述、研究假设、关键词、关联文献、状态。
- 研究笔记、进展日志、里程碑、综述/报告。
- 课题维度的相关性与文献筛选（年份、标签、角色、阅读状态、是否已分析）。
- 同一篇论文可关联多个课题，但底层论文与 PDF 只存一份。
AI 辅助 PDF 阅读器
- 左右分栏：左侧 PDF，右侧结构化分析。
- PDF.js 渲染、文本选择、缩放、适宽/整页、单页/连续模式。
- PDF 目录导航、页面搜索。
- 12 个分析模块：基本信息、研究背景、研究目标、科学问题、研究方法、数据来源、技术路线、实验设计、主要结果、创新点、研究局限、未来研究方向。
- 证据包含 PDF 物理页码、章节、引文和校验状态。
- 点击结论/证据跳转到对应页；文本层可匹配时高亮原文。
- 选中文本：解释、总结、翻译、解释公式/方法、说明与研究目标的关系。
- 高亮、下划线、批注、书签、重点证据。
- 阅读笔记、选中文本保存为课题笔记、阅读状态恢复。
- AI 只提供建议，不会覆盖用户手动编辑；只有用户确认后才保存。
本地优先工程
- 单 Python 进程、单个 SQLite 数据库，无外部服务依赖。
- DeepSeek、Ollama 或任意 OpenAI 兼容端点。
- 本地 PDF.js 资源，阅读器可离线使用。
- 增量 schema 迁移，配套备份与数据校验脚本。
- Windows / Ubuntu / macOS 启动器与打包脚本。
- 干净的源码分发：不包含数据、PDF、密钥、虚拟环境或测试夹具。
技术栈
| 层 | 技术 |
|---|---|
| Web 服务 | FastAPI + Starlette + Uvicorn |
| 模板 | Jinja2，单页视图 |
| 前端 | 原生 JavaScript/CSS，无框架、无 CDN |
| PDF 渲染 | PDF.js 4.10.38（本地 vendored） |
| PDF 解析 | PyMuPDF |
| AI | OpenAI 兼容 SDK（DeepSeek / Ollama / 自定义端点） |
| 存储 | SQLite（WAL）+ 本地文件 |
| 打包 | PyInstaller（可选） |
架构一览
浏览器 UI 原生 JS + PDF.js
FastAPI 本地服务
SQLite data/review.db
本地 PDF data/
DeepSeek / Ollama / OpenAI 兼容
PDF.js 本地 vendored，离线可用
快速开始
Windows
start.batLinux / macOS
chmod +x start.sh
./start.sh启动器会创建私有 .venv、安装依赖并启动本地服务。首次启动还会创建 data/ 和固定访问码。
打开：
http://127.0.0.1:8765输入启动器控制台显示的访问码。之后可在 设置 → 网络 中修改。
只检查环境，不启动
python launcher.py --check环境要求
- 源码运行需要 Python 3.10+。
- Windows 10/11、Ubuntu 20.04+、macOS。
- 不需要管理员权限。
- 只有在检索/下载和远程 AI API 时需要联网；已有本地文件可离线阅读。
目录结构
Paper_Atlas1.5/
├── README.md / README.zh-CN.md
├── app.py # FastAPI 组合根（arXiv + 系统路由）
├── auth.py # 访问码、会话 Cookie、登录页
├── config.py # 兼容 shim -> atlas.core.config
├── launcher.py # uv/venv 自举、启动、诊断、快捷方式
├── paper_atlas.py # 冻结构建入口
├── build.py / build.sh / build.bat
├── start.sh / start.bat
├── install.sh
├── requirements.txt
├── requirements-optional.txt
├── .env.example
├── .github/workflows/build.yml
├── packaging/paper_atlas.spec
├── atlas/
│ ├── core/ # 配置、路径、日志、异常、ID
│ ├── api/ # 课题/Dashboard/阅读器/助手路由
│ ├── db/ # schema、迁移、repository
│ ├── integrations/ # LLM 客户端
│ ├── jobs/ # 持久化下载任务
│ └── services/ # 课题助手、阅读器服务
├── review/ # 期刊获取与分析管线
├── templates/index.html
├── static/
│ ├── app.js / review.js / local.js
│ ├── dashboard.js / projects.js / project-workspace.js
│ ├── reader.js
│ ├── style.css
│ └── vendor/pdfjs/ # PDF.js + cmaps + fonts
├── scripts/ # 备份、校验、迁移
└── docs/data/ 在运行时创建。
配置
推荐在网页中配置：
- AI：DeepSeek、Ollama 或 OpenAI 兼容的 Base URL/模型/Key。
- 网络：监听地址、端口、访问码。
- 下载：大小上限、并发、断点续传、浏览器兜底。
- 界面：语言、主题。
- 期刊流程：研究目标、期刊、分析提示词、Elsevier/Firefox 设置。
设置保存在 data/config.json。环境变量优先于文件，示例见 .env.example。
不要提交 data/config.json 或 .env。 它们可能包含 API Key 和访问码；本仓库不包含这些文件。
数据与隐私
用户数据默认都在 data/：
data/
├── config.json # 设置（可能含 API Key）
├── library.json # arXiv 下载索引
├── pdfs/ # arXiv PDF
├── jobs.db # 持久化下载任务
├── logs/ # 轮转日志
└── review/
├── review.db # 论文、课题、分析、笔记、批注
├── pdfs/ # 期刊 PDF
├── analysis/ # 分析 JSON 副本
├── downloads/ # 人工下载收件箱
└── firefox-profile/ # 人工接管 Firefox 配置（敏感）- 备份：
python scripts/backup_data.py - 校验：
python scripts/verify_data.py - 迁移：
python scripts/migrate_schema.py - 不要把
firefox-profile/复制到共享位置。 - 应用不会上传文献库；AI 请求只发送到你配置的服务商。
环境验证
安装后建议手动验证：
python launcher.py --check
./start.sh # 或 start.bat然后打开工作台，创建课题，打开一篇本地论文，确认 PDF 阅读器、AI 面板和批注按钮可用。
发布构建可检查：
./dist/PaperAtlas --check数据完整性校验：
python scripts/verify_data.py打包为独立程序
# Linux / macOS
./build.sh --clean --zip
# Windows
build.bat --clean --zip产物在 dist/，包含 Python、依赖、模板、静态资源和 PDF.js。构建必须在目标操作系统上进行。
问题排查
先运行：
python launcher.py --check常见问题：
- 端口被占用 → 修改设置或
--port。 - 忘记访问码 → 查看控制台或
data/config.json。 - Ollama 不可达 → 运行
ollama serve，检查设置中的 AI 配置。 - PDF 不存在 → 可能尚未下载，使用下载或导入。
- 扫描版 PDF → 不支持文本提取，应用会明确提示。
- AI 报错 → 检查服务商/模型/Key 和日志。
已知限制
- 印刷页码不能可靠识别；阅读器使用 PDF 物理页码，并明确标注"印刷页码未识别"，不猜测。
- 证据高亮依赖 PDF 文本层；匹配失败时只跳转到页并显示引文，不伪造高亮。
- 扫描版 PDF 需要 OCR，当前未实现。
- 旧版本生成的分析可能缺少背景/目标/数据来源/未来方向，阅读器不会推断缺失内容。
- arXiv 下载任务与期刊队列使用两套状态存储。
- 期刊全文获取受出版商访问权限限制；应用不会绕过验证码或付费墙。