dsh-quant-factor-pipeline

Quant Factor Research Pipeline — a companion user-layer MCP server for DeepSeek Harness (dsh).

把「探针驱动 → 面板 → 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（详见下方「环境变量」）。

# 等价手动安装（绕过 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