docs: add README.md
This commit is contained in:
@@ -0,0 +1,185 @@
|
||||
# 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 中文总结**：按需下载 PDF，调用 `pi` CLI 为每篇论文生成结构化中文解读，完成后清理临时文件。
|
||||
- **浏览与详情**：首页按日期导航、论文详情页展示元数据与总结，提供未总结论文的英文原文回退。
|
||||
- **搜索**：基于 SQLite FTS5 的关键词搜索，覆盖标题、摘要、作者、标签与中文总结正文。
|
||||
- **个人化**：收藏、阅读状态、个人笔记与阅读列表。
|
||||
- **管理后台**：基于 token 鉴权的手动抓取、总结、清扫、删除与日志查看接口。
|
||||
- **定时调度**：APScheduler 内嵌调度，默认每日 08:00 自动抓取与总结（单 worker 防重）。
|
||||
|
||||
---
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **后端**：FastAPI + Uvicorn
|
||||
- **模板**：Jinja2（服务端渲染）
|
||||
- **前端**：HTMX + 原生 JS + 自定义 CSS
|
||||
- **数据库**：SQLite + SQLAlchemy
|
||||
- **全文搜索**：SQLite FTS5
|
||||
- **AI 总结**：`pi` CLI（每篇论文一次调用）
|
||||
- **调度**：APScheduler（单进程内嵌）
|
||||
- **语义搜索**（可选增强）：ChromaDB
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
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
|
||||
│
|
||||
├── data/
|
||||
│ ├── db/papers.db # SQLite 数据库
|
||||
│ ├── papers/{arxiv_id}/ # 长期保存的 meta.json / summary.json / raw_output.txt
|
||||
│ ├── tmp/{arxiv_id}/ # 临时下载的 PDF / 源码（流程完成后清理）
|
||||
│ └── chroma/ # 语义搜索向量库（可选）
|
||||
│
|
||||
├── logs/ # 运行与抓取日志
|
||||
├── tests/ # 测试用例
|
||||
└── scripts/ # 初始化与手动工具脚本
|
||||
```
|
||||
|
||||
> `data/tmp/` 仅作为流程中转，不作为长期资产；`data/papers/` 中的 `meta.json`、`summary.json`、`raw_output.txt` 可长期保留。
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 准备环境
|
||||
|
||||
- Python **3.12+**
|
||||
- 可选：[pi](https://github.com/) CLI（用于 AI 总结，Phase 2 必需）
|
||||
|
||||
### 2. 安装依赖
|
||||
|
||||
```bash
|
||||
# 推荐使用虚拟环境
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# 安装（含开发依赖）
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### 3. 配置环境变量
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# 编辑 .env，至少修改 ADMIN_TOKEN
|
||||
```
|
||||
|
||||
关键配置项：
|
||||
|
||||
| 变量 | 说明 |
|
||||
|------|------|
|
||||
| `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 |
|
||||
|
||||
### 4. 初始化数据库
|
||||
|
||||
```bash
|
||||
python scripts/init_db.py
|
||||
```
|
||||
|
||||
### 5. 启动服务
|
||||
|
||||
```bash
|
||||
uvicorn app.main:app --host 127.0.0.1 --port 8000 --workers 1
|
||||
```
|
||||
|
||||
> ⚠️ 调度器依赖单 worker：`--workers` 必须为 `1`，否则每日任务会被重复触发。
|
||||
|
||||
打开浏览器访问 <http://127.0.0.1:8000> 即可。
|
||||
|
||||
---
|
||||
|
||||
## 常用命令
|
||||
|
||||
### 手动抓取指定日期
|
||||
|
||||
```bash
|
||||
python scripts/manual_crawl.py --date 2025-01-15
|
||||
# 或通过 CLI 模块
|
||||
python -m app.cli crawl --date 2025-01-15
|
||||
```
|
||||
|
||||
### 触发单篇论文总结（管理接口）
|
||||
|
||||
```bash
|
||||
curl -X POST "http://127.0.0.1:8000/admin/summarize/2401.01234" \
|
||||
-H "Authorization: Bearer $ADMIN_TOKEN"
|
||||
```
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
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。
|
||||
- 项目面向本地 / 内网部署，**不包含** 多用户账号体系与公网防护。
|
||||
|
||||
---
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目仅供学习与个人使用，请遵守 HuggingFace、arXiv 与上游论文作者的相关条款。
|
||||
Reference in New Issue
Block a user