diary-news/README.md

# Diary News · 私人多源新闻翻译系统

> 抓境外权威源 → 自动中英对照 → 智能排版/分类/插图/点评。
> 跑在一台 2C/2G/30G 的香港 VPS 上,自用 + 家人/小圈子。

---

## 目录

1. [项目目标](#项目目标)
2. [关键特性](#关键特性)
3. [架构概览](#架构概览)
4. [技术栈](#技术栈)
5. [仓库结构](#仓库结构)
6. [数据模型](#数据模型)
7. [快速开始](#快速开始)
8. [功能详解](#功能详解)
9. [LLM 智能增强](#llm-智能增强)
10. [API 概览](#api-概览)
11. [开发-部署工作流](#开发-部署工作流)
12. [运维工具](#运维工具)
13. [故障排查](#故障排查)
14. [路线图](#路线图)

---

## 项目目标

**Why 存在**:

| 痛点 | 解决 |
|---|---|
| 信息茧房(算法推荐让你只看一类) | 多源并列,无个性化排序,纯时间序 |
| 翻译门槛(英文看不动) | 自动翻译(腾讯云 TMT + 本地 NLLB 降级) |
| 内容保存难(网页 404、推文删) | 抓取入库 + 全文 + 译文,永久可查 |
| 单台服务器成本敏感 | 30G 跑全栈,月费 ≤ 50 HKD |

**Who 给谁用**:

- **owner**: 唯一管理员,管理源 / 提示词 / 看健康看板
- **member**: 家庭成员 / 朋友,登录看文章 / 收藏 / 订阅关键词

---

## 关键特性

- 🌍 **多源 RSS 抓取**:Reuters / BBC / Al Jazeera / NHK / DW,带失败退避(连续 3 次失败把间隔 × 2,封顶 12 小时)
- 🌐 **智能翻译**:腾讯云 TMT(月 500 万字符配额)→ 本地 NLLB-200 降级,30 天 Redis 缓存避免重复
- 🤖 **LLM 智能增强** *(新)*:翻译完成后自动跑 4 项 LLM 任务 — 排版 / 分类 / 插图 / 点评
- 🎨 **AI 配图**:文生图模型自动为每篇文章生成插图(走 Agnes 平台,带限速)
- 👤 **双角色鉴权**:JWT(access 60min + refresh 14d) + API Token(sha256,可撤销,给 Android 预留)
- 📌 **收藏 + 关键词订阅**:用户级书签,服务端定时按关键词命中推送(预留 Telegram 通道)
- 📊 **管理看板**:源健康度 / 翻译配额 / LLM 状态,全部可视化
- 🔄 **热加载**:源/提示词改了不用重启,worker 每天 00:30 重建 job
- 🚀 **一键部署**:SSH 推公钥 + 一键 `git pull` 流程
- 🔒 **安全默认**:bcrypt 密码、API Token 加密、SQL 注入免疫(SQLAlchemy 2.0 参数化)

---

## 架构概览

```
┌─────────────────────────────────────────────────────────┐
│  VPS (HK-News · 2C/2G/30G · Ubuntu 24)                │
│                                                          │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐         │
│  │ postgres │    │  redis   │    │  caddy   │ ← 唯一  │
│  └──────────┘    └──────────┘    │  :80/443 │   对外   │
│       ▲              ▲           └────┬─────┘          │
│       │              │                │                 │
│  ┌────┴──────┐  ┌────┴────┐  ┌────────┴───────┐        │
│  │   api     │  │ worker  │  │   frontend     │        │
│  │  FastAPI  │  │APSch+任务│  │   (nginx + SPA)│        │
│  └────┬──────┘  └────┬────┘  └────────────────┘        │
│       │              │                                  │
│       └──────┬───────┘                                  │
│              │                                          │
│  ┌───────────▼──────────┐                               │
│  │   RSS 抓取(feedparser)│                              │
│  │  翻译(Tencent+NLLB)  │                              │
│  │  LLM 增强(Agnes)      │ ← 排版/分类/插图/点评        │
│  │  url_hash 去重        │                              │
│  └──────────────────────┘                               │
└──────────────────────────────────────────────────────────┘
              │
              │ HTTPS / Push / Pull
              ▼
   ┌──────────────────────┐
   │  Gitea(代码托管)     │
   │  http://...:3000      │
   └──────────────────────┘
```

**数据流**(单篇文章的一生):
```
RSS Feed → feedparser → FetchedItem
   ↓
url_hash = SHA1(url) + ON CONFLICT DO NOTHING  ← 去重
   ↓ (新文章入库,translation_status=pending)
   ↓
[translation_loop]  1篇/秒  Semaphore(1)
   ↓ 调 腾讯 TMT → body_zh_text/html
   ↓ status: pending → ok
   ↓
[enrichment_loop]  扫描 *_status=pending 的已译文章
   ↓ 调 Agnes LLM: 排版 → 分类 → 插图 → 点评
   ↓ 4 任务独立 try/except,共享 chat_sem + image_sem 限速
   ↓ status: ok / failed
   ↓
[文章详情接口]  原文 + 译文 + AI 排版版 + 分类 + 插图 + 点评  全部展示
```

---

## 技术栈

### 后端

| 层 | 选型 |
|---|---|
| 语言 | Python 3.12 |
| Web 框架 | FastAPI 0.115 + Uvicorn |
| ORM | SQLAlchemy 2.0(asyncio)+ Alembic |
| 数据库 | PostgreSQL 16(asyncpg + psycopg2) |
| 缓存/限速 | Redis 7(256MB LRU) |
| HTTP 客户端 | httpx 0.28(异步) |
| RSS 解析 | feedparser 6 |
| HTML 抽取 | trafilatura 2 + BeautifulSoup4 + lxml |
| 翻译主 | 腾讯云 TMT(SDK: tencentcloud-sdk-python) |
| 翻译降级 | transformers + NLLB-200-distilled-600M |
| LLM | Agnes(OpenAI 兼容): agnes-2.0-flash / agnes-image-2.1-flash |
| 调度 | APScheduler 3.10(AsyncIO + Cron + Interval) |
| 鉴权 | passlib[bcrypt] 1.7 + bcrypt 4.0.1 + PyJWT 2.10 |

### 前端

| 层 | 选型 |
|---|---|
| 框架 | Vue 3.5 + Vite 5 |
| UI 库 | Naive UI 2.40 |
| 状态 | Pinia 2.2 |
| 路由 | vue-router 4.4 |
| HTTP | axios 1.7(自动 401 refresh) |
| 时间 | dayjs 1.11 |

### 部署

| 层 | 选型 |
|---|---|
| 容器化 | Docker Compose(7 服务) |
| 反代 | Caddy 2(alpine) |
| 静态 | nginx 1.27-alpine(SPA fallback) |
| 构建 | pyproject.toml(setuptools) + npm |

---

## 仓库结构

```
diary-news/
├── backend/                          # FastAPI 后端
│   ├── app/
│   │   ├── api/                      # HTTP 路由
│   │   │   ├── auth.py               #   /auth/login, /auth/refresh
│   │   │   ├── me.py                 #   /me, /me/usage(翻译配额)
│   │   │   ├── articles.py           #   /articles 列表 + 详情 + 游标分页
│   │   │   ├── sources.py            #   /sources 只读列表
│   │   │   ├── bookmarks.py          #   /bookmarks 收藏
│   │   │   ├── subscriptions.py      #   /subscriptions 关键词订阅
│   │   │   ├── admin.py              #   /admin/sources, /admin/health, /admin/refresh
│   │   │   └── admin_llm.py          #   /admin/llm/settings, /admin/llm/enrich/{id}
│   │   ├── core/
│   │   │   ├── security.py           #   bcrypt + JWT + API Token
│   │   │   └── deps.py               #   get_current_user, require_owner
│   │   ├── models/                   # SQLAlchemy 2.0 ORM
│   │   │   ├── user.py
│   │   │   ├── source.py
│   │   │   ├── article.py
│   │   │   ├── bookmark.py
│   │   │   ├── subscription.py
│   │   │   ├── api_token.py
│   │   │   └── llm_setting.py        # LLM 设置(单行表)
│   │   ├── schemas/                  # Pydantic v2 I/O 模型
│   │   │   ├── auth.py
│   │   │   ├── article.py
│   │   │   ├── source.py
│   │   │   ├── llm.py                # LLM 设置 schemas + 默认提示词
│   │   │   └── misc.py
│   │   ├── services/
│   │   │   ├── fetchers/             #   RSS / HTML / Telegram 采集器
│   │   │   ├── translation/          #   腾讯 TMT + 本地 NLLB + 配额门面
│   │   │   └── llm/                  #   Agnes client + 智能增强
│   │   │       ├── client.py
│   │   │       └── enrichment.py
│   │   ├── workers/
│   │   │   ├── __main__.py           #   APScheduler + translation_loop + enrichment_loop
│   │   │   └── pipeline.py           #   fetch_one_source / translate_article
│   │   ├── scripts/                  # 初始化(create_user / seed_sources)
│   │   ├── config.py                 # Pydantic Settings(从 .env 读)
│   │   ├── database.py               # 异步 SQLAlchemy 引擎
│   │   ├── redis_client.py           # Redis 单例
│   │   └── main.py                   # FastAPI 入口
│   ├── alembic/
│   │   ├── env.py
│   │   ├── versions/
│   │   │   ├── 0001_initial.py       #   6 张表 + 枚举
│   │   │   └── 0002_llm_settings_and_articles_ai.py
│   │   └── alembic.ini
│   ├── Dockerfile                    # python:3.12-slim
│   ├── pyproject.toml
│   └── .env.example
│
├── frontend/                         # Vue 3 + Vite + Naive UI
│   ├── src/
│   │   ├── main.ts                   # createApp + Pinia + Router
│   │   ├── App.vue
│   │   ├── router.ts                 # 路由守卫(requiresAuth / ownerOnly)
│   │   ├── api/
│   │   │   ├── client.ts             # axios + 401 refresh 拦截器
│   │   │   └── articles.ts           # articles / sources / me / bookmarks / admin
│   │   ├── stores/auth.ts            # Pinia 鉴权状态(localStorage 持久化)
│   │   ├── components/
│   │   │   └── AppLayout.vue         # 顶栏 + 侧栏 + 配额条
│   │   └── views/
│   │       ├── Login.vue
│   │       ├── Feed.vue              # 24h 列表 + 游标分页
│   │       ├── ArticleDetail.vue     # 原文/译文/AI 排版/分类/插图/点评
│   │       ├── Bookmarks.vue
│   │       ├── Sources.vue
│   │       ├── AdminSources.vue      # owner: 源管理 CRUD
│   │       └── AdminLlmSettings.vue  # owner: LLM 提示词 + 测连接 + 触发
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── package.json
│
├── docs/
│   ├── architecture.md               # 77 行实现版架构
│   └── acceptance.md                 # MVP 验收清单
│
├── scripts/                          # 工具脚本
│   ├── deploy_pull.py                # 免密部署:clone/pull + 失败回滚
│   ├── server_init.py                # 远程服务器初始化(推公钥 + 7 项系统级运维)
│   ├── push_ssh_key.py               # 单推公钥(已用 fingerprint 去重)
│   ├── _*.py                         # 临时调试脚本(gitignored)
│   └── deploy_remote.sh              # 远程一键部署(老脚本)
│
├── .env.example                      # 配置示例(可 commit)
├── .gitignore                        # 忽略 .env / scripts/_*.py / node_modules 等
├── Caddyfile                         # 反代规则
├── docker-compose.yml                # 7 服务
├── DEPLOY.md                         # 完整部署手册(165 行)
├── README.md                         # 本文件
└── news-aggregator-plan.md           # 613 行方案设计 v0.1(决策背景)
```

---

## 数据模型

6 张表 + 1 张配置表(全部 PostgreSQL):

| 表 | 关键字段 | 说明 |
|---|---|---|
| **users** | role(enum: owner/member), password_hash | 用户 + 角色 |
| **sources** | slug(uniq), kind(rss/html_list/tg_channel), priority, fetch_interval_min, consecutive_failures | 采集源 |
| **articles** | url_hash(uniq), translation_status(pending/ok/partial/failed), category, commentary, body_zh_formatted, image_ai_url, *_status, category, entities(JSONB), sentiment, topic_id, bias | 文章 + 译文 + LLM 增强 |
| **bookmarks** | (user_id, article_id) UNIQUE | 收藏 |
| **subscriptions** | keyword, match_in(any/title/body), channel | 关键词订阅 |
| **api_tokens** | token_hash(sha256), expires_at, revoked_at | Android 预留 |
| **llm_settings** | format_prompt, classify_prompt, commentary_prompt, image_prompt_template, image_size, chat_model, image_model, interval_sec, enabled | LLM 提示词(单行) |

ER 关系:
- `users` 1:N → `bookmarks` / `subscriptions` / `api_tokens`
- `sources` 1:N → `articles`(cascade delete)
- `articles` 1:N → `bookmarks`, self-ref `duplicate_of`(去重链)

---

## 快速开始

### 本地开发(Linux/Mac/WSL2)

```bash
# 1. 克隆
git clone http://<gitea>/xiaji/diary-news.git
cd diary-news

# 2. 配置
cp .env.example .env
# 编辑 .env 填入:
#   POSTGRES_PASSWORD / REDIS_PASSWORD / JWT_SECRET(用 openssl rand -hex)
#   TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY
#   AGNES_API_KEY

# 3. 启动
docker compose up -d --build

# 4. 初始化
docker compose exec api alembic upgrade head
docker compose exec api python -m app.scripts.create_user --username owner --password YOUR_PASS
docker compose exec api python -m app.scripts.seed_sources

# 5. 触发一次抓取
docker compose exec api python -c "import asyncio; from app.workers.pipeline import run_once; asyncio.run(run_once())"

# 6. 打开
open http://localhost/   # macOS
xdg-open http://localhost/  # Linux
```

### Windows 本机(无 WSL)

直接装 Python 3.12 + Node 20:

```powershell
# 后端
cd backend
py -3.12 -m venv .venv
.venv\Scripts\activate
pip install -e .
# 起 postgres / redis(用 docker run -d 或者本机服务)
$env:DATABASE_URL = 'postgresql+asyncpg://...'
alembic upgrade head
uvicorn app.main:app --reload

# 前端
cd ../frontend
npm install
npm run dev
```

### 远程部署

完整步骤见 [`DEPLOY.md`](./DEPLOY.md)。**已部署过一次的机器**只需 2 步:

```bash
# 1. 在本机 push 代码 + 跑 deploy_pull.py
git push origin main
python scripts\deploy_pull.py        # 自动 clone/pull + 失败回滚

# 2. 在服务器上重启应用(代码变了)
ssh hknews
cd /root/diary-news
docker compose restart api worker
docker compose exec api alembic upgrade head
```

---

## 功能详解

### RSS 抓取

- **5 个种子源**:Reuters / BBC / Al Jazeera / NHK / DW
- **抓取频率**:每源 60 分钟(可调),失败连续 3 次后间隔 × 2(封顶 12 小时)
- **去重**:`url_hash = SHA1(url)`,PG `ON CONFLICT DO NOTHING` 幂等
- **HTML 抽取**:trafilatura 抓全文,RSS 摘要短时自动补抓
- **可见性**:`/admin/sources` + `/admin/health` 看板

### 翻译(配额 + 缓存 + 降级)

```
[译文不存在]
   ↓ Semaphore(1) — 1 篇/秒
   ↓
[缓存命中?]
   ├─ 是 → 直接返回(30 天有效)
   └─ 否 ↓
[主引擎(腾讯 TMT)可配额?]
   ├─ 是 → 调 TMT → 写缓存 + 加计数
   └─ 否 ↓
[本地 NLLB 启用?]
   ├─ 是 → 调 NLLB → 写缓存
   └─ 否 → 原文 + [本条未翻译:配额耗尽] 标记
```

配额在 Redis `translation:month:YYYYMM` 计数器(月度自动滚动)。`TENCENT_TMT_QUOTA_BUFFER=0.05` 表示 95% 触发后切本地(避免爆配额)。

### 用户 / 鉴权

- **JWT**:access 60min + refresh 14d,HS256 签名
- **API Token**:Android 客户端用,sha256 存储(可撤销 + 过期)
- **角色**:`owner` 全部权限,`member` 看文章/收藏/订阅
- **密码**:bcrypt 4.0.1(锁版兼容 passlib)

### 收藏 / 关键词订阅

- 收藏:点星星,加到 `bookmarks`,有 note 字段
- 关键词订阅:扫 `articles.body_text`/`title`,命中后写入 `subscriptions.last_hit_at`,预留 Telegram 通道(MVP 不发)

---

## LLM 智能增强

> **新功能**(2026-06-08 加入)。翻译完成后,自动调 Agnes LLM 跑 4 项独立任务。

### 4 项任务

| 任务 | 输出字段 | LLM 类型 | 用途 |
|---|---|---|---|
| **排版** | `articles.body_zh_formatted` | chat | 重写译文为网页排版(分段/加粗/列表) |
| **分类** | `articles.category` | chat(返 JSON) | 给文章打 1-3 个分类标签 |
| **插图** | `articles.image_ai_url` | image | 文生图,英文 prompt 拼自 `title` |
| **点评** | `articles.commentary` | chat | 100-200 字评论,客观有深度 |

### 限速

- 单一 `LlmClient`,内部 `chat_sem` + `image_sem` 各 1 个并发
- 每次调用后 `await asyncio.sleep(LLM_INTERVAL_SEC)`(默认 2.0s)
- chat 和 image 互不阻塞
- 4 个任务在 `enrich_article` 内**串行**(已过 client 限速)

### 设置页(Owner only)

`/admin/llm` → 4 个 textarea + 几个 input:

- **总开关** `enabled`
- **4 个提示词**(可重置默认):`format_prompt` / `classify_prompt` / `commentary_prompt` / `image_prompt_template`
- **模型**:`chat_model` / `image_model`(默认 agnes-2.0-flash / agnes-image-2.1-flash)
- **插图尺寸**:`image_size`(默认 1024x768)
- **限速**:`interval_sec`(默认 2.0)
- **测连接**:发个 `ping` chat 请求,1-2 秒内返 OK
- **手动触发**:`POST /admin/llm/enrich/{article_id}` 跑一篇 4 任务

### 默认提示词

`backend/app/schemas/llm.py` 的 `DEFAULT_PROMPTS`,支持占位符:
- `{body}` — 译文正文
- `{title}` — 译后标题
- `{summary}` — 摘要

### 失败隔离

每个任务独立 try/except,失败标 `*_status='failed'`,**不影响**其他任务。
`enrichment_loop` 扫 `*_status` 是 `pending/failed/n/a` 的文章,自动重试 failed。

### 历史文章批量 enrich

新功能**只对**翻译完成后入库的文章生效。历史已翻译文章,手动 reset:

```sql
UPDATE articles
SET format_status='pending', classify_status='pending',
    image_ai_status='pending', commentary_status='pending'
WHERE translation_status='ok';
```

---

## API 概览

所有 API 在 `/api/v1` 前缀下,完整定义见 `http://<host>/api/docs`(DEBUG 模式)。

### 公开

- `POST /auth/login` — 用户名 + 密码 → access + refresh token
- `POST /auth/refresh` — refresh token → 新 access

### 需要登录(任意角色)

- `GET /me` — 当前用户信息
- `GET /me/usage` — 翻译配额(已用 / 总额 / 百分比)
- `GET /articles?since=...&source=...&q=...&cursor=...` — 列表(游标分页)
- `GET /articles/{id}` — 详情
- `GET /sources` — 源列表(只读)
- `GET /bookmarks` / `POST /bookmarks` / `DELETE /bookmarks/{id}`
- `GET /subscriptions` / `POST /subscriptions` / `DELETE /subscriptions/{id}`

### Owner only(`/admin/*`)

- `GET /admin/sources` / `POST` / `PATCH /{id}` / `DELETE /{id}` — 源 CRUD
- `POST /admin/refresh/{source_id}` — 立即触发抓取
- `POST /admin/translation/rerun/{article_id}` — 重译
- `GET /admin/health` — 源健康看板
- `POST /admin/translation/quota/reset` — 重置本月配额
- `GET /admin/llm/settings` / `PUT` / `POST /reset` / `POST /test` — LLM 设置
- `POST /admin/llm/enrich/{article_id}` — 手动触发某篇 enrich

---

## 开发-部署工作流

```
┌─────────────────────────────────────┐
│  本地 Windows (你)                  │
│  ─ 编辑代码                          │
│  ─ git add / commit                  │
│  ─ git push origin main             │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│  Gitea(代码托管)                    │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│  跑 python scripts\deploy_pull.py  │
│  ─ 免密登录(SSH key)               │
│  ─ git clone/pull                   │
│  ─ 成功:保持 + 报告                 │
│  ─ 失败:git reset --hard <前 sha>   │
└─────────────────┬───────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│  远程 HK-News                       │
│  ─ 代码最新                         │
│  ─ (如果需要)docker compose restart│
│  ─ (如果需要)alembic upgrade head   │
└─────────────────────────────────────┘
```

**完整循环命令**(本机跑):

```bash
git add -A
git commit -m "feat: ..."
git push origin main
python scripts\deploy_pull.py          # 我帮你跑,你说"拉一下"即可
```

---

## 运维工具

| 脚本 | 用途 | 调用 |
|---|---|---|
| `scripts/deploy_pull.py` | 免密拉取 + 失败回滚 | `python scripts\deploy_pull.py` |
| `scripts/server_init.py` | 服务器系统级初始化(推公钥 + 7 项运维) | `REMOTE_PASS=xxx python scripts/server_init.py` |
| `scripts/push_ssh_key.py` | 单推 SSH 公钥(SSH key fingerprint 去重) | `REMOTE_PASS=xxx python scripts/push_ssh_key.py` |
| `docker compose logs -f worker` | 看 worker 日志 | 服务器上 |
| `docker compose exec api alembic upgrade head` | 跑 migration | 服务器上 |

### deploy_pull.py 完整参数

```bash
python scripts\deploy_pull.py \
  --host 207.57.129.228 \
  --port 19717 \
  --user root \
  --repo-dir /root/diary-news \
  --repo-url http://124.223.26.33:3000/xiaji/diary-news.git \
  --branch main

# 干跑
python scripts\deploy_pull.py --dry-run

# 手动回退
python scripts\deploy_pull.py --rollback <sha>
```

也支持 env var:`DEPLOY_HOST` / `DEPLOY_PORT` / `DEPLOY_USER` / `DEPLOY_REPO_DIR` / `DEPLOY_REPO_URL` / `DEPLOY_SSH_KEY`。

---

## 故障排查

### Q: 翻译一直失败?
1. `docker compose logs worker | grep -E "translate|tencent"`
2. 看 `translation:month:YYYYMM` Redis key 是不是满了
3. 调 `.env` 的 `TENCENT_TMT_QUOTA_BUFFER=0.1` 给更多缓冲

### Q: 某个 RSS 源一直 fail?
1. `/admin/health` 看 `consecutive_failures` 字段
2. `docker compose logs worker | grep <source_slug>`
3. 大概率是 RSS URL 失效或被反爬,先 `enabled=false` 暂停,在 `/admin/sources` 编辑后重启 worker

### Q: LLM 增强不工作?
1. `/admin/llm` → 点 "测连接"
2. 看后端日志 `docker compose logs worker | grep -E "enrich|chat"`
3. 确认 `.env` 里有 `AGNES_API_KEY`

### Q: 服务器磁盘快满?
```sql
DELETE FROM articles WHERE published_at < now() - interval '90 day' AND duplicate_of IS NULL;
```

### Q: deploy 失败,想回退?
```bash
python scripts\deploy_pull.py --rollback <之前的好 sha>
# 或者手动
ssh hknews "cd /root/diary-news && git reset --hard <sha>"
```

### Q: 中文用户名乱码?
PowerShell 默认 GBK,运行前先 `chcp 65001` 切 UTF-8。

---

## 路线图

- [x] **Phase 1 (MVP)**:5 RSS 源 + 翻译 + 网页 + admin CRUD
- [x] **Phase 1.5**:LLM 智能增强(排版/分类/插图/点评) ✅ 2026-06-08
- [ ] **Phase 2**:PWA 离线缓存 / 关键词订阅推送(Telegram)
- [ ] **Phase 3**:Android 客户端(API Token 已预留)
- [ ] **Phase 4**:自动分类/点评/实体识别(目前是 LLM 一次性,无 ML pipeline)
- [ ] **Phase 5**:跨源立场对照 / 主题聚类

---

## 文档导航

- 📄 [DEPLOY.md](./DEPLOY.md) — 完整部署手册(新机器从 0 到能访问)
- 📐 [docs/architecture.md](./docs/architecture.md) — 实现版架构(77 行)
- ✅ [docs/acceptance.md](./docs/acceptance.md) — MVP 验收清单
- 📜 [news-aggregator-plan.md](./news-aggregator-plan.md) — 613 行方案设计 v0.1(选型决策背景)
- 🛠 [scripts/deploy_pull.py](./scripts/deploy_pull.py) — 部署工具源码

---

## 设计原则

- **轻量**:单机 30G 能跑,不堆重型服务
- **可控**:源管理 / 翻译配额 / 抓取调度 / LLM 提示词 全部可视化
- **可扩展**:ML 字段(category/commentary/entities/sentiment/bias)已建好,后续直接写值不动表
- **不反爬对抗**:愿意被 ban IP 就 ban,优先合规
- **透明失败**:不静默吞错,每个 stage 都有 `*_status` 字段记录
- **幂等可重跑**:所有运维脚本(server_init / deploy_pull)都幂等,跑多遍无副作用

---

**License**: Private use only.