PaperSpark

AI 驱动的论文阅读、知识沉淀与学术写作工作台

PaperSpark 面向科研与高阶学习场景，提供从文献导入、沉浸式阅读、知识图谱构建到论文编辑导出的完整闭环。

• 支持本地上传、URL 导入、Zotero 同步，统一进入知识库。
• 条目支持摘要翻译、引用信息保留、标签管理与删除联动清理。
• 知识项可与后续助手检索、导读、编辑器引用形成闭环。

• 提供文档信息、翻译、笔记、导读、问答等多侧栏协同模式。
• 支持重点提取与跳转，降低长文定位成本。
• 支持章节结构导图、段落关联视角与阅读进度式浏览。
• 支持文献阅读中的 paper ref 链接定位与上下文回看。

• 支持多智能体切换，适配不同任务（检索、改写、纠错、结构化输出等）。
• 支持引用知识库、引用资产库、快速笔记与会话历史回溯。
• 支持代码块运行反馈与结果回填，便于实验性分析任务。
• 若接入本地或云端 Python 引擎，可进一步解锁在线 Python 执行、绘图与更复杂的实验性工作流。

• 富文本编辑器支持结构化写作、引用插入、目录导航。
• 内置可视化公式编辑与 LaTeX 输入，兼容常见数学表达场景。
• 支持文段纠错与改写辅助，减少学术英文表达阻力。

• 面向论文、作者、概念、方法、关键词构建多类型节点关系。
• 在阅读流程中可触发自动分析与图谱增量构建。
• 提供图谱可视化浏览，支持节点关系理解与论文间关联探索。

• 支持 Markdown、TeX、LaTeX Zip 等导出形态。
• 覆盖作者信息、摘要、关键词、引用与图片资源路径。
• 适配学术写作后续排版与投稿流程。

以下展示按任务流重新编排，便于读者从「阅读 -> 理解 -> 写作 -> 交付」连续浏览。

主编辑区与可视化公式编辑	智能体配置面板
主编辑区内插入画布绘图操作	文档侧重点与版本控制支持
TeX 导出与数学环境兼容	主编辑区文档选区评论功能

双栏翻译与阅读联动	重点提取并跳转原文位置
文献阅读中的链接定位	高亮与批注工作流
章节结构导图	基于论文的交互网页生成

Zotero 批量同步入库

多论文知识图谱构建

引用知识库、快速笔记、代码执行与绘图

资产标签体系与富文本内容归档

建议移步到 https://docs.paper.062679.xyz 查看最新的部署教程和使用文档。(目前正在火速建设中)

PaperSpark 现在更适合被理解为：一个主应用 + 可选解析/运行引擎。

• 主应用：负责知识库、沉浸式阅读、编辑器、助手、图谱、导出等核心体验。
• pdfjs 基础解析：默认内置，无需 Python，提供最基础的 PDF 文本读取与兼容能力。
• Python 引擎：可选接入本地或云端，负责更重的 OCR、版面分析、代码执行、绘图等能力。
• MinerU 云端解析：独立于 Python，可直接作为高级文档解析 provider 使用。

适合先体验产品主体，不折腾 Python 环境。

• 可用：知识库、编辑器、AI 助手、基础 PDF 读取、导出、图谱等。
• 解析：走内置 pdfjs 基础解析。
• 不足：高级 OCR、复杂版面恢复、把本机 Python 当作运行引擎、在线执行 Python 代码都无法完整使用。

适合希望逐步增强本地能力的用户。

• 如果你只配置了较轻量的 Python 环境：
  • 可以逐步承担简单的绘图、实验性脚本、部分本地工具调用等任务。
  • 更适合做“本地辅助运行环境”。
• 如果你把 Python 依赖装全：
  • 可以进一步作为你的本地高级引擎。
  • 可承接 Surya OCR、本地结构化解析、更多代码执行与图像/图表生成工作流。

适合不想在本地长期维护重依赖，但又希望保留高级解析能力的用户。

• Surya 可以部署到 Modal 等云平台，作为远端 Python 解析引擎。
• MinerU 可以直接作为云端解析 provider 使用，不依赖本地 Python。
• 主应用本身仍然只需要正常启动，配置 provider 即可切换高级解析来源。

其中：

• surya-local：本地 Python 引擎
• surya-modal：部署到 Modal 的 Python 引擎
• mineru：独立云端解析 provider，不依赖本地 Python

• Node.js 18+
• pnpm 8+

git clone https://github.com/zongxi1115/paperspark.git
cd paperspark
cp .env.local.example .env.local
pnpm install
pnpm dev

默认访问地址为 http://localhost:3000。

此时即使你没有 Python，也可以先使用主应用的大部分能力，只是高级解析与 Python 运行能力会受限。

适合想把机器逐步升级为本地引擎的用户。

• Python 3.10+
• 推荐 conda

python scripts/start_surya_service.py

启动器会交互提示安装依赖与 CPU/GPU 版本选择，并实时输出安装与启动日志。

也可使用无交互参数：

# CPU 模式（自动安装）
python scripts/start_surya_service.py --accelerator cpu

# GPU 模式（示例：CUDA 12.6）
python scripts/start_surya_service.py --accelerator gpu --cuda cu126

# 仅启动，不安装依赖
python scripts/start_surya_service.py --accelerator skip-install

# macOS/Linux shell 包装脚本
chmod +x scripts/start-surya-service.sh
./scripts/start-surya-service.sh --accelerator cpu

默认服务地址为 http://127.0.0.1:8765。

在应用设置页中，把高级解析 provider 选择为 surya-local，并填写：

SURYA_OCR_SERVICE_URL=http://127.0.0.1:8765
SURYA_SERVICE_URL=http://127.0.0.1:8765
NEXT_PUBLIC_SURYA_SERVICE_URL=http://127.0.0.1:8765
NEXT_PUBLIC_SURYA_OCR_SERVICE_URL=http://127.0.0.1:8765

• 只想让本机承担部分绘图/运行任务的用户
• 想把本机进一步升级为完整解析引擎的用户
• 开发者、本地调试、二次开发场景

• 推荐在支持 CUDA 的环境中运行，以获得更快的文档解析与推理速度。
• 启动器会按你的选择自动安装匹配通道的 PyTorch（支持 cu118/cu121/cu124/cu126）。
• 若无 GPU，会自动以 CPU 方式运行，但大文件处理耗时会明显增加。
• 仓库已补充 ARM64 Docker 打包工作流，CPU 版 Surya 与 Next.js 镜像可额外发布为 ARM 标签。

适合希望把 Surya 这类重依赖迁移到远端的用户。

• Python 3.10+
• 一个可用的 Modal 账号

# 1. 安装 modal CLI
python -m pip install -r services/surya_ocr_service/requirements-modal.txt

# 2. 首次登录
python -m modal setup

# 3. 部署 Surya 云端服务
python -m modal deploy services/surya_ocr_service/modal_service.py

部署成功后，终端会打印一个类似下面的地址：

https://your-name--paperspark-surya-web-app.modal.run

然后在应用设置页把高级解析 provider 选择为 surya-modal，并把地址填入对应 URL。

更完整的 Modal 部署细节见 services/surya_ocr_service/MODAL.md。

适合希望不安装本地 Python、直接使用云端高级文档解析的用户。

• 不依赖本地 Python
• 作为独立高级解析 provider 使用
• 适合扫描版、复杂版面、需要更强结构化还原的文档场景
• 不能替代本地/云端 Python 运行时本身，因此也不能替代在线运行 Python 代码能力

在应用设置页中：

1. 把高级解析 provider 选择为 mineru
2. 填写：
   • MinerU 服务 URL
   • MinerU API Key
   • MinerU 模型版本

当前默认接的是 MinerU 精准 API。

参考文档：

• MinerU API 文档
• MinerU 输出文件说明

如果你希望把前端与本地 Python 引擎一起容器化，也可以继续使用 Docker。

• Docker Desktop（Windows/macOS）或 Docker Engine（Linux）
• 如需 GPU 加速：NVIDIA GPU + NVIDIA Container Toolkit

git clone https://github.com/zongxi1115/paperspark.git
cd paperspark/deploy
cp .env.example .env
docker-compose up -d

docker run --gpus all nvidia/cuda:12.1-base nvidia-smi
docker-compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

我们现在正处于建设初期，项目文档、环境构建步骤尚不健全，可能在体验过程中会或多或少遇到一些问题，如果你在部署或者在使用该应用时遇到了一些困难，或者你想要为我们的项目提供一些可实施的建议，欢迎提交Issue或者Pr，我们会尽快审阅答复，或者你可以加入我们的QQ群小窝里沟通：1082678889，我们会帮助你搭建环境提供一些帮助，同时后续我们会参考各方大佬的意见，尝试为应用开放marketplace，共同进行项目生态的建设！

paper_reader/
├─ app/
│  ├─ api/
│  │  ├─ ai/                    # 助手、纠错、翻译、检索等 AI 接口
│  │  ├─ knowledge/             # 知识摘要、上传与处理
│  │  ├─ knowledge-graph/       # 图谱分析与构建
│  │  ├─ pdf/                   # PDF 与 OCR 处理链路
│  │  └─ zotero/                # Zotero 同步
│  ├─ documents/                # 文档列表
│  ├─ editor/[id]/              # 编辑器主页面
│  ├─ immersive/[id]/           # 沉浸式阅读
│  └─ knowledge-graph/          # 图谱可视化页面
├─ components/                  # 业务组件
│  ├─ Assistant/                # 助手与工具调用面板
│  ├─ Editor/                   # 编辑器、公式、引用等核心组件
│  ├─ Knowledge/                # 知识库面板
│  ├─ Search/                   # 文献检索模块
│  └─ Thought/                  # 随记与思维辅助
├─ lib/                         # 核心能力封装（RAG、导出、图谱、存储等）
├─ services/surya_ocr_service/  # Python OCR 服务
└─ md_assets/                   # README 演示素材

为了方便其他 AI 工具直接读取 PaperSpark 中的本地数据，项目现在提供了“浏览器自动桥接到本地服务 + CLI 查询接口”这一套链路。

启动 PaperSpark 后，应用会在页面打开时自动把浏览器里的工作区数据桥接到本地 Next 服务。

• CLI 默认直接调用 http://127.0.0.1:3000/api/workspace-cli/query
• 不需要再手动指定快照目录
• 如果桥接还没准备好，可以在设置页的“CLI 实时桥接”卡片里点击“立即同步”

示例：

.\paperspark-data.ps1 summary
.\paperspark-data.ps1 list knowledge
.\paperspark-data.ps1 get knowledge <knowledgeId> --field immersive.fullText --raw
.\paperspark-data.ps1 search "transformer"

相关接口：

GET /api/workspace-cli/status
POST /api/workspace-cli/query
GET /api/workspace-cli/snapshot
POST /api/workspace-cli/snapshot

# 查看桥接总体统计
pnpm data:cli summary

# 列出所有知识库条目
pnpm data:cli list knowledge

# 读取某篇知识项的完整 JSON
pnpm data:cli get knowledge <knowledgeId>

# 直接输出某篇精读文章的全文
pnpm data:cli get knowledge <knowledgeId> --field immersive.fullText --raw

# 全局检索文档 / 知识库 / 资产 / 随记 / 会话
pnpm data:cli search "transformer"

如果你明确需要离线 JSON 备份，也可以在设置页点击“导出离线备份”。

• 备份文件名默认是 paperspark-workspace-snapshot.json
• CLI 只有在显式传入 --snapshot 时，才会读取本地 JSON 备份文件

pnpm data:cli summary --snapshot D:\\path\\to\\paperspark-workspace-snapshot.json

• ✅ 每次 push 到开发分支会自动创建/更新 PR
• ✅ 普通 PR merge 到 master 后只会更新工作版本号，不会正式发版
• ✅ 只有带 release label 的 PR merge 到 master 后才会自动发版
• ✅ 遵循 Conventional Commits 规范
• ⚠️ 尽量不要直接使用 Squash and Merge；如必须 squash，请把最终提交标题改成 Conventional Commit
• ⚠️ 不要直接 push 到 master 分支

• Word解析
• 画布
• 批量解析加入任务
• 开放主编辑区api（提供可编辑、读取、可配置样式、可自定义配置Agent、代码）
• 主编辑区AI交互栏 对开启可编辑功能时，经常会莫名调用进行调整控制
• 云服务部署支持数据库持久化
• 教程文档撰写
• 阅读器AI概览（对这篇文章还有那些不足之处可以扩展研究，）

• Next.js
• React
• BlockNote
• Vercel AI SDK
• HeroUI
• Tailwind CSS
• Zotero
• surya-ocr
• linux.do 非常感谢社区的大力支持！

本项目基于 CC BY-NC 4.0 协议开源。

• 允许：学习、研究、个人使用、署名转载
• 禁止：商业化使用、付费分发、集成至商业产品

未经作者授权下，无实质性重构将本项目的代码用于赛事或学术提交（使用该平台产出内容等场景除外），保留追责权利。

详见 LICENSE。

PaperSpark 已提供基本 LaTeX 导出能力，步骤如下

1. 在编辑器中点击导出按钮，选择导出语言（中文或英文）。
2. 系统会生成一个 LaTeX Zip 包，内含 main.tex、图片资源、参考文献和编译说明。
3. 解压后可直接使用 xelatex 或 pdflatex 编译。
4. 含公式、图片、引用的论文草稿可保持较高一致性，后续可进一步使用模板调整格式。