docs: 更新大模型场景配置与去重多源记录说明

- README: 新增「大模型使用场景配置」章节(4 场景表+优先级),M3 去重产物补充
  sources.json 与多源记录说明,M4/M5 环境变量补充 YAML 指引
- continuation.md: checkpoint 更新,记录本次功能实现与验证结果
- .env.example: LLM Provider 段补充 configs/llm_models.yaml 指引

.env.example

@@ -5,6 +5,7 @@
 # ============================
 
 # ---- LLM Provider ----
+# 推荐: 各场景按需独立配置见 configs/llm_models.yaml(优先级高于以下环境变量)
 LLM_PROVIDER=deepseek
 
 # ---- DeepSeek ----

README.md

@@ -209,12 +209,34 @@ uv run python -m scripts.run_dedup --reset
 
 去重产物路径:
 
-- `data/dedup/fingerprints.sqlite3`         指纹库(跨日累积)
-- `data/deduped/{YYYYMMDD}/uniques/{url_hash}.json`  唯一文章(可送 M4+ 处理)
-- `data/deduped/{YYYYMMDD}/duplicates.jsonl`        重复记录(含命中层 / 命中目标)
+- `data/dedup/fingerprints.sqlite3`         指纹库(跨日累积,`source_ids` 列记录多源)
+- `data/deduped/{YYYYMMDD}/uniques/{url_hash}.json`  唯一文章(可送 M4+ 处理,含 `sources` 多源字段)
+- `data/deduped/{YYYYMMDD}/sources.json`            多源记录 `{url_hash: [source_id, ...]}`
+- `data/deduped/{YYYYMMDD}/duplicates.jsonl`        重复记录(含命中层 / 命中目标 / matched_source_ids)
+
+**多源记录**:同一内容被多个新闻源发布时,去重后只保留一条唯一新闻,但会记录全部来源
+(主源居首)。指纹库 `source_ids` 列为跨日累积的权威记录;`uniques/{url_hash}.json` 的
+`sources` 字段与 `data/deduped/{YYYYMMDD}/sources.json`(本次去重涉及内容组的源汇总,
+含跨日命中)为当日产物,展示/下游可按需读取多源列表。
 
 日志:`logs/dedup.log`
 
+### 大模型使用场景配置(configs/llm_models.yaml)
+
+项目共 4 个调用大模型的场景,均可独立配置 provider / model,见 `configs/llm_models.yaml`
+(文件内有每个场景的用途、使用方式、对模型的要求的完整说明):
+
+| 场景 key | 用途 | 调用方 | 模型要求 |
+| --- | --- | --- | --- |
+| `event_extraction` | 投资事件抽取(输出严格 JSON) | M4 `llm/extractor.py` | OpenAI 兼容 + JSON mode + 上下文 ≥16K |
+| `daily_report` | 日报 AI 摘要(500 字要点) | `scheduler/reporter.py` | 长输出(≥1500 tokens)、中文摘要 |
+| `stock_report` | 个股 AI 要点分析 | `scheduler/stock_reporter.py` | 长输出(≥500 tokens)、要点化 |
+| `embedding` | 文本向量化(入库/检索) | M5、MCP、pipeline | 嵌入模型,1024 维,dashscope / local-bge |
+
+配置优先级:**CLI 显式参数 > YAML 场景 > .env 环境变量 > 代码默认**。
+YAML 中字段留空即回退 `.env`(向后兼容,现有部署无需改动即可运行)。
+API Key 一律放 `.env`,YAML 只保存环境变量名(`api_key_env`)。
+
 ### 运行 LLM 事件抽取(M4)
 
 M4 调用 DeepSeek 或 Qwen,从 M3 唯一文章中抽取结构化投资事件(stock_codes/sentiment/importance/event_type 等)。
@@ -253,6 +275,9 @@ uv run python -m scripts.run_event_extraction --no-deduped --source cls
 - `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`
 - `DASHSCOPE_API_KEY` / `QWEN_BASE_URL`
 
+> 注:以上环境变量作为兜底;按场景独立配置 provider/model 推荐使用
+> `configs/llm_models.yaml`(见上文「大模型使用场景配置」)。
+
 日志:`logs/llm.log`
 
 ### 运行 Embedding 向量化(M5)
@@ -288,6 +313,9 @@ uv run python -m scripts.run_embedding --provider local-bge
 - `LOCAL_EMBEDDING_MODEL`        本地模型(默认 `BAAI/bge-m3`)
 - `DASHSCOPE_API_KEY` / `QWEN_BASE_URL`(M4 已配)
 
+> 注:以上环境变量作为兜底;embedding 场景的 provider/model 也可在
+> `configs/llm_models.yaml` 的 `scenes.embedding` 中配置(优先级更高)。
+
 日志:`logs/embedding.log`
 
 ### 运行 Qdrant 入库与检索(M6)

continuation.md

@@ -1,6 +1,6 @@
 # continuation.md
 
-> `checkpoint` @ 2026-08-05 08:30
+> `checkpoint` @ 2026-08-11 17:00
 
 ---
 
@@ -13,12 +13,49 @@
 | 日报 | **M10 完成并已部署 pi5: 结构化入库 MySQL；日报按当天日期生成（新闻 30h 回溯 / xwlb 取前一日 / 公告调研近 15 日）** |
 | DB 连接 | pi 上 systemd 服务 `a-share-db-tunnel` 常驻（0.0.0.0:13306 → doorcome.cn:3306）；**pi5 直连 192.168.1.10:13306** |
 | 调度器 | APScheduler，systemd `a-share-research.service`（pi5）；每天 07:00 首次任务生成日报（12/18/22 点不生成） |
-| LLM | `deepseek-v4-flash`（绝不允许擅自修改；模型必须显式配置，无内置兜底） |
+| LLM | 场景化配置 `configs/llm_models.yaml`（4 场景: event_extraction/daily_report/stock_report/embedding）；YAML 优先、`.env` 兜底；模型必须显式配置，无内置兜底 |
+| 去重 | 多源记录：指纹库 `source_ids` 列 + uniques JSON `sources` 字段 + `data/deduped/{day}/sources.json` |
 | 服务器 | `pi@192.168.1.160`（生产）/ `pi@192.168.1.10`（DB 隧道宿主） |
 | 抓取方式 | js_render=false → httpx 直连；js_render=true → Playwright |
 
 ---
 
+## 本次完成 (2026-08-11) — 大模型场景化配置 + 去重多源记录
+
+**目标：** ① 梳理全部 AI 大模型使用点，新增 `configs/llm_models.yaml` 按场景独立配置 provider/model；② 去重时记录一条唯一新闻的全部来源。
+
+**1. 大模型使用点梳理（共 4 个场景，详见 configs/llm_models.yaml 内注释）：**
+- `event_extraction`（M4 投资事件抽取，JSON mode，llm/extractor.py）
+- `daily_report`（日报 AI 摘要，scheduler/reporter.py）
+- `stock_report`（个股 AI 要点分析，scheduler/stock_reporter.py）
+- `embedding`（向量化，dashscope 远程 / local-bge 本地，embedding/remote.py + local.py）
+- 非使用点确认：crawler 纯抓取、MCP 仅复用 embedding、run_xwlb 抓外部「AI 精编」数据源
+
+**2. 场景配置实现（优先级: CLI 显式参数 > YAML > .env > 内置默认）：**
+- 新增 `configs/loader.py`（lru_cache 读 llm_models.yaml）+ `configs/__init__.py`
+- `llm/client.py`：`load_llm_config(scene=...)` 支持场景；`LLMConfig` 增加 `max_attempts`；模型缺失仍报错（无内置兜底）
+- `llm/extractor.py`：`extract_event(_async)` 的 max_attempts 默认取 `config.max_attempts`
+- `embedding/factory.py` + `remote.py` + `local.py`：provider/model/api_key_env/base_url_env/batch_limit 支持场景覆盖
+- `scheduler/reporter.py`（daily_report）+ `stock_reporter.py`（stock_report）：接入场景，temperature 取配置
+- YAML 中 provider/model 默认留空 → 回退 .env，**现有部署零改动兼容**
+
+**3. 去重多源记录：**
+- `dedup/models.py`：`Fingerprint.source_ids`（validator 保主源居首+去重）；`DedupResult` 增 `matched_source_id`/`all_source_ids`
+- `dedup/store.py`：指纹库加 `source_ids` 列，旧库自动 ALTER 迁移，旧数据回退 `[source_id]`
+- `dedup/deduper.py`：`ingest` 命中重复时把新源合并进匹配指纹
+- `scripts/run_dedup.py`：uniques JSON 附加 `sources` 字段；重复命中时仅更新 sources 不覆盖原文；输出 `data/deduped/{day}/sources.json` 汇总
+
+**验证（Mac 本地）：**
+- 全量 pytest：**215 passed**（仅 crawler 3 个 retry mock 失败为基线预存在问题，与本改动无关）
+- 端到端人工构造 3 源同文：1 条唯一 + sources.json `["cls","eastmoney","sina"]` + 指纹库 source_ids 列正确
+- ruff：9 个错误均为基线既有（crawler/cninfo.py 未用 import、reporter.py L5/L4 命名），本次零新增
+
+**待办：**
+- 生产同步：代码 + `configs/llm_models.yaml` scp 到 pi5（注意 rsync 排除规则含 configs/*.yaml，需显式同步），重启 `a-share-research` 生效
+- 首次同步前 pi5 无 YAML → 全部回退 .env，行为不变，可平滑切换
+
+---
+
 ## 本次完成 (2026-08-05) — 日报可靠性修复与取数逻辑优化
 
 **目标：** 解决日报 AI 摘要偶发失败；修正日报日期与 xwlb/新闻取数语义。