# HF Daily Papers — 中文论文导览站 > 每日自动抓取 HuggingFace Daily Papers，调用 AI 生成结构化中文解读，提供本地 Web 应用用于浏览、搜索、收藏与管理。 --- ## 功能特性 - **每日抓取**：按日期拉取 HuggingFace Daily Papers，提取元数据并入库，自动去重与重试。 - **AI 中文总结**：下载 PDF，调用 `pi` CLI 为每篇论文生成结构化中文解读（动机、方法、结果、局限性等），完成后清理临时文件。 - **浏览与详情**：首页按日期导航、论文详情页展示元数据与总结，提供未总结论文的英文原文回退。 - **搜索**：基于 SQLite FTS5 的关键词搜索（BM25 排序、片段高亮），覆盖标题、摘要、作者、标签与总结正文。 - **语义搜索**（可选）：ChromaDB 向量数据库实现相似度搜索，优雅降级至 FTS5。 - **论文对比**：并排对比最多 5 篇论文的 12 个结构化字段。 - **趋势看板**：Chart.js 驱动的可视化统计（日论文量、Top 标签、投票分布、总结完成率）。 - **个人化**：收藏、阅读状态、个人笔记与阅读列表。 - **RSS 订阅**：最近 7 天论文的 RSS 2.0 输出，支持标签过滤。 - **管理后台**：Token 鉴权的手动抓取、总结、清扫、删除与日志查看接口。 - **定时调度**：APScheduler 内嵌调度，默认每日 08:00 自动抓取与总结（TaskLock 防重）。 - **LaTeX 图片提取**：下载 arXiv 源码，扫描 `.tex` 文件提取论文图片用于详情页展示。 - **HTMX 局部更新**：收藏切换等操作无需整页刷新。 - **键盘快捷键**：`Ctrl+K` 或 `/` 聚焦搜索框。 --- ## 技术栈 | 层级 | 技术 | |------|------| | 后端 | 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） | --- ## 项目结构 ``` paper/ ├── README.md ├── .env.example ├── pyproject.toml │ ├── app/ │ ├── 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/ # 运行时数据（已 gitignore） │ ├── db/papers.db # SQLite 数据库 │ ├── papers/{arxiv_id}/ # 长期资产（meta.json / summary.json / 图片） │ ├── tmp/{arxiv_id}/ # 临时下载（流程完成后清理） │ └── chroma/ # ChromaDB 向量库（可选） │ ├── scripts/ │ ├── init_db.py # 数据库初始化 │ └── manual_crawl.py # 手动抓取脚本 │ ├── tests/ # 10 个测试模块 │ ├── conftest.py # 测试夹具（内存 DB、样本数据） │ └── test_*.py # 各模块测试 │ └── logs/ # 运行日志 ``` --- ## 快速开始 ### 1. 准备环境 - Python **3.12+** - 可选：[`pi`](https://github.com/) CLI（用于 AI 总结） ### 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` | `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. 启动服务 ```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 # 或 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" ``` ### 运行测试 ```bash pytest ``` --- ## 安全提示 - `ADMIN_TOKEN` 是管理接口的唯一鉴权凭证，请使用强随机值并妥善保管。 - 默认仅监听 `127.0.0.1`，如需内网访问请配合反向代理与 HTTPS。 - 项目面向本地 / 内网部署，不包含多用户账号体系与公网防护。 --- ## 许可证 本项目仅供学习与个人使用，请遵守 HuggingFace、arXiv 与上游论文作者的相关条款。