HF Daily Papers — 中文论文导览站
每日自动抓取 HuggingFace Daily Papers，调用 AI 生成中文结构化解读，提供本地 Web 应用用于浏览、搜索、收藏与管理。
文档导航
| 文档 | 说明 |
|---|---|
| REQUIREMENTS.md | 产品需求、技术选型、里程碑与验收标准 |
| docs/services.md | 爬虫、AI 总结、搜索、清理、调度、安全等服务模块说明 |
| docs/data-model.md | SQLite 表结构、summary.json schema、索引与校验策略 |
| docs/api-and-ui.md | 路由、页面、用户流程与验收标准 |
功能特性
- 每日抓取：按日期拉取 HuggingFace Daily Papers，提取元数据并入库，自动去重与重试。
- AI 中文总结：按需下载 PDF，调用
piCLI 为每篇论文生成结构化中文解读，完成后清理临时文件。 - 浏览与详情：首页按日期导航、论文详情页展示元数据与总结，提供未总结论文的英文原文回退。
- 搜索：基于 SQLite FTS5 的关键词搜索，覆盖标题、摘要、作者、标签与中文总结正文。
- 个人化：收藏、阅读状态、个人笔记与阅读列表。
- 管理后台：基于 token 鉴权的手动抓取、总结、清扫、删除与日志查看接口。
- 定时调度：APScheduler 内嵌调度，默认每日 08:00 自动抓取与总结（单 worker 防重）。
技术栈
- 后端：FastAPI + Uvicorn
- 模板：Jinja2（服务端渲染）
- 前端：HTMX + 原生 JS + 自定义 CSS
- 数据库：SQLite + SQLAlchemy
- 全文搜索：SQLite FTS5
- AI 总结：
piCLI（每篇论文一次调用） - 调度：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 CLI（用于 AI 总结，Phase 2 必需）
2. 安装依赖
# 推荐使用虚拟环境
python -m venv .venv
source .venv/bin/activate
# 安装（含开发依赖）
pip install -e ".[dev]"
3. 配置环境变量
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. 初始化数据库
python scripts/init_db.py
5. 启动服务
uvicorn app.main:app --host 127.0.0.1 --port 8000 --workers 1
⚠️ 调度器依赖单 worker：
--workers必须为1，否则每日任务会被重复触发。
打开浏览器访问 http://127.0.0.1:8000 即可。
常用命令
手动抓取指定日期
python scripts/manual_crawl.py --date 2025-01-15
# 或通过 CLI 模块
python -m app.cli crawl --date 2025-01-15
触发单篇论文总结（管理接口）
curl -X POST "http://127.0.0.1:8000/admin/summarize/2401.01234" \
-H "Authorization: Bearer $ADMIN_TOKEN"
运行测试
pytest
里程碑
- Phase 1 — MVP：抓取、入库、首页 / 详情页浏览
- Phase 2 — AI 总结：pi CLI 集成、临时文件清理、summary 校验
- Phase 3 — 搜索与个人化：FTS5 搜索、收藏 / 阅读状态、阅读列表、RSS
- Phase 4 — 管理与自动化：APScheduler、管理后台、日志、删除与清理
- Phase 5 — 后续增强：ChromaDB 语义搜索、相似推荐、趋势看板
详细任务列表与验收标准见 REQUIREMENTS.md。
安全提示
ADMIN_TOKEN是管理接口的唯一鉴权凭证，请使用强随机值并妥善保管。- 默认仅监听
127.0.0.1，如需内网访问请配合反向代理与 HTTPS。 - 项目面向本地 / 内网部署，不包含 多用户账号体系与公网防护。
许可证
本项目仅供学习与个人使用，请遵守 HuggingFace、arXiv 与上游论文作者的相关条款。