ClawQuant Trader

Quantitative trading research infrastructure for AI Agents.

量化研究基建工具链，供 AI Agent（龙虾）通过自然语言调用，实现 批量回测、策略评分、机会扫描、报告生成 等研究能力。

Features

Data Pipeline — 通过 ccxt 从交易所拉取 OHLCV 数据，自动 Parquet 缓存、增量更新、质量检查
Strategy Framework — BaseStrategy ABC，6 个抽象方法，内置 3 个策略（DCA / MA Crossover / Grid）
Backtest Engine — 事件驱动引擎，下一根 K 线开盘价成交，避免未来函数
Batch & Sweep — 多策略 × 多标的批量回测，参数网格/随机扫描，Walk-forward 验证
Evaluation — Sharpe / Sortino / Calmar / MaxDD 等指标 + 5 维稳定性评分（0-100）
Reports — JSON + Markdown + 图表（权益曲线 / 回撤 / 交易标记）
Radar — 多标的实时信号扫描 + 机会解释
Deploy — Paper Trading 模拟 / Live Trading 实盘（带安全确认）
Agent-First — 所有命令支持 --json 输出，附带 6 个 Skill YAML 供 AI Agent 调用

Installation

From PyPI (Recommended)

pip install clawquant

From Source

git clone https://github.com/duolaAmengweb3/clawquant-trader.git
cd clawquant-trader
pip install -e .

安装后即可使用 clawquant 命令：

clawquant --help

Quick Start

# 1. 配置环境变量（可选，用于实盘数据拉取）
cp .env.example .env
# 编辑 .env 填入 Binance API Key 和代理（如需要）

# 2. 拉取数据
clawquant data pull BTC/USDT,ETH/USDT --interval 1h --days 10

# 3. 运行回测
clawquant backtest run ma_crossover --symbol BTC/USDT --interval 1h --days 10

# 4. 生成报告
clawquant report generate <run_id>

# 5. 批量对比
clawquant backtest batch dca,ma_crossover,grid --symbols BTC/USDT,ETH/USDT --days 10

Commands

ClawQuant 提供 6 个命令组，共 17 个子命令：

`data` — 数据管理

# 拉取 OHLCV 数据（自动缓存为 Parquet）
clawquant data pull BTC/USDT,ETH/USDT --interval 1h --days 10

# 数据质量检查（缺口、重复、异常值）
clawquant data inspect BTC/USDT --interval 1h

# 查看本地缓存状态
clawquant data cache-status

`strategy` — 策略管理

# 列出所有可用策略（内置 + 用户）
clawquant strategy list

# 验证策略完整性（用合成数据跑全部 6 个方法）
clawquant strategy validate --name ma_crossover

# 生成自定义策略模板
clawquant strategy scaffold --name my_strategy --output ./strategies_user/

`backtest` — 回测引擎

# 单次回测
clawquant backtest run ma_crossover --symbol BTC/USDT --interval 1h --days 30

# 批量回测（多策略 × 多标的，ProcessPoolExecutor 并行）
clawquant backtest batch dca,ma_crossover,grid --symbols BTC/USDT,ETH/USDT

# 参数网格扫描
clawquant backtest sweep ma_crossover \
  --grid '{"fast_period": [5,10,20], "slow_period": [20,30,50]}'

# Walk-forward 滚动验证
clawquant backtest walkforward ma_crossover --days 90 --splits 3

`radar` — 机会扫描

# 扫描当前交易信号
clawquant radar scan --symbols BTC/USDT,ETH/USDT --strategies ma_crossover,dca

# 解释特定机会
clawquant radar explain BTC/USDT ma_crossover

`report` — 报告生成

# 生成完整报告（JSON + Markdown + 图表）
clawquant report generate <run_id>

# 批量报告对比
clawquant report batch <run_id1>,<run_id2>,<run_id3>

报告输出到 runs/<run_id>/ 目录，包含：

report.json — 结构化数据
report.md — Markdown 可读报告
equity.png — 权益曲线图
drawdown.png — 回撤图
trades.png — 交易标记图

`deploy` — 部署管理

# Paper Trading（模拟交易）
clawquant deploy paper ma_crossover --symbol BTC/USDT

# Live Trading（需显式确认 + 风控必填）
clawquant deploy live ma_crossover --symbol BTC/USDT --i-know-what-im-doing

# 查看运行中的部署
clawquant deploy status

# 停止 / 紧急平仓
clawquant deploy stop ma_crossover
clawquant deploy flatten ma_crossover

JSON Output

所有命令支持 --json 全局标志，输出结构化 JSON，供 AI Agent 程序化消费：

clawquant --json strategy list
clawquant --json backtest run ma_crossover --symbol BTC/USDT --days 10
clawquant --json radar scan --symbols BTC/USDT

Built-in Strategies

Strategy	Description	Type	Key Params
`dca`	Dollar Cost Averaging 定投	Passive	`invest_amount`, `invest_interval`
`ma_crossover`	Moving Average Crossover 均线交叉	Trend Following	`fast_period`, `slow_period`, `ma_type`
`grid`	Grid Trading 网格交易	Mean Reversion	`grid_count`, `grid_spacing_pct`, `order_amount`
`rsi_reversal`	RSI Reversal RSI反转	Mean Reversion	`rsi_period`, `oversold`, `overbought`
`bollinger_bands`	Bollinger Bands 布林带	Mean Reversion	`bb_period`, `bb_std`
`macd`	MACD 指数平滑异同移动平均线	Trend Following	`fast_period`, `slow_period`, `signal_period`
`breakout`	Donchian Breakout 唐奇安突破	Trend Following	`lookback`

Custom Strategies

继承 BaseStrategy，实现 6 个抽象方法：

from clawquant.core.runtime.base_strategy import BaseStrategy, StrategyMetadata

class MyStrategy(BaseStrategy):
    @classmethod
    def metadata(cls) -> StrategyMetadata:
        """策略元信息 + 参数 JSON Schema"""
        ...

    def compute_indicators(self, df, params) -> pd.DataFrame:
        """计算技术指标，返回带新列的 DataFrame"""
        ...

    def generate_signals(self, df, params) -> pd.Series:
        """生成信号序列: 1=BUY, 0=HOLD, -1=SELL"""
        ...

    def position_sizing(self, signal, portfolio_state, params) -> float:
        """返回目标仓位变化量（USDT 计价）"""
        ...

    def risk_controls(self, portfolio_state, market_state, params) -> list:
        """返回风控动作列表"""
        ...

    def explain(self, last_state) -> dict:
        """返回可解释输出"""
        ...

将 .py 文件放入 strategies_user/ 目录即可自动发现，或通过 file: 路径指定：

clawquant backtest run file:./my_strategy.py --symbol BTC/USDT

使用 clawquant strategy scaffold 生成完整模板。

Backtest Engine Design

事件驱动架构

Bar Event → Signal Event → Order Event → Fill Event → Portfolio Update

关键设计决策

决策	选择	原因
成交模型	下一根 K 线开盘价	避免未来函数偏差
数据存储	Parquet	列式读取快，pandas 原生支持
并行回测	ProcessPoolExecutor	CPU 密集型任务需真正并行
策略状态	类实例属性	Grid 等有状态策略最清晰
Run ID	`{strategy}_{symbol}_{ts}_{uuid[:8]}`	人类可读 + 唯一

评分体系

5 维稳定性评分（0-100）：

维度	权重	评估内容
Quality	30%	Sharpe, Sortino, Win Rate
Risk	30%	Max Drawdown, Calmar Ratio
Robustness	20%	年化波动率、连续亏损
Cost Sensitivity	10%	手续费占比
Overtrade	10%	日均交易频率

可复现性保证

每次回测输出 run_meta.json，记录：

策略名称 + 版本 + 参数哈希
数据源 + 时间范围 + 数据哈希
引擎配置（初始资金、手续费、滑点）
Python 版本 + 依赖哈希

相同输入 → 确定性结果。

Project Structure

clawquant/
├── clawquant_cli.py          # Typer CLI 主入口
├── cli/                      # 6 个命令组实现
│   ├── data_cli.py           # data pull/inspect/cache-status
│   ├── strategy_cli.py       # strategy list/validate/scaffold
│   ├── backtest_cli.py       # backtest run/batch/sweep/walkforward
│   ├── radar_cli.py          # radar scan/explain
│   ├── report_cli.py         # report generate/batch
│   └── deploy_cli.py         # deploy paper/live/status/stop/flatten
├── core/
│   ├── data/                 # 数据拉取 / Parquet 缓存 / 质量检查 / 时间对齐
│   ├── runtime/              # BaseStrategy ABC / 策略加载器 / 沙箱
│   ├── backtest/             # 事件引擎 / 组合管理 / 撮合 / 风控 / 批量 / 扫描
│   ├── evaluate/             # 指标计算 / 5维评分
│   ├── radar/                # 信号扫描 / 机会解释
│   ├── report/               # JSON + Markdown + 图表报告
│   ├── deploy/               # Paper / Live 执行循环
│   └── utils/                # Run ID / 日志 / 输出格式
├── strategies_builtin/       # DCA / MA Crossover / Grid
├── strategies_user/          # 用户自定义策略目录
├── integrations/             # ccxt 封装 / Binance Skill 适配
└── skills/                   # 6 个 Agent Skill YAML 定义

Environment Variables

Variable	Description	Default
`BINANCE_API_KEY`	Binance API Key	—
`BINANCE_SECRET`	Binance API Secret	—
`DEFAULT_EXCHANGE`	默认交易所	`binance`
`DATA_CACHE_DIR`	数据缓存目录	`data_cache`
`RUNS_DIR`	回测结果目录	`runs`
`HTTPS_PROXY`	代理地址（访问交易所 API）	—

Agent Skills

ClawQuant 提供 6 个 YAML Skill 定义（skills/ 目录），AI Agent 可通过自然语言调用：

Skill	Description
`quant_data_pull`	拉取交易数据
`quant_backtest_batch`	批量回测
`quant_backtest_sweep`	参数扫描
`quant_radar_scan`	机会扫描
`quant_report_get`	获取报告
`quant_deploy`	部署交易

示例对话：

"在 BTC 和 ETH 上对比 DCA、均线交叉、网格三个策略，过去 10 天，给我 top3 报告"

Agent 将自动编排 data pull → backtest batch → report batch 完成全流程。

Tech Stack

Component	Technology
CLI Framework	Typer
Exchange API	ccxt
Data Processing	pandas + PyArrow
Charts	matplotlib
Data Models	Pydantic v2
Terminal Output	Rich

Requirements

Python >= 3.10
网络访问交易所 API（可配置代理）

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
clawquant		clawquant
docs		docs
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ClawQuant Trader

Features

Installation

From PyPI (Recommended)

From Source

Quick Start

Commands

`data` — 数据管理

`strategy` — 策略管理

`backtest` — 回测引擎

`radar` — 机会扫描

`report` — 报告生成

`deploy` — 部署管理

JSON Output

Built-in Strategies

Custom Strategies

Backtest Engine Design

事件驱动架构

关键设计决策

评分体系

可复现性保证

Project Structure

Environment Variables

Agent Skills

Tech Stack

Requirements

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

ClawQuant Trader

Features

Installation

From PyPI (Recommended)

From Source

Quick Start

Commands

data — 数据管理

strategy — 策略管理

backtest — 回测引擎

radar — 机会扫描

report — 报告生成

deploy — 部署管理

JSON Output

Built-in Strategies

Custom Strategies

Backtest Engine Design

事件驱动架构

关键设计决策

评分体系

可复现性保证

Project Structure

Environment Variables

Agent Skills

Tech Stack

Requirements

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`data` — 数据管理

`strategy` — 策略管理

`backtest` — 回测引擎

`radar` — 机会扫描

`report` — 报告生成

`deploy` — 部署管理