# DeepFusion

> 中国金融市场全品类数据获取、周期定位与投研分析系统。以 **MCP（Model Context Protocol）服务器** 为核心，向上为 AI Agent 提供 **177 个**数据/分析工具；同时自带一套 **React 可视化看板（dashboard）**，经由本地 HTTP API 消费同一套工具。

本文件面向**接手项目的架构师 / 工程师**，目标是给出系统结构、技术栈、能力边界与运维方式的完整、准确说明。AI 助手的协作约束见 [`AGENTS.md`](./AGENTS.md)。

> **数字核实方式**：运行 `python -m deep_fusion inspect`（FastMCP 自带子命令），输出 **177 工具 / 14 资源 / 7 提示**（核实于 2026-08-30）。本文档第 4、5 节以该输出与源码为准，替代此前 README 中过时的「140 工具 / 27 模块」描述。

---

## 1. 系统定位与两种运行形态

DeepFusion 在同一份 Python 代码上提供两种运行形态：

| 形态 | 入口 | 端口 | 用途 |
|------|------|------|------|
| **MCP 服务器（Stdio）** | `uv run python -m deep_fusion` | stdio | 供 Claude / Cursor / OpenCode 等 MCP 客户端接入，Agent 调用 177 个工具 |
| **Web 服务 + 看板** | `restart_all.sh` → `serve.py`（后端）+ `vite`（前端） | 后端 `5173` / 前端 `8080` | 浏览器访问可视化看板，前端经 `/api/tools/call` 调用后端工具 |

两种形态共享同一套 `deep_fusion/` 包与同一套工具实现，**工具逻辑只有一份**。Stdio 形态走 `mcp.run()`（FastMCP JSON-RPC over stdio）；Web 形态把 FastMCP 实例包进 FastAPI（`serve.py`）+ Starlette（`deep_fusion/__init__.py` 的 `--http` 模式），对外暴露 MCP HTTP 路由。

> **后台采集已解耦**：`serve.py` / `deep-fusion --http` **只启动 API 服务**，不再内置常驻采集线程。周期预热、政策/行业/市场采集、日报类任务统一由 `deep-fusion-collect` CLI（`deep_fusion/scheduler.py`）以「单次执行」模式运行，由外部调度（cron / systemd timer / docker sidecar）驱动。详见 §7。

> ⚠️ **关键约束（红线之一）**：本进程既作 stdio MCP 服务又作 Web 服务时，日志**只能走 stderr / 文件**，绝不可写 stdout——否则会污染 stdio JSON-RPC 协议流，导致任何 stdio 客户端 `JSONDecodeError`。见 `deep_fusion/logging_config.py`（`StreamHandler` 固定用 `sys.stderr`）。

---

## 2. 技术栈

### 2.1 后端（Python）
| 维度 | 选型 |
|------|------|
| 语言 / 运行时 | Python ≥ 3.11（项目 pyproject 要求），包管理用 **uv**（`uv.lock` 锁定） |
| MCP 框架 | **FastMCP**（`server.py` 中 `mcp = FastMCP(...)`），工具用 `@mcp.tool` 装饰注册 |
| Web 框架 | **FastAPI** + **uvicorn**（`serve.py`，端口 5173，支持多 worker：`DF_WORKERS`） |
| 数据处理 | pandas / numpy / scipy |
| 计量 / 统计 | statsmodels（Granger 因果）、arch（GARCH / DCC-GARCH）、scikit-learn（PCA / 聚类） |
| 频谱分析 | numpy.fft / scipy.signal（FFT / ACF / 小波 / EMD / Lomb / MUSIC / ESPRIT / MEM） |
| 数据源 | **akshare**（A股/港股/美股/基金/期货/外汇/财新等）、自研 **NBS 客户端**（国家统计局流式 API）、东方财富 / 新浪 / 同花顺 / 申万 / 99qh / OKX / Binance / SGE / FRED / 世界银行 / 雪球 |
| 持久化 | **SQLite**（多库，见 §5）；可选 **PostgreSQL**（部分行业分析管线曾用，现已以 SQLite 为准） |
| 缓存 | 双层：`deep_fusion/cache.py`（L1 内存 `TTLCache` + L2 磁盘 `diskcache`，统一 `CacheKey`） |
| 日志 | **structlog**（结构化 JSON，含 `trace_id`），缺包时降级标准 logging（见 §8 健壮性） |
| 图表 | matplotlib（Agg 后端，相位着色等公共工具在 `shared/chart_helpers.py`） |

### 2.2 前端（dashboard/）
| 维度 | 选型 |
|------|------|
| 框架 | **React 18** + **Vite 5**（`dashboard/`） |
| 状态 | **Zustand**（`src/store/`，`activeTab` + 各域子导航 `activeXxxSub`） |
| 数据请求 | **TanStack Query v5**（`src/hooks/useMCP.js`）+ 自研 `services/mcp.js`（`fetch('/api/tools/call')`） |
| 图表 | **ECharts 5** |
| 路由 | **react-router-dom v6**（侧栏子导航卡片切换，无滚动定位） |
| 样式 | CSS（`global.css` 全屏背景图 `body::before`） |
| 测试 | **Vitest** + @testing-library |

### 2.3 部署 / 运维
- `restart_all.sh`：一键启动（先杀 5173/8080 占用，再 nohup 拉后端+前端，日志落 `logs/backend.log` / `logs/frontend.log`）
- `Dockerfile` + `docker-compose.yml`：容器化部署
- `smithery.yaml`：Smithery 部署配置
- 桌面快捷方式：`~/桌面/deepfusion.desktop`（须 `chmod +x`，Exec 指向 `restart_all.sh`）

---

## 3. 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│  AI Agent (Claude / Cursor / OpenCode)   │   浏览器用户          │
│   MCP 客户端 (stdio)                      │   React Dashboard    │
└───────────────┬──────────────────────────┴──────────┬───────────┘
                │ stdio JSON-RPC                        │ HTTP
                ▼                                       ▼
        ┌──────────────────────────────────────────────────────┐
        │              deep_fusion 包（单一工具实现）            │
        │  server.py (FastMCP 实例)                              │
        │     ├── Stdio 形态: mcp.run()                         │
        │     └── Web 形态: FastAPI(serve.py)                   │
        │            /mcp  (POST, streamable HTTP)             │
        │   （仅 API，无内置后台线程）                            │
        └───────────────┬──────────────────────────────────────┘
                        │ @mcp.tool 注册的工具（177 个）
        ┌───────────────┼──────────────────────────────────────┐
        │  tools/ (28 个工具模块文件)  →  analysis/ + data/sources/ + shared/ │
        └───────────────┬──────────────────────────────────────┘
                        │ 数据获取 / 计算 / 落库
        ┌───────────────┴──────────────────────────────────────┐
        │  外部数据源 (akshare/NBS/东方财富/新浪/同花顺/申万/      │
        │  FRED/WB/OKX/Binance/SGE/99qh/财新/政策爬虫/雪球)       │
        │  本地持久层 (SQLite 多库 + diskcache 派生缓存)         │
        └──────────────────────────────────────────────────────┘
```

**模块分层**（详见 `AGENTS.md` 架构边界）：
- `tools/` — 工具层：每个 `@mcp.tool` 函数即一个对外能力，参数用 Pydantic `Field` 描述
- `analysis/` — 计算引擎层：周期引擎（基钦/朱格拉/库兹涅茨/康波）、行业轮动、个股筛选、宏观
- `data/sources/` — 数据源层：NBS 客户端、行情采集器、市场桥接（DB-first）、本地爬虫
- `shared/` — 跨工具复用：缓存、相关性/因果/GARCH 分析、图表工具、数据库辅助、频谱
- `cache.py` / `freshness.py` — 缓存与数据新鲜度（见 §6）
- `prompts.py` / `resources.py` / `server.py` — MCP 协议层（7 个 SOP 提示词 / 14 个资源 / 服务器实例）

---

## 4. 能力清单（177 个 MCP 工具，28 个工具模块 + 周期子模块）

> 工具名经 `python -m deep_fusion inspect` 实测（2026-08-30）。每个模块为一个能力板块；括号内为 `@mcp.tool` 名。

### 4.1 工具模块一览（按文件）

| 模块 | 工具数 | 能力板块 / 关键工具 |
|------|--------|---------------------|
| `stocks.py` | 7 | 个股基础：`stock_quote` / `market_overview` / `market_prices` / `individual_info` / `individual_hist` / `stock_concepts` / `search` |
| `tech_indicators.py` | 1 | `stock_tech_indicators`（技术指标） |
| `stock_reports.py` | 7 | 财报/新闻：`financial_statements` / `financial_indicators` / `peer_comparison` / `sentiment_side` / `capital_tracking` / `stock_indicators_hk` / `stock_indicators_us` |
| `analysis.py` | 6 | 诊断/回测：`composite_stock_diagnostic` / `backtest_strategy` / `trading_suggest` / `market_anomaly_scan` / `draw_ascii_chart` / `cache_clear`+`cache_status` |
| `anti_fraud.py` | 1 | `anti_fraud_report`（财务反欺诈） |
| `quality.py` | 1 | `quality_stock_review`（质量体检） |
| `industry.py` ★ | 20 | 行业全栈：分类/行情/估值/资金流/申万三级树(31/131/336)·成分·日报表 / 日采集·查询 / 主题(相关性聚类+动量+资金流 / DCC-GARCH / Granger 因果+龙头识别) / 现货(99qh) / **财新指数** / **FF 因子** |
| `market.py` | 11 | 行情面板：`sector_rotation` / `sector_valuation` / `northbound_funds` / `margin_balance` / `stock_sector_fund_flow_rank` / `stock_zt_pool_em` / `stock_zt_pool_strong_em` / `stock_lhb_ggtj_sina` / `stock_news_global` / `market_anomaly_scan`(同 analysis) / `get_current_time` |
| `market_data.py` | 3 | 公共行情库读写（DB-first，`data/market_data.db`）：`market_data_query` / `market_data_refresh` / `market_data_search_name` |
| `market_snapshot.py` | 3 | 快照：`market_broad_snapshot` / `market_snapshot_read` / `capital_flows_snapshot` |
| `macro.py` | 13 | 宏观：GDP/工业增加值 / CPI·PPI / PMI / M2·社融·LPR·失业率·进出口 / 库存周期 / 固定资产投资 / 全球 PMI（DB-first 增量更新） |
| `cycles.py` ★ + `analysis/macro/cycles/dispatch.py` | 16 + 6 | 四周期定位（基钦/朱格拉/库兹涅茨/康波）+ `cycle_detect`/`cycle_phase`(spectral) + `cycle_nesting`(嵌套Z) + `cycle_collect`/`cycle_cache_status` + FRED/世界银行 + 4 张 `chart_*` 图 + 4 类 `data_*` 结构化数据（dispatch 子模块含 `kitchin/juglar/kuznets_cycle` 与对应 `chart_*`） |
| `precious_metals.py` | 7 | 贵金属：SGE 现货 / 国际金银 / ETF 持仓 / COMEX 库存 / 基差 / 基准价 / 综合诊断 |
| `futures.py` | 4 | 期货：主力合约 / 仓单库存 / 期现基差 / 机构持仓排名 |
| `bonds.py` | 4 | 债券/期权/美股：`bond_collect` / `bond_yields` / `option_ivix` / `us_economic_indicators` |
| `forex.py` | 2 | 外汇：`fx_rates` / `fx_history` |
| `crypto.py` | 9 | 加密：BTC/ETH 行情+技术指标 / 合约多空比 / 恐惧贪婪指数(`fear_greed_index`) / 综合诊断 / Binance AI 报告 / 资金费率 / 持仓量 / ASCII 图 / 策略回测 |
| `funds.py` | 9 | 基金：信息/净值/持仓/排名/债持/行业配置/风险收益/盈利概率/资产配置 |
| `portfolio.py` | 3 | 模拟持仓：增/查/图 |
| `allocation.py` ★ | 1 | `asset_allocation`（周期调整资产配置：ERC 战略 + 四周期 TAA 战术倾斜） |
| `policy.py` | 9 | 政策：6 大官网采集(国务院/央行/财政部/发改委/统计局/外管局) → `policy_cache.db`；搜索/详情/统计/时间线/简报/热点信号/市场联动/主题个股 |
| `limit_up.py` | 4 | 连板：扫描 / 最新 / 历史 / 校准（落 `reports.db`） |
| `invest_theme.py` | 4 | 题材→个股映射：`invest_theme_collect` / `_latest` / `_history` / `_date` |
| `event_calendar.py` | 9 | 投研日历：采集/刷新/种子 + `calendar_add`/`upcoming`/`month`/`range`/`event_detail`/`frontrun` + `domain_constituents`(板块成分) |
| `reports_view.py` | 4 | 调度报告查看（四区）：`report_latest` / `report_history` / `report_by_date` / `report_types` |
| `butler.py` | 7 | 管家长期记忆：`memory_save` / `memory_search` / `memory_update` / `memory_archive` / `memory_export` / `memory_import` / `memory_context` |
| `spectral.py` | 2 | 频谱周期检测：`cycle_detect` / `cycle_phase`（多方法 FFT/ACF/小波/EMD/Lomb/MUSIC/ESPRIT/MEM + CF 带通相位） |
| `international.py` | 4 | 国际/跨市场：`asset_bubble_watch` / `capital_flow_monitor` / `debt_sustainability` / `financial_stress_index` |

> 注：`event_calendar.py` 未直接列入 `_TOOL_MODULES`，但被 `reports_view.py` 导入、作为副作用注册，其 9 个工具实际可用。周期图表/扩展数据工具定义于 `analysis/macro/cycles/dispatch.py`（被 `cycles.py` 引用）。

### 4.2 按投研层次的能力域映射
| 能力域 | 主要模块 |
|--------|----------|
| 行情与数据底座 | `stocks` · `market_data` · `market_snapshot` |
| 个股研究（基本面/技术/事件/诊断） | `stocks` · `tech_indicators` · `stock_reports` · `analysis` · `anti_fraud` · `quality` |
| 行业与板块 | `industry` · `market`(sector_*) · `event_calendar`(domain_constituents) |
| 宏观与经济指标 | `macro` · `bonds`(us_economic_indicators) · `international` · `industry`(caixin/ff_factors) |
| 经济周期 | `cycles` + `analysis/macro/cycles/dispatch` · `spectral` |
| 大宗商品（贵金属/期货/现货） | `industry`(spot_*) · `precious_metals` · `futures` |
| 债券与期权 | `bonds` |
| 外汇 | `forex` |
| 加密资产 | `crypto` |
| 基金 | `funds` |
| 资产配置与组合 | `allocation` · `portfolio` |
| 政策研究 | `policy` |
| 资金·情绪·舆情 | `market`(northbound/margin/stock_sector_fund_flow_rank) · `market_snapshot`(capital_flows_snapshot) · `crypto`(fear_greed_index) · `international`(capital_flow_monitor) · `stock_reports`(capital_tracking) |
| 主题投资 | `invest_theme` |
| 投研日历 | `event_calendar` |
| 管家长期记忆 | `butler` |
| 调度报告 | `reports_view` |
| 缓存与运维 | `analysis`(cache_clear/cache_status) · `cycles`(cycle_cache_status) |

### 4.3 资源（14 个 `skill://investment/*`）
```
fundamental: internal-inspection · industry-comparison · quality-assessment
sentiment:   institutional-behavior · public-opinion · market-trading · alternative-nbs_dictionary
cycle:       kitchin-cycle · juglar-cycle · positioning-logic
integration: analysis-path · decision-framework
visualization: core-formula · chart-specs
```
> 这些资源是投研方法论/SOP 知识，被 AI 推理时作为背景框架调用（对应 `agents/` 下的 SOP 技能）。

### 4.4 提示（7 个 SOP）
`analyze-stock-full`(个股全景) · `analyze-financial-quality`(财务质量) · `analyze-industry-position`(行业地位) · `analyze-cycle-position`(周期位置) · `generate-investment-charts`(生成图表) · `quick-health-check`(快速体检) · `full-investment-report`(完整投研报告)

---

## 5. 数据层与落盘位置

数据按"**原始数据（Actual）永不过期、增量追加；处理/信号数据（Derived）版本号锁定 + TTL**"分层（见 §6）。

| 库 / 缓存 | 路径 | 性质 | 主要写入方 |
|-----------|------|------|-----------|
| `reports.db` | `<repo>/data/reports.db`（`REPORTS_DB_PATH`） | 业务库 | `reports/store.py`（调度报告/连板/日历/主题/校准） |
| `butler.db` | `<repo>/data/butler.db`（`BUTLER_DB_PATH`） | 业务库 | `butler/store.py`（管家长期记忆） |
| `market_data.db` | `<repo>/data/market_data.db`（`MARKET_DATA_DB_PATH`） | Actual 永久库 | `data/sources/market_collector.py` + `market_bridge.py`（个股/指数日行情，前复权 + stock_info） |
| `industry_data.db` | `<repo>/data/industry_data.db` | Actual 永久库 | `shared/industry_db.py`（同花顺行业日行情/分类/资金流 + 申万） |
| `market_snapshot.db` | `<repo>/data/market_snapshot.db`（`MARKET_SNAPSHOT_DB`） | 业务库 | `tools/market_snapshot.py`（大盘/资金面快照） |
| `policy_cache.db` | `~/output/data/policy_cache.db` | Actual 永久库 | `shared/policy_db.py` + `scrapers/`（政策源落库） |
| `cycle_cache.db` | `~/output/data/cycle_cache.db` | Actual 永久库（FRED/世界银行/周期原始序列） | `shared/cycle_db.py` |
| `data_lake.db` | `~/.cache/deep_fusion/data_lake.db`（diskcache 同目录） | Derived/通用 | `shared/constants.py`（`DATA_LAKE_FILE`） |
| 派生 diskcache | `data/cache`（`DEEP_FUSION_CACHE_DIR`，CacheKey L2）与 `~/.cache/deep_fusion`（`get_cache_dir` 默认） | Derived | `cache.py` |
| 后端内存 L1 | `serve.py` 进程内 `TTLCache` | Derived（热数据，重启即清） | `cache.py` |

> **运维红线**：`cycle_cache.db` / `industry_data.db` / `market_data.db` 等 Actual 库**不可整体删除**——否则丢失增量基线，逼全量重拉（NBS 有频率限制）。清缓存只清派生 diskcache + 对应脏表 + 重启后端（见 §8）。

---

## 6. 缓存与数据新鲜度机制

核心原则：**原始数据（Actual）永不过期，处理/信号数据（Derived）需新鲜度机制**。管理模块 `deep_fusion/shared/freshness.py`（`DATA_CLASSIFICATION` 注册表）。

- **派生缓存（CacheKey）**：键名内嵌**版本号**。改算法逻辑时**必须 +1 版本号**，旧缓存自动失效，否则前端会一直看到旧数据。当前版本锁（2026-08）：
  - 康波：`kondratiev_cycle` v3 / `data_kondratiev` v5 / `cycle_collect` v3
  - 基钦：`data_kitchin` v2；朱格拉：`data_juglar` v2；库兹涅茨：`data_kuznets` v2
  - 扩展序列：`data_*_extended` v1；`cycle_nesting` v4
  - 版本号变更须同步登记到 `freshness.py` 的 `DATA_CLASSIFICATION`。
- **TTL 分级**：轻量 1h/1d，中量 7d/30d，重量 1d/7d。
- **增量更新**：Actual 库从"DB-first 永不过期"升级为"DB-first + `needs_incremental_update()` 检查"；间隔按频率分级（实时 5min / 日频 4h / 月频 3d / 季频 15d / 年频 60d），用 `INSERT OR REPLACE` 只追加新日期不删旧行。

> 涉及周期相位/信号公式/阈值/数据源/置信度的计算定义享有最高保护优先级，重构不得改动（见 `AGENTS.md` 红线）。

---

## 7. API 契约（前端消费方式）

> 前端看板已**独立为 `deepfusion-webui` 模块**（见其仓库 README），本仓库只提供 HTTP API。

- **JSON-RPC 风格调用**：前端 `services/mcp.js` 以 `POST /api/tools/call`（`{name, arguments}`）调用工具，`GET /api/tools/list` 列出全部工具。面板 `deepfusion-desktop` 与 webui 均消费此接口（默认 `http://localhost:5173`）。
- **MCP 协议入口**：`deep-fusion --http` 额外在 `/mcp` 暴露标准 MCP streamable-HTTP，供 Claude / Cursor 等 MCP 客户端接入。
- **采集与 API 解耦**：看板的"每日新鲜"数据由独立调度器 `deep-fusion-collect` 周期性填充（写入 `data/*.db` 与派生缓存）；API 进程本身不负责定时任务。若采集未跑，看板展示的是上次采集的快照，而非实时失效。调度方式见 §9。
- **附加路由**：`/api/butler/*`（管家记忆 CRUD/导入导出）、`/api/model-config`（运行时模型配置）、`/api/logs`（运行时日志）、`/metrics`（Prometheus）。

---

## 8. 运维、健壮性约束与常见坑

### 8.1 启动 / 重启
- **API 服务（面板 / webui 消费）**：`uv run python serve.py`（端口 5173，纯 `/api/*`，无内置后台线程）。
- **MCP 协议服务**：`uv run deep-fusion --http --host 0.0.0.0 --port 5173`（暴露 `/mcp`）。
- **后台采集**：由 `deep-fusion-collect` CLI 单次执行，外部调度（cron / systemd timer / docker sidecar）周期触发。
- 前端（webui / desktop panel）由各自独立模块启动，详见对应仓库 README。

### 8.2 健壮性硬约束（定时任务/后台线程 import 的模块）
- `logging_config.py`：原无条件 `import structlog`，环境缺则整个 serve 进程起不来 → 已加降级标准 logging。
- `nbs_client.py`：`_NbsClient` 单例缓存/索引 JSON 原裸读，损坏即崩 → 已加 try/except + 原子写。
- **任何被后台线程 import 的模块，顶层依赖必须有降级保护；读缓存/索引 JSON 必须 try/except，禁止裸 `json.load(read_text)`。**

### 8.3 stdio 日志污染（critical）
`deep_fusion/__init__.py` 的 `main()` 各入口（含 stdio `mcp.run()`）必须调 `configure_logging()`，日志只走 stderr/文件。否则 structlog 默认 PrintLogger 打 stdout 会破坏 stdio 协议流，e2e 测试 `JSONDecodeError`。

### 8.4 代理
- 东方财富（经 akshare）/ 同花顺（经 akshare）/ 雪球 等需 HTTP 代理（推荐 Clash Verge 混合端口 `7897`）。`serve.py` 默认设 `HTTP(S)_PROXY=127.0.0.1:7897`，并在 `NO_PROXY` 强制直连：申万、同花顺、新浪、雪球、巨潮、**国家统计局 stats.gov.cn**。
- 境内源（申万/同花顺/新浪/雪球/巨潮/NBS）直连不经代理，代理不可达时不致命；腾讯 gtimg 行情直连始终可用。

### 8.5 清缓存 SOP（三层都要动，否则仍返旧值）
1. 派生 diskcache：`rm -rf ~/.cache/deep_fusion` 与 `rm -rf data/cache`
2. Actual 脏表（只清脏表）：`from deep_fusion.shared.cycle_db import clear; clear("<indicator>")`
3. 后端内存 L1：重启后端

---

## 9. 测试与开发

```bash
# 依赖安装（uv）
uv sync
cp .env.example .env        # 配置代理等

# 启动 MCP（Stdio）
uv run python -m deep_fusion
uv run python -m deep_fusion --inspect   # 查看已注册工具/资源/提示词（实测 177/14/7）

# 启动 MCP HTTP API（端口 5173，纯 API，无后台采集）
uv run deep-fusion --http --host 0.0.0.0 --port 5173
# 或直接用便捷脚本（含 butler 记忆路由）
uv run python serve.py

# 后台采集（独立运行，由外部调度触发；不加 while True 常驻）
uv run deep-fusion-collect --kind warmup    # 预热周期缓存
uv run deep-fusion-collect --kind daily     # 每日数据采集
uv run deep-fusion-collect --kind all       # 全部依次执行一次

# Docker 部署（API + 采集 sidecar 分离）
docker compose up -d deep-fusion            # 仅 API
docker compose run --rm collector           # 触发一次采集（可用 cron/systemd timer 周期调用）

# 初始化本地数据资产（可选；scripts/ 从源仓库取，或按需自建）
uv run python scripts/init_data.py   # 若 scripts/ 未随仓库分发，可忽略此步

# 后端测试（pytest）
uv run pytest tests/ -v

# 语法检查
uv run python -m compileall .
```

- 测试覆盖：`cache` / `correlation` / `industry_collector` / `industry_sw` / `policy_collector` / `market_*` / `reports_store` / `server` / `limit_up` / `calibrated_prob` / `chart_helpers` / `shared` 等。
- **测试导入规范**：`CacheKey` 从 `deep_fusion.cache` 导入（不在顶层包）；`load_portfolio`/`save_portfolio` 在 `deep_fusion/shared/utils.py`；`industry.py` 工具参数用 `_val()` 解包 `FieldInfo`（兼容 MCP 框架与直接 Python 调用）。

---

## 10. 目录结构

```
DeepFusion/
├── deep_fusion/                 # 主包（单一工具实现）
│   ├── __init__.py              # 入口 + main() + --inspect + lazy import + configure_logging
│   ├── __main__.py              # python -m deep_fusion
│   ├── server.py                # FastMCP 实例 + 决策树 INSTRUCTIONS
│   ├── serve.py                 # Starlette Web 服务（5173，/api/*，无内置后台线程）
│   ├── cache.py                 # 双层缓存 L1 内存/L2 磁盘 + CacheKey 版本锁
│   ├── freshness.py             # 数据分类注册表 + 新鲜度判定
│   ├── metrics.py / logging_config.py
│   ├── prompts.py / resources.py
│   ├── analysis/                # 计算引擎
│   │   ├── engine.py            # CycleEngine 核心（IndicatorDef.fetch + 增量更新）
│   │   ├── kondratiev.py / juglar.py / kuznets.py / kitchin.py
│   │   ├── industry/rotation.py
│   │   ├── stock/screener.py
│   │   └── macro/cycles/        # engine.py + dispatch.py（chart_*/data_* 工具定义处）
│   ├── data/sources/            # 数据源层
│   │   ├── nbs_client.py        # 国家统计局流式 API（_NbsClient 单例 + 8 fetch）
│   │   ├── industry_collector.py / market_collector.py / market_bridge.py
│   │   ├── fred.py / world_bank.py / data_lake.py
│   │   ├── registry.py          # 数据源优先级登记（tdx/tencent/sina/ths/eastmoney/akshare/scrapers/xueqiu）
│   │   └── scrapers/            # 本地采集工具包（监管/财联社/新闻/热搜）
│   ├── shared/                  # 跨工具复用
│   │   ├── chart_helpers.py / phase_utils.py
│   │   ├── correlation.py / dcc_garch.py / causality.py / network_analysis.py
│   │   ├── industry_db.py / cycle_db.py / policy_db.py
│   │   ├── spectral.py / indicators.py / normalize.py / schema.py
│   │   ├── request.py / utils.py（ak_cache + EM 回退）
│   └── tools/                   # 28 个工具模块文件（177 @mcp.tool）
├── agents/skills/               # 投研 SOP 技能（adversarial-review / cycle-allocator / ...）
├── references/                  # 投研参考文档
├── tests/                       # 测试文件
├── scripts/                     # 可选辅助脚本（calendar_collect / report_writer / init_data / 健康检查等，从源仓库取）
├── logs/                        # 运行日志 + API 健康报告（运行时生成）
├── Dockerfile / docker-compose.yml
├── smithery.yaml / server.json / pyproject.toml / uv.lock
└── README.md / AGENTS.md
```

> **前端已独立**：React 看板在 `deepfusion-webui` 仓库；桌面面板在 `deepfusion-desktop` 仓库。两者均经本仓库的 `/api/tools/call` 消费工具。

---

## 11. 扩展指南（给架构师）

**新增一个 MCP 工具**：
1. 在合适的 `tools/<module>.py` 中写函数，用 `@mcp.tool` 装饰（可 `name=` 显式命名）。
2. 参数用 Pydantic `Field(default, description=...)`；若可能被框架传 `FieldInfo` 默认值，参考 `industry.py` 的 `_val()` 解包。
3. 若该模块未在 `deep_fusion/__init__.py` 的 `_TOOL_MODULES` 注册，追加模块名（触发 `@mcp.tool` 执行注册）。
4. 返回 `str`：结构化数据用 JSON，表格用 CSV，报告用 text。

**新增周期/信号处理算法**：
- 必须保留旧计算的输入/输出接口；改算法时把 `freshness.py` / 相关缓存键版本号 +1。
- 涉及相位/信号公式/阈值的改动，执行前列出旧↔新逻辑差异，并 `@相关方` 确认（见 `AGENTS.md` 红线）。

**新增数据源**：
- 走 `data/sources/`，优先 DB-first + 增量更新；读缓存/索引 JSON 必须 try/except。
- 实测验证接口可用（项目铁律：引入 URL/接口必须逐一 http 实测，不可盲搬）。

---

## 12. 文档索引

| 文件 | 用途 |
|------|------|
| `AGENTS.md` | AI 助手/架构师协作指南：架构边界、红线禁令、缓存版本锁、共享模块契约、工具注册表、扩展 SOP |
| `server.json` | MCP 客户端配置模板 |
| `agents/skills/` | 12 个投研 SOP 技能 |
| `references/` | 投研参考词典（宏观/中观/微观） |
| `AGENT_BOARD.md` | 量化分析师 ↔ 代码维护 Agent 跨 Agent 异步交接板 |
| `PROJECT_ANALYSIS.md` | 本项目的深度能力/板块/数据支持分析（与本文档 §4/§5 同源，由 `inspect` 实测生成） |