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

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

python -m stock_simulator.demo --offline

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

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

# 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
#   「复盘当前账户风险，并提出调整建议。」（演示账户含行业集中度超限等真实风控触发）

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

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/                   维护脚本（演示数据生成、盘前选股）