Rain-Bus
f1be24ab83
- Add FastAPI app with paper browsing UI and REST API - Add crawler service and database models - Add scripts for DB init and manual crawl - Add docs (api-and-ui, data-model, services) - Add requirements and project config
270 lines
6.9 KiB
Markdown
270 lines
6.9 KiB
Markdown
# 服务模块详解
|
||
|
||
> 本文档描述各服务模块的职责、输入输出、失败处理和实现约束。
|
||
|
||
---
|
||
|
||
## 1. 爬虫服务
|
||
|
||
**职责**：从 HuggingFace Daily Papers 获取论文列表，写入元数据。PDF 不在抓取阶段长期保存。
|
||
|
||
### 数据源
|
||
|
||
- Daily Papers API：`GET https://huggingface.co/api/daily_papers?date=YYYY-MM-DD`
|
||
- PDF：`https://arxiv.org/pdf/{arxiv_id}.pdf`（总结阶段按需下载）
|
||
- 源码（后续增强）：`https://arxiv.org/e-print/{arxiv_id}`
|
||
|
||
HuggingFace 官方 Hub API 文档说明 `/api/daily_papers` 支持 `date` 查询参数。
|
||
|
||
### 规则
|
||
|
||
- `arxiv_id` 是唯一键。
|
||
- 重复抓取同一天时，已有论文只更新 upvotes、标签等可变元数据，不重复插入。
|
||
- 网络请求必须设置 timeout、User-Agent、重试次数。
|
||
- API 返回空列表时记录成功日志，不视为失败。
|
||
- 抓取阶段不下载 PDF；总结阶段 PDF 下载失败时更新 `asset_status=failed` 和 `summary_status.error_type=pdf_download_failed`。
|
||
|
||
### 接口
|
||
|
||
```python
|
||
async def fetch_daily(date: str, top_n: int) -> list[PaperMeta]: ...
|
||
async def upsert_papers(papers: list[PaperMeta]) -> list[Paper]: ...
|
||
```
|
||
|
||
---
|
||
|
||
## 2. AI 总结服务
|
||
|
||
**职责**：调用 pi CLI，把单篇论文转成结构化中文总结。
|
||
|
||
### 调用原则
|
||
|
||
- 一篇论文一次 pi 调用。
|
||
- 并发数由 `SUMMARY_CONCURRENCY` 控制，默认 3。
|
||
- 单篇超时由 `SUMMARY_TIMEOUT_SECONDS` 控制，默认 300 秒。
|
||
- pi 路径通过 `PI_BIN` 配置，当前可以先使用宿主机路径；跑通后再抽象部署方式。
|
||
- PDF 在总结开始前按需下载到 `data/tmp/{arxiv_id}/paper.pdf`，总结成功或失败后清理。
|
||
|
||
### 调用示例
|
||
|
||
```bash
|
||
pi -p --skill daily-paper-summary \
|
||
"请深度解读以下论文，并按指定 JSON schema 输出：
|
||
@data/papers/2401.12345/meta.json
|
||
@data/tmp/2401.12345/paper.pdf"
|
||
```
|
||
|
||
### 流程
|
||
|
||
```text
|
||
取 pending 论文
|
||
-> 下载 PDF 到 data/tmp/{arxiv_id}/paper.pdf
|
||
-> status=processing
|
||
-> 调 pi
|
||
-> 提取 JSON
|
||
-> Pydantic 校验
|
||
-> 写 summary.json
|
||
-> 写 paper_summaries / paper_tags / papers_fts
|
||
-> status=done
|
||
-> 清理 PDF/源码临时文件
|
||
```
|
||
|
||
失败时保存 raw output、更新 `summary_status`，并清理下载文件。
|
||
|
||
PDF 下载失败不调用 pi，直接记录 `pdf_download_failed` 并进入重试流程。
|
||
|
||
---
|
||
|
||
## 3. 搜索服务
|
||
|
||
**职责**：MVP 提供 FTS5 关键词搜索；后续接入 ChromaDB 语义搜索。
|
||
|
||
### FTS5 搜索
|
||
|
||
索引字段：
|
||
|
||
- 英文标题
|
||
- 中文标题
|
||
- 英文摘要
|
||
- 作者
|
||
- 标签
|
||
- 中文总结正文
|
||
|
||
应用层负责同步 FTS：
|
||
|
||
```python
|
||
def build_fts_document(paper: Paper, summary: PaperSummary | None) -> FtsDocument:
|
||
summary_text = ""
|
||
if summary:
|
||
summary_text = " ".join([
|
||
summary.one_line or "",
|
||
summary.motivation_problem or "",
|
||
summary.motivation_goal or "",
|
||
summary.method_overview or "",
|
||
summary.method_key_idea or "",
|
||
" ".join(summary.results_main or []),
|
||
])
|
||
return FtsDocument(...)
|
||
```
|
||
|
||
### ChromaDB 语义搜索（后续）
|
||
|
||
接入时要求：
|
||
|
||
- `CHROMA_ENABLED=true` 才初始化。
|
||
- embedding API 失败不能影响总结入库。
|
||
- embedding 维度和配置不匹配时记录日志并跳过。
|
||
- 使用当前 ChromaDB 官方 API 重新确认查询和过滤语法后实现。
|
||
|
||
---
|
||
|
||
## 4. 页面渲染服务
|
||
|
||
**职责**：从 SQLite 读取数据并渲染 Jinja2 模板。
|
||
|
||
kami 只作为风格参考：
|
||
|
||
- 参考纸张质感、留白、字体层级和墨蓝强调色。
|
||
- 不调用 kami，不依赖 kami 生成页面。
|
||
- CSS 放在 `app/static/css/style.css`，按本项目页面实际结构维护。
|
||
|
||
页面必须支持降级状态：
|
||
|
||
- 无总结：显示英文元数据和“AI 总结尚未生成”。
|
||
- 总结失败：显示错误类型和手动重跑入口。
|
||
- degraded/low：显示提示，但仍展示已有内容。
|
||
|
||
---
|
||
|
||
## 5. 用户数据服务
|
||
|
||
**职责**：本地个人化数据，无账号体系。
|
||
|
||
功能：
|
||
|
||
- 收藏/取消收藏。
|
||
- 阅读状态：`unread`、`skimmed`、`read_summary`、`read_full`。
|
||
- 个人 Markdown 笔记。
|
||
- 阅读列表：按收藏、状态、标签、日期筛选。
|
||
|
||
所有用户数据跟随论文删除一起删除。
|
||
|
||
---
|
||
|
||
## 6. 清理和删除服务
|
||
|
||
**职责**：清理临时文件，并支持管理员手动删除指定日期范围内的数据。
|
||
|
||
### 临时文件清理
|
||
|
||
触发时机：
|
||
|
||
- 单篇总结成功后。
|
||
- 单篇总结失败后。
|
||
- 每日任务结束后兜底扫描 `data/tmp/`。
|
||
|
||
### 手动删除
|
||
|
||
接口：
|
||
|
||
```python
|
||
async def delete_papers_by_date_range(
|
||
date_start: date,
|
||
date_end: date,
|
||
include_notes: bool = True,
|
||
) -> DeleteResult: ...
|
||
```
|
||
|
||
要求：
|
||
|
||
- 删除前统计目标论文数量。
|
||
- 删除 DB 记录、FTS 索引、本地文件。
|
||
- 删除失败时记录具体 arXiv ID 和错误。
|
||
- 日期范围必须有限制，避免误删全部数据；管理接口需要二次确认参数。
|
||
|
||
---
|
||
|
||
## 7. 调度服务
|
||
|
||
**职责**：自动执行每日抓取和总结。
|
||
|
||
### 约束
|
||
|
||
- 应用以单 worker 运行。
|
||
- `APP_WORKERS` 必须为 1，或 `SCHEDULER_ENABLED=false`。
|
||
- 启动时检查运行中任务，避免重复执行。
|
||
- 同一日期同一任务使用数据库锁或日志状态防重入。
|
||
- 推荐使用 `task_locks` 表；抢锁失败时，自动任务跳过，管理接口返回 409。
|
||
|
||
### 每日流程
|
||
|
||
```text
|
||
08:00
|
||
-> 按 APP_TIMEZONE 计算 today
|
||
-> crawl(date=today)
|
||
-> summarize pending papers
|
||
-> cleanup tmp files
|
||
-> write logs
|
||
```
|
||
|
||
手动触发方式：
|
||
|
||
- CLI：`python -m app.cli crawl --date YYYY-MM-DD`
|
||
- API：`POST /admin/crawl`
|
||
|
||
---
|
||
|
||
## 8. 管理和安全服务
|
||
|
||
**职责**：保护所有有副作用的管理操作。
|
||
|
||
### 鉴权
|
||
|
||
管理接口必须要求 `ADMIN_TOKEN`：
|
||
|
||
```text
|
||
Authorization: Bearer <ADMIN_TOKEN>
|
||
```
|
||
|
||
受保护接口：
|
||
|
||
- `POST /admin/crawl`
|
||
- `POST /admin/summarize/{arxiv_id}`
|
||
- `POST /admin/summarize`
|
||
- `POST /admin/cleanup`
|
||
- `POST /admin/delete`
|
||
- `GET /admin/logs`
|
||
|
||
如果 `ADMIN_TOKEN` 为空或为默认值 `change-me`，应用启动时应警告；如果 `APP_HOST` 不是 `127.0.0.1`，应拒绝启动或要求显式确认。
|
||
|
||
用户数据接口默认仅面向本地使用。如果 `APP_HOST=127.0.0.1`，收藏、阅读状态、笔记接口不额外要求 token；如果绑定到非本地地址，应启用 same-origin 检查或要求 `ADMIN_TOKEN`，避免内网其他人修改本地笔记。
|
||
|
||
---
|
||
|
||
## 9. RSS 服务
|
||
|
||
**职责**：输出最近论文的 RSS Feed。
|
||
|
||
MVP 只做 `/rss.xml`：
|
||
|
||
- 默认最近 7 天。
|
||
- 支持 `?tag=RAG`。
|
||
- 有中文标题则用中文标题，否则用英文标题。
|
||
- 详情链接指向本站 `/paper/{arxiv_id}`。
|
||
|
||
Atom 和 JSON Feed 作为后续增强。
|
||
|
||
---
|
||
|
||
## 10. 后续增强服务
|
||
|
||
这些能力暂不进入 MVP：
|
||
|
||
- LaTeX 图片提取。
|
||
- ChromaDB 语义搜索。
|
||
- 相似论文推荐。
|
||
- 趋势看板。
|
||
- 论文对比页。
|
||
|
||
实现前需要重新评估数据量、API 成本、页面复杂度和验收标准。
|