dsh-quant

一句话定位

给 DeepSeek Harness 的 Agent 装上一套量化研究工具箱：拉行情、算技术指标、做因子评价、跑策略回测、度量风险、模拟下单、生成报告，一行命令能跑完整条 PDAT→PET 流水线。它不用任何凭据就能取公开行情，所有数学计算都是纯函数、可离线验证。

核心能力

• 拉取公开行情：从 Binance、OKX、Bybit、Sina、腾讯财经、Yahoo Finance 六个来源取 K 线，无需登录或 API key（src/dsh-data/market.ts:31-69）
• 计算 12 个技术指标：SMA、EMA、RSI、MACD、布林带、ATR、KDJ、威廉指标、CCI、OBV、ADX、ROC（src/dsh-alpha/indicators.ts:1-100）
• 跑策略回测并出报告：双均线、布林带突破、RSI 反转、多资产组合再平衡、参数网格搜索五种内置策略（src/dsh-ml/backtest.ts:1-30）
• 做因子评价与中性化：IC/RankIC/分位/多空/换手率，按市场或风格因子做 OLS 残差中性化（src/dsh-alpha/factor.ts:1-30）
• 度量风险与做 VaR 回测：VaR、CVaR、Beta、Alpha、信息比率、跟踪误差，配合 Kupiec 检验验证风险模型（src/dsh-risk/risk.ts:1-30）
• 模拟下单 + 私募基金模拟：带滑点/费率的撮合与带 2% 管理费、20% 高水位业绩报酬的资金曲线（src/dsh-execution/execute.ts、fund.ts）

技术实现

• 语言: TypeScript（ESM，NodeNext，package.json:6 type:module），21 个源文件，零运行时依赖
• 关键依赖: @deepseek-ai/cordis ^4.0.0（钩子上下文）、@deepseek-ai/dsh-tools ^0.1.0-rc.5（defineTool schema DSL）、@deepseek-ai/dsh-system-prompt ^0.1.0-rc.5（schema 注入）；业务侧零依赖（指标/回测/期权/债券全用纯 JS 数学）
• 架构模式: Cordis 函数插件 —— 命名导出 name='dsh-quant'、inject=['tools']、apply(ctx) 通过 ctx.tools.register(defineTool(...)) 注册 46 个工具（src/index.ts:68-77）；用 cordis.patch.yml 作为 bundle patch 在宿主 profile 加载；HMR 可逆 —— fiber 销毁时 dispose 工具
• 入口文件: src/index.ts（主插件，2379 行 apply 函数），编译输出 lib/index.js 作为 NodeNext ESM 入口（package.json:17-23）；CLI 入口 cli/main.mjs 跑在外提供交互式 TUI 浏览

适用场景

在 DSH Agent 里想跑量化研究、又不想自己写一堆数学库的人：上传一组价格就能算指标、能拼回测、能出报告，给聊天机器人或编程 Agent 装上"会算量化"的能力。量化研究者可以把它当作可复用的计算底座，把自己的数据源和策略接进同一个六域插槽体系。需要实盘交易、做单、做业绩归因的用户需要换插件，本工具不含撮合/账户/合规部分。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:pengpengyi92/dsh-quant

配置项

本插件无需额外配置。

配置由两个层面控制：

1. DSH 注册：通过 cordis.patch.yml 在 profile 中以 name: 'dsh-quant' / id: 'quant-indicators' 加载；用户可在自己的 patch 中覆盖或禁用该 row（cordis.patch.yml:1-10）
2. 每次调用：所有"配置"通过调用时传入的参数（symbol、window、feeRate、stopLoss、confidence、interval、provider 等）下达，每个工具都有 schema 校验与默认值，无需预先打开任何开关

常见问题

Q: 安装后为什么 DSH 里看不到 quant_ 工具？*

A: 安装只把包拉下来，cordis patch 必须被加载到当前 profile 才会注册。在 cordis.yml 加 - name: 'dsh-quant'，或在 dsh web 的插件管理面板里启用对应 bundle，重启一次 dsh web 就能看到 46 个 quant_* 工具。

Q: 没有网络能不能用？

A: 能用。174 个手算单测全部离线通过（tests/ 下 26 个 spec 文件），覆盖 12 个指标、5 种回测、因子组合、Kupiec 检验、期权、债券、模拟盘等；只有 quant_market_fetch / quant_repo_stats / quant_npm_stats 这类工具需要网络。

Q: A 股和美股怎么取数据？

A: 把 provider 参数切换即可。sina / tencent 取 A 股（symbol 形如 sh600000、sz000001、bj430047），yahoo 取美股/港股/指数（AAPL、^GSPC、0700.HK），这三家都不需要 token；crypto 用 binance / okx / bybit，同样不需 key。

Q: 回测会不会引入未来函数？

A: 不会。src/dsh-ml/backtest.ts 与 README 第 215 行明确写了"signal confirms on bar i, fills at bar i+1 close, no look-ahead"；quant_walk_forward 走滚动训练样本外验证，适合用来做策略过拟合检查。

Q: 这个插件能实盘下单吗？

A: 不能。quant_execute_sim 是带滑点/费用/延迟的撮合模拟，不是券商接口；README 第 369-374 行清楚标了 "no live trading, framework only"。

Q: 行情数据要花钱或者自己提供 key 吗？

A: 自带的 6 个 provider（binance/okx/bybit/sina/tencent/yahoo）一律公开接口、无需凭据，但有频率上限和服务条款限制。要用更高质量/更全品种数据（akshare/tushare/wind/jqdata），插件内置 quant_data_guide 与 quant_data_advice 给出 15 个外部渠道的对比，自己去配 token。

Q: 为什么用 TypeScript 而不是 Python？

A: 因为它跑在 DSH 同进程的 Node 运行时里，必须走 TypeScript 才能被 Loader 热注册、HMR 安全；Python 部分由 dsh 的子进程能力承担，计算内核全部手算可验证（README 第 56-72 行解释）。

Q: 怎么加自己的策略或数据？

A: 6 大域（data/alpha/ml/risk/execution/community）都是插槽 —— 直接改 src/dsh-* 加新工具，或者写一个独立 cordis 插件 import 这边的纯函数（src/index.ts:43-67 把 21 个纯函数全部 re-export）；扩展入口见 GitHub Issue #27。

上手难度

进阶 — 需要懂一点量化基础（指标、回测、夏普比率、滑点）和 DSH 的 cordis 插件机制；安装只有一行，但想真正发挥出六域插槽价值要先看 docs/ONBOARDING.md 和 mcp/AGENT_GUIDE.md。

已知问题与限制

• 行情以加密货币为主：binance / okx / bybit 三个 crypto 接口自动回退，A 股通过 sina / tencent / yahoo 公开接口接入，没有专门的 akshare / tushare 通道（需要 A 股深度数据的用户要接外部数据源，README.md:355-357）
• 回测是内置策略族：双均线、布林带突破、RSI 反转、组合再平衡、参数网格搜索五种；自定义策略回调（dynamic callback）是未来路线，README.md:358-360
• presentCall / presentResult 未定制：指标类结果没有专属的文件/终端/diff 表现语义，UI 端只能用通用卡片展示，README.md:361-362
• 行情工具需要网络：quant_market_fetch / quant_repo_stats / quant_npm_stats 走外网；离线用例可以靠 verify.ts 之外的预抓数据绕开，README.md:363-364
• 快慢均线等参数有手检：backtestMaCross 强制 fast < slow、feeRate >= 0、stopLoss ∈ (0,1)、takeProfit > 0，违反时抛 RangeError（src/dsh-ml/backtest.ts:50-58），调用方需要在调用前保证参数合法
• market_fetch 的 limit 上限 1000：超过 1000 触发参数校验抛错，src/index.ts:323-325

🌐 Site: https://dsh-quant-site.pages.dev · ✅ Listed in awesome-dsh-plugin (one-click install via dsh-market)

AI-native & DSH-native quant toolkit for every quant aspect — 46 tools · 6 domains (data / alpha / ML / risk / execution / ecosystem) · one end-to-end PDAT→PET research pipeline. Methods open, secrets internal.

🧩 Core Philosophy: Everything is a Plugin (quant edition)

dsh's philosophy is everything is a plugin; dsh-quant brings it to quant — open-sourcing the internal five-team paradigm (PDAT → PAAT → PCPT → PRT → PET) as five pluggable modules:

data plugin   dsh-data      market data / sources / quality  ← plug in Binance or your own data
alpha plugin  dsh-alpha     indicators / factors / eval      ← write your own alpha (internal alpha stays private)
model plugin  dsh-ml        backtests / ML/DL/RL framework   ← train your own models (internal research stays private)
risk plugin   dsh-risk      VaR / drawdown / options / bonds ← set your own risk limits
exec plugin   dsh-execution sim execution / fund / report    ← build your own trading system (paper or live)

• What's open is the paradigm: how modules compose, how contracts are defined (null alignment / no look-ahead / hand-computed tests), how results are validated — not the internal secrets
• You fill it in: product power = UI + strategies + data interfaces + DL/RL models + trading-system building, all self-assembled, all pluginized
• Infinite self-evolution: fill the framework with your modules → run paper/live → feed the ecosystem back — that's dsh-quant

Plugin call for proposals: Issue #27 (five modules × many plugins) — PDAT plugins, PET plugins, anything you can imagine 🐋

🤖 AI-Native Is Deliberate (design statement)

dsh-quant's primary consumer is the agent (the model), not the human — a deliberate choice from day one:

• Tool schemas are injected into the system prompt — every contract (args / outputs / alignment rules) is written from the model's perspective
• Equal-length null alignment — outputs match input length; leading window positions are null, so the model aligns by index and never pads
• Canonical JSON + render separation — machines read structure, humans read prose
• All isConcurrencySafe — pure functions, no shared state; agents can call all 46 tools in parallel without interference
• Skill layer — skill/quant-research lets the model load the workflow itself

Full statement: Issue #14 "AI-native is deliberate".

🐍 Why Almost No Python?

A common question: a quant project without .py files? Answer: 0 Python files, 21 TypeScript source files, zero runtime dependencies — deliberate:

• dsh-quant is a dsh plugin running inside the harness's Node runtime: same process as the agent, composable by the Loader, reversible registration (HMR-safe) — TypeScript is the only natural choice
• Where Python is needed (akshare / tushare / baostock), use the channel knowledge base (quant_data_guide, 15 channels): dsh ships shell / subprocess capabilities, so the agent decides whether to spawn Python — dsh-quant carries no runtime
• All numerical methods (indicators / backtests / options / bonds) are pure functions with hand-computed baselines: zero deps, offline-verifiable, npm test green anywhere

One goal: build the most usable AI-native quant repo 🐋

46 quant_* tools · 6 domains · 174 unit tests · zero runtime deps. Full positioning: pinned Issue #9.

🤖 For visiting agents

Agents landing on this repo: start at AGENTS.md (root-level, auto-read by Copilot / Claude Code / dsh), then the closed-loop example plugin/CASE_STUDY.md or Discussion #38, and the one-glance contract mcp/AGENT_GUIDE.md.

Quick Install (dsh users)

npm i dsh-quant

Add one line to your cordis.yml:

- name: 'dsh-quant'

46 tools auto-register — indicators / backtests / factors / risk / fund simulation / ecosystem metrics out of the box. One quant_research_pipeline runs the whole PDAT→PET chain. ML/DL knowledge: docs/ML_GUIDE.md; executable demo: npx tsx demos/ml-workflow.ts.

🚀 Product Experience: Three Minutes to a Full Quant Pipeline

Right after install, experience the complete PDAT→PET flow (BTC public data + simple strategy + backtest + paper trading):

data(quant_market_fetch) → quality(quant_data_quality) → factors(quant_factor_evaluate)
→ backtest(quant_backtest) → metrics(quant_metrics) → risk(quant_risk)
→ drawdown(quant_drawdown) → paper sim(quant_execute_sim) → fund sim(quant_fund)
→ report(quant_report)

One-liner: quant_research_pipeline(symbol=BTCUSDT, limit=120) returns everything in one call.

Then plug your own plugins into each module (data sources / alpha / models / risk / execution — everything is a plugin, proposals at Issue #27).

Five-step walkthrough with commentary: docs/ONBOARDING.md · Agent one-glance guide: mcp/AGENT_GUIDE.md

🖥️ UI Workbench (dsh-quant-ui)

dsh-quant-ui: candlesticks + MA overlays + trade markers, equity curves, fund NAV / management-fee / performance-fee cards, metric selector — plus a swimming chibi whale 🐋 (click the title 3 times).

Live demo: https://dsh-quant-ui.pages.dev

⌨️ CLI (dsh-quant terminal)

Zero-dependency readable terminal (pure Node + ANSI, same philosophy as the P-Research CLI). Browse the research columns and live market data without a browser:

node cli/main.mjs repo                      # 46 tools · 6 domains
node cli/main.mjs history                   # 53 firm archives index
node cli/main.mjs history citadel           # one firm's archive (rendered)
node cli/main.mjs history --reports         # ANALYSIS / TIMELINE / LINEAGE / BANK_LINEAGE
node cli/main.mjs history --search 高频      # cross-archive search
node cli/main.mjs kline BTCUSDT --limit 20  # colored OHLC table + stats
node cli/main.mjs browse                   # interactive TUI: arrow-key firm browser

After npm install -g ., the commands shorten to dsh-quant repo, dsh-quant history citadel, etc.

Tools

Typical chain (model's view)

quant_market_fetch(symbol: BTCUSDT, interval: 1d, limit: 100)
  → take close → quant_sma / quant_ema / quant_rsi / quant_macd / … → quant_backtest

Verified live: real Binance daily bars → indicators → backtest (fast 5 / slow 20) end to end.

Backtest contract

• Dual-MA crossover: buy all-in when fast SMA crosses above slow SMA, liquidate when it crosses below; signals confirm on bar i and fill at bar i+1 close (no look-ahead).
• Fees are charged on both sides of notional (feeRate per side).
• Open tail position: the last trade's exitIndex/exitPrice/returnPct are null.
• position and equityCurve match input length; equity is normalized (starts at 1); Sharpe is annualized assuming daily frequency (√365).

Alignment conventions

• All outputs are equal-length with inputs; leading unwindowed positions are null — the model aligns by index, no padding needed.
• Empty series or window > series length is a legal result (all null), not an error.
• Non-finite numbers (NaN/Infinity) are rejected at the registry's lossless-JSON argument snapshot layer (the model's JSON boundary) and never reach execute.
• Constraints (window ≥ 1 integer, macd fast < slow, atr arrays equal length, multiplier > 0) are hand-checked in execute; thrown errors become isError results via the registry.

Contract (defineTool)

• Arguments use the unified schema DSL, validated by defineTool before execute (types / required / integers).
• execute returns only the canonical JSON value; output.render produces the model-facing prose.
• Every tool is isConcurrencySafe: true — pure functions, no shared state, no side effects, parallel-schedulable.
• Registration is a reversible effect: ctx.tools.register returns a disposer; fiber disposal unregisters.

Model Experience

What the model sees

Each tool's name/description/JSON schema is injected into the system-prompt assembly (ctx.systemPrompt.tools()). Descriptions state the alignment rules (which head positions are null), so the model never guesses.

Token impact

Each tool costs one fixed schema block; call results are charged by rendered content. The null-alignment design avoids repeated padding requests from the model.

KV cache impact

The schema prefix is stable (reused as long as the tool set and order are unchanged); results append after the reusable prefix.

Release history (NEWS)

Full records: NEWS.md and CHANGELOG.md.

Known limitations & roadmap

• Market coverage is crypto-first: Binance / OKX / Bybit public APIs (automatic fallback), no credentials; A-shares go through the channel knowledge base (akshare et al. as future providers).
• Backtests are a built-in strategy family: dual-MA / Bollinger breakout / RSI reversion / portfolio rebalancing / grid search; custom strategy callbacks are the future route.
• presentCall/presentResult not customized: indicator results have no file / terminal / diff semantics; UI falls back to generic cards.
• Market tools need network: live cases live in verify.ts; offline indicator / backtest cases are unaffected.

Domain layout (PDAT→PET pipeline mapping)

src/dsh-data/       data (PDAT): 3 exchanges, 15 channels, quality/annotation, resample
src/dsh-alpha/      alpha (PAAT): 12 indicators + factor eval/combine (alphalens methodology)
src/dsh-ml/         portfolio (PCPT): strategy backtests + portfolio + metric catalog
src/dsh-risk/       risk (PRT): VaR/CVaR/Beta/Alpha/IR + Kupiec test + options + bonds
src/dsh-execution/  delivery (PET): chart data plane, fund sim, research report (no live trading)
src/dsh-community/  ecosystem (unique to the open side): GitHub/npm data + influence pulse

The boundary: data and conclusions stay internal; tools and methods ship to dsh-quant — no alpha, no production strategies, no live-trading engineering, but frameworks, indicators, factor evaluation, UI and demos. See pinned Issue #9.

Quick start (after fork/pull)

npm ci && npm run build && npm test    # offline full tests (174 unit + 4 Loader)
npm run test:verify                    # live market integration (needs network)
npm run gen:tools                      # regenerate mcp/tools.json

Build & use

# build lib/ (tsc, NodeNext ESM; ships .js + .d.ts)
cd quant-indicators && tsc -p tsconfig.json

# use in dsh: add one line to cordis.yml
# - name: 'dsh-quant'
# (the Loader resolves the package exports → lib/index.js from node_modules)

Verification

# pure-function numeric correctness + market parsing + backtests (174 cases, node:test, zero deps)
cd deepseek-harness && pnpm exec tsx --test ../quant-indicators/tests/*.spec.ts

# REAL-composition: cordis.yml booted through the real Loader (registration visible / pipeline / isError / HMR-safety)
cd deepseek-harness && pnpm exec tsx --test ../quant-indicators/tests/loader-composition.spec.ts

# harness integration (schemas → execution pipeline → isError → live fetch→indicators→backtest end-to-end)
cd deepseek-harness && pnpm exec tsx ../quant-indicators/verify.ts

# consumer simulation: built lib loaded through real node_modules resolution (simulates post-install)
cd deepseek-harness && pnpm exec tsx ../quant-indicators/consumer-test/boot.ts

⭐ Support

If dsh-quant helps your research, a ⭐ makes the project visible to more dsh users.

This whale stands for DeepSeek Harness (dsh) — trading on its holographic screen 🐋

Issues / PRs / discussions welcome; share your domain perspective in Discussion #10. 🐋

Ecosystem infrastructure: quant ecosystem directory · ecosystem playbook · ecosystem map Discussion #11

Research columns: quant-history (firm archives) · quant-repo (open-source special)

Plugin library (five slots × external repos & MCPs): plugin/