Metadata-Version: 2.4
Name: hamuna-quant-cli
Version: 0.1.0
Summary: Hamuna A 股回测 + 实盘统一 CLI (akquant 0.3.x). 替代 v1 自建 driver + QMT-style 策略规范.
Author-email: Hamuna Team <team@hamuna.example>
License: MIT
Project-URL: Homepage, https://hamuna.example
Project-URL: Bug Tracker, https://github.com/hamuna/hamuna-strategy-platform/issues
Keywords: quant,backtest,akquant,A-share,QMT,hamuna
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: akquant<0.4,>=0.3.41
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Requires-Dist: pyarrow>=10
Requires-Dist: pyyaml>=6
Requires-Dist: requests>=2.28
Requires-Dist: boto3>=1.34
Requires-Dist: cryptography>=41
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Provides-Extra: polars
Requires-Dist: polars>=0.20; extra == "polars"
Provides-Extra: backtest-extra
Requires-Dist: matplotlib>=3.7; extra == "backtest-extra"
Requires-Dist: plotly>=5.15; extra == "backtest-extra"

# hamuna-quant-cli

A 股回测 + 实盘统一 CLI (akquant 0.3.x).

替代 v1 自建 driver (`hamuna-strategy`) + QMT-style (`init/handlebar/passorder`).
**同一份策略代码天然兼容回测与实盘** (akquant `Strategy` 双引擎一等公民).

## 安装

```bash
pip install hamuna-quant-cli
# 或本地源码装
pip install -e /path/to/hamuna-strategy-platform
# 或本地 wheel
pip install /path/to/hamuna_quant_cli-*.whl
```

**Windows / macOS / Linux 全支持** (Python ≥3.10).

依赖: `akquant>=0.3.41,<0.4` (Rust + Python 混合引擎).

## 构建 (版本号自动更新)

每次构建版本号自动 +1 (基于 git 提交数):

```bash
# 一键: 先 bump 版本 → 再 build wheel + sdist
bash scripts/build_python.sh

# 或手动两步 (效果相同)
python3 scripts/bump_version.py --python
python3 -m build
```

产物在 `dist/`。版本格式 `0.1.0.dev<git提交数>` (PEP 440),同一 commit 版本可重现。

## 子命令一览

| 命令 | 用途 |
|---|---|
| `hamuna_quant_cli run <strategy.py> --config cfg.json` | 跑 akquant backtest → result.json |
| `hamuna_quant_cli check <strategy.py> --config cfg.json` | 8 条纪律静态审查 (不回测) |
| `hamuna_quant_cli upload <strategy_id> --result result.json` | PUT metrics → server |
| `hamuna_quant_cli create --name ... --config ...` | 新建 strategy 拿 strategy_id |
| `hamuna_quant_cli parity` | 5 内置 strategy × 1 universe parity test |
| `hamuna_quant_cli qmt-translate <strategy.py> cfg.json` | akquant → QMT body 翻译 (本地 stub) |
| `hamuna_quant_cli commit <strategy_id>` | 5 步打包上传 (translate + bundle + PUT + POST + export) |
| `hamuna_quant_cli dataset {list\|fetch\|manifest}` | prebuilt 数据集管理 |
| `hamuna_quant_cli live run <strategy.py>` | **实盘 / 仿真运行** (包装 akquant.run_live) |

## 端到端回测 (10 行)

```bash
# 0) 安装
pip install hamuna-quant-cli

# 1) 写策略
cat > /tmp/s.py <<'EOF'
# coding: utf-8
from akquant import Strategy
class S(Strategy):
    warmup_period = 1
    def on_bar(self, bar):
        if self.get_position(bar.symbol) == 0:
            self.buy(bar.symbol, 100)
EOF

# 2) 写 cfg
cat > /tmp/c.json <<'EOF'
{
  "backtest_start": "20240701",
  "backtest_end":   "20241231",
  "pool":           {"hs300": {"codes": ["600000.SH", "600036.SH"]}},
  "init_capital":   1000000.0
}
EOF

# 3) 静态审查
hamuna_quant_cli check /tmp/s.py --config /tmp/c.json
# 期望 stderr: "纪律 self-check 通过 (0 条)"

# 4) 跑回测
hamuna_quant_cli run /tmp/s.py --config /tmp/c.json --output /tmp/r.json

# 5) 上传 (auto-create strategy)
hamuna_quant_cli upload --name "v2_smoke" --config /tmp/c.json --code /tmp/s.py --result /tmp/r.json
```

## 实盘 (5 行)

```bash
# 1) 写策略 (同上)

# 2) paper 模式 (smoke, 不连真实 broker)
hamuna_quant_cli live run /tmp/s.py \
    --mode paper --broker replay --symbols sh600000,sz600036 --duration 30s

# 3) qmt 实盘 (需配 broker=qmt + market_broker=qmt_market + gateway_options)
hamuna_quant_cli live run /tmp/s.py \
    --mode broker_live --broker qmt --market-broker qmt_market \
    --symbols sh600000,sz600036 \
    --gateway-options "qmt_account_id=8888888888,qmt_base_url=http://127.0.0.1:9000"
```

## 不在 hamuna-quant-cli 范畴

- ❌ 5m / tick / 多周期 (akquant 0.3.x Phase B 锁日线)
- ❌ ETF / 期权 / 期货 (akquant 仅股票)
- ❌ 自建回测引擎 / 私有 IR / DSL (ADR-001/002 禁止)
- ❌ realtime dashboard / live trading 控制台 (v2 是离线回测 + 一次性实盘 run)

## 关联文档

- 项目根: `../CLAUDE.md`
- v2 skill (skill 文档, 不再含代码): `../skills/hamuna-strategy-v2/SKILL.md`
- AKQuant Guide (引擎手册): `../docs/AKQUANT_GUIDE.md`
- v1 skill (旧, QMT-style 不变): `../skills/hamuna-strategy/`
