dsh-quant-factor-pipeline

Readme

# dsh-quant-factor-pipeline

> Quant Factor Research Pipeline — a companion **user-layer MCP server** for [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness).
>
> 把「探针驱动 → 面板 → IC/5 门 → 回测 → Regime」的量化研究流水线封装成模型可逐步调用的 MCP 工具。
> 作者：**helibeiqi**（本仓库为本地源码，配套装于 dsh web profile）。

---

## 核心定位

把一套**工程纪律严格**的因子研究流程变成 dsh 里模型能直接编排的工具：

```
panel_probe  ──►  ic_gate  ──►  regime_check  ──►  factor_backtest
   (拉面板)        (IC/5门)       (regime切换)        (多空近似回测)
        │                                              │
        └──────────── project_save / project_load ─────┘
                  (持久化研究项目 manifest YAML)
```

设计原则（与本地量化工程纪律一致）：
- **探针驱动**：任何数据源先 `panel_probe` 核验覆盖度与完整性，再下游使用。
- **防前视**：前瞻收益用「调后收盘→收盘」，信号取 `T-1` 收盘，杜绝 look-ahead。
- **稳健统计**：IC 显著性用 **Newey-West** t 统计，而非朴素 t。
- **单一真理源 / 可归因**：每个工具输出机读、可溯源的结果，便于审计。

---

## 工具清单（模型命名空间 `mcp__quant_factor__*`）

| 工具 | 作用 | 阶段 |
|---|---|---|
| `panel_probe` | 拉取 A 股日频面板，汇报换手率覆盖率，产出完整性 `panel_hash`（F4） | 探针 / 面板 |
| `ic_gate` | 构建 CGO 处置效应因子，计算 RankIC vs 前瞻收益、Newey-West t 统计、R² 机械健康度（F5） | IC / 5 门 |
| `regime_check` | 对信号/收益序列做粗粒度 regime 状态 + 相关性断裂 / 正交性检测（F5 / P1-F9） | Regime |
| `factor_backtest` | 纯 Node 多空十分位回测近似（RankIC / ICIR / Sharpe / 换手 / 净值曲线）（P1-F7）。**注：P1 近似，非 engine_max** | 回测 |
| `project_save` | 将研究项目 manifest 写入 `quant-workspace/.quant-pipeline/projects/<id>.yaml`（F1） | 持久化 |
| `project_load` | 读回上述 manifest（F1） | 持久化 |

---

## 协议与运行

- **协议**：NDJSON（JSON-RPC 2.0，每行一个 JSON 对象，以 `\n` 结束，容忍末尾 `\r`）。这与 dsh-mcp-client / MCP SDK 的帧格式一致。**不要**用 Content-Length 帧（会被误判，导致 server 挂不上）。
- **传输**：stdio。
- **运行时**：managed Node 22.22.2（绝对路径，无需构建）。
- **依赖**：**零依赖**，仅用 Node 内置（`http/https`、`zlib`、`crypto`、`fs`、`path`）。

---

## 数据源（已验证端点）

仅使用从既有 quant MCP 继承的**已验证**端点：

- `push2his.eastmoney.com/api/qt/stock/kline/get` —— kline + 换手率
- `datacenter-web.eastmoney.com/api/data/v1/get` —— `RPT_LICO_FN_CPD` 财务数据
- `qt.gtimg.cn` —— 腾讯快照

### 数据源禁区（DO NOT CALL — 反爬 / 失效 / 403 / 重定向）

- `emweb.securities`（旧东方财富 emweb 站点）—— 已下线
- `f10.eastmoney.com/zycwzbAjax` —— 反爬 403
- `web.ifzq.gtimg.cn`（部分历史端点）—— 已停服

---

## 安装到 dsh

1. 在 dsh web profile 中作为 user-layer MCP server 挂接（见 `cordis.patch.yml`）。
2. patch 层为**纯覆盖式**：`- insert:` 完整条目，必须带 `name: '@deepseek-ai/dsh-mcp-client'` 并将 server 配置包在 `config:` 下。
3. 所有本地路径（日志 / 项目持久化目录 / QMT 数据目录 / akshare 桥接）均可通过环境变量覆盖，默认按"脚本目录 / 用户主目录"解析，因此在**任何机器上都是 drop-in**（详见下方「环境变量」）。

```bash
# 等价手动安装（绕过 pnpm forwarder 时）
npm pack && cd ~/.dsh/profiles/web && npm install /path/to/dsh-quant-factor-pipeline-0.1.0.tgz --no-save --no-audit --no-fund
# 重启 dsh web（端口 3080）生效
```

> ⚠️ 不要裸装 `@latest`，请以本仓库锁定版本为准。

---

## 环境变量

| 变量 | 作用 | 默认值 |
|---|---|---|
| `QMT_DATADIR` | QMT 仿真终端 `datadir` 路径；设空则禁用 QMT 数据源层 | 未设置 = 禁用 |
| `AKSHARE_PYTHON` | 运行 akshare 桥接脚本的 Python 解释器 | `python3`（系统 PATH 查找） |
| `AKSHARE_HELPER` | akshare 桥接 `.py` 脚本路径 | 同目录 `dsh_akshare_kline.py` |
| `QUANT_MCP_LOG` | 侧向日志文件路径（stdout 仅供 NDJSON），用于排障 | 同目录 `dsh-mcp-quant-factor-server.log` |
| `QUANT_PROJECTS_DIR` | `project_save` / `project_load` 持久化 manifest 目录 | 用户主目录下 `.quant-pipeline/projects` |

> 注：本仓库源码不依赖任何本地绝对路径；上述默认值在任意机器均可解析。

---

## 当前状态

- ✅ 加载健康；`panel_probe` 实测可拉取真实面板数据（2790+ 条）。
- 🔧 待完善（P0）：① 本仓库首次发布；② 本 README；③ 单文件缺单元测试；④ 与 `dsh-quant-data-mcp` 的职责边界需进一步厘清（避免重复数据源）。

---

## License

MIT — Copyright (c) 2026 helibeiqi