signal-intelligence

多源情报分析系统 — 从 RSS、World Monitor 等多来源获取事件线索，提取实体与主张，交叉验证，生成分析报告。

快速启动

# 使用 Docker（推荐）
docker compose up

# 访问界面
open http://localhost:8000/reports   # 每日情报简报
open http://localhost:8000/status    # 系统运行状态
open http://localhost:8000/docs      # API 文档

⚠️ 默认使用 Mock 模式。Docker Compose 不再覆盖 .env 中的 WORLD_MONITOR_MOCK / DATAFORSEO_MOCK。API 鉴权默认关闭（开发模式）； 部署到公网前必须设置 API_KEY。详情见下方鉴权说明。

运行管道

一键触发事实分析链路（采集 → 实体提取 → 事件聚类 → 主张提取 → 证据关联 → 冲突识别 → 评分 → 评估 → 引用报告）：

curl -X POST http://localhost:8000/api/v1/pipeline/run

系统架构

用户界面 (/reports, /status)
    │
API (FastAPI /api/v1)
    │
服务层
├── PipelineService — 端到端分析管道
├── 采集引擎 — RSS/Web 采集 + trafilatura 提取
├── 适配器 — World Monitor / DataForSEO（可插拔 Mock/真实）
├── 实体提取 — 关键词规则匹配
├── 主张提取 — 正则模式匹配
├── 评分引擎 — 透明置信度公式
└── 调度器 — APScheduler 定时采集
    │
数据库 (PostgreSQL 16)
├── sources / documents
├── entities / events / claims / evidence
├── assessments / search_signals
└── daily_metrics

Mock 模式 vs 真实模式

服务	环境变量	Mock 模式	真实模式
World Monitor	WORLD_MONITOR_MOCK=true/false	返回模拟新闻/风险数据	需设置 WORLD_MONITOR_API_KEY
DataForSEO	DATAFORSEO_MOCK=true/false	返回模拟搜索量/难度	需设置 DATAFORSEO_LOGIN/PASSWORD

系统状态页面（/status）顶栏和简报页面（/reports）会清晰标注当前运行模式。

API 鉴权

默认开发模式不开启鉴权。部署到公网前必须启用：

1. 设置环境变量 API_KEY=your-secret-key
2. AUTH_ENABLED=true（或留空，检测到 API_KEY 非空时自动建议开启）
3. 可选：AUTH_READONLY=true 让 GET 读取操作也需要鉴权
4. 可选：API_KEY_HEADER_NAME=X-API-Key 自定义请求头名称

# 使用 API Key 调用写操作
curl -X POST http://localhost:8000/api/v1/pipeline/run \
  -H "X-API-Key: your-secret-key"

鉴权规则：

• /health, /docs, /status, /reports 始终公开
• GET /api/v1/* 读操作默认公开（AUTH_READONLY=true 时需鉴权）
• POST/PUT/DELETE/PATCH 写操作全部需鉴权
• 密钥仅从环境变量读取，不进入日志、响应或 Git
• 使用 hmac.compare_digest() 防止时序攻击

DataForSEO 当前是可选的搜索信号研究能力，未接入自动事实分析管道，也不作为 Claim 的事实证据。World Monitor 的真实 API 路径和响应结构尚待契约测试；在完成前， 真实模式不能视为生产验证通过。Mock 数据仅用于测试和演示，不代表真实运行结果。

开发

# 初始化
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 配置
cp .env.example .env
# 编辑 .env 中的 DATABASE_URL（本地开发用 localhost，Docker 用 db）

# 迁移
alembic upgrade head

# 启动
uvicorn app.main:app --reload

# 测试
pytest --cov=app --cov-report=term-missing
ruff check .
mypy app/

API 端点

端点	说明
GET /health	健康检查
GET /docs	Swagger API 文档
POST /api/v1/pipeline/run	触发完整分析管道
GET /api/v1/sources	来源 CRUD
GET /api/v1/documents	文档列表
POST /api/v1/collection/feed	RSS 采集
GET /api/v1/entities	实体 CRUD
GET /api/v1/events	事件 CRUD
GET /api/v1/claims	主张 CRUD
GET /api/v1/evidence	证据 CRUD
GET /api/v1/reports/briefing	简报 JSON
GET /api/v1/reports/events/{id}	事件详情 JSON
POST /api/v1/world-monitor/news	World Monitor 采集
POST /api/v1/seo/keywords	搜索信号采集
GET /api/v1/status/health	系统健康 JSON
GET /api/v1/status/metrics	运行指标 JSON

去重策略

1. URL Hash — source_id + url_hash 唯一约束，防止同一来源重复采集同一 URL
2. Content Hash — 正文 SHA-256 完全匹配检测
3. 标题相似度 — Jaccard 相似度 >0.7 判定为潜在重复
4. 正文相似度 — 3-句 shingle Jaccard 相似度检测

项目状态

模块	状态
项目骨架 (FastAPI + SQLAlchemy + Alembic)	✅
来源与 RSS 采集	✅
事件与证据模型	✅
World Monitor 适配	✅
OpenSEO/DataForSEO 适配	✅
报告与界面	✅
固定 Mock RSS 事实链路验收	✅
SEO 自动接入事实管道	⏳ 未接入
World Monitor 真实 API 契约验证	⏳ 未完成
API 鉴权与公网部署保护	✅
7 天真实运行验证	⏳ 未完成
运行状态监控	✅