# 路线图

> Phase 1 已交付 MVP,Phase 2 / 3 按 PRD §5 推进。

## 0. 总览

```
Phase 1: Research Agent   ✅  已完成 (rules-based MVP)
Phase 2: Tracking Agent   ⏳  待启动
Phase 3: Decision Agent   ⏳  待启动
```

每阶段的"完成定义"沿用 PRD §5 的边界,不蔓延。

## 1. Phase 1 — Research Agent (DONE)

**目标**:从原始事件文本 → 结构化分类 → 聚合周报,本地能闭环跑通。

### 1.1 已交付

| 模块 | 文件 | 状态 |
|---|---|---|
| 本体 ontology | `ontology.py` | ✅ 4 主线 / 6 场景 / 6 维度 / Thesis 三态 + 关键词词典 |
| Rules-based 分类器 | `classifier.py` | ✅ 含负向反义 + RISK fallback + dedupe 防护 |
| SQLite schema | `db.py` | ✅ events / companies / market_model / thesis_state 4 表 |
| CRUD + 公司反哺 | `repository.py` | ✅ `enrich_with_company_threads` |
| 种子数据 | `seed.py` | ✅ 84 条市场模型 + 6 家代表公司 |
| 周报生成 | `report.py` | ✅ markdown + JSON 双格式 |
| 回归评测 | `regress.py` | ✅ 整体指标 + per-thread P/R/F1 + 失败列表 |
| CLI | `cli.py` | ✅ 9 个子命令 |
| FastAPI | `api.py` | ✅ 8 个业务端点 + /health |
| 测试 | `tests/` | ✅ 18 个 test,含 30 条样本回归 |

### 1.2 当前指标 (round 1 修复后)

- 30 条 labeled regression: **100% 三项全过**
- per-thread macro F1: **1.000**
- pytest: **18 / 18 通过**
- 全链路 smoke test: ✅ CLI + FastAPI 都验证

### 1.3 已知 limitations (留给 Phase 2 / 3 解决)

参见 [`regression.md` §6](./regression.md#6-已知-limitations)。

## 2. Phase 2 — Tracking Agent (TODO)

**目标**:让 agent 自己抓数据,从被动入库 → 主动巡检。**抓取 schema 必须为 Phase 3 决策层准备好数字字段**——这是本阶段的核心约束,与 PRD §3.1 / §3.2.2 对齐。

### 2.1 拆解

| Story | 复杂度 | 建议优先级 | 备注 |
|---|---|---|---|
| 真实新闻 20-50 条盲测,回归基线再评 | M | ✅ 完成 | 见 [`regression-real.md`](./regression-real.md) |
| 词典扩展(rules v1) | S | ✅ 完成 | 三项全过 40% → 64% |
| LLM 兜底分类(置信度低或 thread 命中 ≥ 3) | L | **P0** | 升级原 P2 → P0, 目标真实集三项全过 ≥ 85% |
| 公司反哺改弱信号 + confidence 折扣 | S | P0 | 与 LLM 兜底同批 |
| events 表 schema 扩展(订单金额 / capex / opex / 客户主体) | M | **P0** | **决策层依赖, 不做这个 Phase 3 没米下锅** |
| 公司卡片字段扩展(orders / revenue_mapping / peer_rank) | M | P0 | 同上 |
| 接 RSS / 公司公告抓取 + 金额解析 | L | P1 | 抓取必须解析订单金额, 不能只存事件文本 |
| 自动归类入库(复用 ingest pipeline) | S | P1 | |
| Thesis impact 实时评分 → `thesis_state` 表写入 | M | P1 | |
| 风险预警推送(置信度 + 主线 + 用户订阅) | M | P2 | |

### 2.2 入口点

- 抓取层独立成 `satellite_agent/sources/` 子包,每个数据源一个模块 (`sources/wechat.py` / `sources/sse.py` / `sources/rss.py`)
- 公共 `Source` 接口:`fetch() -> Iterator[RawEvent]`,其中 `RawEvent` 字段须支持 `numeric_fields: dict`(订单金额 / 时间窗 / 客户主体的解析结果)
- 调度器优先选 `schedule` 库或 cron 表达式 + asyncio
- 抓到的 raw 直接走 `classify` + `extract_numeric` + `insert_event`,新增 `extract_numeric` 子步骤(可用正则 + LLM 兜底)

### 2.3 完成定义

- LLM 兜底跑通,真实集三项全过 ≥ 85%
- events 表扩展字段 + 公司卡片扩展字段,migration 落档
- 至少 3 个数据源跑通(公司公告 / 工信部 / 行业 RSS),每条事件带 ≥ 1 个 numeric_field
- 真实新闻盲测准确率 ≥ 85% (三项全过, 替代原 75% threads-only 目标)
- 风险预警端点 `/alerts` 可订阅
- 定时任务可一键起,失败有重试与日志

## 3. Phase 3 — Decision Agent · 决策辅助 (TODO)

**目标**:从"看清楚"到"判清楚",输出**双视角决策建议** —— CEO 看战略,投资人看仓位。**不是**自动生成 DOCX / Excel / PPT(那只是分发载体)。本阶段对齐 PRD §3.3 决策层。

### 3.1 拆解

#### 3a · CEO 视角(产业决策)

| Story | 复杂度 | 备注 |
|---|---|---|
| 主驱动变量识别 + 强度评分(本周期 top-3) | L | 输入:Phase 2 事件分布 + 数字字段;输出:本周"是哪个变量在推动产业" |
| 主线评分(本周 vs 上周变化 + 驱动归因) | M | 每条主线评分变化,归因到具体事件 |
| 战略建议生成(进入 / 等待 / 退出 / 加速)+ 触发条件 | L | 建议挂在变量上,带"达到 X 阈值即触发" |
| 风险预警 + 下周跟踪清单 | S | 沿用 Phase 2 alerts,加 CEO 视角的关键问题 |

#### 3b · 投资视角(二级市场)

| Story | 复杂度 | 备注 |
|---|---|---|
| 市场模型动态更新(用真实 capex / opex / 订单修正情景) | L | 替代 seed.py 占位数 |
| 同主线公司相对位势矩阵 | M | 估值 × 订单变化 × thesis 影响 → 排序 |
| 仓位调节信号(主线级 加 / 减 / 持)+ 证据链 | L | 信号必须带 evidence:近 N 周的驱动力变化 + 公司订单变化 |
| 公司估值映射(订单 / 收入 → DCF / PE) | XL | 接入 Phase 3a 主驱动变量作为情景假设 |
| 异常告警(超预期订单 / 监管事件 / 业绩反转) | M | 触发后立即写仓位信号 |

#### 3c · 分发载体(附属,不是产品价值本身)

| Story | 复杂度 | 备注 |
|---|---|---|
| DOCX 自动生成(python-docx) | M | 包装 3a + 3b 输出 |
| Excel 自动生成(openpyxl + pivot)| M | 仓位矩阵 + 公司排名 |
| PPT 自动生成(python-pptx + 模板) | M | CEO / 投资双版本模板 |
| 多 agent 辩论编排(参考 `web/app.html` 工作台) | L | 辩论结果反哺仓位信号置信度 |

### 3.2 完成定义

- **CEO 双周报**:每两周输出本周期主驱动变量 top-3 + 主线评分变化 + 战略建议清单
- **投资双周报**:每两周输出主线热度排名 + 公司相对位势矩阵 + 仓位调节信号(可追溯证据链)
- 三套估值模型(保守 / 基准 / 乐观)对每家公司输出价格区间(基于真实订单 / 收入数据, 非占位)
- 周报可一键导出 DOCX / Excel / PPT(双版本:CEO 简报 + 投资人详报)
- 与 `web/app.html` 投研工作台前端打通, 仓位信号可在前端订阅

## 4. 横向(Cross-phase)

下面这些不与单个 Phase 绑定,但每阶段都要顾着:

| 项 | 现状 | 改善方向 |
|---|---|---|
| 真实数据 | 0 条 | Phase 2 引入 |
| 文档 | ✅ 6 份 MD + 1 份 HTML | 每加 1 个模块同步更新 |
| 可观测 | 无 | 加 OpenTelemetry / 简单 metric 端点 |
| 部署 | 本地 | Docker compose 化 |
| 鉴权 | 无 | API 加 token,Phase 2 起 |
| 多语 | 中文为主 | 英文 LM 模型时考虑 |

## 5. 当前优先级建议

按 ROI 排序的下一步候选(用户可挑):

1. ~~**真实数据盲测**~~ — ✅ **已完成 (2026-06-02)**, 25 条公开新闻, 三项全过 **40%**, macro F1 **0.822**。详见 [`regression-real.md`](./regression-real.md)
2. ~~**Phase 2.0 词典扩展**~~ — ✅ **已完成 (2026-06-02)**, rules v1 真实集三项全过升到 **64%**, thesis 准确率 **92%**, 运营支撑 F1 **0.80**, 合成集 30 条 100% 不退化
3. ~~**PRD / 路线图双视角对齐**~~ — ✅ **已完成 (2026-06-02)**, PRD §3 重组为输入侧 / 判断层 / 决策层三层, Phase 3 从"文档自动化"重定义为"决策辅助"
4. **Phase 2.1 LLM 兜底 + 公司反哺弱信号化**(3-5 天) — `confidence < 0.55` 或 thread 命中 ≥ 3 触发, 廉价模型(DeepSeek-V3 / Qwen2.5-32B)即可, 主要解关键词漂移 / 对冲句 / 描述性新闻。目标真实集三项全过 ≥ 85%
5. ~~**events / companies 表 schema 扩展**(1-2 天)~~ — ✅ **已完成 2026-06-02**, events 加 6 个数字字段、companies 加 4 个、`migrate_schema()` 幂等、CLI/API 透传、23/23 tests。详见 [`data.md` §7](./data.md#7-数据缺口--phase-3-决策层需要补什么)
6. **Phase 2 抓取最小化** — ✅ **脚手架已交付 2026-06-02**(`satellite_agent/sources/` + `extract.py` + `ingest_pipeline.py`)。`Source` 抽象 + JsonlSource + TextFileSource + 管线编排 + 中文金额提取器(亿/万自动换算,12 条测试)。CLI `satagent fetch --source jsonl|text` · 49/49 tests。**真实 HTTP / RSS 源待对接**(新增源只需 sources/ 下加 1 个模块 + 注册到 `load_source`)
7. ~~**Phase 3a · 双视角周报原型**(7-10 天)~~ — ✅ **MVP 已交付 2026-06-02**, `satellite_agent/decision.py` 产出 CEO(主驱动变量 + 主线评分 + 战略建议) + 投资(主线热度 + 公司位势矩阵 + 仓位信号 加/减/持 + 证据链)双视角。CLI `satagent decision --view ceo|investor|both` · REST `GET /decision/weekly` · 28/28 tests。规则版,未接 LLM
8. **前端打通** — 把 `web/app.html` 工作台的模拟数据切换到真实 API, 仓位信号 + 战略建议订阅
9. **Phase 3b 投资视角深化** — 估值映射(订单 → DCF / PE)/ 市场模型动态修正(用真实 capex/opex 滚动覆盖 seed 占位)/ 异常告警自动触发仓位信号

5、6 (脚手架) 、7 已完成。接下来自然顺序:
- 4 LLM 兜底 + 公司反哺弱信号化(独立改造,提升分类天花板)
- **真实 HTTP 源对接**(在 6 的脚手架基础上 — 选 1 个稳定数据源如沪深交易所公告 API,加 `sources/sse.py` 模块,跑通真实数据闭环。需用户决定先接哪个源)
- 8 前端打通(把 web/app.html 的 mock 切到 `/decision/weekly` + `/events`)

Phase 3a 决策层规则版当前由 8 条 demo 事件驱动,**真实使用前的瓶颈是真实数据源对接**。