# Satellite Agent Infra Analyst — MVP

> 卫星互联网产业研究 Agent · Phase 1 Research Agent · **rules-based MVP**

PRD: [`./PRD.md`](./PRD.md)　·　文档总览: [`docs/dashboard.html`](docs/dashboard.html)（视觉化）/ [`docs/README.md`](docs/README.md)（索引）

## 文档地图

| 主题 | 入口 |
|---|---|
| 视觉化总览(设计 · 路线 · 进度) | [`docs/dashboard.html`](docs/dashboard.html) |
| 架构与设计思路 | [`docs/architecture.md`](docs/architecture.md) |
| 本体与关键词词典 | [`docs/ontology.md`](docs/ontology.md) |
| CLI / REST 接口参考 | [`docs/api.md`](docs/api.md) |
| 回归评测与基线指标 | [`docs/regression.md`](docs/regression.md) |
| 路线图(Phase 1/2/3) | [`docs/roadmap.md`](docs/roadmap.md) |

## 是什么

一个本地可跑的 Python 服务,把卫星互联网产业的事件(新闻 / 公告 / 政策 / 产品)按四条主线分类、识别主驱动变量, 最终输出**双视角决策辅助**:

- **CEO 视角**:本周期的主驱动变量是什么?对应的战略 / 策略建议怎么调整?
- **投资视角**:四主线的相对热度、公司相对位势、二级市场各环节 加 / 减 / 持 信号

Phase 1 已交付输入侧(事件结构化分类), Phase 2 接入 LLM 兜底 + 抓取数字字段, Phase 3 是决策层(主驱动变量识别 + 仓位信号)。**纯关键词规则起步**,SQLite 落盘, 决策层用规则 + LLM 混合。

四主线: 核心网 / 终端 / 芯片 / 运营支撑
场景:    低空 / 车载 / 海事航空 / 工业 IoT / 应急 / 具身智能
维度:    技术 / 产品 / 市场空间 / 商业模式 / 公司竞争力 / 风险
Thesis:  增强 / 削弱 / 中性 + 置信度

## 安装

```bash
cd agent
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

## 快速开始

```bash
# 1. 初始化数据库 + 写入种子市场模型与公司卡片
satagent init

# 2. 录入一条事件(自动分类)
satagent ingest --text "中国卫通完成 5G NTN 核心网端到端试验,信关站投运成功"

# 3. 仅做分类(不入库),用于调试规则
satagent classify --text "海格通信卫星通信基带芯片研发推迟,量产受阻"

# 4. 从 JSONL 批量录入示例事件(或等价 fetch)
satagent ingest-file samples/events.jsonl
# satagent fetch --source jsonl --path samples/events.jsonl

# 4b. 抓取任意公告文本,自动 extract 金额/时间窗
echo "海格通信中标某军种订单,合同金额 5.2 亿元,2026 年三季度交付" > /tmp/ann.txt
satagent fetch --source text --path /tmp/ann.txt --source-name "公司公告"

# 5. 生成本周 markdown 周报
satagent report --format md

# 5b. Phase 3a 双视角决策周报 (规则版, 8 条 demo 数据已带 numeric)
satagent ingest-file samples/events.jsonl   # 先灌入示例数据
satagent decision --view ceo                # CEO 视角:主驱动 + 战略建议
satagent decision --view investor           # 投资视角:公司位势矩阵 + 仓位信号

# 6. 查看市场模型与公司卡片
satagent market-model --thread 核心网
satagent companies
```

## FastAPI

```bash
uvicorn satellite_agent.api:app --reload
# 浏览器打开 http://127.0.0.1:8000/docs
```

主要端点:

| Method | Path | 说明 |
|---|---|---|
| GET  | `/health` | 健康检查 |
| POST | `/classify` | 只做分类,不入库 |
| POST | `/events/ingest` | 录入事件并分类 |
| GET  | `/events` | 查询事件(支持 thread/since/until/limit) |
| GET  | `/events/{id}` | 单个事件详情 |
| GET  | `/report/weekly?window=7&format=md` | 周报 |
| GET  | `/decision/weekly?view=both&window=7` | Phase 3a 双视角决策周报 🆕 |
| GET  | `/market-model?thread=芯片&year=2027` | 市场模型 |
| GET  | `/companies?thread=终端` | 公司卡片 |

## 测试

```bash
pytest -q
```

## 目录

```
agent/
├── pyproject.toml
├── README.md
├── data/                       # SQLite 落盘位置(运行后生成 agent.db)
├── samples/
│   └── events.jsonl            # 8 条示例事件,可一键灌入
├── satellite_agent/
│   ├── ontology.py             # 4 主线 + 场景 + 维度 + 关键词词典
│   ├── classifier.py           # rules-based 分类器
│   ├── db.py                   # SQLite schema + migration
│   ├── repository.py           # events / companies CRUD
│   ├── seed.py                 # 市场模型 + 公司卡片种子数据
│   ├── report.py               # 周报聚合 + markdown 渲染
│   ├── decision.py             # Phase 3a 双视角决策周报
│   ├── extract.py              # Phase 2 中文金额/时间窗提取器
│   ├── ingest_pipeline.py      # Phase 2 抓取管线编排
│   ├── sources/                # Phase 2 Source 抽象 + 实现
│   │   ├── base.py             # Source ABC + RawEvent
│   │   ├── jsonl.py            # JSONL 文件源
│   │   └── text.py             # 纯文本文件源
│   ├── cli.py                  # CLI 入口 (satagent)
│   └── api.py                  # FastAPI app
└── tests/                      # 49 tests · classifier / report /
    └── ...                     #   enrich / regression / schema /
                                #   decision / extract / sources
```

## MVP 边界

PRD Phase 1 之内:
- ✅ 文档结构化(事件 → 主线/场景/维度/影响/置信度/跟踪指标)
- ✅ ontology 建模
- ✅ 事件分类(关键词规则)
- ✅ 周报输出(markdown + JSON)

显式留给后续 Phase 的:
- ❌ 网页/公告抓取(Phase 2)
- ❌ LLM 语义理解 / 共指消解
- ❌ 动态市场模型更新(Phase 3)
- ❌ DOCX / Excel / PPT 自动生成(Phase 3)

## 数据说明

`seed.py` 中的市场模型(2025-2031 × 4 主线 × 3 情景)与公司卡片为 **MVP 占位估算**,
仅用于流程演示与回归测试。**不构成投资建议**。
接入实盘前需要由真实数据(财报、券商研报、产业访谈)覆盖。

## 后续路线

- **Phase 2 抓取脚手架 ✅ 已交付**: `Source` 接口 + JsonlSource / TextFileSource + 中文金额提取器(亿/万自动换算) + `ingest_pipeline` 编排。真实 HTTP / RSS 源待对接
- Phase 2.1 — LLM 兜底:`confidence < 0.55` 或 thread 命中 ≥ 3 触发,目标真实集三项全过 ≥ 85%
- **Phase 3a — Decision Agent (规则版 MVP ✅ 已交付)**:
  - CEO 视角 — 主驱动变量识别 + 战略建议(进入 / 加速 / 等待 / 退出 / 观察)
  - 投资视角 — 公司相对位势矩阵 + 仓位调节信号(加 / 减 / 持)+ 证据链
- Phase 3b — 估值映射(订单 → DCF / PE)+ 市场模型动态修正
- Phase 3c — 分发载体 DOCX / Excel / PPT(包装 3a / 3b 输出, 不是产品价值本身)