fix: update

crawler/README.md

@@ -54,6 +54,86 @@ pip install -r requirements.txt
 
 **事件脉络不更新时**：多半是未启动 `npm run gdelt`。只跑 `npm run api` 时，事件脉络会显示空或仅有缓存。
 
+## 如何检查爬虫是否工作正常
+
+按下面顺序做即可确认整条链路（爬虫 → 数据库 → Node 重载 → API/WebSocket）正常。
+
+### 1. 一键验证（推荐）
+
+先启动 API，再执行验证脚本（可选是否顺带启动爬虫）：
+
+```bash
+# 终端 1：必须
+npm run api
+
+# 终端 2：执行验证（不启动爬虫，只检查当前状态）
+./scripts/verify-pipeline.sh
+
+# 或：顺带启动爬虫并等首次抓取后再验证
+./scripts/verify-pipeline.sh --start-crawler
+```
+
+脚本会检查：API 健康、态势数据含 `lastUpdated`、爬虫服务是否可达、`news_content`/situation_update、战损字段、`POST /api/crawler/notify` 是否可用。
+
+### 2. 手动快速检查
+
+| 步骤 | 命令 / 操作 | 正常表现 |
+|-----|-------------|----------|
+| API 是否在跑 | `curl -s http://localhost:3001/api/health` | 返回 `{"ok":true}` |
+| 态势是否可读 | `curl -s http://localhost:3001/api/situation \| head -c 300` | 含 `lastUpdated`、`usForces`、`recentUpdates` |
+| RSS 能否抓到 | `npm run crawler:test` | 输出「RSS 抓取: N 条」，N>0 表示有命中 |
+| 爬虫服务（gdelt） | `curl -s http://localhost:8000/crawler/status` | 返回 JSON，含 `db_path`/`db_exists` 等 |
+| 库里有无爬虫数据 | `sqlite3 server/data.db "SELECT COUNT(*) FROM situation_update; SELECT COUNT(*) FROM news_content;"` 或访问 `http://localhost:3001/api/db/dashboard` | situation_update、news_content 条数 > 0（跑过流水线后） |
+| 通知后是否重载 | 爬虫写库后会 POST `/api/crawler/notify`，Node 会 `reloadFromFile` 再广播 | 前端/`/api/situation` 的 `lastUpdated` 和内容会更新 |
+
+### 3. 跑一轮流水线（不常驻爬虫时）
+
+不启动 gdelt 时，可单次跑完整流水线（抓取 → 去重 → 写表 → notify）：
+
+```bash
+npm run api   # 保持运行
+cd crawler && python3 -c "
+from pipeline import run_full_pipeline
+from config import DB_PATH, API_BASE
+n_fetched, n_news, n_panel = run_full_pipeline(db_path=DB_PATH, api_base=API_BASE, notify=True)
+print('抓取:', n_fetched, '去重新增:', n_news, '面板写入:', n_panel)
+"
+```
+
+有网络且有关键词命中时，应看到非零数字；再查 `curl -s http://localhost:3001/api/situation` 或前端事件脉络是否出现新数据。
+
+### 4. 仅测提取逻辑（不写库）
+
+```bash
+npm run crawler:test:extraction   # 规则/db_merge 测试
+# 或按 README「快速自测命令」用示例文本调 extract_from_news 看 combat_losses_delta / key_location_updates
+```
+
+**常见现象**：抓取 0 条 → 网络/RSS 被墙或关键词未命中；situation_update 为空 → 未跑流水线或去重后无新增；前端不刷新 → 未开 `npm run api` 或未开爬虫（gdelt）。
+
+### 5. 爬虫与面板是否联通
+
+专门检查「爬虫写库」与「面板展示」是否一致：
+
+```bash
+./scripts/check-crawler-panel-connectivity.sh
+```
+
+会对比：爬虫侧的 `situation_update` 条数 vs 面板 API 返回的 `recentUpdates` 条数，并说明为何战损/基地等不一定随每条新闻变化。
+
+## 爬虫与面板数据联动说明
+
+| 面板展示 | 数据来源（表/接口） | 是否由爬虫更新 | 说明 |
+|----------|---------------------|----------------|------|
+| **事件脉络** (recentUpdates) | situation_update → getSituation() | ✅ 是 | 每条去重后的新闻会写入 situation_update，Node 收到 notify 后重载 DB 再广播 |
+| **地图冲突点** (conflictEvents) | gdelt_events 或 RSS→gdelt 回填 | ✅ 是 | GDELT 或 GDELT 禁用时由 situation_update 同步到 gdelt_events |
+| **战损/装备毁伤** (combatLosses) | combat_losses | ⚠️ 有条件 | 仅当 AI/规则从新闻中提取到数字（如「2 名美军死亡」）时，merge 才写入增量 |
+| **基地/地点状态** (keyLocations) | key_location | ⚠️ 有条件 | 仅当提取到 key_location_updates（如某基地遭袭）时更新 |
+| **力量摘要/指数/资产** (summary, powerIndex, assets) | force_summary, power_index, force_asset | ❌ 否 | 仅 seed 初始化，爬虫不写 |
+| **华尔街/报复情绪** (wallStreet, retaliation) | wall_street_trend, retaliation_* | ⚠️ 有条件 | 仅当提取器输出对应字段时更新 |
+
+因此：**新闻很多、但战损/基地数字不动**是正常现象——多数标题不含可解析的伤亡/基地数字，只有事件脉络（recentUpdates）和地图冲突点会随每条新闻增加。若**事件脉络也不更新**，请确认 Node 终端在爬虫每轮抓取后是否出现 `[crawler/notify] DB 已重载`；若无，检查爬虫的 `API_BASE` 是否指向当前 API（默认 `http://localhost:3001`）。
+
 ## 写库流水线（与 server/README 第五节一致）
 
 RSS 与主入口均走统一流水线 `pipeline.run_full_pipeline`：
@@ -80,6 +160,7 @@ RSS → 抓取 → 清洗 → 去重 → 写 news_content / situation_update /
 
 - `DB_PATH`: SQLite 路径，默认 `../server/data.db`
 - `API_BASE`: Node API 地址，默认 `http://localhost:3001`
+- **`DASHSCOPE_API_KEY`**：阿里云通义（DashScope）API Key。**设置后全程使用商业模型，无需本机安装 Ollama**（适合 Mac 版本较低无法跑 Ollama 的情况）。获取： [阿里云百炼 / DashScope](https://dashscope.console.aliyun.com/) → 创建 API-KEY，复制到环境变量或项目根目录 `.env` 中 `DASHSCOPE_API_KEY=sk-xxx`。摘要、分类、战损/基地提取均走通义。
 - `GDELT_QUERY`: 搜索关键词，默认 `United States Iran military`
 - `GDELT_MAX_RECORDS`: 最大条数，默认 30
 - `GDELT_TIMESPAN`: 时间范围，`1h` / `1d` / `1week`，默认 `1d`（近日资讯）