# A 股 AI 研究与验证系统（ashare-ai-research）

> **确定性引擎负责计算，LLM 负责归纳，交易判断保留人工确认。**

一个从 0 到 1 独立设计搭建的 A 股投研系统：研究链路为「宏观与产业证据 → 主线候选 → 价格确认 → 风险预算 → 成交记录 → 成本后验证」，覆盖数据更新、每日复盘、产业分析、观察池、策略验证与研究回放。当前主流程为持有 1–4 周的主线波段，**不自动下单**。

## 为什么这样设计（三条核心决策）

| 决策 | 被否掉的备选 | 理由 |
|---|---|---|
| 确定性引擎与 LLM 分工 | LLM 端到端给建议 | 账户、规则、成本、回测计算必须是可复算的；LLM 只做信息归纳——可靠性、可解释性、责任归属三个角度都指向同一结论 |
| 基于公开时点信息的历史重建 | 直接用当前数据回测 | 防「未来数据」污染：研究只允许使用当时已存在的信息，保留信息来源、时间戳、分析过程与**失败记录** |
| 能力开放（MCP + Plugins） | 封闭单体系统 | 领域能力封装为兼容 Agent Plugins 1.0 的插件，并通过 MCP 向不同 Agent 客户端开放——研究能力可被任意 Agent 复用 |

## 验证状态（诚实口径）

- **69 个交易日回放、116 日研究、独立对账，168 项自动化测试通过**
- 截至六月底的独立回放与完整回放前缀完全一致；**研究失败日照实保留，没有重抽答案或按收益调参**
- 诚实边界：历史数据回填和模型训练记忆无法完全排除，因此**不是严格前瞻盲测**；没有真实下单；「研究功能可用」不等于「已证明交易盈利」

## 目录速览

```
src/ashare_review/    核心引擎（数据、研究链路、复盘）
strategy_factory/     策略工厂
plugins/              Agent Plugins 1.0 兼容插件
mcp_server.py         MCP 能力开放服务
web/                  本地工作台（默认 http://127.0.0.1:8787）
scripts/              数据更新 / 回放 / 健康检查
tests/                自动化测试（168 项）
docs/                 产品与系统文档（从 0 到 1 搭建过程、项目地图、业务指南）
```

一键健康检查：`python3 scripts/check_project.py` ｜ 一键启动：`./start_ai_strategy.command`

数据源：Tushare 本地日频快照（需自备 token，见 `docs/tushare_usage.md`）+ DeepSeek API。仓库不含行情原始数据与实验数据库（体积与数据源协议原因），复算材料另行保留。

---

# A-share Intelligence Review MVP（使用手册）

一个从“宏观与产业证据 → 主线候选 → 价格确认 → 风险预算 → 成交记录 → 成本后验证”的 A 股研究系统。当前主流程是持有 1–4 周的主线波段，不自动下单。

2026-09-05 新增默认首页「主线波段」，接通真实宏观指标、近期快讯全文、行情缺日补采、AI 传导与反证、模拟/实际分账。当前使用方法、验收证据、时间目标和未完成项见 [主线波段使用说明](docs/swing_workbench.md)。

系统从 0 到 1 的搭建过程、问题复盘、当前能力和后续调优方向见：

```text
docs/system_product_document.md
```

面向业务理解和日常沟通的通俗版文档见：

```text
docs/system_business_guide.md
```

当前使用 Tushare 本地日频快照与增量研究缓存、DeepSeek API，保留样例数据入口。它不是实时行情或券商执行系统。

当前尚未完整接入研报和公告正文、公司分业务营收及行业订单/价格/库存序列。快讯全文不等于其引用的公告原文；研究功能可用不等于已证明交易盈利。

## 很久没看项目时，从这里重新开始

先读 [项目地图](docs/project_map.md)，它只保留当前主线、目录职责、已知风险和下一步；完整文档导航见 [docs/README.md](docs/README.md)。

然后执行一键健康检查：

```bash
python3 scripts/check_project.py
```

这会检查 Python 与全部 JavaScript（网页脚本）语法，并运行项目自动化测试。

## 快速开始

一键启动本地操作界面：

```bash
./start_ai_strategy.command
```

在 macOS Finder 中也可以直接双击 `start_ai_strategy.command`。脚本默认只启动 Web 工作台并打开：

```text
http://127.0.0.1:8787
```

如果 8787 端口已被占用，脚本会提示先关闭旧服务，不会自动切换端口。MCP 服务保持可选，不随一键启动默认启动；数据更新仍在页面中点击“更新数据”手动触发。

```bash
python3 scripts/run_review.py --date 2026-05-15
```

输出报告会生成到：

```text
reports/2026-05-15.md
```

批量回放样例历史数据：

```bash
python3 scripts/backfill_reviews.py
```

默认只回放有行情数据的日期。如果要把只有新闻、没有行情的日期也生成出来：

```bash
python3 scripts/backfill_reviews.py --include-news-only
```

报告索引：

```text
reports/index.md
```

启动本地操作界面：

```bash
python3 scripts/serve_app.py
```

然后打开：

```text
http://127.0.0.1:8787
```

页面包含八个工作区：

0. `主线波段`：默认首页，自动采集宏观与快讯、更新行情、研究产业传导、等待价格确认、制定风险计划并记录成交结果。
1. `宏观研究`：查看经典周期地图、生成 AI 研究简报，维护结构性方向、产业链、证据、催化剂和失效条件。
2. `每日复盘`：生成事件、题材、涨停、龙虎榜和全量候选池。
3. `策略实验室`：理解近期市场，验证单战法或多战法组合。
4. `观察池`：用已验证策略筛选并持续维护标的。
5. `个股分析`：复盘成本、关键位和后续情景。
6. `风控监控`：统一查看市场与持仓风险。
7. `盘中信号`：扫描分钟级机会和风险信号。

首页加载主线波段与基础数据状态；其余工作区首次进入时按需加载。

### DeepSeek AI 分析

当前已内置 DeepSeek V4 Pro，配置读取自本机私有文件 `.env.local`。页面不会把 Key 暴露给浏览器源码。

使用方式：

1. 启动本地操作界面。
2. 进入 `策略实验室`。
3. 等待“近期盘感与Agent假设”加载完成。
4. 点击 `AI深度分析`。

AI 分析发生在“本地规则盘感生成之后、战法回测之前”：系统先用本地数据生成市场阶段、题材、来源反馈和规则假设，再把这份结构化材料交给 DeepSeek V4 Pro，生成市场叙事、研究假设、观察纪律和风险提醒。

如果要更换 Key 或模型，编辑：

```text
.env.local
```

策略实验室当前支持：

- 近阶段盘感：市场阶段、来源反馈、题材上下文和 Agent 假设
- DeepSeek V4 Pro 深度分析：输出市场叙事、研究假设、观察纪律和风险提醒
- 假设卡片：可回测假设可一键带入实验，待编码假设先沉淀
- 单战法学习模式：先理解用途、规则、适用场景和常见误判，再运行回测
- 多战法组装模式：支持“全部满足”和“至少满足两个”两种组合关系
- 价升量缩
- 过左峰
- 回马枪
- 长阴短柱
- 经典日本蜡烛图：看涨吞没、锤子线、早晨之星
- 固定持有或九阴风控
- 持有 `1、2、3、5、10` 个交易日对比
- 双边成本、一字涨停无法买入和一字跌停延后卖出模拟

回测口径为复盘日收盘确认信号，下一交易日开盘尝试买入。持有 `1` 日表示买入后至少隔夜，于下一交易日收盘卖出。

页面中点击“更新最新数据”，会自动拉取最近交易日的：

```text
日线、每日指标、市值、涨跌停价、资金流、涨停专题、连板梯队、
热点题材、停复牌、主要指数、龙虎榜和新闻
```

也可以在终端执行：

```bash
python3 scripts/update_market.py
```

指定历史日期：

```bash
python3 scripts/update_market.py --date 20260612
```

批量补齐日期区间：

```bash
python3 scripts/update_market_range.py --start-date 2026-05-15 --end-date 2026-06-15
```

生成回测汇总：

```bash
python3 scripts/summarize_backtest.py --start-date 2026-05-15 --end-date 2026-06-15
```

如果当前环境不能启动本地端口，也可以生成静态看板：

```bash
python3 scripts/build_static_dashboard.py
```

然后直接打开：

```text
reports/dashboard.html
```

## MCP Server（AI Agent 接口）

系统内置 MCP Server，让 AI Agent（Claude、GPT、Cursor 等）可以通过标准 tool call 调用全部功能。

### 安装

```bash
# 创建虚拟环境并安装依赖（需要 Python 3.10+）
uv venv .venv --python 3.11
source .venv/bin/activate
uv pip install -r requirements.txt
```

### 启动

```bash
source .venv/bin/activate
python3 mcp_server.py
```

### Claude Desktop 配置

```json
{
  "mcpServers": {
    "ashare": {
      "command": "/Users/menke/Desktop/AI策略/.venv/bin/python3",
      "args": ["/Users/menke/Desktop/AI策略/mcp_server.py"]
    }
  }
}
```

### Cursor / VS Code Copilot 配置

```json
{
  "servers": {
    "ashare": {
      "command": "/Users/menke/Desktop/AI策略/.venv/bin/python3",
      "args": ["/Users/menke/Desktop/AI策略/mcp_server.py"]
    }
  }
}
```

### 可用 Tools

| 工具 | 说明 | 工作流步骤 |
|------|------|------------|
| `cycle_list` | 查看经典周期地图与当前评估 | Step 0: 宏观研究 |
| `cycle_save` | 保存周期阶段、证据、反证与复查日期 | Step 0 |
| `cycle_delete` | 清除一个周期评估 | Step 0 |
| `narrative_list` | 查看宏观叙事和复查日期 | Step 0: 宏观研究 |
| `narrative_save` | 新建/更新叙事卡 | Step 0 |
| `narrative_delete` | 删除叙事卡 | Step 0 |
| `macro_research_brief` | DeepSeek 综合周期、货币、行业和盘面 | Step 0 |
| `update_market_data` | 拉取最新行情数据 | Step 1: 每日复盘 |
| `daily_review` | 生成某日复盘报告 | Step 1 |
| `market_sense` | 近期盘感 | Step 1 |
| `ai_market_sense` | DeepSeek AI 深度分析 | Step 1 |
| `available_dates` | 查询可用日期 | Step 1 |
| `profile` | 系统数据概况 | Step 1 |
| `strategy_config` | 列出战法和条件类型 | Step 2: 策略实验室 |
| `strategy_run` | 运行战法回测 | Step 2 |
| `strategy_create` | 创建自定义战法 | Step 2 |
| `strategy_draft` | 自然语言生成战法草案 | Step 2 |
| `strategy_delete` | 删除自定义战法 | Step 2 |
| `observation_pool` | 查看/筛选观察池 | Step 3: 观察池 + 个股演绎 |
| `observation_scan` | 用战法扫描入池 | Step 3 |
| `observation_update` | 更新池项状态/备注 | Step 3 |
| `stock_analysis` | 个股深度分析（含场景演绎） | Step 3 |
| `stock_lookup` | 查找股票代码/题材 | Step 3 |
| `daily_klines` | 获取日K线数据 | Step 3 |
| `risk_monitor` | 组合风控监控 | Step 4: 盘中实战 |
| `minute_signals` | 分钟级信号扫描 | Step 4 |

### Agent 典型调用链

```
0. cycle_list() → cycle_save(cycle_id="kitchin", ...)
1. narrative_list() → macro_research_brief() → narrative_save(name="AI基础设施", ...)
2. update_market_data() → daily_review(date="2026-06-17") → ai_market_sense()
3. strategy_draft("缩量回踩20日线后放量突破") → strategy_run(...) → strategy_create()
4. observation_scan(date="2026-06-17", strategy_ids=[...]) → stock_analysis(query="000001")
5. risk_monitor() → minute_signals(ts_codes=["000001.SZ"])
```

## 当前能力

- 读取历史新闻事件样例
- 根据题材知识库做事件到题材映射
- 读取历史行情/涨停样例
- 判断题材是否被市场验证
- 生成涨停梯队、情绪周期、次日观察池
- 将结构化结果保存为 Markdown 复盘
- 提供本地 Web 控制台，便于选择日期和测试报告

## 目录

```text
config/
  themes.yaml              # 题材知识库
  concept_rules.yaml       # Tushare 概念清洗规则
data/sample/
  news_events.csv          # 样例事件
  market_daily.csv         # 样例行情
  limit_up_daily.csv       # 样例涨停
reports/                   # 复盘输出
scripts/
  run_review.py            # 一键运行
  backfill_reviews.py      # 批量回放
  serve_app.py             # 本地操作界面
  build_static_dashboard.py # 静态看板
src/ashare_review/
  datasources.py           # 数据读取
  local_daily.py           # 本地日线 CSV 适配
  event_mapper.py          # 事件 -> 题材映射
  market_validator.py      # 市场验证评分
  report.py                # 报告生成
  models.py                # 数据结构
```

## 当前完成状态

- 本地历史日线与 Tushare 每日市场快照
- 股票名称、行业、概念板块和多题材归属
- Tushare 真实新闻采集、去重、分类和题材映射
- 题材热度、事件市场验证和情绪周期
- 准确涨跌停价、封板时间、开板次数、封单金额和连板梯队
- 热门涨停反查原因，区分个股直接消息、题材新闻共振、涨停专题共振和低置信度盘面归因
- 指数、换手率、市值和资金流
- 龙虎榜每日明细和机构席位
- 次日观察池、表现追踪和结果分类
- 观察池记录“资讯驱动 / 市场热度 / 热门涨停反查”来源，支持后续分组回测
- 观察池量价二次筛选和多持有期回测
- 原始观察池、量价战法与随机对照组比较
- 逐笔命中依据、买卖日期、收益和最大回撤下钻
- 页面一键更新最新数据、一键生成复盘
- 按交易日保存市场快照，最新复盘约 0.5 秒生成
- 战法库维护模板和流程说明：`docs/strategy_playbook_guide.md`
- DeepSeek V4 Pro AI 分析入口：`策略实验室 -> AI深度分析`

当前产品范围不包含研报和公告正文，AKShare 也不再是必需依赖。

## 后续产品优化

1. 增加人工修正入口：修改事件分类、主炒题材、龙头/中军和观察池。
2. 增加历史统计看板：观察池胜率、平均收益、最大回撤和题材持续性。
3. 优化新闻精选：合并同一事件，降低 ETF 推广和重复行情播报权重。
4. 增加题材和个股详情页，支持历史事件、涨停、龙虎榜和表现追踪。
5. 将本地 CSV 逐步迁移到 SQLite，提高历史查询和批量回放速度。

## Tushare

Tushare 初始化方式已封装在：

```text
src/ashare_review/tushare_client.py
```

调用说明见：

```text
docs/tushare_usage.md
```

测试命令：

```bash
python3 scripts/test_tushare_client.py
```

新闻接口测试：

```bash
python3 scripts/test_tushare_news.py
```

分钟交易提示：

```bash
PYTHONPATH=src python3 scripts/run_minute_signals.py --ts-code 000001.SZ --freq 1min --limit 120
```

说明见：

```text
docs/minute_signals.md
```

SQLite 本地缓存：

```bash
PYTHONPATH=src python3 scripts/sync_sqlite.py --all
PYTHONPATH=src python3 scripts/sync_sqlite.py --local-daily
```

说明见：

```text
docs/sqlite_local_cache.md
```

拉取股票基础信息：

```bash
python3 scripts/fetch_stock_basic.py
```

输出：

```text
data/tushare/stock_basic.csv
```

拉取概念板块和概念成分：

```bash
python3 scripts/fetch_concepts.py
```

输出：

```text
data/tushare/concepts.csv
data/tushare/concept_members.csv
```

拉取新闻事件：

```bash
python3 scripts/fetch_news.py --src cls --start-date "2026-04-01 00:00:00" --end-date "2026-04-01 23:59:59"
```

输出：

```text
data/tushare/news_events.csv
```

拉取龙虎榜：

```bash
python3 scripts/fetch_lhb.py --trade-date 20260401
```

输出：

```text
data/tushare/top_list_20260401.csv
data/tushare/top_inst_20260401.csv
```

批量生成观察池并计算次日表现：

```bash
python3 scripts/backfill_tracking.py --start-date 2026-03-30 --end-date 2026-04-01
```

输出：

```text
data/tracking/watchlist.csv
data/tracking/outcomes.csv
```

追踪指标：

```text
次日开盘涨幅、最高涨幅、最低涨幅、收盘涨幅、开盘后最大回撤、是否涨停、结果分类
```

同一只股票即使属于多个题材，也只计为一个追踪样本，避免胜率重复统计。