Rain-Bus/daily-paper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update README and remove deprecated documentation

Browse Source
This commit is contained in:
Rain&Bus
2026-06-06 00:44:23 +08:00
parent 904eec392e
commit 5d4de50c8b
5 changed files with 119 additions and 1203 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+119 -80
View File
@@ -1,42 +1,42 @@
# HF Daily Papers — 中文论文导览站
> 每日自动抓取 HuggingFace Daily Papers，调用 AI 生成中文结构化解读，提供本地 Web 应用用于浏览、搜索、收藏与管理。
---
## 文档导航
| 文档 | 说明 |
|------|------|
| [REQUIREMENTS.md](REQUIREMENTS.md) | 产品需求、技术选型、里程碑与验收标准 |
| [docs/services.md](docs/services.md) | 爬虫、AI 总结、搜索、清理、调度、安全等服务模块说明 |
| [docs/data-model.md](docs/data-model.md) | SQLite 表结构、`summary.json` schema、索引与校验策略 |
| [docs/api-and-ui.md](docs/api-and-ui.md) | 路由、页面、用户流程与验收标准 |
> 每日自动抓取 HuggingFace Daily Papers，调用 AI 生成结构化中文解读，提供本地 Web 应用用于浏览、搜索、收藏与管理。
---
## 功能特性
- **每日抓取**：按日期拉取 HuggingFace Daily Papers，提取元数据并入库，自动去重与重试。
- **AI 中文总结**：按需下载 PDF，调用 `pi` CLI 为每篇论文生成结构化中文解读，完成后清理临时文件。
- **AI 中文总结**：下载 PDF，调用 `pi` CLI 为每篇论文生成结构化中文解读（动机、方法、结果、局限性等），完成后清理临时文件。
- **浏览与详情**：首页按日期导航、论文详情页展示元数据与总结，提供未总结论文的英文原文回退。
- **搜索**：基于 SQLite FTS5 的关键词搜索，覆盖标题、摘要、作者、标签与中文总结正文。
- **搜索**：基于 SQLite FTS5 的关键词搜索（BM25 排序、片段高亮），覆盖标题、摘要、作者、标签与总结正文。
- **语义搜索**（可选）：ChromaDB 向量数据库实现相似度搜索，优雅降级至 FTS5。
- **论文对比**：并排对比最多 5 篇论文的 12 个结构化字段。
- **趋势看板**：Chart.js 驱动的可视化统计（日论文量、Top 标签、投票分布、总结完成率）。
- **个人化**：收藏、阅读状态、个人笔记与阅读列表。
- **管理后台**：基于 token 鉴权的手动抓取、总结、清扫、删除与日志查看接口。
- **定时调度**：APScheduler 内嵌调度，默认每日 08:00 自动抓取与总结（单 worker 防重）。
- **RSS 订阅**：最近 7 天论文的 RSS 2.0 输出，支持标签过滤。
- **管理后台**：Token 鉴权的手动抓取、总结、清扫、删除与日志查看接口。
- **定时调度**：APScheduler 内嵌调度，默认每日 08:00 自动抓取与总结（TaskLock 防重）。
- **LaTeX 图片提取**：下载 arXiv 源码，扫描 `.tex` 文件提取论文图片用于详情页展示。
- **HTMX 局部更新**：收藏切换等操作无需整页刷新。
- **键盘快捷键**：`Ctrl+K` 或 `/` 聚焦搜索框。
---
## 技术栈
- **后端**：FastAPI + Uvicorn
- **模板**：Jinja2（服务端渲染）
- **前端**：HTMX + 原生 JS + 自定义 CSS
- **数据库**：SQLite + SQLAlchemy
- **全文搜索**：SQLite FTS5
- **AI 总结**：`pi` CLI（每篇论文一次调用）
- **调度**：APScheduler（单进程内嵌）
- **语义搜索**（可选增强）：ChromaDB
| 层级 | 技术 |
|------|------|
| 后端 | Python 3.12+ · FastAPI · Uvicorn |
| 模板 | Jinja2（服务端渲染） |
| 前端 | HTMX · 原生 JS · Chart.js · 自定义 CSS（"kami" 纸质风格） |
| 数据库 | SQLite + SQLAlchemy · SQLite FTS5（全文搜索） |
| AI 总结 | `pi` CLI（外部工具） |
| 语义搜索 | ChromaDB（可选） |
| 调度 | APScheduler（内嵌单进程） |
| CLI | Typer |
| 测试 | pytest · pytest-asyncio |
| 构建 | Hatchling（PEP 517） |
---
@@ -45,39 +45,71 @@
```
paper/
├── README.md
├── REQUIREMENTS.md
├── docs/
│ ├── services.md
│ ├── data-model.md
│ └── api-and-ui.md
├── .env.example
├── pyproject.toml
│
├── app/
│ ├── main.py # FastAPI 入口
│ ├── config.py # 配置加载
│ ├── database.py # SQLAlchemy 引擎与会话
│ ├── models.py # ORM 模型
│ ├── security.py # 管理接口 token 鉴权
│ ├── cli.py # 命令行入口（手动抓取等）
│ ├── routes/ # 页面与 API 路由
│ ├── services/ # 爬虫、总结、搜索、清理、调度等服务
│ ├── templates/ # Jinja2 模板（含 partials）
│ └── static/ # CSS / JS
│ ├── main.py # FastAPI 入口（lifespan 管理）
│ ├── config.py # pydantic-settings 配置加载
│ ├── database.py # SQLAlchemy 引擎、会话与 FTS5
│ ├── models.py # 11 个 ORM 模型
│ ├── utils.py # 共享工具函数
│ ├── cli.py # Typer CLI（crawl / summarize / init-db）
│ │
│ ├── routes/ # 页面与 API 路由
│ │ ├── pages.py # 首页、日期页、论文详情
│ │ ├── admin.py # Token 鉴权管理接口
│ │ ├── search.py # 搜索、阅读列表、RSS
│ │ ├── user.py # 收藏、阅读状态、笔记 API
│ │ ├── trends.py # 趋势看板
│ │ └── compare.py # 论文对比页
│ │
│ ├── services/ # 业务逻辑层
│ │ ├── crawler.py # HuggingFace API 爬虫
│ │ ├── summarizer.py # AI 总结编排
│ │ ├── searcher.py # FTS5 + 语义搜索
│ │ ├── schemas.py # Pydantic 总结校验
│ │ ├── cleaner.py # 临时文件清理 + 日期范围删除
│ │ ├── scheduler.py # APScheduler 每日管线
│ │ ├── user_data.py # 收藏、阅读状态、笔记
│ │ ├── embedder.py # ChromaDB 向量索引
│ │ ├── trends.py # 趋势统计聚合
│ │ ├── pdf_downloader.py # PDF + LaTeX 源码下载
│ │ ├── pi_client.py # pi CLI 封装 + JSON 提取
│ │ └── image_extractor.py # LaTeX 图片提取
│ │
│ ├── templates/ # Jinja2 模板
│ │ ├── base.html
│ │ ├── index.html
│ │ ├── detail.html
│ │ ├── search.html
│ │ ├── reading_list.html
│ │ ├── compare.html
│ │ ├── trends.html
│ │ ├── admin_logs.html
│ │ └── partials/paper_card.html
│ │
│ └── static/
│ ├── css/style.css # 自定义 CSS（kami 风格）
│ └── js/app.js # 键盘快捷键
│
├── data/
│ ├── db/papers.db # SQLite 数据库
│ ├── papers/{arxiv_id}/ # 长期保存的 meta.json / summary.json / raw_output.txt
│ ├── tmp/{arxiv_id}/ # 临时下载的 PDF / 源码（流程完成后清理）
│ └── chroma/ # 语义搜索向量库（可选）
├── data/ # 运行时数据（已 gitignore）
│ ├── db/papers.db # SQLite 数据库
│ ├── papers/{arxiv_id}/ # 长期资产（meta.json / summary.json / 图片）
│ ├── tmp/{arxiv_id}/ # 临时下载（流程完成后清理）
│ └── chroma/ # ChromaDB 向量库（可选）
│
├── logs/ # 运行与抓取日志
├── tests/ # 测试用例
└── scripts/ # 初始化与手动工具脚本
├── scripts/
│ ├── init_db.py # 数据库初始化
│ └── manual_crawl.py # 手动抓取脚本
│
├── tests/ # 10 个测试模块
│ ├── conftest.py # 测试夹具（内存 DB、样本数据）
│ └── test_*.py # 各模块测试
│
└── logs/ # 运行日志
```
> `data/tmp/` 仅作为流程中转，不作为长期资产；`data/papers/` 中的 `meta.json`、`summary.json`、`raw_output.txt` 可长期保留。
---
## 快速开始
@@ -85,16 +117,13 @@ paper/
### 1. 准备环境
- Python **3.12+**
- 可选：[pi](https://github.com/) CLI（用于 AI 总结，Phase 2 必需）
- 可选：[`pi`](https://github.com/) CLI（用于 AI 总结）
### 2. 安装依赖
```bash
# 推荐使用虚拟环境
python -m venv .venv
source .venv/bin/activate
# 安装（含开发依赖）
pip install -e ".[dev]"
```
@@ -107,20 +136,23 @@ cp .env.example .env
关键配置项：
| 变量 | 说明 |
|------|------|
| `APP_HOST` / `APP_PORT` | 服务监听地址，默认 `127.0.0.1:8000` |
| `ADMIN_TOKEN` | 管理接口 token，**必须修改** |
| `HF_API_BASE` | HuggingFace API 地址 |
| `TOP_N` | 每日抓取 Top N 论文 |
| `PI_BIN` / `SUMMARY_SKILL` | pi CLI 路径与使用的 skill |
| `SCHEDULER_ENABLED` | 是否启用每日定时任务 |
| `DATABASE_URL` | SQLite 数据库 URL |
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `APP_HOST` / `APP_PORT` | `127.0.0.1` / `8000` | 服务监听地址 |
| `ADMIN_TOKEN` | `change-me` | **必须修改** — 管理接口鉴权 |
| `TOP_N` | `20` | 每日抓取 Top N 论文 |
| `SCHEDULER_ENABLED` | `false` | 启用每日自动抓取 |
| `SCHEDULE_HOUR` / `SCHEDULE_MINUTE` | `8` / `0` | 定时任务时间（Asia/Shanghai） |
| `DATABASE_URL` | `sqlite:///data/db/papers.db` | 数据库路径 |
| `CHROMA_ENABLED` | `false` | 启用语义搜索 |
| `PI_BIN` | — | `pi` CLI 路径 |
| `SUMMARY_CONCURRENCY` | `3` | 最大并行总结数 |
### 4. 初始化数据库
```bash
python scripts/init_db.py
# 或：python -m app.cli init-db
```
### 5. 启动服务
@@ -129,9 +161,9 @@ python scripts/init_db.py
uvicorn app.main:app --host 127.0.0.1 --port 8000 --workers 1
```
> ⚠️ 调度器依赖单 worker：`--workers` 必须为 `1`，否则每日任务会被重复触发。
> 调度器依赖单 worker：`--workers` 必须为 `1`，否则每日任务会被重复触发。
打开浏览器访问 <http://127.0.0.1:8000> 即可。
打开浏览器访问 `http://127.0.0.1:8000` 即可。
---
@@ -141,13 +173,32 @@ uvicorn app.main:app --host 127.0.0.1 --port 8000 --workers 1
```bash
python scripts/manual_crawl.py --date 2025-01-15
# 或通过 CLI 模块
python -m app.cli crawl --date 2025-01-15
# 或
python -m app.cli crawl --date 2025-01-15 --top 20
```
### 触发单篇论文总结（管理接口）
### 手动触发总结
```bash
# 单篇
python -m app.cli summarize 2401.01234
# 批量（所有待总结论文）
python -m app.cli summarize
```
### 管理接口（Token 鉴权）
```bash
# 抓取今日论文
curl -X POST "http://127.0.0.1:8000/admin/crawl" \
-H "Authorization: Bearer $ADMIN_TOKEN"
# 批量总结
curl -X POST "http://127.0.0.1:8000/admin/summarize" \
-H "Authorization: Bearer $ADMIN_TOKEN"
# 单篇总结
curl -X POST "http://127.0.0.1:8000/admin/summarize/2401.01234" \
-H "Authorization: Bearer $ADMIN_TOKEN"
```
@@ -160,23 +211,11 @@ pytest
---
## 里程碑
- **Phase 1 — MVP**：抓取、入库、首页 / 详情页浏览
- **Phase 2 — AI 总结**：pi CLI 集成、临时文件清理、summary 校验
- **Phase 3 — 搜索与个人化**：FTS5 搜索、收藏 / 阅读状态、阅读列表、RSS
- **Phase 4 — 管理与自动化**：APScheduler、管理后台、日志、删除与清理
- **Phase 5 — 后续增强**：ChromaDB 语义搜索、相似推荐、趋势看板
详细任务列表与验收标准见 [REQUIREMENTS.md](REQUIREMENTS.md)。
---
## 安全提示
- `ADMIN_TOKEN` 是管理接口的唯一鉴权凭证，请使用强随机值并妥善保管。
- 默认仅监听 `127.0.0.1`，如需内网访问请配合反向代理与 HTTPS。
- 项目面向本地 / 内网部署，**不包含** 多用户账号体系与公网防护。
- 项目面向本地 / 内网部署，不包含多用户账号体系与公网防护。
---