247 lines
14 KiB
Markdown
247 lines
14 KiB
Markdown
# tech-spec.md - 技术架构总览
|
||
|
||
> 本文档面向未来的 AI Agent 与核心开发者，目的是在阅读源码之前快速建立对项目的整体认识：项目定位、运行模式、核心数据流、模块边界、部署形态、关键约束。
|
||
>
|
||
> **本文写什么**：架构层面的"是什么、为什么、边界在哪里"；跨模块的数据流和契约；部署/运行环境约束；不读源码就无法获知的设计决策。
|
||
>
|
||
> **本文不写什么**：源码摘录、函数签名、字段清单、命令行帮助、变更日志、UI/文案。这些信息以源码、`README.md`、`docs/plan.md`、`config.json` 为准。
|
||
>
|
||
> **维护原则**：当架构边界、数据流、运行环境、部署形态或核心设计决策发生变化时同步更新本文；普通实现调整、字段增删、文案修改不在维护范围内。
|
||
>
|
||
> update: 2026-05-17
|
||
|
||
## 项目定位
|
||
|
||
AI 驱动的 RSS 新闻聚合与推送系统：周期性抓取 400+ AI 领域信息源，调用 LLM 评分筛选，按调度规则将高分内容汇总推送到 Discord / 飞书；高分热点条目在 fetch 阶段即时推送。
|
||
|
||
面向单机部署、单租户使用，所有状态以本地文件（JSON / Markdown）持久化，不依赖外部数据库或队列。
|
||
|
||
## 运行模式
|
||
|
||
| 模式 | 触发方 | 适用场景 |
|
||
|------|--------|----------|
|
||
| **生产**（推荐） | systemd timer 分别触发 `fetch` 与 `push` 单次任务 | 服务器长期运行，依赖 systemd 提供调度、重启、开机自启 |
|
||
| **开发** | `loop` 子命令在单进程内并发跑 fetch/push 双循环 | 本地调试，无需 systemd |
|
||
|
||
CLI 子命令分工（详见 `python -m src.main --help`）：
|
||
|
||
- `check`：**唯一**的 LLM 健康检查入口，仅在部署期由 `install.sh` 调用
|
||
- `fetch` / `push`：单次执行后退出，由 systemd timer 触发；运行期不再做 LLM 健康检查，异常由统一的告警通道兜底
|
||
- `loop`：开发模式，启动时做一次健康检查，然后并发跑 fetch/push 循环
|
||
- `github` / `hackernews`：单板块手动调试入口；只跑对应板块（含 LLM 总结），打印 markdown 到终端，**不**推送、**不**写入 push 文件。仅供 prompt 调优期使用
|
||
|
||
关键约束：`fetch` / `push` 失败时进程退出码非 0，systemd 据此判定 service 失败，下个 timer 周期自动重试。
|
||
|
||
## 核心架构
|
||
|
||
### 调度模型（生产）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ config.json │
|
||
│ schedule.fetch_interval_minutes → dnews-fetch.timer │
|
||
│ schedule.push_cron → dnews-push.timer │
|
||
│ log.retention_days → journald@dnews retention│
|
||
└────────────────────────┬────────────────────────────────────┘
|
||
│ scripts/install.sh 渲染并安装
|
||
┌────────────┴────────────┐
|
||
▼ ▼
|
||
┌───────────────────┐ ┌───────────────────┐
|
||
│ dnews-fetch.timer │ │ dnews-push.timer │
|
||
└─────────┬─────────┘ └─────────┬─────────┘
|
||
▼ ▼
|
||
┌───────────────────┐ ┌───────────────────┐
|
||
│ fetch.service │ │ push.service │
|
||
│ 抓取+评分+热点推送│ │ 收集+汇总+推送 │
|
||
└─────────┬─────────┘ └─────────┬─────────┘
|
||
└────────────┬────────────┘
|
||
▼
|
||
┌─────────────────┐
|
||
│ news-data/ │
|
||
│ fetch-*.json │
|
||
│ push-*.md │
|
||
│ notify-*.md │
|
||
└─────────────────┘
|
||
```
|
||
|
||
开发模式（`loop`）以 `asyncio.gather(fetch_loop, push_loop)` 并发运行两条循环，`push_loop` 通过 croniter 计算下次触发时间，行为等价于生产模式但共享单进程。
|
||
|
||
### 数据流
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph Sources ["📡 RSS Sources"]
|
||
RS1[Twitter/X]
|
||
RS2[博客 / 媒体]
|
||
RS3[微信公众号]
|
||
end
|
||
|
||
subgraph Fetch ["🔄 fetch job (周期触发)"]
|
||
F1[抓取 RSS] --> F2[HTML→Markdown] --> F3[LLM 批量评分]
|
||
F3 --> HOT{score ≥ hot_threshold?}
|
||
HOT -->|是| IP[即时推送 + notify-*.md]
|
||
end
|
||
|
||
subgraph Push ["📅 push job (cron 触发)"]
|
||
P1[读取近 N 天 fetch + 历史 push 上下文] --> P2[LLM 汇总去重] --> P3[生成 push-*.md] --> P4[推送 Discord / 飞书]
|
||
end
|
||
|
||
subgraph Storage ["💾 news-data/"]
|
||
DB[(JSON / MD)]
|
||
end
|
||
|
||
Sources --> F1
|
||
F3 --> DB
|
||
IP --> DB
|
||
DB --> P1
|
||
P3 --> DB
|
||
```
|
||
|
||
**关键数据契约**：
|
||
|
||
- `fetch-YYYY-MM-DD.json`：当日抓取与评分结果（含 score / summary / tags / content）
|
||
- `push-YYYY-MM-DD.md`：汇总推送内容（YAML frontmatter + Markdown 正文），同时作为下一次 push 的去重上下文
|
||
- `notify-YYYY-MM-DD.md`：即时推送记录，作为 LLM 即时推送时的去重上下文
|
||
|
||
具体字段以源码 `src/storage.py` 与样例文件为准，README "数据示例" 章节给出了一份示例。
|
||
|
||
## 关键模块边界
|
||
|
||
```
|
||
src/ 运行时代码
|
||
├── main.py CLI 入口；定义 fetch_job / push_job / loop 的编排顺序
|
||
├── config.py 加载 config.json，合并 OPML + add/block，做配置校验
|
||
├── fetcher.py RSS 抓取；并发控制、UA 伪装、域名通配符屏蔽；nitter/xcancel 走独立的 requests+Inoreader UA 低并发池
|
||
├── processor.py HTML → Markdown 转换
|
||
├── llm.py LLM 客户端;批量评分、即时推送生成、汇总生成、错误聚合
|
||
├── storage.py news-data 文件读写;按日期分片;过期清理
|
||
└── push/ 推送平台抽象
|
||
├── base.py PushPlatform 基类(validate_config / send)
|
||
├── discord.py
|
||
└── feishu.py
|
||
|
||
scripts/ 部署脚本(仅生产 systemd 部署使用)
|
||
├── install.sh 一键安装:uv sync → LLM check → 渲染单元 → 装入系统 → 启用
|
||
├── uninstall.sh 卸载 systemd 单元、daily-news 包装脚本和日志 drop-in;不删数据
|
||
├── status.sh 查看 timer/service 状态(daily-news status 包装它)
|
||
├── _gen_units.py 从 config.json 渲染 systemd 单元和 daily-news 包装脚本
|
||
└── daily-news.tmpl /usr/local/bin/daily-news 的脚本模板,封装 systemctl/journalctl
|
||
|
||
systemd/ systemd 单元模板(由 _gen_units.py 渲染并装入 /etc/systemd/system/)
|
||
├── dnews-fetch.service.tmpl fetch service 单元模板
|
||
├── dnews-fetch.timer.tmpl fetch 定时器(OnUnitActiveSec 间隔触发)
|
||
├── dnews-push.service.tmpl push service 单元模板
|
||
├── dnews-push.timer.tmpl push 定时器(OnCalendar 日历触发)
|
||
└── journald-dnews.conf.tmpl journald 命名空间 dnews 的日志保留 drop-in
|
||
|
||
config.json 主配置;运行参数 + 调度 + LLM + 推送渠道;唯一可热改的运行配置
|
||
prompts/ LLM 提示词文本;score / immediate_push / digest 各自独立文件
|
||
resources/rss.opml 基础 RSS 订阅源(约 420 个),通过 sources.add/block 增量调整
|
||
.env 敏感凭证(API Key / Webhook URL),通过环境变量注入,不入库
|
||
```
|
||
|
||
### 板块化扩展 (morning push)
|
||
|
||
早报推送在 RSS 之上扩展三个板块:GitHub 趋势 / Hacker News 热议 / 跨板块洞察。模块结构、数据流与失败降级详见 `docs/extra-sections-design.md`。架构层关键约束:
|
||
|
||
- 仅在当天 `schedule.push_cron` 列表里最早那次触发时启用(单条 cron 时每次都启用),其余时段维持纯 RSS 行为
|
||
- 各板块封装为 `src/sections/<board>/section.py::run_xxx_section(config, now) -> (markdown, error)`
|
||
- `push_job` 用 `asyncio.gather` 并发跑 RSS / GH / HN,串行接 insights;最后用 `<!-- SECTION:xxx BEGIN/END -->` sentinel 包入 push 文件
|
||
- 仅 RSS 失败会让 push_job 整体退出非 0;其余板块失败 → 板块整段省略 + 告警
|
||
|
||
新增持久化文件:`news-data/trending-history.json`(GH 已查阅 repo 索引,按 `filter.keep_days` 过期)
|
||
|
||
模块协作的关键约定：
|
||
|
||
- **fetch 与 push 之间通过文件系统解耦**：双方不直接通信，push 只读 fetch 已写入的 JSON
|
||
- **LLM 调用的错误处理由调用方决定**：`llm.py` 不做 fallback，失败时返回 `(空内容, 错误列表)`；调用方决定是否告警或跳过推送，避免一个批次失败污染整次任务
|
||
- **批量评分按 `link` 字段对齐**：LLM 返回的条目数可能少于输入，按 link 匹配并丢弃无法对齐的结果，错误聚合后由调用方统一上报
|
||
- **推送平台通过基类多态**：新增平台只需实现 `validate_config()` 与 `send()`，并在工厂函数注册，main.py 无需改动
|
||
|
||
## 数据边界与持久化
|
||
|
||
- 所有持久化数据落在项目根目录的 `news-data/`：按日期分片的 `fetch-*.json` / `push-*.md` / `notify-*.md`
|
||
- 过期文件由 fetch job 在每次执行后清理，保留窗口由 `filter.keep_days` 控制
|
||
- 没有数据库、没有外部缓存、没有跨机器同步；状态完全可由文件系统重建
|
||
- 敏感信息（API Key、Webhook URL）只通过环境变量注入，禁止写入 `config.json` 或代码
|
||
|
||
## 配置与约束
|
||
|
||
完整配置字段说明见 `README.md` 的"配置详解"章节，本文只列出对架构有影响的约束。
|
||
|
||
### schedule
|
||
|
||
| 字段 | 约束 |
|
||
|------|------|
|
||
| `fetch_interval_minutes` | systemd 部署下用 `OnUnitActiveSec` 实现，从上次任务**完成**开始计时（非日历对齐） |
|
||
| `fetch_lookback_minutes` | 必须大于 `fetch_interval_minutes`，用作 RSS 延迟的冗余窗口，依赖 link 去重防止重复入库 |
|
||
| `push_cron` | systemd 部署下**只支持 minute/hour 字段**，其他位必须为 `*`；不支持范围、列表、`*/N`。`loop` 模式下走 croniter，支持完整语法 |
|
||
| `timezone_hours` | 整数小时偏移；用于显示和 cron 计算 |
|
||
|
||
### log
|
||
|
||
`log.retention_days` 仅对 systemd 部署生效，由 `install.sh` 渲染到 journald 命名空间 `dnews` 的 drop-in 配置；修改后必须重跑 `install.sh`。
|
||
|
||
### LLM
|
||
|
||
`llm.max_prompt_chars` 决定批次切分粒度，`llm.max_concurrent_batches` 决定批次并发数。这两个值同时影响吞吐和单次推送的成本上限。
|
||
|
||
### 环境变量
|
||
|
||
敏感凭证名通过 config.json 的 `*.apiKeyName` 字段指定环境变量名，由 `os.environ` 读取；约定通过 `.env` 提供，systemd 部署时 install.sh 会注入到 service 单元的 `EnvironmentFile`。
|
||
|
||
## systemd 部署形态
|
||
|
||
### 文件落点
|
||
|
||
| 文件 | 位置 | 来源 |
|
||
|------|------|------|
|
||
| `dnews-{fetch,push}.{service,timer}` | `/etc/systemd/system/` | `systemd/*.tmpl` 由 `_gen_units.py` 渲染 |
|
||
| `journald@dnews` retention drop-in | `/etc/systemd/journald@dnews.conf.d/` | `systemd/journald-dnews.conf.tmpl` |
|
||
| `daily-news` 包装脚本 | `/usr/local/bin/` | `scripts/daily-news.tmpl` |
|
||
| 持久化数据 | 项目目录下的 `news-data/` | 运行时生成 |
|
||
|
||
### cron → OnCalendar 转换
|
||
|
||
由 `scripts/_gen_units.py` 完成：
|
||
|
||
- `fetch_interval_minutes` → `OnActiveSec` + `OnUnitActiveSec`（间隔触发，跟随上次完成时间）
|
||
- `push_cron` → `OnCalendar`（日历触发，按指定时刻）
|
||
- 不支持的 cron 语法（范围、列表、`*/N` 在 minute/hour、非 `*` 的 day/month/dow）在 install 阶段直接报错
|
||
|
||
### 日志
|
||
|
||
- 所有 stdout/stderr 进入 journald 命名空间 `dnews`，与系统其他服务隔离
|
||
- 查询：`journalctl --namespace=dnews -u dnews-fetch -f`
|
||
- 卸载不会清理历史日志，需要时手动 `journalctl --namespace=dnews --vacuum-time=1s`
|
||
|
||
## 设计决策（重要的"为什么"）
|
||
|
||
| 决策 | 原因 |
|
||
|------|------|
|
||
| 调度交给 systemd timer 而非 asyncio 循环 | 进程崩溃和服务器重启可自愈；调度配置即声明式单元，热更新只需重跑 install.sh |
|
||
| LLM 健康检查只在 `check` 子命令做 | 每次 timer 触发都校验会产生无意义的 LLM API 调用；运行期错误由 `notify_llm_errors` 兜底 |
|
||
| LLM 失败时不生成 fallback 内容 | 避免低质量内容污染推送；由调用方决定告警或跳过 |
|
||
| 用 journald 命名空间而非文件日志 | 自动轮转、与系统日志隔离、无需写文件 IO 代码 |
|
||
| 数据全用本地文件而非数据库 | 单机单租户场景下足够；可读、可备份、可手动审阅 |
|
||
| `fetch_lookback_minutes` 冗余窗口 | RSS 源时间戳常有延迟，仅按时间过滤会漏读；冗余抓取后按 link 去重 |
|
||
| Push 上下文带入近 N 天历史 push 文件 | 避免汇总推送在多个时段重复推同一条目 |
|
||
|
||
## 扩展指南
|
||
|
||
- **新推送平台**：在 `src/push/` 新建文件，继承 `PushPlatform`，在工厂注册
|
||
- **新评分维度**：编辑 `prompts/score.txt`，调整评分标准
|
||
- **新 RSS 源**：编辑 `config.json` 的 `sources.add` / `sources.block` / `sources.block_domains`，无需修改 OPML
|
||
|
||
## 测试
|
||
|
||
测试入口分两类，详细命令参考 `README.md` 与 `tests/` 目录：
|
||
|
||
- `tests/pytest/`：单元/集成测试，CI 友好，`uv run pytest tests/pytest/` 一键跑
|
||
- `tests/*.py`：交互式实操脚本（`fetch_news.py` / `push_news.py` / `run_llm_test.py` 等），针对真实 RSS 与 LLM 做端到端验证，用于调参和手测
|
||
|
||
## 相关文档
|
||
|
||
- 用户文档与配置详解：`README.md`
|
||
- 任务进度与产品决策：`docs/plan.md`
|