AI Paper Coach

读论文更快，理解更深，复现更稳。

GitHub About（建议配置）

可直接复制到仓库 About

Description（中文）
面向学生和研究者的 AI 论文阅读与复现助手：结构化分析、复现指导、七问洞察、全流程可追踪。

Description (English)
An AI paper coach for students and researchers: structured paper analysis, reproducibility guidance, 7-question insights, and traceable history.

Suggested Topics
ai paper-reading research-assistant llm fastapi vue3 pdf reproducibility arxiv education

Repo Pitch

一条流完成：导入 -> 分析 -> 审阅 -> 整理 -> 报告
双模型协作 + 七问框架 + 可回放 trace/API 诊断
适合课堂汇报、组会复述与复现实验落地

简体中文

项目简介

AI Paper Coach 是一个面向学生和研究者的论文阅读与复现助手。
输入 arXiv/PDF 链接或直接上传 PDF，就能自动生成结构化报告，并支持后续问答与历史追踪。

30 秒价值说明

解决什么问题：把论文阅读中分散的「摘要理解、创新判断、复现落地」整合成一条可执行流程。
核心能力：结构化分析 + 七问框架 + 复现指导，并保留 trace 方便回溯诊断。
适用人群：课程汇报场景下的学生、做文献调研和实验复现的研究者。

为什么值得用

一条流完成：导入 -> 分析 -> 审阅 -> 整理 -> 报告
七问结构化输出：更适合课堂汇报、组会复述、复现实验
原文阅读联动：报告和 PDF 原文可对照查看
RAG 问答：基于论文原文的检索增强问答，支持跨语言查询（中文问英文论文）
可追踪可回放：保留 trace、历史记录、已保存报告
支持删除管理：历史记录和已保存报告都可删除
API 连通性验证：一键检查后端是否可达

七问框架（完整）

论文试图解决什么问题？这是否是一个新的问题？
有哪些相关研究？如何归类？谁是这一课题在领域内值得关注的研究者（公司）？
论文中提到的解决方案之关键是什么？
论文中的实验是如何设计的？
用于定量评估的数据集是什么？代码有没有开源？
文中的实验及结果有没有很好地支持需要验证的科学假设/提出方案？
这篇论文到底有什么贡献？下一步呢？有什么工作可以继续深入？

核心功能

论文导入：URL / 本地 PDF
双模型协作：支持模型校验与配置保存
七问阅读框架：横向切换，间距紧凑
RAG 问答：基于论文原文的检索增强生成，支持跨语言查询、引用溯源
结果管理：历史记录、已保存报告、删除功能
AI 对话工具：内置常用提问下拉，可一键插入论文高频问题模板
导出能力：Markdown / PDF 报告导出
诊断信息：运行日志 + trace 记录

内容要求阈值（当前）

摘要（论文问题与目标）：>= 800 字
复现指导（整体）：>= 1000 字
七问长答：每题 >= 700 字

常见问题（FAQ）

Q1：模型 key 放哪里？
A：放在项目根目录 .env，并按 .env.example 填写。生产环境建议用系统环境变量注入，不直接写入仓库文件。

Q2：为什么 finalize 阶段有时比较慢？
A：finalize 会进行结构整理、长度校验、必要时触发 repair 和重试。现在已经在 trace 中增加模型调用耗时、repair 触发标记和重试次数，便于定位慢点。

Q3：为什么标题显示“论文中未明确说明”？
A：当 PDF/元数据解析失败或命中占位文本时会回退到该占位。当前版本已补 arXiv API 标题补全和占位识别逻辑，建议对同一论文重新执行完整流程。

Q4：复现指导为空怎么处理？
A：当前版本已增加兜底合并逻辑。若仍为空，按「ingest -> analyze -> review -> finalize」重新跑一次，trace 会显示是否触发 repair 与重试。

Q5：PDF 导出里出现乱码或方块怎么办？
A：当前版本已在 PDF 导出前做字符规范化（清理异常替代字符并过滤字体不支持的符号），并将列表符号改为兼容性更高的格式。若历史报告仍异常，请重新导出最新报告。

版本与路线图

v0.1（已完成）
- 完整主流程：ingest -> analyze -> review -> finalize -> report
- 七问结构化输出与阈值校验
- 历史记录/保存报告管理（含删除）
- finalize 可观测性（耗时、repair、重试）与 trace 回放
- 标题提取增强（含 arXiv API 兜底）和复现指导空内容修复
v0.2（进行中）
- RAG 检索增强问答，支持跨语言查询
- Pipeline 服务化（async 架构，analyze.py 从 634 行瘦身到 170 行）
- ModelRouter 异步方法（httpx 非阻塞 HTTP）
- 全局异常处理加固，不再向客户端泄漏内部异常
- SQLite 连接池、PDF 按页提取、LangSmith 追踪集成
v0.3（计划中）
- 失败可恢复执行（按阶段断点续跑）
- 更细粒度质量评分和告警
- 前端组件化拆分（ResultsView 解耦）
- RAG 语义检索（向量数据库集成）

Release Note：见 docs/releases/v0.1.2.md

安全声明

API Key 不会提交到仓库：.env、.env.*、*.env.local 已在 .gitignore 中忽略。
支持 gitleaks 历史扫描；当前仓库历史扫描结果为 0 命中（无疑似密钥泄露）。
CORS 白名单：APC_ALLOWED_ORIGINS 必须显式配置，不允许通配符 *。
全局异常处理：500 响应不包含原始异常信息，详细堆栈仅写入服务端日志。
可选开启后端鉴权：APC_REQUIRE_API_KEY=1 + APC_API_KEY，请求头使用 x-api-key。

项目结构

ai-paper-coach/
|- apps/web/                  # Vue 3 + Vite 前端
|  |- src/views/              # 页面组件（ResultsView, TaskView 等）
|  |- src/composables/        # 组合式函数（useTraceHistory 等）
|  `- src/lib/                # 工具库（API 调用、本地存储）
|- services/api/              # FastAPI 后端
|  |- app/core/
|  |  |- model_router.py      # 模型调用路由（同步 + 异步双轨）
|  |  |- orchestrator.py      # 分析/审阅/整理编排
|  |  |- pipeline.py          # Pipeline 任务管理（async）
|  |  |- rag.py               # RAG 检索增强生成
|  |  |- tracing.py           # LangSmith 追踪集成
|  |  |- storage.py           # SQLite 存储（连接池）
|  |  `- parser.py            # PDF 解析（按页提取）
|  |- app/routers/            # HTTP 端点
|  `- tests/                  # pytest 测试
|- services/data/             # 运行时数据（DB、上传、缓存）
|- caogao/                    # README 截图素材
|- run.py                     # 一键启动前后端
`- README.md

快速开始

1) 安装后端依赖

cd services/api
pip install -r requirements.txt

2) 安装前端依赖

cd apps/web
npm install

3) 配置环境变量

cp .env.example .env

按需填写模型配置；不填也可在 MVP 模式下运行部分流程。

安全相关可选配置：

APC_ALLOWED_ORIGINS：CORS 白名单，逗号分隔（如 http://localhost:5500,https://your-domain.com）
APC_MAX_UPLOAD_MB：上传 PDF 大小限制（默认 20）
APC_REQUIRE_API_KEY：是否开启 API Key 鉴权（0/1）
APC_API_KEY：鉴权 key（请求头使用 x-api-key）

4) 一键启动

python run.py

5) 运行后端测试（新增）

cd services/api
pytest -q

手动启动（可选）

后端：

cd services/api
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

前端：

cd apps/web
npm run dev -- --host 127.0.0.1 --port 5500

主要 API

GET /health — API 连通性检查
POST /validate-models — 模型接口校验
POST /ingest — 论文导入（URL / PDF 上传）
POST /analyze — 结构化分析
POST /review — 审阅
POST /finalize — 整理定稿
POST /pipeline/start — 启动全自动流水线（异步，SSE 进度）
GET /pipeline/jobs/{job_id}/events — 流水线 SSE 事件流
POST /rag/query — RAG 检索问答
GET /report/{paper_id} — 获取报告
GET /export/{paper_id}.md — 导出 Markdown
GET /export/{paper_id}.pdf — 导出 PDF
GET /trace/{paper_id} — 获取 trace 记录
GET /history / DELETE /history/{record_id} — 历史管理
GET /saved / DELETE /saved/{record_id} — 已保存报告管理

统一响应结构

除流式接口外，JSON 接口统一返回：

{
  "success": true,
  "data": {},
  "error": null
}

失败返回：

{
  "success": false,
  "data": null,
  "error": {
    "code": 400,
    "message": "...",
    "details": null
  }
}

适用场景

上课/组会前 10 分钟快速吃透论文
形成复现实验 TODO 清单
比较不同模型配置下的输出质量
长期积累论文阅读档案

English

Overview

AI Paper Coach helps students and researchers read papers faster and reproduce results with more confidence. You can ingest a paper from URL/PDF, generate structured reports, and continue with Q&A and traceable history.

30-Second Value

Problem solved: unify scattered paper reading tasks (understanding, critique, reproducibility) into one workflow.
Core capability: structured analysis + 7-question framework + reproducibility guidance with traceable diagnostics.
Audience: students preparing talks and researchers doing literature review or reproduction work.

Highlights

End-to-end pipeline: ingest -> analyze -> review -> finalize -> report
Structured 7-question reading framework
RAG Q&A: retrieval-augmented generation over paper text, with cross-lingual query support
AI chat quick prompts: built-in dropdown with common paper questions for one-click insertion
Side-by-side report + original PDF reading
History and saved reports with deletion support
Async pipeline architecture with SSE progress streaming
LangSmith tracing integration for observability

Content Thresholds (Current)

Summary (three_minute_summary.problem): >= 800 chars
Reproduction guide (combined fields): >= 1000 chars
7 Q&A answers: each >= 700 chars

FAQ

Where should I put model keys?
Use the project root .env (based on .env.example). For production, prefer environment-variable injection.

Why can finalize be slow?
finalize may trigger repair/retry loops after validation. Trace now records per-call latency, repair trigger, and retry count.

Why does title show a placeholder?
When parsing metadata/title fails, a placeholder is used. Current version adds arXiv API fallback and better placeholder detection.

What if reproduction guidance is empty?
Current version includes fallback merge logic. Re-run ingest -> analyze -> review -> finalize and inspect trace if needed.

Version & Roadmap

v0.1 done: full pipeline, 7-question outputs, trace observability, title fallback, reproduction-guide fixes.
v0.2 in progress: RAG with cross-lingual support, async pipeline architecture, ModelRouter async methods, security hardening, SQLite connection pool, LangSmith tracing.
v0.3 planned: resumable stage runs, finer quality scoring, frontend component refactoring, vector-based RAG.

Security Statement

API keys are not committed: .env, .env.*, and *.env.local are ignored.
gitleaks history scan reports 0 findings.
CORS whitelist is enforced (no wildcard * allowed).
Global exception handler: 500 responses never expose raw exception details.
Optional backend key auth: APC_REQUIRE_API_KEY=1 and APC_API_KEY via x-api-key header.

Quick Start

# backend
cd services/api
pip install -r requirements.txt

# frontend
cd apps/web
npm install

# run all
python run.py

# backend tests
cd services/api
pytest -q

Optional security env vars in .env:

APC_ALLOWED_ORIGINS: comma-separated CORS whitelist
APC_MAX_UPLOAD_MB: upload limit in MB (default 20)
APC_REQUIRE_API_KEY: enable API key auth (0/1)
APC_API_KEY: expected value in x-api-key header

Key APIs

GET /health — connectivity check
POST /validate-models — model provider validation
POST /ingest — paper import (URL / PDF upload)
POST /analyze — structured analysis
POST /review — review
POST /finalize — finalize
POST /pipeline/start — async full pipeline with SSE progress
POST /rag/query — RAG retrieval Q&A
GET /report/{paper_id} — get report
GET /export/{paper_id}.md / .pdf — export
GET /trace/{paper_id} — trace records

Unified Response Envelope

For non-streaming JSON APIs, the response format is:

{
  "success": true,
  "data": {},
  "error": null
}

Error format:

{
  "success": false,
  "data": null,
  "error": {
    "code": 400,
    "message": "...",
    "details": null
  }
}

Contributing

Issues and PRs are welcome. Please include:

clear problem statement
reproducible steps
expected vs. actual behavior

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
apps/web		apps/web
caogao		caogao
docs		docs
scripts		scripts
services		services
.env.example		.env.example
.gitignore		.gitignore
PROJECT_PLAYBOOK.md		PROJECT_PLAYBOOK.md
README.md		README.md
run.py		run.py

Folders and files

Latest commit

History

Repository files navigation

AI Paper Coach

GitHub About（建议配置）

简体中文

项目简介

30 秒价值说明

为什么值得用

最新界面截图

整体界面

论文原文阅读区

摘要面板

复现指导

AI 对话（常用提问）

七问切换

Trace 面板

导出 PDF

七问框架（完整）

核心功能

内容要求阈值（当前）

常见问题（FAQ）

版本与路线图

安全声明

项目结构

快速开始

1) 安装后端依赖

2) 安装前端依赖

3) 配置环境变量

4) 一键启动

5) 运行后端测试（新增）

手动启动（可选）

主要 API

统一响应结构

适用场景

English

Overview

30-Second Value

Highlights

Content Thresholds (Current)

FAQ

Version & Roadmap

Security Statement

Quick Start

Key APIs

Unified Response Envelope

Contributing

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages