# Macro-Narrative Driven ETF Investment Agent (MND-IA)

## 1. 项目概述 (Project Overview)

**MND-IA** 是一个基于 **“宏观叙事生命周期 + 资金流向交叉验证”** 的自动化 ETF 投资智能体系统。

### 核心哲学 (Core Philosophy)

1. **叙事即信号 (Narrative as Signal):** A 股是政策市，新闻联播及部委政策是市场趋势的先行指标。
2. **资金即真相 (Flow as Truth):** 只有资金实际流入的板块，叙事才具备可信度。
3. **信任指数 (Trust Index):** 决策基于叙事热度与资金强度的共振程度。
4. **生命周期管理 (Lifecycle):** 新闻不是孤立的脉冲，而是具有“潜伏-发酵-兑现-衰退”周期的持久对象。

---

## 2. 系统架构 (System Architecture)

本系统采用 **Multi-Agent "Skills" 架构**，由一个不可拆分的**共享内核 (Shared Kernel)** 和五个独立职能的 **Agent Skills** 组成。

### 2.1 共享内核 (Shared Kernel) - *不可拆分*

这是系统的数据中心和逻辑基石，所有 Agent 必须遵循此协议。

1. **MCP World Book (世界书):** 一个动态更新的 JSON 数据库，存储宏观状态、活跃叙事对象和历史经验。
2. **Asset Map (资产映射表):** 连接自然语言（如“低空经济”）与金融代码（如 `512XXX`）的静态字典。
3. **Macro Matrix (宏观逻辑矩阵):** 定义宏观因子（如利率、汇率）对各 ETF 板块的**基础理论影响值 ()**。

### 2.2 Agent Skills 群 (The Squad)

| Agent ID | 名称 | 职能 (Skill) | 输入 | 输出 |
| --- | --- | --- | --- | --- |
| **Skill_A** | **情报分析师** (Analyst) | NLP 提取、新闻分级、叙事打分 | 新闻文本 (News) | `Narrative_JSON` |
| **Skill_B** | **量化研究员** (Quant) | 行情分析、资金流计算、异常检测 | 行情数据 (Akshare) | `Market_Data_JSON` |
| **Skill_C** | **宏观策略师** (Strategist) | 维护世界书、判断周期、更新叙事权重 | `Narrative_JSON` + 历史 WorldBook | 更新后的 `World_Book` |
| **Skill_D** | **基金经理** (PM) | 计算信任指数、风控、生成订单 | `World_Book` + `Market_Data_JSON` | `Trade_Orders` |
| **Skill_E** | **复盘审计员** (Auditor) | 绩效归因、偏差修正 | 历史预测 vs 实际走势 | `Correction_Report` |
| **Skill_F** | **新闻联播爬虫** (Crawler) | 抓取新闻联播文字稿 | 目标日期 | 新闻文本列表 |

---

## 3. 数据协议与 Schema (Data Protocols)

**注意：AI 生成代码时必须严格遵守以下 JSON 结构。**

### 3.1 World Book Schema (世界书结构)

```json
{
  "timestamp": "2025-10-01T09:00:00",
  "macro_cycle": {
    "status": "upward", // upward(上行) | downward(下行)
    "liquidity": "loose", // loose | neutral | tight
    "policy_wind": "stimulus" // stimulus | regulation | wait_and_see
  },
  "active_narratives": [
    {
      "id": "narrative_low_altitude_economy_202510",
      "topic": "低空经济",
      "related_etfs": ["512XXX", "159XXX"],
      "lifecycle_stage": "fermentation", // incubation | fermentation | realization | decay
      "base_score": 85, // 初始新闻强度
      "decay_factor": 0.95, // 每日衰减系数
      "current_weight": 80.75, // 动态权重
      "last_updated": "2025-10-01"
    }
  ],
  "static_matrix_snapshot": {
    // 基础宏观因子影响表 ($x$)
    "tech_etf": {"rate_cut": 8, "currency_depreciation": 2},
    "bank_etf": {"rate_cut": -5, "currency_depreciation": -1}
  }
}

```

### 3.2 Trust Index Formula (信任指数算法)

Agent D (PM) 必须使用以下逻辑计算得分：

* **Score_narrative:** 来自 World Book 中 `current_weight`。
* **Score_flow:** 来自 Skill_B (Quant) 的资金净流入归一化评分。
* **Penalty_divergence:** 当 `Narrative > 80` 但 `Flow < 30` 时，惩罚值设为 100 (一票否决)。

---

## 4. 业务流程 (Workflows)

### 4.1 每日批处理流程 (Daily Batch) - *08:30 AM*

1. **Ingest:** Skill_A 读取昨夜今晨新闻，Skill_B 读取昨日行情。
2. **Cognition:** Skill_C 读取 Skill_A 的结果，更新 MCP World Book（增强或衰减叙事权重）。
3. **Decision:** Skill_D 读取最新的 World Book 和 Skill_B 的资金数据，计算 Trust Index。
4. **Execution:** Skill_D 输出具体的 `buy/sell` 指令列表。

### 4.2 盘中哨兵流程 (Intraday Sentinel) - *09:30 - 15:00*

1. **Monitor:** 系统监听快讯接口（如财联社红色资讯）。
2. **Trigger:** 若检测到 `Level A` 级新闻（如印花税、降准）。
3. **Interrupt:** 唤醒 Skill_C 临时修改 World Book 状态。
4. **Re-eval:** 触发 Skill_D 重新计算当日持仓建议。

### 4.3 盘后复盘流程 (Post-Market Feedback) - *16:00 PM*

1. Skill_E 对比昨日的 `Trade_Orders` 和今日实际涨跌幅。
2. 若偏差过大，Skill_E 向 MCP 写入一条 `correction_log`，调整 Skill_C 未来对同类新闻的打分权重。

---

## 5. 项目结构 (Project Structure)

建议 AI 按照以下目录结构生成代码：

```text
/mnd_agent
├── /core                # 共享内核
│   ├── world_book.py    # MCP 读写逻辑
│   ├── asset_map.json   # 资产映射字典
│   └── macro_matrix.json # 静态因子表 ($x$)
├── /skills              # Agent 能力群
│   ├── analyst.py       # Skill A: LLM Prompts for News
│   ├── quant.py         # Skill B: Akshare Data Analysis
│   ├── strategist.py    # Skill C: World Book Update Logic
│   ├── pm.py            # Skill D: Trust Index & Trade Logic
│   ├── auditor.py       # Skill E: Feedback Loop
│   └── crawler.py       # Skill F: XinwenLianbo Crawler
├── /data                # 本地存储 (Parquet/SQLite)
├── /logs                # 运行日志
├── main.py              # 主调度入口
└── README.md            # 本文件

```

---

## 6. 技术栈约束 (Tech Stack Constraints)

* **Language:** Python 3.10+
* **LLM Interface:** OpenAI SDK (兼容 GLM-4/Claude-3.5)
* **Data Source:** `akshare` (A股行情), `crawl4ai` (新闻联播爬虫)
* **Data Process:** `pandas`, `numpy`
* **Storage:** 本地 JSON 文件模拟 MCP Server (MVP阶段)

---

## 7. 给 AI 工具的构建指令 (Instructions for AI Builder)

1. **Step 1:** 首先创建 `core/` 目录，定义好 `WorldBook` 类和 JSON 数据结构，这是所有 Skill 通信的基础。
2. **Step 2:** 实现 `skills/quant.py`，确保能从 Akshare 获取 ETF 数据并计算“资金放量”指标。
3. **Step 3:** 实现 `skills/analyst.py`，编写能够将新闻文本转化为 JSON 对象的 Prompt。
4. **Step 4:** 实现 `skills/pm.py` 中的 **Trust Index** 算法，确保逻辑与上述公式一致。
5. **Step 5:** 编写 `main.py` 将上述模块串联起来，完成每日一次的模拟运行。