# Fund Trading Agent

面向长期基金投资的多 Agent 辅助决策系统，集成持仓批次、赎回费、
QDII 海外行情、净值估算、确定性风控、MCP 工具、微信通知与可审计决策链路。

> 本项目只提供投资研究和辅助决策能力，不自动连接基金平台执行真实交易，
> 不构成投资建议，也不承诺收益。

## 当前版本

- 版本：V5
- 策略画像：激进型、长期投资、最大可接受回撤 30%
- 状态：准生产，仍需完成连续交易日 dry-run
- 时区：`Asia/Shanghai`
- Python：3.11+
- 测试基线：244 个公开仓库测试；本地生产账本另有 3 个隐私对账测试

## 核心能力

### 交易与持仓

- SQLite 交易账本和持仓汇总
- 买入批次与 FIFO 卖出分配
- 不同批次持有天数自动更新
- 基于持有期限的赎回费计算
- 待确认订单、定投计划、已实现与未实现收益
- 总资产、总持仓、可用资金和待确认金额一致性校验

当前四只配置基金的赎回费规则为：

| 持有时间 | 赎回费率 |
|---|---:|
| 少于 7 天 | 1.50% |
| 7 天至不足 30 天 | 0.50% |
| 30 天及以上 | 0.00% |

### 市场数据

- A 股、港股、基金净值、行业、资金流和新闻数据
- CME E-mini Nasdaq-100 期货 `NQ=F`
- NDX 和 QQQ 代理降级，明确返回 `is_proxy`
- 美股科技七巨头、半导体和 AI 基础设施标的
- 三星电子、SK 海力士
- SpaceX `SPCX` 与太空经济 ETF
- 市场时区、交易日、数据时间和
  `realtime/delayed/stale/unknown` 新鲜度标记

### 决策与风控

- 技术面、基本面、资金面、消息面和风险 Agent
- 一次分析内共享不可变 `AnalysisSnapshot`
- 数据质量分级和失败降级
- LLM 超时、非法 JSON、越权动作时 fail-closed
- 单基金仓位、组合仓位、行业集中度、现金缓冲和回撤限制
- 决策、Agent 调用、通知和数据快照审计记录

### 集成

- MCP Server 工具接口
- 日间预分析、正式分析、晚间复盘和 QDII 校准任务
- 微信通知及失败重试
- 海外行情 5 分钟数据库缓存与失败后的过期缓存降级

## 项目结构

```text
agents/          多维分析和决策 Agent
analytics/       指标、暴露、背离和尾部风险计算
application/     分析服务与金额计算
core/            编排、快照、信号契约和风控策略
data/collectors/ 类型化数据采集器
evaluation/      回测、回放和评估指标
notification/    通知发送、记录和重试
scheduler/       日间、晚间和 QDII 调度任务
scripts/         校验、模拟和运维脚本
tests/           自动化测试
mcp_server.py    MCP 服务入口
```

## 快速开始

### 1. 创建环境

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

Windows PowerShell：

```powershell
py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
```

### 2. 配置

编辑 `config.yaml`：

- `portfolio.funds`：关注或持有的基金
- `fund_exposure`：基金市场、行业、ETF 和基准映射
- `user_profile`：风险类型、最大回撤和投资期限
- `risk`：仓位、集中度、现金和操作限制
- `portfolio_settings.fund_fee_overrides`：基金赎回费规则

LLM 密钥仅通过环境变量提供：

```bash
export DEEPSEEK_API_KEY="your-key"
```

不要将 `.env`、数据库、持仓文本或交易流水提交到 Git。

### 3. 运行测试

```bash
PYTHONPATH=. pytest -q
python scripts/security_check.py
python scripts/validate_p0.py
```

### 4. 启动 MCP Server

```bash
python mcp_server.py
```

主要 MCP 工具包括：

- `analyze_fund`
- `run_daily_analysis`
- `run_evening_review`
- `get_nasdaq_futures`
- `get_overseas_stock_quote`
- `get_overseas_hot_stocks`
- `get_positions`
- `preview_trade`
- `confirm_trade`

## 数据质量约定

海外行情统一返回以下关键字段：

```json
{
  "source": "yfinance_cme",
  "data_time": "2026-06-19 00:00:00-04:00",
  "fetch_time": "2026-06-22T00:00:00+08:00",
  "timezone": "America/New_York",
  "freshness": "delayed",
  "is_proxy": false
}
```

- `realtime`：处于对应市场会话且数据足够新
- `delayed`：最近交易日或数据有正常延迟
- `stale`：已经落后于当前应有交易日
- `unknown`：缺少可靠数据时间

代理数据和 `stale/unknown` 数据只作为弱参考，不得驱动强交易动作。

## 安全与隐私

仓库不会包含：

- 真实持仓数据库和备份
- 账户余额、收益和完整交易流水
- API Key、Webhook 和访问令牌
- 本地 Hermes 或微信运行配置

生产数据默认保存在本地 SQLite 中。提交前应执行：

```bash
python scripts/security_check.py
git status --short
```

## 上线检查

详细门禁见 [docs/production_readiness.md](docs/production_readiness.md)。

上线前至少确认：

1. 全量测试和安全扫描通过。
2. 数据源断连时正确降级，不输出强动作。
3. NQ 期货代理和数据新鲜度标识正确。
4. 持仓批次、持有天数和赎回费边界正确。
5. 连续 5 个交易日 dry-run 无重复推送和越权建议。

## 免责声明

基金、QDII、杠杆 ETF 和海外证券均可能产生显著损失。系统输出受数据延迟、
模型误差、市场休市、汇率和基金净值确认周期影响。所有真实交易必须由用户
独立核对并手动确认。