# MoFin 专家系统 — 完整架构文档 v2.0

> 最后更新：2026-06-09
> 维护人：莫荷（Hermes Agent）
> 铁律：任何系统改动必须先读本文档，改完必须同步更新

---

## 一、核心理念

```
每份分析都成为下一次分析的养料
每次建议都成为下一次建议的参考
从内到外（知识→分析），从外到内（分析→沉淀）的持续闭环
```

## 二、股票操作策略生命周期

```
                    ┌─────────────────────────────┐
                    │   大环境+行业趋势研判         │
                    │   (盘前热点扫描·每天8:30)     │
                    │   板块扫描→发现新标的         │
                    └──────────┬──────────────────┘
                               │ 写入 watchlist.json
                               ▼
                    ┌─────────────────────────────┐
                    │   自选股池 (watchlist.json)   │
                    │                              │
                    │   🟢 可操作 — 价格在买入区内   │
                    │   🟡 关注 — 距触发3~5%        │
                    │   ⚪ 观察 — 距触发>5%          │
                    │                              │
                    │   监控：                      │
                    │   • 快速盯盘(每15分钟)         │
                    │   • 持仓情报-盘后(每天)        │
                    │   • 自选股体检(每周六)         │
                    └──────────┬──────────────────┘
                        进入买入区 │ 建仓
                               ▼
                    ┌─────────────────────────────┐
                    │   持仓股 (portfolio.json)     │
                    │                              │
                    │   监控：                      │
                    │   • 价格监控(每分钟·纯脚本)    │
                    │   • 快速盯盘(每15分钟·LLM)     │
                    │   • 持仓情报-盘中(每小时·LLM)  │
                    │   • 持仓情报-盘后(每天·LLM)    │
                    │   • 分析师-持仓复查(每周·LLM)  │
                    └──────────┬──────────────────┘
                    触发止损/止盈/清仓 │
                               ▼
                    ┌─────────────────────────────┐
                    │   回到自选股池                │
                    │   (保留策略，等待下次机会)     │
                    └─────────────────────────────┘
```

## 三、系统架构总览

```
┌──────────────────────────────────────────────────────────────────┐
│                         MoFin 专家系统 v2.0                       │
├──────────────────────────────────────────────────────────────────┤
│                                                                    │
│  ┌─────────────────────────┐  ┌──────────────────────────────┐   │
│  │    基础设施层(纯脚本)     │  │    分析层(LLM驱动)            │   │
│  │  0配额消耗               │  │  每次运行消耗1次配额          │   │
│  │                         │  │                              │   │
│  │  • 价格监控(1分钟)       │  │  • 盘前热点扫描(8:30)        │   │
│  │    腾讯批量API拉所有股票  │  │    → 持仓分析+板块扫描        │   │
│  │    写入portfolio/watchlist│  │    → 新机会发现→写入watchlist│   │
│  │    比对区间触发→输出     │  │                              │   │
│  │                         │  │  • 集合竞价观察(9:28)         │   │
│  │  • 市场数据采集(30分钟)   │  │    → A股竞价异常监控          │   │
│  │    板块数据→market.json  │  │                              │   │
│  │                         │  │  • 快速盯盘(每15分钟)          │   │
│  │  • 数据同步(8:55)        │  │    → 持仓操作窗口+自选接近提醒 │   │
│  │    update_data+server检查│  │                              │   │
│  │                         │  │  • 持仓情报-盘中(每小时40分)   │   │
│  │  • XMPP中继(每分钟)      │  │    → 详细盘中分析              │   │
│  │    扫输出目录→推知微     │  │                              │   │
│  │                         │  │  • 持仓情报-盘后(20:00)       │   │
│  └─────────┬───────────────┘  │    → 完整复盘+自选回顾         │   │
│            │                  │                              │   │
│            ▼                  │  • 分析师-持仓复查(周四20:00)  │   │
│  ┌─────────────────────────┐  │    → 基本面深度复查            │   │
│  │    数据层                │  │                              │   │
│  │  portfolio.json(持仓)   │  │  • 自选股体检(周六20:00)      │   │
│  │  watchlist.json(自选)   │  │    → 每只自选评估：保留/移除   │   │
│  │  decisions.json(决策库) │  │                              │   │
│  │  market.json(板块数据)  │  │  • 知微周复盘(周日22:00)      │   │
│  │  daily_reviews.json     │  │    → 周度总结                 │   │
│  │  stock_profiles.json    │  └──────────┬───────────────────┘   │
│  └─────────┬───────────────┘             │                        │
│            │                             │                        │
│            ▼                             ▼                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                   推送层                                   │   │
│  │  cron_to_xmpp.py(每分钟·纯脚本)                            │   │
│  │  扫描 ~/.hermes/cron/output/*/ 目录                       │   │
│  │  发现新 .md 文件 → 提取正文 → XMPP推送【知微】             │   │
│  │  已推送的记在 .relay_journal.json，不重复推                │   │
│  └──────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────┘
```

## 四、完整 Cron Job 清单（14个）

### 🟢 基础设施层（纯脚本，0配额消耗）

| # | 名称 | 频率 | 脚本 | 输出 | 说明 |
|---|------|------|------|------|------|
| 1 | **价格监控-1分钟** | 工作日 每分钟(9-11/12/13-16) | `price_monitor.py` | 有触发→推送；无→SILENT | 腾讯批量API拉所有股票实时价，写入portfolio/watchlist，比对区间触发条件 |
| 2 | **市场数据采集** | 工作日 每30分钟 | `market_watch.py` | 成功→SILENT；失败→报错 | 东方财富API采集板块数据→market.json |
| 3 | **数据同步-dashboard** | 每天 8:55 | `sync_dashboard.py` | 有数据→推送；无→SILENT | 跑update_data.py+检查server，挂了自动重启 |
| 4 | **cron-推XMPP中继** | 工作日 每分钟(9-16) | `cron_to_xmpp.py` | 有新报告→推送；无→静默 | 扫所有job输出目录，推新报告到XMPP |
| 5 | **中继-16点收盘** | 工作日 16:00-16:10 | `cron_to_xmpp.py` | 同上 | 收盘时段推港股报告 |

### 🔵 分析层（LLM驱动，每次1次配额）

| # | 名称 | 频率 | 关键职责 | 价格获取方式 |
|---|------|------|---------|------------|
| 6 | **盘前热点扫描** | 工作日 8:30 | 持仓分析+**板块扫描→新机会发现→写入watchlist** | 读文件(price_monitor刷新) |
| 7 | **集合竞价观察** | 工作日 9:28 | A股竞价异常监控，无异常SILENT | A股curl竞价价+港股读文件 |
| 8 | **快速盯盘-15分钟** | 工作日 每15分钟 | 持仓操作窗口+**自选股接近买入区提醒**，无则SILENT | 读文件 |
| 9 | **持仓情报-盘中** | 工作日 每小时40分 | 详细盘中分析+异动搜因 | 读文件 |
| 10 | **持仓情报-盘后** | 工作日 20:00 | 完整复盘+**自选股回顾**+数据沉淀daily_reviews | 读文件 |
| 11 | **分析师-持仓复查** | 周四 20:00 | 每周基本面深度复查 | 读文件 |
| 12 | **自选股体检-每周** | **周六 20:00 🆕** | 每只自选评估：已建仓→移除、>30天未接近→建议移除、行业变化→更新理由 | 读文件+web_search |
| 13 | **知微周复盘** | 周日 22:00 | 周度总结 | 读文件 |
| 14 | **策略评估-每日** | 工作日 21:00 | 双维度评估36条策略，生成反馈闭环 | 读文件+LLM | 无变化→SILENT |
| 15 | **建议对账-每周** | 周六 20:00 | 对比建议vs实际持仓变化，算准确率 | 纯脚本 | 有数据→推送 |
| 16 | **策略评估-每周** | 周六 21:00 | 完整评分+趋势分析+策略参数调整 | 纯脚本 | 有数据→推送 |

## 五、数据文件

| 文件 | 路径 | 作用 | 更新频率 | 更新者 |
|------|------|------|---------|--------|
| 持仓数据 | `data/portfolio.json` | 持仓快照+实时价 | 每分钟 | price_monitor |
| 自选数据 | `data/watchlist.json` | 自选股列表+买入区+实时价 | 每分钟 | price_monitor+盘前扫描+自选体检 |
| 决策库 | `data/decisions.json` | 策略+trigger+建议历史+评估数据 | 每次讨论后+每日评估 | LLM job+策略评估 |
| 每日复盘 | `data/daily_reviews.json` | 当日判断+修正沉淀 | 每日20:00 | 持仓情报-盘后 |
| 股票档案 | `data/stock_profiles.json` | 行业/业务/逻辑 | 发现新信息时 | LLM |
| 市场数据 | `data/market.json` | 板块涨跌+概念热度 | 每30分钟 | market_watch |
| 价格事件 | `data/price_events.json` | 价格触发记录（止盈/止损/买入区） | 每分钟 | price_monitor |
| 评估结果 | `data/evaluation.json` | 双维度评估+评分 | 每天21:00 | 策略评估 |
| 准确率统计 | `data/accuracy_stats.json` | 建议对账+准确率 | 每周六20:00 | 对账脚本 |
| 反馈闭环 | `data/strategy_feedback.json` | 反馈+调整建议+知识萃取 | 每天21:00 | 策略评估 |
| 区间偏离 | `~/.hermes/zone_breach.json` | 价格偏离标记 | 每分钟 | price_monitor |
| 触发状态 | `~/.hermes/price_trigger_state.json` | 每只股票各区间的进出状态 | 每分钟 | price_monitor |

## 六、数据流转

```
price_monitor(每分钟)
  │  腾讯批量API 1次请求
  │
  ├──→ portfolio.json (持仓实时价)
  ├──→ watchlist.json (自选实时价)
  ├──→ 比对decisions.json的trigger区间
  ├──→ 有触发 → 输出 → 中继 → 知微
  └──→ 无触发 → [SILENT] → 丢弃

market_watch(每30分钟)
  │  东方财富API
  └──→ market.json (板块数据)

盘前热点扫描(每天8:30)
  │  读 market.json → 分析强势板块
  │  发现新标的 → 写入 watchlist.json
  └──→ 输出报告 → 中继 → 知微

快速盯盘(每15分钟)
  │  读 portfolio.json + watchlist.json
  │  持仓操作窗口 + 自选接近买入区
  └──→ 有发现 → 输出 → 中继 → 知微

持仓情报-盘后(每天20:00)
  │  读 portfolio.json + watchlist.json
  │  持仓回顾 + 自选回顾
  └──→ 写入 daily_reviews.json
  └──→ 输出报告 → 中继 → 知微

自选股体检(每周六20:00)
  │  读 watchlist.json + portfolio.json
  │  每只评估：保留/移除/更新
  └──→ 输出报告 → 中继 → 知微
```

## 七、报告推送策略

| 报告 | 推送 | 频率 | 静默规则 |
|------|------|------|---------|
| 价格监控 | ✅ 有触发才推 | 每分钟 | 无触发→[SILENT] |
| 盘前扫描 | ✅ | 每日1次 | 有发现才写 |
| 集合竞价 | ✅ 有异常才推 | 每日1次 | 无异常→SILENT |
| 快速盯盘 | ✅ 有发现才推 | 每15分钟 | 无操作窗口+无自选接近→SILENT |
| 持仓情报-盘中 | ✅ 有发现才推 | 每小时40分 | 无操作窗口→合并后停止 |
| 持仓情报-盘后 | ✅ | 每日20:00 | 有实质内容才写 |
| 分析师复查 | ✅ | 每周四 | 有发现才写 |
| 自选股体检 | ✅ | 每周六 | 有建议才写 |
| 知微周复盘 | ✅ | 每周日 | 有实质内容才写 |
| 市场数据采集 | ❌ 不推 | 每30分钟 | 只写文件 |
| 数据同步 | ✅ 有数据才推 | 每天8:55 | 无更新→SILENT |

## 八、关键设计决策

| 方面 | 决策 | 原因 |
|------|------|------|
| 价格获取 | 腾讯批量API `qt.gtimg.cn/q=sh600110,sz000001,...` | 1次请求拉所有股票，无频率限制 |
| 价格监控类型 | 纯脚本(`no_agent=True`) | 不需要LLM，0配额消耗 |
| 中继类型 | 纯脚本(`no_agent=True`) | 文件扫描+XMPP推送，不需要LLM |
| 市场数据采集 | 纯脚本(`no_agent=True`) | 只写文件不输出，不需要LLM |
| 数据同步 | 纯脚本(`sync_dashboard.py`) | 包装脚本含server检查，不需要LLM |
| LLM job价格来源 | 读文件(price_monitor每1分钟刷新) | 不再逐个curl，节省配额 |
| 新机会发现 | 合并到盘前热点扫描(每天) | 每天分析板块数据，发现新标的写入watchlist |
| 自选股进出管理 | 自选股体检(每周六) | 系统评估+提请确认，不自动删除 |
| 午休 | 价格监控跳过12:05-12:55(保留12:00) | A股午休无行情 |

## 九、配额消耗估算（一个上午）

| 组件 | 运行次数 | 配额消耗 |
|------|---------|---------|
| 价格监控 | ~240次(每分钟) | **0** (纯脚本) |
| 市场数据采集 | ~10次 | **0** (纯脚本) |
| 数据同步 | 1次 | **0** (纯脚本) |
| XMPP中继 | ~240次 | **0** (纯脚本) |
| 盘前热点扫描 | 1次 | **1次** |
| 集合竞价 | 1次 | **1次** |
| 快速盯盘 | ~20次 | **~20次** (有操作窗口才跑，无则SILENT不消耗) |
| 持仓情报-盘中 | ~6次 | **~6次** |
| 策略评估-每日 | 1次 | **1次** |
| **总计** | | **~29次 LLM调用** |

---

## 十、策略评估反馈闭环架构

### 核心流程

```
price_monitor（每分钟·纯脚本）
  │  腾讯批量API拉所有股票实时价
  │  比对策略区间 → 触发 → 记录到 price_events.json
  │
  ├──→ 价格触发事件持久化（price_events.json）
  │     event_type: entry_zone / stop_loss / take_profit
  │     code, name, price, trigger_value, timestamp
  │
  ▼
strategy_evaluator（每天21:00·纯脚本）
  │  读 decisions.json + price_events.json + portfolio.json
  │  双维度评估每只股票：
  │    阶段一（策略制定→价格达标）：
  │      - 理论：价格是否达到过止盈/止损/买入区
  │      - 实际：持仓盈亏、建议执行情况
  │    阶段二（价格回落→新止损验证）：
  │      - 新止损是否被后续走势验证
  │  写入 decisions.json 的 evaluation 字段
  │
  ├──→ 写入 evaluation.json
  │
  ▼
strategy_feedback（每天21:00·纯脚本，评估后自动）
  │  读 evaluation.json
  │  自动决策：
  │    - 价格达到止盈 → 标记阶段一成功，萃取经验
  │    - 跌破止损 → 标记阶段一失败，生成新区间
  │    - 14天无触发 → 标记 stale，建议重评
  │    - 准确率持续下降 → 收紧区间宽度
  │  写入 strategy_feedback.json
  │
  ├──→ 写入 strategy_feedback.json
  │
  ▼
每日评估 cron（每天21:00·LLM驱动）
  │  读 strategy_feedback.json
  │  处理反馈 → 更新策略 → 输出日报
  │  无变化 → [SILENT]
  │
  ▼
盘后知识萃取（每天16:30·LLM驱动）
  │  读 feedback 中的 knowledge 字段
  │  写入 analyst-knowledge-log.md
  │
  ▼
建议对账（每周六20:00·纯脚本）
  │  对比 advice_timeline vs portfolio.json
  │  算准确率 → 写入 accuracy_stats.json
  │
  ▼
策略评估-每周（每周六21:00·纯脚本）
  │  完整评分 → 趋势分析 → 策略参数调整
  │  写入 evaluation.json + strategy_feedback.json
```

### 双维度评估模型

| 维度 | 阶段一 | 阶段二 |
|------|--------|--------|
| 理论（策略规划） | 价格是否达到止盈/止损/买入区？何时？理论盈亏？ | 新止损是否被后续走势验证？ |
| 实际（用户执行） | 实际持仓盈亏？建议是否被采纳？ | 用户是否按新止损操作？实际损失？ |

### 反馈引擎自动决策规则

| 检测条件 | 自动动作 |
|----------|----------|
| 价格达到止盈位 | 标记阶段一成功，萃取经验到知识日志，创建新自选策略 |
| 跌破止损位 | 标记阶段一失败，分析原因，生成新止损/买入区间 |
| 策略14天未触发任何区间 | 标记为 stale，建议重新评估基本面和技术面 |
| 准确率持续下降（<50%） | 收紧策略区间宽度（10%→8%） |
| 准确率持续上升（>80%） | 放宽策略区间宽度（10%→12%） |

---

## 十、v2.0 更新说明（2026-06-09）

本次更新基于知微与莫荷、老爸的深入讨论，对系统做了全面重构。以下记录讨论过程中的关键意图、决策和待办事项。

### 本次改动驱动因素

1. **火山引擎(volcengine) 429配额超限** → 触发对 provider 配置和 fallback 链的全面梳理
2. **发现价格监控逐个curl拉取价格** → 效率极低且浪费配额，触发了对价格获取方式的全面改造
3. **知微反馈"问了不在回答长篇报告"** → 触发了对 session 管理、system prompt、对话识别机制的修复
4. **老爸指出持仓和自选股之间的动态生命周期关系** → 触发了对股票操作策略完整生命周期的重新设计

### 已完成的改造

**基础设施层：**
- 价格监控从 LLM驱动(每5分钟) 改为 纯脚本(每1分钟)，使用腾讯批量API一次拉所有股票
- XMPP中继从 LLM驱动 改为 纯脚本(每1分钟)
- 市场数据采集从 LLM驱动 改为 纯脚本
- 数据同步从 LLM驱动 改为 纯脚本(含server检查包装脚本)
- 所有LLM job的价格获取从"逐个curl拉取"改为"直接读文件(price_monitor每1分钟刷新)"

**股票生命周期完善：**
- 新机会发现：合并到盘前热点扫描(每天8:30)，板块扫描→发现新标的→写入watchlist
- 自选接近提醒：快速盯盘(每15分钟)新增自选接近买入区(<5%)单独提醒
- 自选回顾：持仓情报-盘后(每天20:00)新增自选股回顾板块
- 自选体检：新增每周六20:00的自动评估+建议移除/保留

**provider配置统一：**
- 莫荷(默认profile)：默认ocg-old(旧key) → fallback ocg-new(新key) → volcengine(火山)
- 知微(position-analyst)：默认volcengine(火山) → fallback ocg-old(旧key) → ocg-new(新key)
- 火山已恢复可用

**对话机制修复：**
- 知微SOUL新增对话上下文识别规则(打招呼vs分析请求vs模糊提问)
- 知微SOUL新增系统自动追加消息(bg-review)说明
- position-analyst启用压缩(protect_last_n=200, hygiene_hard_message_limit=400)

**策略评估反馈闭环（v2.0 深夜追加）：**
- 价格事件持久化：price_monitor每分钟记录价格触发事件到price_events.json
- 双维度评估：strategy_evaluator每天评估36条策略，分阶段一（策略制定→价格达标）和阶段二（价格回落→新止损验证），每个阶段同时记录理论盈亏和实际盈亏
- 反馈引擎：strategy_feedback自动检测止盈/止损/stale策略，生成调整建议，萃取知识到知识日志
- Dashboard评估tab：展示评分、理论vs实际盈亏对比、反馈闭环卡片
- 建议对账：advice_reconciliation.py每周对比建议vs实际持仓变化算准确率
- 36条策略全部填充建议记录，平均分4.8/10

### 设计原则/意图

1. **知微是分析师，不是决策者** — 她出建议，老爸决定是否执行，是否执行的唯一真相来源是截图/持仓更新
2. **莫荷是参谋，不是执行者** — 莫荷出报告和建议，不做交易操作
3. **建议≠事实** — 不能假设建议=被执行，需要等持仓更新来验证
4. **持仓/自选动态循环** — 持仓清仓→自动转自选保留策略，自选建仓→自动转为持仓管理
5. **自选股进出需人工确认** — 系统可以建议移除，但不能自动删除，需老爸确认
6. **轻对话，重分析** — 不是每条消息都需要全面分析报告，区分打招呼和干活

### 尚未完成/待定事项

1. **建议自动记录+对账闭环** — 莫荷发出的建议自动记入decisions.json的advice_timeline，每周对比实际持仓变化，统计准确率（✅ 已完成：/api/advice/record + advice_reconciliation.py + accuracy_stats.json）
2. **MoFin Dashboard整合** — server.py应整合所有数据源，包括待确认决策、准确率统计等（✅ 已完成：决策库tab + 评估tab + 反馈闭环tab）
3. **知微XMPP通信通道优化** — 当前xmpp_zhiwei_bot.py断线重连机制有缺陷(Event().wait阻塞)，需修复（✅ 已完成：watchdog循环每10秒检查连接状态）
4. **session跨profile检索** — 知微无法搜到莫荷CLI session的内容，需手动转发（✅ 已完成：session_search profile参数可用）
5. **策略双维度评估体系** — 理论策略vs实际执行，分阶段跟踪，自动反馈闭环（✅ 已完成：strategy_evaluator.py + strategy_feedback.py + 每日/每周cron）
6. **价格事件持久化** — price_monitor每分钟记录价格触发事件供回溯评估（✅ 已完成：price_events.json + record_event()）