clawquant 0.3.3

Quantitative trading research infrastructure for AI Agents

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（可配置代理）

---

License

MIT © duolaAmeng