# 🪖 军事科技每日摘要系统 V3

完整的军事科技 RSS 抓取 + AI 智能分析 + 增量缓存 + 运行监控系统

## ✨ 完整功能

### 📥 数据抓取
- 🔗 可配置 RSS 源直抓（rss_feeds.txt 管理，支持 100+ 源）
- ⏰ 24 小时时间窗口过滤
- 🔄 同源标题去重（保留跨源对同一事件的不同报道）
- ⚡ ThreadPoolExecutor 并发抓取，内置失败重试

### 🗄️ 增量缓存
- 💾 SQLite 本地缓存：文章翻译/AI分析结果持久化
- 📰 网摘文本缓存：再次运行零 token 消耗
- 🏷️ 分类介绍缓存：按日期+分类独立存储
- 🧹 自动过期清理（7天）+ 表结构自动迁移

### 🌐 智能翻译
- 🔍 自动识别外文文章
- 📝 分步翻译：先标题 → 再正文（仅通过筛选的文章）
- ⚡ 并发翻译（ThreadPoolExecutor）

### 🔑 关键词筛选
- 🎯 44 个军事科技专业关键词库
- 📊 命中数排序，文章 >15 篇时自动过滤

### 🤖 AI 智能分析
- ⭐ 多维度评分（技术35% + 战略30% + 信息20% + 时效15%）
- 📋 自动分类：今日必看 / 装备动态 / 地区冲突 / 战略政策
- ✍️ 每篇文章 AI 智能摘要（80-120字）
- 🔮 分类深度洞察分析（每类50字综述）
- 🏆 TOP3 必看深度分析
- ⚡ 批量并发评分 + 分类

### 🖼️ 图片生成
- 📄 3800px 超长网摘图片
- 🎨 军事主题视觉设计
- 📊 包含TOP3完整内容
- 💾 自动保存PNG文件

### 📊 运行监控
- ⏱ 各阶段耗时统计，自动输出结构化报表
- 🤖 API 调用量/token 按用途和模型分组统计
- 📰 源抓取成功/失败率一目了然
- 📡 文章统计 + 缓存命中率

## 🚀 快速开始

### 方式一：本地直接运行（推荐）

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 配置环境
cp config/.env.example config/.env
vim config/.env
# 编辑 OPENAI_API_KEY

# 3. 运行
make local
```

### 方式二：Docker 部署

```bash
# 1. 克隆或解压
cd military-digest-v3

# 2. 配置环境
cp config/.env.example config/.env
vim config/.env
# 编辑 OPENAI_API_KEY

# 3. 构建镜像
make build

# 4. 测试运行
make run-once

# 5. 安装定时任务
make install-cron
```

## 📁 目录结构

```
military-digest-v3/
├── scripts/
│   ├── military_daily_report_v3.py   # 主入口 — 流程编排
│   └── modules/                      # 功能模块包
│       ├── __init__.py               # 包初始化 + 统一导出
│       ├── config.py                 # 配置模块：常量 + AI配置加载
│       ├── utils.py                  # 工具函数：语言检测/HTML清洗/AI调用/换行
│       ├── rss_fetcher.py            # RSS抓取：12源 × 6线程并发
│       ├── translator.py             # 翻译处理：中英分离 + 并发翻译
│       ├── keyword_filter.py         # 关键词筛选：49词命中排序
│   │   ├── ai_analyzer.py            # AI分析：评分/分类/摘要/洞察/网摘生成
│   │   ├── cache.py                  # SQLite缓存：文章/网摘/分类介绍增量缓存
│   │   ├── monitor.py                # 运行监控：阶段耗时/API/AI token调用统计
│   │   ├── pusher.py                 # 推送模块：企业微信/飞书 webhook 推送
│   │   ├── image_generator.py        # 图片生成：TOP3合并3800px长图
│       └── get_chinese_font.py       # 字体模块：跨系统中文字体适配
├── config/
│   ├── config.json                   # 系统配置
│   └── .env.example                  # 环境变量示例
├── output/                           # 输出目录
│   ├── military_report_YYYYMMDD.md    # 完整报告（Markdown格式，支持链接、样式）
│   ├── military_webzine_YYYYMMDD.txt  # TOP3网摘文本
│   └── military_webzine_YYYYMMDD.png  # TOP3网摘合并长图
├── logs/                             # 日志目录
├── Dockerfile
├── docker-compose.yml
├── Makefile
└── README.md
```

## 🧩 模块架构

```
military_daily_report_v3.py  ← 主入口（流程编排）
  ├── config.py              ← 配置常量，零依赖
  ├── logger.py              ← 统一日志模块
  ├── cache.py               ← SQLite增量缓存，自动迁移
  ├── monitor.py             ← 运行监控统计
  ├── pusher.py              ← 企业微信/飞书推送
  ├── rss_fetcher.py         ← 依赖 config + utils + monitor
  ├── translator.py          ← 依赖 utils
  ├── keyword_filter.py      ← 依赖 config
  ├── ai_analyzer.py         ← 依赖 config + utils
  ├── image_generator.py     ← 依赖 utils + get_chinese_font
  └── get_chinese_font.py    ← 零依赖
```

### 各模块职责

| 模块 | 行数 | 职责 | 对外导出 |
|------|------|------|----------|
| `config.py` | 90 | RSS源、关键词库、评分维度、分类定义、AI配置加载 | `RSS_FEEDS`, `WECHAT_SOURCES`, `KEYWORDS`, `SCORE_DIMENSIONS`, `CATEGORIES`, `load_ai_config()` |
| `utils.py` | 130+ | 语言检测、HTML清理、时间解析、AI API封装（含监控钩子）、文本换行 | `is_chinese()`, `clean_html()`, `extract_content()`, `parse_pub_time()`, `call_ai()`, `wrap_text()` |
| `rss_fetcher.py` | 100+ | 多线程并行抓取RSS源（MAX_THREADS并发，含2次重试+监控上报） | `fetch_all_feeds()` |
| `translator.py` | 150+ | 中英文分离 + 标题/正文分步AI并发翻译 | `batch_translate_titles()`, `batch_translate_contents()` |
| `keyword_filter.py` | 23 | 44关键词命中计数 → 排序 → Top15筛选 | `keyword_filter()` |
| `ai_analyzer.py` | 240+ | 四维度评分、智能分类、中文摘要、分类洞察、《参考消息》风格网摘生成 | `score_and_classify_article()`, `calculate_weighted_score()`, `generate_category_overview()`, `generate_webzine_for_article()`, `batch_score_and_classify_articles()` |
| `cache.py` | 310+ | SQLite增量缓存：文章处理结果+网摘+分类介绍，支持自动迁移+过期清理+断点续跑 | `get_cache()`, `get_article()`, `save_article()`, `save_article_webzine()`, `get_category_summary()`, `save_category_summary()` |
| `monitor.py` | 160+ | 运行时监控：阶段耗时/AI API调用量+token/源成功率/缓存命中率，结束自动输出报表 | `get_monitor()`, `monitor.stage()`, `monitor.report()` |
| `pusher.py` | 130+ | 企业微信文本/图片/Markdown推送 + 飞书文本推送，主流程末自动触发，失败优雅降级 | `send_daily_push()`, `push_wechat_text()`, `push_wechat_image()`, `push_feishu_text()` |
| `image_generator.py` | 220 | 网摘文本渲染为PNG图片（单篇 + TOP3合并长图） | `create_webzine_image()`, `create_combined_webzine_image()` |
| `get_chinese_font.py` | 50 | 跨系统中文字体自动匹配，支持Windows/Linux/macOS，内置开源字体可选 | `get_chinese_font(size, bold)` |

## ⚙️ 配置说明

### 环境变量 (.env)

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| OPENAI_API_KEY | OpenAI API 密钥 | - |
| OPENAI_API_BASE | API 地址 | https://api.openai.com/v1 |
| OPENAI_MODEL | AI 分析模型 | gpt-4o-mini |
| WEBZINE_MODEL | 网摘专用模型 | deepseek-v3.2-250518 |

### config.json 配置项

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| time_window_hours | 时间窗口（小时） | 12 |
| max_articles | 最多保留文章数 | 15 |
| top3_count | TOP3 必看文章数 | 3 |
| wechat_target | 微信接收者ID | - |
| wechat_account | 微信机器人账号 | - |
| enable_wechat_push | 开启微信推送 | true |
| enable_feishu_push | 开启飞书推送 | false |
| enable_image_gen | 开启图片生成 | true |
| enable_txt_gen | 开启TXT文件生成 | true |

### rss_feeds.txt 订阅源配置
所有RSS源都在`config/rss_feeds.txt`文件中管理，不需要修改代码即可增删订阅源：
- 格式：每行 `源名称|RSS地址`
- 以`#`开头的行是注释，会自动忽略
- 空行会自动跳过
- 修改后直接运行程序，无需重启或改代码
- ✅ 容错保障：文件不存在、为空或格式错误时，自动回退使用内置的12个默认源，不会影响程序运行
- 支持所有标准RSS/Atom格式，中英文源无需区分，系统自动识别翻译

## ⏰ 定时任务

### 方式一：宿主机 crontab

```bash
make install-cron
# 或手动添加
crontab -e
# 加入：0 8 * * * cd /path/to/military-digest-v3 && python3 scripts/military_daily_report_v3.py >> logs/cron.log 2>&1
```

### 方式二：Docker Cron

```bash
docker-compose --profile cron up -d
```

## 🔍 RSS 源列表

1. Defense One - 美国防务新闻
2. NEWUAS - 无人机系统新闻
3. Seapower - 海军力量杂志
4. The War Zone - 战区军事分析
5. 国防科技要闻
6. 战略前沿技术
7. 无人机邦
8. 浮空飞行器
9. 海鹰资讯
10. 渊亭防务
11. 电波之矛
12. 龙牙的一座山

## 📊 输出示例

```
🪖 军事科技每日摘要
📅 2026年05月12日 | 共收录 12 篇

====================
🔥 今日必看 TOP3
====================

1.【美军MQ-9无人机测试发射激光制导火箭弹】
   ⭐ 综合评分：9.2/10
   📰 来源：The War Zone
   📝 摘要：美国通用原子公司联合美空军在内华达测试场完成...
   🔮 深度洞察：低成本改装令察打无人机获得反无人机能力...
   🔗 阅读原文：...

...
```

## 🔄 数据流程

```
main()
  ├── Step 1:   RSS 并行抓取（ThreadPoolExecutor × MAX_THREADS 并发，内置重试）
  ├── Step 2:   24小时时间窗口过滤
  ├── Step 3:   同源标题去重
  ├── Step 4:   SQLite 缓存查询（分离已处理/待处理文章）
  ├── Step 5:   外文标题并发翻译（ThreadPoolExecutor × AI_CONCURRENCY）
  ├── Step 6:   关键词筛选（仅当 >15篇）
  ├── Step 7:   外文正文并发翻译（仅筛选通过的文章，大幅省 token）
  ├── Step 8:   批量 AI 评分 + 分类 + 摘要（并发）
  ├── Step 9:   新处理文章写入 SQLite 缓存
  ├── Step 10:  合并缓存+新文章，按评分降序
  ├── Step 11:  TOP3 网摘生成（优先缓存命中，支持字数重试，TXT+PNG）
  ├── Step 12:  四分类整理 + 深度洞察生成（优先缓存命中）
  ├── Step 13:  Markdown 报告输出（全缓存+文件已存在则跳过）
  ├── Step 14:  多渠道推送（企业微信/飞书 webhook，失败优雅降级）
  └── 监控报告输出（阶段耗时/API+token统计/源成功率/缓存命中率）
```

## ✅ 系统要求

- Python 3.8+ 或 Docker
- OpenAI API Key（或兼容API，如火山引擎、DeepSeek等）
- 内存 ≥ 512MB
- 磁盘 ≥ 1GB

## ❓ 常见问题

### 生成的图片中文字体乱码怎么办？
无需额外配置，代码已自动适配所有主流系统的自带中文字体：
- Windows: 自动匹配宋体/黑体/微软雅黑
- Linux: 自动匹配NotoSansCJK/文泉驿微米黑
- macOS: 自动匹配PingFang/黑体

如果需要完全不依赖系统字体，可以下载开源无版权的NotoSansCJK字体放到`scripts/modules/assets/fonts/`目录下：
- 粗体：`NotoSansCJK-Bold.ttc`
- 常规：`NotoSansCJK-Regular.ttc`

### 日志输出在哪里？
日志默认输出到标准错误流，包含INFO/WARNING/ERROR三个级别，运行时会实时打印到控制台，也可以重定向到日志文件：
```bash
python scripts/military_daily_report_v3.py >> logs/runtime.log 2>&1
```

---

*V3 版本 - 全流程重构 + 模块化拆分 + 跨系统字体适配 + 日志标准化 + Markdown报告输出，2026年5月发布*