# 基于 Hermes 的 A 股金融投研 Agent

基于 **Hermes Agent 运行时**与 **MCP 协议**构建的 A 股投研 Agent：将行情、新闻、技术分析、组合风控、回测与模拟交易能力封装为 **11 个可组合的 MCP 工具**，Agent 自主规划研究步骤并调用工具，输出**带数据来源与计算依据**的结构化研究报告，支持个股研究、行业分析与持仓复盘三类工作流。

> 本项目仅用于研究与模拟交易（纸面交易），不连接真实券商账户，不构成投资建议。

## 这是什么 / Hermes 负责什么

技术边界（Hermes 不做金融计算，本项目不绑定任何 LLM）：

```text
用户投研问题
    ↓
Hermes Agent 运行时          ← 理解问题、规划步骤、选择工具、组织答案
    ↓  MCP (stdio / HTTP)
金融工具服务（本项目）        ← 行情、新闻、指标、风控、回测、模拟交易
    ↓
AKShare / TrendRadar / 腾讯·东财行情接口 / SQLite
```

- **Hermes 侧**：加载 `agent/system_prompt.md` 与三个 Skill（`agent/skills/`），通过 MCP 调用工具（接入配置见 `agent/hermes_mcp.example.json.md`）
- **工具侧**：`stock_simulator/agent_tools/` 的 11 个核心工具，全部返回统一响应包 `{success, data, sources, as_of, warnings}`，每次调用写入 SQLite 可复查

## 11 个核心工具

| 分组 | 工具 | 说明 |
| --- | --- | --- |
| 数据获取 | `get_stock_quote` / `get_price_history` | 最近行情（含时间戳）/ 历史 K 线与区间统计 |
| | `get_finance_news` / `get_sector_performance` / `get_market_regime` | 相关新闻 / 板块表现 / 市场环境判定 |
| 投研分析 | `screen_stocks` / `analyze_stock_signals` | 多因子选股 / 技术指标与规则信号（附计算依据） |
| | `analyze_news_impact` / `evaluate_portfolio_risk` | 新闻事件影响（附判断依据）/ 组合风险体检 |
| 执行验证 | `run_backtest` / `execute_paper_trade` | 历史回测 / 模拟交易（须用户确认） |

**证据链**：每个数值可追溯到提供方（provider）、交易日（trade_date）与抓取时间（retrieved_at）；新闻记录含标题/时间/原始来源/链接/抓取时间/情感判断与判断依据（关键词命中）。

**交易风控（fail-closed）**：查询与分析允许降级（离线回退演示数据并标注）；交易保守失败——价格缺失/时间戳不可证明/行业信息缺失/风控检查异常/账户数据异常时拒绝执行，且必须 `user_confirmed=true`（研究建议 ≠ 自动下单）。

## 快速开始

需要 Python 3.11+。

```bash
python -m venv .venv && source .venv/bin/activate   # Windows: .\.venv\Scripts\Activate
pip install -r requirements.txt
cp .env.example .env                                  # 可不修改，全部有默认值
```

**一条离线演示命令**（无需网络、无需 LLM 密钥，使用 `data/demo/` 内置演示数据）：

```bash
python -m stock_simulator.demo --offline
```

依次调用 `get_stock_quote → get_price_history → get_finance_news → analyze_news_impact → analyze_stock_signals → get_market_regime → evaluate_portfolio_risk → run_backtest`，生成：

- [examples/research_report.md](examples/research_report.md) — 带来源引用的研究报告
- [examples/tool_trace.json](examples/tool_trace.json) — 完整工具调用轨迹（参数/结果/来源/耗时）

**启动 MCP 服务（供 Hermes 调用）**：

```bash
python -m stock_simulator.mcp_server                  # stdio（默认）
# STOCK_SIM_MCP_TRANSPORT=streamable-http python -m stock_simulator.mcp_server
```

**运行测试与评测**：

```bash
python -m unittest discover -s tests    # 15 项离线测试（含风控 fail-closed 用例）
python evals/run_evals.py               # 24 条评测：工具选择/参数契约/计算口径/引用完整性/异常降级
```

## 三个演示问题（对应三个 Skill）

```bash
# Skill 1 · 个股研究（验收场景）
python -m stock_simulator.demo --offline --skill stock --stock 600519
#   「分析贵州茅台最近的行情、相关新闻和技术信号，判断其主要风险，并给出研究结论。」

# Skill 2 · 行业研究
python -m stock_simulator.demo --offline --skill sector --sector 半导体
#   「分析近期 A 股半导体行业表现，并筛选三只值得进一步研究的股票。」

# Skill 3 · 持仓复盘
python -m stock_simulator.demo --offline --skill portfolio --account demo
#   「复盘当前账户风险，并提出调整建议。」（演示账户含行业集中度超限等真实风控触发）
```

联网时去掉 `--offline` 即使用实时数据（腾讯/东财行情、TrendRadar 新闻、AKShare 回退）。产出的另两份示例报告：[examples/sector_report.md](examples/sector_report.md)、[examples/portfolio_report.md](examples/portfolio_report.md)。

## Hermes 接入

配置片段（完整说明见 [agent/hermes_mcp.example.json.md](agent/hermes_mcp.example.json.md)）：

```json
{
  "mcpServers": {
    "a-share-financial-research": {
      "command": "python",
      "args": ["-m", "stock_simulator.mcp_server"],
      "cwd": "/path/to/a-share-agent-trading-simulator"
    }
  }
}
```

系统提示词 `agent/system_prompt.md` 约定 Agent 行为：不编造缺失数据、区分事实/计算/判断、每项结论引用来源、数据源失败明说、结论不作投资承诺、交易必须确认。所有工具调用（含参数与返回来源）记录在主库 `agent_tool_calls` 表，支持事后复查。

## 数据来源与能力边界

| 数据 | 在线来源 | 离线回退 |
| --- | --- | --- |
| 实时行情/K线 | 腾讯行情、东方财富（自动回退切换） | `data/demo/` 演示数据（provider=demo，warnings 显式标注） |
| 财经新闻 | TrendRadar 本地库 → akshare | 演示新闻（含情感判断依据） |
| 行业/指数 | 东方财富板块与指数接口 | 演示板块/指数数据 |
| 持仓/成交/决策 | — | SQLite（`data/` 目录，路径可用环境变量覆盖） |

- **无 LLM 密钥时**：全部能力可用。新闻情感与事件影响为关键词规则计算（附命中词依据），非模型判断；工具层不调用任何 LLM。
- **无网络时**：研究/演示/评测可完整运行（演示数据）；**模拟交易保守拒绝**（无法证明行情时效）。
- 演示数据由 `scripts/build_demo_data.py` 固定种子生成，仅用于演示与测试，不可作真实投资参考。

## 项目结构

```text
agent/                     Agent 定义（提示词 / 三个 Skill / Hermes 接入示例）
stock_simulator/
  agent_tools/             11 个 MCP 工具实现（与传输层解耦，可离线测试）
  mcp_server.py            MCP 服务入口（stdio/sse/http）
  demo.py                  离线/在线演示（生成报告与调用轨迹）
  agents/ eqlib/ strategies/ core/ utils/   交易模拟与回测内核（既有能力）
  paths.py config.py       统一路径与环境变量（.env）
evals/                     评测集（cases.json + run_evals.py）
examples/                  演示产物（研究报告 / 工具调用轨迹）
data/demo/                 内置演示数据（固定种子生成）
tests/                     离线测试（unittest）
scripts/                   维护脚本（演示数据生成、盘前选股）
```

更详细的系统设计见 [design_doc.md](design_doc.md) 与 [docs/](docs/)。

## 风险声明

本项目为研究用途的模拟交易系统：历史回测不预示未来收益；技术信号与新闻影响判断均为规则计算；离线演示数据不可作为投资参考；本项目不构成任何投资建议。

## 开源协议

MIT