Metadata-Version: 2.4
Name: tdx-link-mcp
Version: 0.21.0
Summary: 通达信 AI Agent MCP Server - pip + 国内镜像安装，降低用户门槛
Project-URL: Homepage, https://github.com/JueJuez/tdxLinkMcp
Project-URL: Repository, https://github.com/JueJuez/tdxLinkMcp
Project-URL: Issues, https://github.com/JueJuez/tdxLinkMcp/issues
Author: TdxLink Team
License-Expression: MIT
Keywords: ai-agent,mcp,stock,tdx,trading,uac,权限提权,通达信
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Requires-Dist: akshare>=1.18.0
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# TdxLink — 通达信量化框架 + MCP Server

> 一个项目两种用法:AI Agent 通过 MCP 工具操作通达信,Python 开发者通过 tdx_lib 写量化策略。

## 适合谁看

| 你是 | 用什么 | 看哪段 |
|------|--------|--------|
| AI Agent 用户(用 Cursor/Claude/Trae 等让 AI 操作通达信) | MCP Server | [快速安装](#快速安装) + [MCP 可用工具](#mcp-可用工具) + [AI 调用时机](#ai-调用时机) |
| Python 开发者(自己写选股/交易/回测策略) | tdx_lib 框架 | [框架架构](#框架架构) + [快速上手](#快速上手) |
| 项目维护者(改代码/发版) | 全部 | [目录结构](#目录结构) + `PUBLISH_GUIDE.md` |
| 想了解产品方向与商业模式 | 全部 | `docs/reference/product-strategy.md` |

---

## 快速安装(MCP Server)

### 方式一:通过 AI 平台安装(最简,推荐)

把下面这段复制给你正在用的 AI Agent,**它只需要执行两条命令**:

```
帮我安装 TdxLink MCP Server(通达信 AI Agent)。

请依次执行以下命令:

第一步 - 安装包(使用国内镜像加速):
pip install --upgrade tdx-link-mcp -i https://pypi.tuna.tsinghua.edu.cn/simple

第二步 - 配置 MCP:
python -m tdx_link_mcp.setup_mcp

完成后告诉我结果。
```

> **为什么用 pip 而不是 uvx？**
> - pip 是 Python 标配，AI 编码平台自带，无需额外安装
> - 清华镜像在国内，下载速度快（vs uvx 从国外服务器下载）
> - 安装后直接 `python -m` 运行，简洁稳定
>
> 支持平台: Trae, Cursor, Claude Code, VS Code/Copilot, Gemini CLI,
> OpenCode, OpenClaw, Cline, Kimi CLI, Pi Agent, Codex CLI,
> Antigravity, Windsurf, Mistral Vibe, Qoder（共 16 个）

### 方式二:一键脚本安装

**Windows(PowerShell):**
```powershell
powershell -c "irm https://raw.githubusercontent.com/JueJuez/tdxLinkMcp/main/install.ps1 | iex"
```

**Mac/Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/JueJuez/tdxLinkMcp/main/install.sh | bash
```

脚本会自动:检测 Python → 用国内镜像安装包 → 检测已装的 AI 工具 → 写入 MCP 配置。

### 方式三:手动安装(高级用户)

**1. 安装包**
```bash
# 使用清华镜像(推荐，国内速度快)
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tdx-link-mcp

# 或使用阿里镜像
pip install -i https://mirrors.aliyun.com/pypi/simple tdx-link-mcp
```

**2. 配 MCP**

在 AI 工具的 MCP 配置中添加:
```json
{
  "mcpServers": {
    "tdxLink": {
      "command": "python",
      "args": ["-m", "tdx_link_mcp.server"]
    }
  }
}
```

**配置文件位置**(常用平台):
- Trae:`~/.trae/User/mcp.json`(Windows: `%APPDATA%\Trae CN\User\mcp.json`)
- Cursor:`~/.cursor/mcp.json`
- Claude Code/Desktop:`~/.claude/claude_desktop_config.json`(Windows: `%APPDATA%\Claude\claude_desktop_config.json`)
- VS Code:`~/.vscode/mcp.json`
- OpenCode:`~/.config/opencode/opencode.json`(注意:键名是 `mcp` 不是 `mcpServers`)
- 其他:Cline / Kimi CLI / Pi Agent / Codex CLI / Gemini CLI / Antigravity / Windsurf / Qoder / Mistral Vibe

> 如果配置文件已有其他 MCP,把 `tdxLink` 合并进 `mcpServers` 对象,不要覆盖整个文件。
> 非标准格式(OpenCode/OpenClaw/Mistral Vibe)建议直接用 `python -m tdx_link_mcp.setup_mcp` 自动处理。

**3. 重启 AI 工具**

---

### 备选安装方式(uvx)

如果 pip 安装失败，可以尝试 uvx 方式:

```bash
uvx tdx-link-mcp --upgrade
```

uvx 会自动管理 Python 环境，适合没有 Python 的机器。但需先安装 uv 工具:

```bash
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Mac/Linux  
curl -LsSf https://astral.sh/uv/install.sh | sh
```

---

## MCP 可用工具

装好后,AI 会自动发现 19 个工具:

| 工具 | 功能 | 底层模块 |
|------|------|---------|
| `ensure_tdx_ready` | 通达信启动/检测 | tdx_lib |
| `get_market_info` | 行情/公式/板块/日历/指标计算/列表等 20 种 info_type（快照/K线/基础/搜索/公式/板块/日历/指标序列/股票列表/更多资料/ETF/除权/股本/量价/新股/可转债/交易…） | tdx_lib |
| `screen_stocks` | 涨跌停/公式/自定义选股（formula 走官方公式） | tdx_lib.selector |
| `screen_and_save` | 一步式选股并写入板块（选股 + 落板块） | tdx_lib.selector |
| `screen_combo` | 跨周期组合选股（多段筛选链，每段可指定周期/来源，G6） | tdx_lib.screen_combo |
| `run_backtest` | 筛选/回测统一入口（无 mode 参数；支持 `stock_period` 周期 / `max_klines` / `end_date` as-of 回测截至日 / `codes` 组合回测） | tdx_lib |
| `get_financial_info` | 财务数据查询（EPS/ROE/股东等，含专业财务权限降级） | tdx_lib.financial |
| `manage_portfolio` | 板块管理（增删改查/预警）+ 客户端交互 | tdx_lib.portfolio |
| `manage_realtime` | 实时行情订阅管理（subscribe/unsubscribe/list/clear） | tdx_lib.realtime |
| `execute_trade` | 下单/撤单/持仓查询 | tdx_lib.trade |
| `get_market_stats` | 市场统计（涨跌家数/宽度/多指数对比） | tdx_link_mcp.server |
| `manage_risk` | 风险管理（止损止盈/仓位计算/组合风控） | tdx_lib.risk |
| `setup_grid_trading` | 网格交易配置（等差/等比/买卖信号） | tdx_lib.grid |
| `schedule_strategy` | 定时策略调度（定时执行/CRON表达式） | tdx_lib.scheduler |
| `manage_task` | 定时任务管理（add/list/remove/register，生成 .bat + schtasks/cron 注册，G4） | tdx_lib.task_manager |
| `check_version` | 版本检查（当前版本 vs PyPI 最新版本） | tdx_link_mcp.version_check |
| `run_daily_session` | **专家模式·每日工作流**（早盘/午盘/收盘的投研复盘+选股研判+业绩记录+人读报告） | tdx_lib.review_orchestrator |
| `list_experts` | 列出所有专家角色（预设+自建），含启用态/类型/逻辑/EV样本/最近运行 | tdx_lib.expert_registry |
| `manage_expert` | 专家管理：开关预设 / 创建·删除自定义专家（自建专家=官方公式硬筛+可选人设） | tdx_lib.expert_registry |

> 注：`run_backtest` 是统一筛选/回测入口（旧文档曾称 `run_strategy`，实际注册名为 `run_backtest`，无 mode 参数；选股与回测合并，写板块请用 `manage_portfolio`）。`end_date` 仅做"回测截至日 / as-of"截断（防未来函数），**不做幸存者偏差校正**（TDX 桥 `get_all_a_stocks` 只返今天列表）；分钟线（1m–60m）回测为 roadmap，引擎会返回清晰 error。

### 专家模式（已合并入 `main`，v0.17.0 起）

专家模式（投研决策助手 `analyze_market` / `analyze_signals` / `get_trade_advice` + 业绩闭环 `record_advice` / `review_performance` / `get_expert_stats`）已于 2026-07-29 经 merge commit `dc5fe70` **合并进 `main`**。上述专家能力均为 `tdx_lib` **自用 Python 库函数，未注册为 MCP 工具**；对外仅以 `run_daily_session` 单一 MCP 入口暴露每日工作流闭环（见下方「暴露边界」）。

> ⚠️ **暴露边界**：专家相关代码主体为**自用 Python 库**（`tdx_lib/` 下 market/signals/advisor/expert/strategies_config/universe/financial_source/performance/review_orchestrator），**未逐个注册为 MCP 工具**。但每日工作流已通过 `run_daily_session` **单一 MCP 入口对外暴露**——外部 AI 调用该工具即可触发「早盘选股预选 → 多专家研判 → 自动写入业绩库 → 人读报告」的完整闭环，无需直接操作底层专家库。原始专家子工具（analyze_market 等）待评审后再决定是否逐一注册。

专家库模块（均在 `tdx_lib/`，供本地 Python / 内部调用，非 MCP 入口）：

| 模块 | 职责 |
|------|------|
| `tdx_lib/market.py` | 大盘状态判定（趋势市/震荡市/下跌市） |
| `tdx_lib/signals.py` | 个股信号共振分析（量能/MACD/KDJ/板块/财务 5 信号） |
| `tdx_lib/advisor.py` | 综合决策建议（建仓/止盈/日内方向，多信号共振） |
| `tdx_lib/expert.py` | 专家实例（策略+人设正交）+ 多专家矩阵 `run_all_experts` |
| `tdx_lib/strategies_config.py` | 策略配置表（内核保护 + 按行业放宽规则） |
| `tdx_lib/universe.py` | 专家硬筛股票池解析（all/codes/block/all_except） |
| `tdx_lib/financial_source.py` | 财务数据源（官方接口 + 东财 akshare 兜底） |
| `tdx_lib/performance.py` | 专家业绩记录/复盘/EV 计算/淘汰（数据驱动淘汰劣势策略） |
| `tdx_lib/review_orchestrator.py` | 每日工作流编排（pre_market/midday/after_close/ingest_news），`run_daily_session` 底层驱动 |
| `tdx_lib/external_shock.py` | 外围冲击监测（外资离场/政策/美联储/地缘/商品行业冲击，带 sector 标签路由） |

### 使用示例

```
你: 帮我查今天涨停的股票
AI: [调用 run_backtest(conditions={"limit_up_lookback": 1})] → 返回涨停股列表

你: 查贵州茅台的财务数据
AI: [调用 get_financial_info(codes=["600519.SH"])] → 返回财务信息

你: 买入100股贵州茅台
AI: [调用 execute_trade(buy, code="600519.SH", quantity=100)] → 执行交易

你: 帮我回测一个策略：近8日有涨停，回调不破实体50%，缩量，站上MA5
AI: [调用 run_backtest(conditions={limit_up_lookback:8, pullback_body_ratio:50, ...})] → 回测报告

你: 今天市场整体是涨是跌？哪些板块强？
AI: [调用 get_market_stats()] → 涨跌家数/宽度/多指数对比；[调用 get_market_info(info_type="sector_list")] 看板块强弱
```

## AI 调用时机

> **外部 AI 首次连接时，请先读取 MCP Resource `SKILL_USER.md`**，内有完整的工具使用指南、防呆规则和决策树。

当用户在 AI 会话中询问以下问题时，会优先调用 TdxLink MCP：
- 股票行情查询
- 股票筛选（涨停/跌停）
- 财务数据分析
- 板块管理
- 交易操作
- 市场统计
- 策略回测（口语描述策略→AI 自动转参数执行）
- 风险管理（止损止盈/仓位计算）
- 网格交易配置
- 定时策略调度
- 投研决策（大盘状态 / 个股信号共振 / 建仓止盈日内方向建议）
- 专家业绩跟踪（记录建议→复盘盈亏→EV 评价，数据驱动淘汰劣势策略）

### 调用示例
```python
# 获取茅台实时行情
get_market_info(info_type="snapshot", codes=["600519.SH"])

# 筛选涨停股票
run_backtest(conditions={"limit_up_lookback": 1})

# 获取茅台财务数据
get_financial_info(codes=["600519.SH"], data_type="financial")

# 策略回测 — 口语描述即可，AI 自动转为参数
run_backtest(conditions={
    "limit_up_lookback": 8,
    "pullback_body_ratio": 50,
    "volume_shrink_ratio": 60,
    "require_close_above_ma": [5],
    "ma_trend_up": [20, 60],
})

# 风险管理
manage_risk(action="calculate", capital=100000, price=10.0, stop_loss_pct=5.0)
```

---

## 每日工作流（专家模式）

专家模式把"筛股 → 多专家研判 → 业绩记录 → 收盘复盘 EV → 淘汰回灌"串成每日闭环。三种触发方式:

### 1. 守护进程（自动，推荐上生产）

`scripts/start_review_daemon.py` 按既定时刻自动跑（依赖通达信在线 + akshare，均优雅降级）:

- **前置依赖 · akshare 必装**：新闻/情绪/板块/外围冲击/分红/财报兜底数据源，`pip install tdx-link-mcp` 现已自动安装。缺失时这些节为空但 TDX 路径仍正常，报告顶部 `## 依赖状态` 会提示：
  ```bash
  pip install akshare --upgrade
  # 国内加速
  pip install akshare -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com --upgrade
  ```

- **08:30 `pre_market` 早盘**：全球宏观快讯 + 多专家硬筛预选 + 逐股深入研究 + **自动把研判建议写入业绩库**
- **11:30 `midday` 午盘**：上午盘面快照 + 临时消息 + 预选更新
- **15:30 `after_close` 收盘**：市场情绪 + 流动性 + 强势板块 + 业绩 EV 复盘 + **EV 淘汰回灌策略软弃用标志**
- 盘中 `poll_news` 轮询快讯，命中持仓/预选则打标签并触发自选池调仓

### 2. MCP 工具 `run_daily_session`（外部 AI 按需调用）

```
run_daily_session(session="pre_market" | "midday" | "after_close" | "base_screen", auto_record=true, force=false)
```

- 返回: 人读报告（`report_md` 内联前 4000 字 + `report_md_path` / `report_json_path` 完整文件路径）+ 关键结论 `summary`
- 早盘 `auto_record=true` 会自动把研判建议写入业绩库（供 EV 复盘闭环）；`auto_record=false` 仅研判不记录
- 依赖通达信在线（选股/研判）与 akshare（新闻/情绪/外围冲击/板块/分红，akshare 缺失时这些节为空、顶部 `## 依赖状态` 提示，但 TDX 路径仍正常）
- **akshare 安装**：`pip install akshare --upgrade`（国内源 `pip install akshare -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com --upgrade`）
- **周末/非交易日门控**：默认 `skip_weekend=true`，周末调用四段方法会早退产出 `{"skipped":"non_trading_day"}` 报告，不调 akshare/TDX（根因：休市 TDX 返回 `Now=0` 会污染 EV 闭环样本数）。`force=true` 绕过门控（调试 / 节假日补跑用）

### 3. CLI（本地 / 手动）

```
python scripts/run_daily.py --session all        # pre+mid+close 全跑
python scripts/run_daily.py --session pre --print # 仅早盘并打印 markdown
python scripts/run_daily.py --session close --no-record  # 收盘但不写业绩库
python scripts/run_daily.py --session close --force      # 周末/非交易日也照跑(调试用)
```

依次跑对应时段，打印报告路径与记录条数，可选 `--print` 直接打印 markdown。`--force` 绕过周末门控。

### 4. MCP 原生定时自动化（`manage_task` function=`daily`）

发布后用户最该用的"每日复盘自动化"入口——经 MCP 工具 `manage_task` 注册系统调度器，**注册后即使本 MCP 不在线也会按时跑**（Windows schtasks / Linux crontab）：

```
manage_task(
  action='add', name='每日收盘复盘',
  function='daily',                                  # = run_daily_session(after_close)
  schedule={type:'weekly', time:'15:30', days:['MON','TUE','WED','THU','FRI']},
  auto_register=True                                  # 立即注册生效
)
```

- 报告自动落 `exports/review_<日期>_<HHMM>_after_close.md` + `.json`。
- ⚠️ `schedule_strategy` 只能排选股/回测类策略，**排不了每日复盘**；每日复盘定时化必须用 `manage_task(function='daily')`。
- 也可纯手动/开发态用 `scripts/start_review_daemon.py` 前台守护（见 `docs/REVIEW_DAEMON.md`），但对外发布推荐走 `manage_task`。

### 产出物

| 产物 | 路径 | 说明 |
|------|------|------|
| 人读报告 | `exports/review_YYYYMMDD_HHMM_<session>.md` + `.json` | 候选/研判/情绪/板块/冲击/业绩/EV 淘汰 |
| 业绩库 | `data/expert_records.json` | 早盘 `pre_market` 自动写入研判建议 |
| 专家淘汰 | `data/expert_status.json` | 收盘 `after_close` 按 EV 自动淘汰劣势专家 |
| 策略弃用 | `data/strategy_status.json` | EV 淘汰结论镜像到策略软弃用标志（不碰内核指纹） |
| 专家注册表 | `data/expert_registry.json` | **用户配置**（不入库）：预设专家启用态 + 自定义专家定义 |

### 5. 专家管理（路线1：开关预设 / 自建专家）

`run_daily_session` 跑的是**多专家矩阵**。现在前端模型/用户可经两个 MCP 工具管理这些专家角色：

- **`list_experts()`** — 列出所有专家角色（内置 7 个预设 + 用户自建），含：
  - `type`：`preset`（内置，逻辑冻结不可改） / `custom`（用户自建）
  - `enabled`：是否启用（决定是否参与 `run_daily_session`）
  - `logic`：硬筛公式（预设来自策略配置；自定义来自你给的公式）
  - `ev_sample_size` / `last_run`：EV 已复盘样本数 / 最近运行日
- **`manage_expert(action, ...)`** — 四类操作：
  - `enable` / `disable`：开/关**任意**专家（预设或自建）。关掉的预设不会参与每日复盘。
  - `create`：建自己的专家。收 `name` + `formulas`（TDX 官方公式列表，如 `['C130','B007']` 或 `[{'formula':'GHJ','arg':'0,1'}]`）+ 可选 `persona`/`persona_prompt`/`desc`。返回 `expert_id`，并提示 `invalid_formulas`（不在 107 公式集内的会被静默跳过硬筛）。
  - `delete`：删**自建**专家（仅 `user_` 开头可删；预设冻结不可删）。

**设计边界（路线1）**：内置 7 个专家的策略（公式/内核）是冻结的，**只能开/关，不能改逻辑**；用户想用不同条件（例如用 `GHJ` 替代某预设的默认公式），应走 `manage_expert(action='create')` 建一个自定义专家。自定义专家 = 你给的官方公式硬筛 + 可选人设研判，**无 FN 内核计算**，启用后即自动加入 `run_daily_session` 矩阵。

```
# 先看所有专家 + 谁开着 + 各跑什么逻辑
list_experts()
# 关掉不想要的预设
manage_expert(action='disable', expert_id='expert_0_default')
# 建一个自己的专家（用 C130 经常涨停 + B007 触及涨停）
manage_expert(action='create', name='涨停共振', formulas=['C130','B007'], persona='打板客')
# 之后再跑每日复盘，启用的专家（含你新建的）都会参与
run_daily_session(session='pre_market')
```

### 测试建议(从无副作用到有副作用)

1. `ensure_tdx_ready` — 确认客户端就绪
2. `get_market_stats`(stat_type=`limit_count`)— 秒查涨跌停家数
3. `get_market_info`(info_type=`snapshot`, codes=`["600519.SH"]`)— 单只快照
4. `get_market_info`(info_type=`kline`, kline_count=`10`)— K线
5. `get_market_info`(info_type=`search`, key_word=`"茅台"`)— 搜索
6. `run_backtest(conditions={...})`— 条件筛选(全市场约 2s)
7. `get_financial_info`(data_type=`financial`, codes=`["600519.SH"]`)— 财务
8. `manage_portfolio`(action=`query`)— 查所有自定义板块(只读)
9. `execute_trade`(action=`query_asset`)— 查资产(只读,要交易端登录)
10. `run_backtest(conditions={...})`— 策略回测（口语描述→参数，无副作用）
11. `manage_risk`(action=`calculate`)— 仓位/止损计算（只读）
12. `setup_grid_trading`(action=`status`)— 网格状态查询（只读）
13. 最后才碰有写副作用的:`manage_portfolio` 的 create/send/clear、`execute_trade` 的 buy/sell。**交易务必小额先试**。

---

## 框架架构

> 下面是给 Python 开发者看的。如果你只用 MCP,跳过即可。

```
┌──────────────────────────────────────────────────────────┐
│                    strategies/  策略层                      │
│        用户只写这里: 继承 StrategyBase, 实现 analyze()       │
├──────────────────────────────────────────────────────────┤
│           strategy.py        backtest.py    scheduler.py  │
│           策略生命周期        回测引擎       定时调度        │
├──────────────────────────────────────────────────────────┤
│  data.py      trade.py     portfolio.py   risk.py  grid.py│
│  行情数据     交易下单      板块管理      风控止损  网格交易  │
├──────────────────────────────────────────────────────────┤
│              client.py              utils.py              │
│              HTTP通信               计算工具               │
└──────────────────────────────────────────────────────────┘
```

**设计原则**:策略层只依赖框架层,框架层只依赖服务层,服务层只依赖基础层。换策略不用改基础设施,加功能不用动底层通信。

## 功能清单

| 模块 | 功能 | 状态 |
|------|------|------|
| **client.py** | HTTP JSON-RPC 通信、批量并发调用、连通性检测 | ✅ |
| **launcher.py** | 通达信进程检测/自动拉起/HTTP就绪轮询(一行调用) | ✅ |
| **data.py** | 股票列表、K线、快照、more_info 批量查询、预筛框架 | ✅ |
| **financial.py** | 官方财务/交易数据9接口(FN/GP/BK/SC/GO系列),透传官方 | ✅ |
| **selector.py** | 官方公式选股(B007),与客户端"条件选股"一致 | ✅ |
| **guard.py** | 官方优先守卫,运行时强制官方入参 | ✅ |
| **trade.py** | 买入/卖出/市价/限价/涨跌停价/隔夜挂单/批量撤单/账户查询 | ✅ |
| **portfolio.py** | 板块创建/删除/清空/重写、预警信号、客户端跳转 | ✅ |
| **strategy.py** | 策略基类,串联完整生命周期(选股→预筛→分析→输出→写板块) | ✅ |
| **custom_strategy.py** | 全参数化自定义策略，50+ 条件参数，AI 无需写策略类 | ✅ |
| **risk.py** | 止损(固定/移动/ATR)、止盈(固定/移动)、仓位管理(固定/比例/凯利) | ✅ |
| **grid.py** | 网格交易(等差/等比),自动低买高卖 | ✅ |
| **backtest.py** | 历史回测(全参数化),绩效统计(胜率/回撤/夏普/盈亏比),支持周期/as-of 截至日/组合回测 | ✅ |
| **scheduler.py** | 定时执行策略,支持 HH:MM 和 cron 表达式 | ✅ |
| **realtime.py** | 实时行情订阅管理（`subscribe_hq` 封装,本地缓存兜底 list/clear） | ✅ (v0.14.0) |
| **periods.py** | 周期校验/归一化/内存防御（G5，新增） | ✅ (v0.18.0) |
| **screen_combo.py** | 跨周期组合选股（多段筛选链，G6，新增） | ✅ (v0.18.0) |
| **task_manager.py** | 定时任务管理（schtasks/cron 注册，G4，新增） | ✅ (v0.18.0) |
| **replay.py** | 真实抓取+离线回放客户端（G1，新增） | ✅ (v0.18.0) |

> 注：上述模块为 `main` 分支实际包含的通用能力。专家模式相关模块（`market.py` / `signals.py` / `advisor.py` / `expert.py` / `strategies_config.py` / `universe.py` / `financial_source.py` / `performance.py` / `review_orchestrator.py` / `external_shock.py`）及对应投研决策助手 / 业绩闭环工具**已于 v0.17.0 合并进 `main`**（merge commit `dc5fe70`）；其中 `review_orchestrator.py` 为 `run_daily_session` 的底层驱动，`external_shock.py` 负责外围冲击监测。

> MCP Server 暴露 **19 个工具**（通用 13 个 + `run_daily_session` 每日工作流 + `screen_and_save` + `screen_combo` + `manage_task` + `list_experts` 专家总览 + `manage_expert` 专家管理），覆盖行情/筛选/财务/板块/实时订阅/交易/统计/启动/回测/风控/网格/调度/任务/版本检查/专家每日复盘/专家开关与自建。专家相关子工具保持 `tdx_lib` 自用库，未注册为 MCP 工具。

---

## 快速上手

### 1. 选股策略 — 只写 analyze()

```python
# strategies/my_strategy.py
from tdx_lib import StrategyBase, calc_ma, parse_kline_float

class MyStrategy(StrategyBase):
    name = "我的策略"
    block_code = "MINE"
    min_cap = 50
    max_cap = 500

    def analyze(self, code, kline_data):
        parsed = parse_kline_float(kline_data)
        closes = parsed["Close"]
        if len(closes) < 20:
            return None
        ma5 = calc_ma(closes, 5)
        ma20 = calc_ma(closes, 20)
        if ma5 > ma20 and closes[-1] > ma5:
            return {"code": code, "close": round(closes[-1], 2)}
        return None
```

运行: 自定义策略类现已通过 `run_backtest` 的 conditions 参数化入口执行，不再需要 CLI 类文件（详见下文「2. 回测」），也可经 `schedule_strategy` 注册为定时任务。

### 2. 回测 — 全参数化，无需写策略类

```python
from tdx_lib.backtest import BacktestEngine
from tdx_lib.custom_strategy import CustomStrategy

# AI 将策略条件转为参数即可回测，无需写 Python 类
conditions = {
    "limit_up_lookback": 8,             # 近8日有涨停
    "pullback_body_ratio": 50,          # 回调不破实体50%
    "volume_shrink_ratio": 60,          # 缩量至60%
    "require_close_above_ma": [5],      # 站上MA5
    "ma_trend_up": [20, 60],            # MA20/MA60向上
    "require_yang_line": True,          # 今日收阳
    "min_market_cap": 30,               # 市值≥30亿
    "max_market_cap": 300,              # 市值≤300亿
}

# 模式① 快照池（默认，都不指定）：今天行情跑策略筛出的池
engine = BacktestEngine(
    CustomStrategy,
    initial_capital=1_000_000,
    conditions=conditions,
    stock_period="1d",                  # 周期：1d/1w/1mon/1M（日/周/月线）
)
engine.stop_loss_pct = -5.0
engine.take_profit_pct = 10.0
engine.trailing_stop = True
report = engine.run(start_offset=60, stock_limit=200)
engine.print_report()

# 模式② as-of 回测截至日（仅 end_date）：K线截断到该日防未来函数，宇宙仍为今天全量
#   engine = BacktestEngine(CustomStrategy, conditions=conditions, end_date="20240102")
# 模式③ 组合回测（仅 codes）：池子=指定持仓/标的，测这些标的上的历史回报
#   engine = BacktestEngine(CustomStrategy, conditions=conditions, codes=["600519.SH","000001.SZ"])
```

> ⚠️ **回测周期边界**：`stock_period` 支持 `1d`/`1w`/`1mon`/`1M`（日/周/月线）。**分钟线 1m–60m 为 roadmap**——回测引擎是"逐日回放"模型（1 根 K 线 = 1 交易日），对分钟线语义不匹配；`run_backtest` 传日内周期会返回清晰 error，不会给误导性「0 信号」。选股层（`screen_stocks`/`screen_combo`）可用任意周期（含分钟线）做筛选，不受影响。
> ⚠️ **`end_date` 非真 point-in-time**：它把 K 线截断到指定日（防未来函数），**但股票清单仍是今天全量**（TDX 桥 `get_all_a_stocks` 只返当前列表，无法提供"某历史日有哪些股票在交易/已退市"）。故 `end_date` 模式**含幸存者偏差**，文档/打印均明确标注，勿当"当时宇宙"解读。真 PIT 宇宙需 Wind/Choice/RQData 等历史成份库，超出 TDX 桥能力。

### 3. 交易 + 止损止盈

```python
from tdx_lib import TdxClient, TdxTrader, RiskManager, StopLoss

client = TdxClient()
trader = TdxTrader(client)
rm = RiskManager(stop_loss_type=StopLoss.Type.TRAILING, sl_pct=5.0,
                 capital=trader.get_total_asset())

# 买入
volume = rm.calc_volume(price=10.0)
trader.limit_buy("600000", volume, 10.0)
rm.on_buy("600000", 10.0)

# 检查止损
should_exit, exit_price, reason = rm.check_exit("600000", high=10.5, low=9.6)
```

### 4. 网格交易

```python
from tdx_lib import GridTrader

grid = GridTrader("600000", lower_bound=8, upper_bound=12,
                  grid_count=20, volume_per_grid=200)
grid.setup(current_price=10.0)

actions = grid.on_price_update(current_price=10.5)
# → [{"action": "sell", "price": 10.5, "volume": 200, ...}]
```

### 5. 定时自动运行

```python
from tdx_lib import StrategyScheduler

sched = StrategyScheduler()
sched.add_strategy("my_strategy", time_str="15:30")  # 每天15:30选股
sched.add_task(overnight_orders, time_str="14:50", name="隔夜挂单")
sched.run()
```

### 6. 条件筛选 — 涨跌停/涨幅/市值(两层过滤,秒级)

```python
from tdx_lib import TdxClient, TdxSelector, get_market_limit_count

client = TdxClient()

# 秒查涨跌停家数 (1次请求, ~0.005s)
r = get_market_limit_count(client)
print(f"涨停 {r['limit_up']} 家, 跌停 {r['limit_down']} 家")

# 涨停筛选 (官方公式 B007, 推荐用 MCP run_backtest)
# 详见 MCP run_backtest(conditions={"limit_up_lookback": 1})
```

### 运行策略

自定义策略无需再写成独立 CLI 类文件。将选股/回测逻辑表达为 `conditions`（参数化条件），通过 MCP 工具 `run_backtest`（统一筛选/回测入口）统一执行；需定时跑则经 `schedule_strategy` 注册。原 `run_strategy.py` CLI 入口已于 v0.15.0 清理删除（死代码，`strategies/` 已清空且全仓无引用）。

---

## 目录结构

```
tdxLinkMcp/
├── tdx_lib/                        # 核心框架(本地脚本直接 import)
│   ├── __init__.py                 # 统一导出
│   ├── client.py                   # HTTP 客户端
│   ├── utils.py                    # 工具函数
│   ├── launcher.py                 # 客户端启动器
│   ├── data.py                     # 行情数据
│   ├── financial.py                # 官方财务/交易数据
│   ├── selector.py                 # 官方公式选股 (B007)
│   ├── guard.py                    # 官方优先守卫
│   ├── trade.py                    # 交易接口
│   ├── portfolio.py                # 板块管理
│   ├── risk.py                     # 风险管理
│   ├── grid.py                     # 网格交易
│   ├── strategy.py                 # 策略基类
│   ├── custom_strategy.py          # 全参数化自定义策略
│   ├── backtest.py                 # 回测引擎 (周期/as-of 截至日/组合回测)
│   ├── scheduler.py                # 定时调度
│   ├── realtime.py                 # 实时行情订阅管理 (v0.14.0)
│   ├── periods.py                  # 周期校验/归一化/内存防御 (G5, v0.18.0)
│   ├── screen_combo.py             # 跨周期组合选股 (G6, v0.18.0)
│   ├── task_manager.py             # 定时任务管理 schtasks/cron (G4, v0.18.0)
│   ├── replay.py                   # 真实抓取+离线回放客户端 (G1, v0.18.0)
│   ├── cli.py                      # 统一 CLI 入口 (capture/screen/screen-save/backtest/combo/daily)
│   ├── market.py                    # [专家库] 大盘状态判定 (未暴露 MCP)
│   ├── signals.py                   # [专家库] 个股信号共振 (未暴露 MCP)
│   ├── advisor.py                   # [专家库] 综合决策建议 (未暴露 MCP)
│   ├── expert.py                    # [专家库] 专家实例+多专家矩阵 (未暴露 MCP)
│   ├── strategies_config.py         # [专家库] 策略配置表 (未暴露 MCP)
│   ├── universe.py                  # [专家库] 专家股票池解析 (未暴露 MCP)
│   ├── financial_source.py          # [专家库] 财务数据源(东财兜底) (未暴露 MCP)
│   └── performance.py               # [专家库] 专家业绩/EV/淘汰 (未暴露 MCP)
├── strategies/                     # 策略目录（已清空，无 CLI 入口）
├── src/tdx_link_mcp/               # MCP Server (PyPI 包)
│   └── server.py                   # 17 个 MCP 工具注册 (含 run_daily_session 每日工作流)
├── tests/                          # 测试: 单元测试(test_*.py) + 现场真机测试(live_*/e2e_*.py, 详见 tests/README.md)
├── SKILL_USER.md                   # AI 使用指南（外部 AI：MCP 工具 + 防呆规则）
├── SKILL_DEV.md                    # AI 开发文档（内部维护：API 签名 + 策略指南）
├── PUBLISH_GUIDE.md                # 发版维护指南
├── install.ps1 / install.sh        # 一键安装脚本(Shell)
├── setup_mcp.py                    # 一键安装工具(Python, AI 调用入口)
└── README.md                       # 本文件
```

---

## 前置条件 & 依赖

- **Python 3.10+**(MCP 通过 uv 自动管理,无需手动装)
- **通达信客户端**:必须在本地运行(Windows),并开启 HTTP 服务(默认端口 17709)
- **交易接口**:需通达信已登录交易终端
- 框架本身**无第三方依赖**(纯标准库),MCP Server 依赖 `httpx` + `mcp`(uv 自动装)

---

## 常见问题

**Q: 提示"无法连接通达信"?**
A: 确保通达信客户端已启动且 HTTP 服务已开启(默认端口 17709)。

**Q: 可以远程使用吗?**
A: 当前仅支持本地使用(通达信客户端必须在本地运行)。

**Q: 支持哪些 AI 工具?**
A: 所有支持 MCP 协议的工具。`setup_mcp.py` 已内置 16 个平台自动配置:
Trae、Cursor、Claude Code、VS Code+Copilot、OpenCode、OpenClaw、Cline、
Kimi CLI、Pi Agent、Codex CLI、Gemini CLI、Antigravity、Windsurf、Qoder、Mistral Vibe、CommandCode。

**Q: 如何更新到最新版本?**
A: 配置中已启用 `--upgrade`,每次启动 AI 工具会自动检查。手动更新:`uv cache clean tdx-link-mcp`。

**Q: 安装后没有生效?**
A: 重启 AI 工具,确保配置文件已正确写入。

**Q: MCP 工具和 tdx_lib 框架是什么关系?**
A: MCP 是 tdx_lib 的子集封装。框架 20+ 个模块里 18 个被封装成 MCP 工具(给 AI 用);专家模式模块(`expert`/`strategies_config`/`universe`/`financial_source`)当前为自用 Python 库,未暴露 MCP;策略框架 `StrategyBase` 只给本地 Python 用(写自定义策略类)。

---

## 开发者说明

### 本地开发测试

```bash
# 克隆项目
git clone https://github.com/JueJuez/tdxLinkMcp.git
cd tdxLinkMcp

# 安装依赖
pip install -e .

# 运行测试
python -m pytest tests/

# 本地启动 MCP Server(用于调试)
python -m tdx_link_mcp.server
```

### 相关文档

| 文档 | 给谁看 | 内容 |
|------|--------|------|
| `README.md`(本文件) | 所有人 | 安装 + 框架介绍 |
| `SKILL_USER.md` | 外部 AI 模型 | MCP 工具使用指南 + 防呆规则 + 决策树（严禁读源码） |
| `SKILL_DEV.md` | 项目维护者 AI | 框架 API 签名、策略编写指南、回测与风控说明 |
| `PUBLISH_GUIDE.md` | 维护者 | 发版到 PyPI 的步骤 |

### 项目铁律(给 AI 的话)

**首要原则: 官方入参优先。** 用户与 AI 沟通形成的策略/条件,最终必须是通达信官方接口的入参,本框架只取数与呈现。详见 `.trae/rules/official-first.md`(项目铁律,由 `tdx_lib/guard.py` 运行时强制)。

涨跌停判定必须走 `TdxSelector`(官方公式 B007),禁止本地 ZAF 阈值。

如果需要修改、扩展、或添加新功能,请**先读 `SKILL_DEV.md`** — 它是 API 速查与操作指南。

### 发布到 PyPI

见 `PUBLISH_GUIDE.md`。

---

## 版本历史

> **分支说明**：自 2026-07-16 起，专家模式（投研决策助手 + 业绩闭环，v0.13.0/v0.14.0）在独立分支 `expert-mode` 开发；2026-07-29 经 merge commit `dc5fe70` **已合并进 `main`**，`main` 现为统一分支（17 个 MCP 工具）。下列 v0.13.0 / v0.14.0 条目原描述 `expert-mode` 分支内容，现已随合并进入 `main`。当前 `main` 同时包含通用工具集 + `run_daily_session` 每日工作流 + `screen_and_save` / `screen_combo` / `manage_task`（v0.18.0 缺口交付）。

- **v0.18.0** (2026-07-30):缺口 G1/G4/G5/G6 交付 + 回测宇宙三模式。`main` 现统一分支（17 个 MCP 工具）。
  - **G1 真实抓取+离线回放**：新增 `tdx_lib/replay.py`（`capture_samples` 落真实 K 线/快照到 `data/samples/` + `ReplayTdxClient` 离线客户端）；统一 CLI 新增 `capture` 子命令。永不合成假数据。
  - **G4 定时调度**：新增 `tdx_lib/task_manager.py`，MCP 新增 `manage_task`（add/list/remove/register，生成 `.bat` + schtasks/cron 注册）。
  - **G5 回测多周期 + 宇宙三模式**：`tdx_lib/periods.py`（周期校验/归一化/内存防御）；`run_backtest` 新增 `stock_period`（`1d`/`1w`/`1mon`/`1M`）+ `max_klines` + `end_date`（as-of 回测截至日，截断 K 线防未来函数，宇宙仍为今天全量含幸存者偏差，非真 PIT）+ `codes`（组合回测）；**日内周期 1m–60m 守卫**返回清晰 error（roadmap）。
  - **G6 跨周期组合选股**：新增 `tdx_lib/screen_combo.py`（`combo_screen`），MCP 新增 `screen_combo`（多段筛选链，首段无 `from_codes` 懒加载全市场池）。修复首段空输入池导致整组合恒为 0 的严重 bug。
  - **统一 CLI**（`tdx_lib/cli.py`）：`capture`/`screen`/`screen-save`/`backtest`/`combo`/`daily` 六子命令，支持 `--json`/`--json-file`。
  - MCP 工具 14 → 17（新增 `screen_and_save`/`screen_combo`/`manage_task`）；版本 0.17.0→0.18.0。
  - 详见 `CHANGELOG.md` 与 `docs/gaps_test_report.md`（TDX 在线实测验证）。
- **v0.20.0** (2026-07-31 ~ 08-01):复盘硬化 (P0) + 策略能力扩展 + 资金面补强 (P1) + 3 新专家落地 (信号覆盖)。详见 `CHANGELOG.md` 顶部 v0.20.0 条目。
  - **资金面补强（P1）**：北向资金 2024-08 起停止披露（东财恒 0）已移除出资金面；南向降为独立信息（内资出海情绪，非外资 proxy）。资金面改走三真实信号：板块主力净流入（行业/概念 Top8，`stock_fund_flow_industry`/`stock_fund_flow_concept`）+ ETF 宽基净申购额（跨日 Δ 份额，落盘 `data/fund_flow/etf_broad_<date>.json`）+ 融资余额变化（`stock_margin_account_info`，亿元 T+0）。三信号独立取数、独立降级 error。
  - **3 新专家（信号覆盖）落地**：`STRATEGY_CONFIGS` 新增 `trend_momentum` / `sentiment_hot` / `short_term`（技术/题材驱动，shell_conditions 用 DTPL+C117 / C130+C124 / B007+UPN）；`expert.py screen()` 公式门槛放开为 `formula in FORMULAS`（旧 `startswith("A")` 废弃），B/C/D/形态/涨停系列技术公式全部触发硬筛。
  - **现共 7 个专家**：价投 4（default / cig Butt / cig Butt_simple / dividend）+ 信号覆盖 3。复盘 EV 节新增「待复盘 N 条」标识（样本=已复盘，待复盘=候选未到观察日，避免新专家样本=0 被误读为死专家）。
  - MCP 工具仍为 17 个；版本 0.18.0→0.20.0。
- **v0.19.0** (2026-07-30):B1 误判修复 + F1/F2/F3 缺口交付 + 财务兜底实盘校验 + 测试套件全量修复。详见 `CHANGELOG.md`。
- **v0.17.0** (2026-07-29):每日报告硬化（已合并 expert-mode 入 `main`，merge `dc5fe70`）。见 `CHANGELOG.md` 顶部。
- **v0.15.0** (2026-07-16 ~ 07-17):`main` 半接口解写死（batch_indicator/batch_expression/formula_calc 暴露 return_count/return_date/formula_dividend + 去魔法数）+ 新增 info_type=stock_list/more_info + **口语/自然语言→参数集中到 `SKILL_NL_MAP.md` 单一权威源**（SKILL_USER/SKILL_DEV/trae 索引改指针，server.py 内嵌「107 公式表」+「自然语言→参数表」裁剪 ~227 行）+ 版本 0.14.0→0.15.0（未发布，未合并 expert-mode）
  - `get_market_info` 半接口去写死：`batch_indicator` / `batch_expression` / `formula_calc` 暴露 `return_count`（最近 N 个值序列）/ `return_date`（带日期）/ `formula_dividend`（0 不复权/1 前/2 后），去掉魔法数
  - 新增 info_type：`stock_list`（list_market 实测映射 5=全部A股/6=深圳/7=上海/8=创业板类/9=北交所类/0=指数）、`more_info`（单只更多资料）
  - 文档同步：README / SKILL_USER / SKILL_DEV 工具清单与 info_type 速查表对齐真实 20 种 info_type、13 个工具
  - ⚠️ `formula_format_data`（单股自定义K线公式管线）**暂不暴露**，留待专家模式后续使用（见 `docs/OPEN_ISSUES.md`）
- **v0.14.0** (2026-07-16):专家模式（**仅 `expert-mode` 分支**，未合并 main）— 多专家矩阵 + 业绩闭环 + EV 淘汰
  - 新增 `strategies_config.py`：策略配置表（内核+外壳+放宽规则 + 内核保护指纹校验）
  - 新增 `expert.py`：专家实例（策略+人设正交）+ 多专家矩阵 `run_all_experts`（自用库，未暴露 MCP）
  - 新增 `universe.py`：专家硬筛股票池解析（all/codes/block/all_except 四种来源，默认全市场）
  - 新增 `financial_source.py`：财务兜底源抽象（通达信权限墙→东方财富 akshare 自动回退）
  - `performance.py` 扩展：EV 淘汰模块（样本<30 不评价，EV≤0 且样本足→淘汰）
  - 调度器接线 `register_expert_scheduler`（盘后 15:30 跑全市场）
  - 4 个专家（v0.14.0 时）：0号基线 / 烟蒂简化 / 烟蒂完整(内核待实盘) / 红利(B型人设)。（**现共 7 个**，v0.20.0 已新增趋势/情绪/短线 3 个信号覆盖专家，见上文 v0.20.0 条目）
  - ⚠️ Phase 3 部分完成，财务内核受通达信权限墙影响靠东财兜底（见 `docs/OPEN_ISSUES.md`）
- **v0.13.0** (2026-07-16):投研决策助手（**仅 `expert-mode` 分支**，未合并 main）— 从"选股工具"升级为"投研决策助手"
  - 新增 `market.py`：大盘状态判断（趋势市/震荡市/下跌市，沪深300日K+布林带+均线）
  - 新增 `signals.py`：个股信号共振（量能/MACD/KDJ/板块/财务 5 信号，3 个技术信号走官方公式）
  - 新增 `advisor.py`：综合决策建议（建仓/止盈/日内方向，多信号共振规则硬编码）
  - 新增 3 个 `tdx_lib` 内部库函数（**非 MCP 工具**，仅 expert-mode）：`analyze_market` / `analyze_signals` / `get_trade_advice`；最终对外仅以 `run_daily_session` 单一 MCP 入口暴露每日工作流闭环（底层专家子工具未逐一注册）
  - 决策方法：多信号共振（≥3 信号才出手），高胜率低频次
- **v0.12.0** (2026-07-15):业绩闭环基础（专家模式前置）
  - 原 PRD 计划 `expert-mode` 暴露 15 个 MCP 工具（含 `analyze_*` / `record_*` / `review_*` / `get_expert_stats`）；**实际落地收敛为：通用 13 个 + `run_daily_session` 单一工作流入口 = 共 14 个 MCP 工具**，专家子工具保持 `tdx_lib` 自用库，未注册为 MCP 工具
  - 详见 `docs/active/PRD/`
- **v0.11.1** (2026-07-08):修复导入断裂 + mode 分发 + 文档同步
  - 修复 `get_market_limit_count` 导入链断裂 (P0)
  - 实现 `run_backtest` 的 mode 参数分发逻辑 (P1)
  - 同步 README.md / SKILL_DEV.md / pyproject.toml
- **v0.11.0** (2026-07-07):筛选统一 + 模块清理
  - `run_backtest` 新增 mode 参数 (list/analyze/full/backtest)，统一筛选/分析/回测入口（v0.11.0 PRD 曾计划将 `screen_stocks` 合并进 `run_backtest` 并改名 `run_strategy`，实际未落地：`screen_stocks` 与 `run_backtest` 至今并存、均注册为 MCP 工具；`run_strategy` 曾仅作为 CLI 文件名 `run_strategy.py` 存在，从未成为 MCP 工具名；该 CLI 已于 v0.15.0 作为死代码清理删除）
  - 删除 StockScreener，筛选逻辑下沉到 TdxSelector.select_chain()
  - `get_market_limit_count` 从 screener.py 搬到 data.py
  - 删除 refresh_kline 调用，策略执行提速 3x
  - 去掉默认过滤（ST/市值/MA5），策略没说就不过滤
- **v0.8.0** (2026-07-04):接口核查修复 + 文档管理规范化
  - `screen_stocks` 工具 description 补全 107 个官方选股公式（按 16 类分组，形态类 24 个全列）
  - 新增口语同义名标注（如 `YYD 鸳鸯底（口语: 双底/W底）`），消除 AI 因"官方名≠口语名"自写代码
  - `screen_stocks` 新增 `stock_period`/`count`/`dividend_type` 参数（支持周线/月线/复权选股）
  - `manage_portfolio` 修复 `down_type` 文档值错误（1=十大股东，非龙虎榜）+ 新增 `stock_code` 参数
  - `execute_trade` 新增 `account_type`（STOCK/CREDIT 信用账户）
  - `setup_grid_trading` 新增 `total_capital`/`base_position_ratio`/`reset` action
  - `schedule_strategy` 新增 `trading_days_only` + 7 个预设时间点（PRE_OPEN/MARKET_OPEN/PRE_CLOSE/POST_CLOSE 等）
  - `run_backtest` 新增形态条件命名对照（double_bottom = YYD 鸳鸯底）
  - 文档管理规范化：`docs/README.md` 规则 + active/archive/reference 三级目录 + 失实文档标记 obsolete
- **v0.5.1** (2026-07-02):文档拆分 + 防呆加固
  - SKILL.md 拆分为 SKILL_USER.md（外部 AI 用户指南，含防呆规则 + 决策树）+ SKILL_DEV.md（内部开发者文档）
  - MCP Resource 改为暴露 SKILL_USER.md，防止外部 AI 读取源码文档后绕过 MCP 自写脚本
  - 增强 MCP 工具描述：manage_portfolio/execute_trade/run_backtest/screen_stocks 加入防呆提示
  - 新增 6 条防呆规则：意图不明反问、条件矛盾纠错、前置步骤检查、危险操作确认、类型检查、禁止行为清单
- **v0.5.0** (2026-07-02):回测全面重构 + 策略条件扩展 + 自然语言速查表
  - `run_backtest` 全面重构: 移除固定策略，改为全参数化自定义模式，新增 `CustomStrategy` 类
  - 策略条件从 18 个扩展到 50+ 个，覆盖 MACD/KDJ/RSI/布林带/形态/箱体/均线/换手率等 12 组
  - `utils.py` 新增 8 个技术指标计算函数（EMA/MACD/KDJ/RSI/布林带/均线方向）
  - MCP 工具描述新增 60+ 条自然语言→参数速查表，AI 直接映射用户口语到策略参数
  - `get_market_info`/`get_financial_info` 新增字段编码速查表，AI 可将中文需求转为字段编码
  - 新增 `docs/category.txt`，22 个标准策略场景全部可映射到 MCP 参数
  - MCP 工具从 7 个扩展到 11 个（`run_backtest`/`manage_risk`/`setup_grid_trading`/`schedule_strategy`）
- **v0.3.1** (2026-07-01):优化发布流程 + 清理旧包缓存
  - 优化 PyPI 发布流程，支持持久化验证 venv
  - 清理本地 pip 缓存，移除旧版本残留
  - 修复安装后 import 验证问题
- **v0.3.0** (2026-06-30):官方优先强制机制 + 财务数据接口完善
  - `tdx_lib/guard.py` 官方优先守卫上线，运行时强制官方入参
  - 完善财务数据 9 接口（FN/GP/BK/SC/GO系列），透传官方数据
  - `TdxSelector` 涨跌停判定走官方公式 B007，禁止本地 ZAF 阈值
- **v0.2.0** (2026-06-29):功能完善 + 策略框架
  - 新增策略框架、回测引擎、风险管理、网格交易、定时调度
  - MCP 工具扩展到 7 个
- **v0.1.5** (2026-06-29):权限自动提权 + 智能缓存目录
  - **UAC 提权机制**：MCP Server 启动时自动检测权限，权限不足时请求 UAC 提权
  - **智能缓存目录检测**：自动检测可写的缓存目录，避免权限拦截
  - 优先使用用户主目录（`%USERPROFILE%\.uv-cache`），降级到临时目录
  - 完全自动化安装流程，用户无需手动配置
- **v0.1.2** (2026-06-28):一键安装工具 + 多平台支持
  - 新增 `setup_mcp.py`:Python 一键安装工具,AI 只需执行一条命令即可完成全部安装
  - 支持 15 个 AI 编码平台自动配置:Trae/Cursor/Claude/VS Code/OpenCode/OpenClaw/
    Cline/Kimi/Pi/Codex/Gemini/Antigravity/Windsurf/Qoder/Mistral Vibe
  - 智能合并不覆盖已有 MCP 配置(解决旧脚本覆盖用户配置的问题)
  - 支持 3 种配置格式:标准 JSON `mcpServers` / OpenCode `mcp` 键 / Mistral Vibe TOML
  - 修复 `install.ps1` 中 Trae 配置路径错误 + 改为合并写入
  - 解决 AI 逐步安装需 5-10 分钟的问题(脚本 30-60 秒完成)
- **v0.1.1** (2026-06-27):修复打包 bug
  - 修复:打包后 `from tdx_lib import` 找不到模块(v0.1.0 用户安装后无法启动)
  - 改为单一真源:tdx_lib 作为独立顶级包打包,删除 src 下拷贝
  - 文档重组:README 合并 MCP_README,删除 3 个冗余文档
- **v0.1.0** (2026-06-27):首次发布
  - 7 个场景化 MCP 工具
  - 14 个 tdx_lib 框架模块
  - 支持 Trae/Qoder/Cursor/Claude Desktop
  - 全自动安装脚本

---

## 许可证

MIT License
