# 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 与上游论文作者的相关条款。