Files

T

simon 3b44f64f66 refactor: 清理历史 AI Agent 文档残留 + 重构 docs/ + Pipeline 健壮性修复

- docs: 删除 CLAUDE.md / continuation.md / english-news-plan.md 及旧版 intlnews_usage.*，
        统一迁移到 docs/{README,architecture,quickstart,usage,pipeline,configuration,deployment,development,faq}.md
- README: 精简为仓库入口，指向 docs/
- configs/sources.yaml: 更新注释指向新文档
- .env.example: 修正 DashScope Embedding 端点说明

Pipeline 修复：
- dedup/llm/embedding/vectorstore/reporter: 过滤 M2 no_content / 空正文，避免污染下游与 Qdrant
- dedup/pipeline: 改为先写唯一文件再写指纹，避免崩溃导致文章永久丢失
- crawler/orchestrator: sources_crawled 改为“尝试数”，成功数 = crawled - failed
- crawler/storage: write_index_jsonl 从文章路径推断日期，修复跨天/测试路径问题
- scheduler/pipeline: STEP_TIMEOUTS 实际生效（SIGALRM）
- scheduler/reporter: emb_count 排除 index.json；日报跳过无原文事件
- vectorstore/pipeline: payload 增加 source_ids；--recreate --all 时空日期也重建 collection
- app/cli: extract/dedup/translate/embed/index/pipeline 支持 --date；embed/index 支持 --all；crawl 全源失败返回非零
- scripts: domestic_full/crawl_8g/crawl_2g/pipeline 安全加载 .env；M1 全失败不标记且最终退出码=1

2026-08-22 20:47:53 +08:00

4.4 KiB

Raw Blame History

使用手册

1. CLI 命令（`uv run en-news`）

命令	功能	常用参数
`crawl`	M1 抓取新闻	`--source/-s <id>` 只抓单源；`--profile/-p` 指定 Profile
`extract`	M2 正文提取	`--source/-s <id>` 只处理单源；`--date/-d` 指定日期
`dedup`	M3 三层去重	`--date/-d` 指定日期
`translate`	M4 翻译+事件抽取	`--date/-d` 指定日期
`embed`	M5 向量生成	`--date/-d` 指定日期；`--all` 处理全部日期
`index`	M6 写入 Qdrant	`--recreate` 重建；`--date/-d` 指定日期；`--all` 全量回灌
`search`	M6 语义检索	必需 query；`--top-k` 返回条数
`report`	M9 生成日报并入库	无
`pipeline`	M2→M6（+日报）	`--skip-report` 跳过日报；`--date/-d` 指定日期
`mcp-server`	M8 启动 MCP 服务	无

示例：

# 只抓取 CNBC
uv run en-news crawl --source cnbc

# 单步正文提取
uv run en-news extract

# 搜索
uv run en-news search "美联储" --top-k 5

# 重建 Qdrant collection（慎用！会清空现有向量）
uv run en-news index --recreate

# 指定历史日期处理
uv run en-news translate --date 20260801
uv run en-news embed --date 20260801
uv run en-news index --date 20260801

# 全量回灌历史向量（--recreate 搭配 --all 时只会在首个日期重建 collection）
uv run en-news index --all
uv run en-news embed --all

2. Shell 脚本

脚本	用途
`scripts/domestic_full.sh`	国内服务器全流程：M1 抓取 + M2→M6 管道 + 日报
`scripts/domestic_full.sh --resume`	同上，但跳过当天已完成步骤
`scripts/pipeline.sh`	仅 M2→M6 管道 + 日报
`scripts/pipeline.sh --resume`	同上，支持步骤级断点续跑
`scripts/domestic_crawl_8g.sh [source]`	8G headful + HTTP 代理抓取 M1
`scripts/domestic_crawl_2g.sh [source]`	2G headless stealth 轻量抓取 M1
`scripts/cleanup_logs.sh`	清理 14 天前日志
`scripts/domestic_sync.sh [date]`	从海外服务器同步 raw 数据（海外已停用，保留兼容）

2.1 全流程示例

cd /home/pi/intlnews

# 每天定时任务可执行
bash scripts/domestic_full.sh

# 手动中断后继续
bash scripts/domestic_full.sh --resume

2.2 步骤级断点说明

步骤状态记录在 data/run_state/{YYYYMMDD}.state：

每成功一个步骤追加一行，如 M1_crawl、M2_extract、M3_dedup、M4_translate、M5_embed、M6_index、report。
--resume 只跳过已标记步骤；失败步骤不会标记，所以会从失败处重试。
跨天自动失效，状态文件按天隔离。

3. MCP 服务（M8）

MCP 是给 Cherry Studio / Claude Code 等 Agent 客户端接入的研究工具层。

启动：

uv run en-news mcp-server

提供工具：

工具	功能
`search_news`	语义检索新闻
`search_by_stock`	按美股代码检索相关事件
`search_by_sentiment`	按情绪倾向（利好/利空/中性）过滤检索
`get_today_events`	获取当日重要投资事件
`get_stats`	获取系统统计概览

具体接入方式由客户端决定，通常是在 MCP 配置中指向 uv run --directory /path/to/intlnews en-news mcp-server。

4. 日报查看

日报已结构化写入 MySQL：

主表：news_report
- report_type = 'intl'
- ai_summary 为 AI 日报摘要
- stats 为 JSON 统计快照
明细表：news_event
- section = 'intl'
- 包含标题、摘要、来源、情绪、重要度、URL

可通过 SQL 查看最新日报：

SELECT id, report_date, generated_at, ai_summary
FROM news_report
WHERE report_type = 'intl'
ORDER BY report_date DESC, generated_at DESC
LIMIT 5;

5. 日志

全流程日志：logs/domestic_full_{YYYYMMDD_HHMMSS}.log
管道日志：logs/pipeline_{YYYYMMDD_HHMMSS}.log
运行时也实时输出到终端。

快速查看最近日志：

tail -100 logs/pipeline_$(ls -t logs/pipeline_*.log | head -1 | sed 's#logs/##')

6. 常见操作组合

目标	命令
只抓取新闻	`bash scripts/domestic_crawl_8g.sh`
从已有 raw 跑全管道	`uv run en-news pipeline --skip-report`
增量补齐翻译	`uv run en-news translate`（自动跳过已有）
只生成日报	`uv run en-news report`
搜索知识库	`uv run en-news search "关键词"`
启动 MCP	`uv run en-news mcp-server`

4.4 KiB Raw Blame History Unescape Escape