Hermes Finance — 缠论+多维度金融市场分析框架

# Hermes Finance — 缠论+多维度金融市场分析框架

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-v1.1.1-green.svg)](https://github.com/Lzh-xbccz/hermes-finance/releases)
[![Releases](https://img.shields.io/github/v/release/Lzh-xbccz/hermes-finance?include_prereleases&label=latest)](https://github.com/Lzh-xbccz/hermes-finance/releases)

> 基于 [czsc](https://github.com/waditu/czsc) v1.0 缠论库，覆盖 **加密货币 / 商品期货 / 外汇 / A股 / 美股** 五大市场。每个市场采用多维因果分析框架，集成缠论作为核心技术分析维度。

---

## 🚀 v1.1.1：双版本金融分析 + AI 客户端适配

Hermes Finance 现在同时支持 **Skills** 和 **MCP** 两种使用方式：

- **Skills 版**：给 Codex/Agent 使用的市场分析技能，保留八大技能目录和严格输出框架。
- **MCP 版**：给 Claude Desktop、Cursor、支持 MCP 的 Agent 客户端调用，暴露标准 tools/resources/prompts。
- **AI 工具适配**：新增 Claude Code、Codex、Cursor、VS Code/Copilot、Gemini、Roo、Continue、Zed 等项目级配置，以及 Claude Desktop、Windsurf、Cline、Amp 等用户级模板。
- **MCP server instructions**：连接后自动提示 AI 先路由标的、读取市场框架、分离事实与推断，并报告数据源状态。
- **共享核心库**：`hermes_finance/` 统一路由、采集器调用、缠论确认和 Markdown/JSON 输出，避免维护两套行情逻辑。

完整安装、使用、MCP 接入、AI 客户端适配、功能和排错见 [docs/USAGE.md](docs/USAGE.md) 与 [docs/AI_CLIENTS.md](docs/AI_CLIENTS.md)。

---

## 🏗️ 项目架构

```
hermes-finance/
├── requirements.txt                 # Python 依赖
├── requirements-mcp.txt             # MCP 可选依赖
├── .mcp.json                        # Claude Code / 通用 MCP 项目配置
├── .codex/config.toml               # Codex 项目 MCP 配置
├── .cursor/mcp.json                 # Cursor 项目 MCP 配置
├── .vscode/mcp.json                 # VS Code / Copilot MCP 配置
├── .gemini/settings.json            # Gemini CLI MCP 配置
├── .continue/mcpServers/            # Continue MCP server 配置
├── install.sh                       # 一键安装
├── VERSION                          # 版本号
├── CHANGELOG.md                     # 完整更新日志
├── bin/hermes_finance_mcp.py        # 便携 MCP launcher
├── integrations/                    # 各 AI 客户端用户级配置模板
├── hermes_finance/                  # 共享核心 API（CLI / Skills / MCP 共用）
├── hermes_finance_mcp/              # MCP server
├── scripts/
│   ├── czsc_analyze.py              # 缠论多级别联立分析（核心引擎）
│   ├── market_analyze.py            # 多市场统一入口（共享核心薄封装）
│   └── localize_chart.py            # 图表中文化工具
└── skills/                          # 8 个分析技能
    ├── crypto-market-analysis/      # 🟠 加密货币 — 八维分析
    ├── futures-market-analysis/     # 🟡 商品期货 — 六维分析
    ├── forex-market-analysis/       # 🔵 外汇 — 六维分析+利率差
    ├── a-share-market-analysis/     # 🔴 A股 — 六维+量化选股(Sequoia-X)
    ├── us-equity-market-analysis/   # 🟣 美股 — 六维分析
    ├── multi-market-analysis/       # 🔀 智能路由
    ├── czsc-ccxt-analysis/          # 🎯 缠论引擎（薄封装→主脚本）
    └── microcap-pnd-system/         # ⚠️ 极端山寨检测
```

---

## 🔌 双版本入口

### 1. Skills 版本

Skills 目录保留 8 个分析技能：

- `multi-market-analysis`：跨市场总路由
- `crypto-market-analysis`：加密货币七维因果 + 缠论确认
- `futures-market-analysis`：商品/股指期货六维分析
- `forex-market-analysis`：外汇六维 + 利率差
- `a-share-market-analysis`：A股六维 + Sequoia-X 选股
- `us-equity-market-analysis`：美股/ETF/指数分析
- `czsc-ccxt-analysis`：缠论引擎
- `microcap-pnd-system`：极端山寨/Pump & Dump 风险识别

### 2. MCP 版本

```bash
pip install -r requirements-mcp.txt
python3 bin/hermes_finance_mcp.py
```

`.mcp.json`、`.codex/config.toml`、`.cursor/mcp.json`、`.vscode/mcp.json`、`.gemini/settings.json` 等项目级配置已放在仓库内；`integrations/` 提供 Claude Desktop、Windsurf、Cline、Amp 等用户级模板。

MCP 暴露的 tools：

- `route_market_tool`
- `fetch_market_data_tool`
- `analyze_market_tool`
- `analyze_crypto`
- `analyze_futures`
- `analyze_forex`
- `analyze_us_equity`
- `analyze_a_share`
- `czsc_analyze_tool`

MCP resources/prompts：

- `finance://routing`
- `finance://framework/{market}`
- `deep_market_analysis`
- `czsc_confirmation_review`

### 3. 共享 CLI

```bash
python3 -m hermes_finance route BTC
python3 -m hermes_finance fetch futures GC
python3 scripts/market_analyze.py crypto bitcoin --with-czsc --markdown
```

### 4. AI 客户端适配

项目内已放好常见 AI 工具的配置：

| 工具 | 文件 |
|---|---|
| Claude Code | `.mcp.json`, `CLAUDE.md` |
| Codex CLI / IDE | `.codex/config.toml`, `AGENTS.md` |
| Cursor | `.cursor/mcp.json`, `.cursor/rules/hermes-finance.mdc` |
| VS Code / GitHub Copilot | `.vscode/mcp.json`, `.github/copilot-instructions.md` |
| Gemini CLI | `.gemini/settings.json`, `GEMINI.md` |
| Roo / Continue / Zed | `.roo/mcp.json`, `.continue/mcpServers/hermes-finance.yaml`, `.zed/settings.json` |

生成用户级配置模板：

```bash
python3 scripts/render_ai_client_config.py claude-desktop
python3 scripts/render_ai_client_config.py windsurf
python3 scripts/render_ai_client_config.py cline
python3 scripts/render_ai_client_config.py codex
```

完整矩阵见 [docs/AI_CLIENTS.md](docs/AI_CLIENTS.md)。

---

## 🎯 八大分析技能

### 1. 加密货币 — 八维分析 🟠

| # | 维度 | 核心问题 |
|---|------|---------|
| 1 | 技术结构 | 趋势方向？支撑阻力在哪？ |
| 2 | 合约数据 | OI / 资金费率 / 多空比 — 谁在押注？ |
| 3 | 量价关系 | 放量还是缩量？真实买盘还是对倒？ |
| 4 | 基本面 | 链上数据 — 抛压从哪来？解锁在何时？ |
| 5 | 情绪面 | 恐惧贪婪指数 — 市场狂热还是绝望？ |
| 6 | 宏观联动 | **实时拉取** VIX / DXY / SPY + BTC-SPY 5日趋势联动

... (truncated)