# dsh-quant-workspace

[English](README.md) | [中文](README.zh.md)

一个**完全自包含的量化调研工作台**插件，用于 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)。
Python 引擎随包分发——从聊天里直接拉取 Yahoo Finance 日线数据、回测规则策略、生成交互式
可视化报告。

> ⚠️ **非投资建议。** 工作台只呈现规则状态与证据；决策永远由你自己做出。它绝不自动下单、
> 绝不改动仓位。

## 功能

- **数据拉取** —— Yahoo Finance 日线（默认 2 年），支持 OHLCV + 指标导出。
- **回测** —— 逐笔交易明细、总收益、最大回撤、胜率、平均持有天数、买入持有基准对比。
- **可视化报告** —— 自包含交互式 HTML 图表：K线 + 布林带 + 买卖点标记 + 成交量 + %B + 净值曲线；
  滚轮缩放（锚定光标）、拖拽平移、十字光标、红涨绿跌一键切换；零依赖，浏览器直接打开。
- **策略注册** —— 调研后把策略保存进工作台注册表，按 id 复用。
- **只读设计** —— 不下单、不改仓位、不需要行情 API key。

## 环境要求

- 已安装 DeepSeek Harness（`web` profile）且可用 `pnpm`。
- 装有 `uv`（运行随包引擎；首次使用会同步 `python/.venv`）。
- 能访问 Yahoo Finance。

## 安装

> **安装状态：** 尚未发布到 npm。在此之前可用 git 地址安装
> （`dsh plugin --profile web add github:AllenCX/dsh-quant-workspace`），或用下面的本地 overlay 方式。

```sh
dsh plugin --profile web add dsh-quant-workspace
```

所有配置都是可选的。用户层 patch 示例（`$DSH_HOME/profiles/web/cordis.patch.yml`）：

```yaml
- id: quant-workspace
  config:
    ledgerPath: 'C:\path\to\trade_log.csv'   # 可选：跟踪你的真实持仓
    reportsDir: 'C:\path\to\reports'          # 可选：可视化报告输出目录
```

| 选项 | 默认 | 含义 |
|---|---|---|
| `ledgerPath` | *（无）* | 持仓流水 CSV（`date,ticker,action,price`，FIFO）。持仓只从该文件跟踪。 |
| `reportsDir` | `$DSH_HOME/dsh-quant-workspace/reports` | 可视化报告产物（HTML 图表）与状态导出目录。 |
| `registryPath` | `$DSH_HOME/dsh-quant-workspace/strategies.json` | 策略注册表 JSON 文件。 |
| `defaultRule` | *（无）* | 调用未指定规则时使用的默认规则族。 |
| `timeoutMs` | `180000` | 每次工具调用的前台超时。 |
| `pythonCommand` | `uv run --project <包>/python dsh-quant` | 覆盖运行随包引擎的命令（例如用预建的 venv）。 |

### 开发 / 本地 overlay

```sh
pnpm dsh web --patch ./dev.patch.yml
```

## 快速上手

在 Harness 会话里直接说：

- "查一下 TSLA 今天的信号卡" —— `single_ticker`，mode `daily`。
- "给 META 跑个回测并生成图表" —— `single_ticker`，mode `backtest`，`chart: true`。
- "对 TSLA 做一次健康检查" —— `single_ticker`，mode `review`。

每次调用执行一条规则：传入示例 `rule` 族、已注册的 `strategy` id，或使用配置的
`defaultRule`（两者都没传时）。都没有的话，工作台会如实告诉你未选择策略。

## 工具

### `single_ticker`

- `ticker`（必填）—— 代码，如 `TSLA`。自动转大写；只接受字母、数字、点号和短横线。
- `mode`（默认 `daily`）—— `daily` 信号卡 · `backtest` 回测（逐笔明细）· `review` 健康检查。
- `rule` —— 示例规则族（目前 `bollinger_mean_reversion`）。
- `strategy` —— 工作台注册表里已注册策略的 id。
- `chart`（默认 false）—— 同时生成交互式 HTML 报告和状态 CSV 到 `reportsDir`，产物路径会包含在输出里。

## 策略注册

调研之后把策略保存下来，按 id 复用：

```sh
dsh-quant strategy register --id tsla_dip --family bollinger_mean_reversion --bollinger-window 30 --note '2026-08 调研后的抄底策略'
dsh-quant strategy list
dsh-quant strategy remove --id tsla_dip
```

## 示例规则

随包引擎内置一条示例规则，保证开箱即用：日线布林带均值回归——`%B <= 0` 入场，`%B >= 1` 出场
（布林带 20, 2σ；当日收盘成交；v1 不建模交易成本）。规则参数都是 CLI 选项，更多规则族
（MA 交叉、Donchian、RSI、趋势过滤）在路线图上。

## CLI 参考

```
dsh-quant single-ticker --ticker <T> --mode <daily|backtest|review> (--rule <family> | --strategy <id>) [--ledger <path>] [--chart <dir>] [--export-state <dir>] [--registry <path>] [--data-file <csv>]
dsh-quant strategy register|list|remove [options]
```

- 成功：退出码 0，输出纯文本报告；数据加载失败：退出码 1；非法调用：退出码 2。
- `--data-file` 从本地 OHLCV CSV 读取而非联网（测试用）。

## 开发

```sh
pnpm install && pnpm run typecheck && pnpm run test && pnpm run build   # TS 外壳
cd python && uv run --project . pytest tests -q                          # 随包引擎
```

## 许可证

MIT