hamuna-quant-cli 0.1.0.dev93__tar.gz

hamuna_quant_cli-0.1.0.dev93/MANIFEST.in

@@ -0,0 +1,4 @@
+include hamuna_quant_cli/README.md
+include hamuna_quant_cli/scripts/*.json
+recursive-exclude * __pycache__
+recursive-exclude * *.py[cod]

hamuna_quant_cli-0.1.0.dev93/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: hamuna-quant-cli
+Version: 0.1.0.dev93
+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
+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/`

hamuna_quant_cli-0.1.0.dev93/README.md

@@ -0,0 +1,163 @@
+# Hamuna.Trade 量化策略平台
+
+React + Vite 前端、Go + Gin API、MongoDB 和 Redis 组成的本地可执行栈。
+
+## 一键启动（全本地，Docker 自带 Mongo + Redis + MinIO）
+
+前置条件：Docker Desktop（包含 Docker Compose）。
+
+```bash
+copy .env.example .env
+# 编辑 .env，至少更换 MONGO_PASSWORD 和 JWT_SECRET
+docker compose up -d --build
+docker compose ps
+```
+
+服务地址：
+
+| 服务 | 地址 |
+|---|---|
+| Web 前端 | http://localhost:3000 |
+| Go API | http://localhost:8080 |
+| API 健康检查 | http://localhost:8080/health |
+| 前端代理健康检查 | http://localhost:3000/health |
+| MongoDB | mongodb://localhost:27017 |
+| Redis | redis://localhost:6379 |
+
+> 完整本地栈请改用 `docker-compose.local.yml` 旧版（Mongo + Redis + MinIO + Backend + Frontend 都在容器里）。当前根目录 `docker-compose.yml` 仅为生产部署使用。
+
+## 验证前后端闭环
+
+需要 Node.js 18 或更高版本：
+
+```bash
+node scripts/smoke.mjs
+```
+
+数据库通过根目录 `.env` 配置；MongoDB 端口使用 `MONGO_PORT`，远程托管服务可直接设置 `MONGODB_URI` 覆盖全部 `MONGO_*` 字段。
+
+脚本会依次验证：
+
+1. API 健康检查
+2. 注册与登录
+3. JWT 鉴权后的策略、因子、模板和数据集查询
+4. API Key 创建与列表查询
+
+成功时每一步输出 `[OK]` 并以状态码 0 结束。可通过 `API_BASE` 指定 API 地址。
+
+## 本地开发
+
+数据库仍可使用容器：
+
+```bash
+docker compose up -d mongo redis
+```
+
+后端需要 Go 1.22：
+
+```bash
+cd backend
+# 根目录 .env 支持 MONGO_HOST、MONGO_PORT、MONGO_USERNAME、
+# MONGO_PASSWORD、MONGO_DATABASE，也可用 MONGODB_URI 整体覆盖。
+go mod download
+go run ./cmd/api
+```
+
+前端使用 Vite 代理 `/api` 和 `/health` 到 `http://localhost:8080`：
+
+```bash
+cd frontend
+npm ci
+npm run dev
+```
+
+访问 http://localhost:3000。只有需要绕过 Vite/Nginx 代理时才设置 `VITE_API_BASE`。
+
+## 生产部署（Vercel + Docker）
+
+前端 = Vercel，后端 = Docker Compose；MongoDB / Redis / S3 全部使用托管服务。
+
+### 1. 准备托管服务
+
+| 服务 | 推荐 |
+|---|---|
+| MongoDB | [MongoDB Atlas](https://www.mongodb.com/atlas) Free Tier → 拿 `MONGODB_URI` |
+| Redis | [Upstash Redis](https://upstash.com/) 或 [Redis Cloud](https://redis.com/cloud/) → 拿 `REDIS_ADDR`（URL 形式含密码） |
+| 对象存储 | AWS S3 / 阿里云 OSS / Tencent COS（S3 兼容）→ 拿 `S3_*` 凭证 |
+
+### 2. 部署后端（Docker）
+
+```bash
+cp .env.example .env
+# 编辑 .env，填入 MONGODB_URI / REDIS_ADDR / JWT_SECRET / HAMUNA_MASTER_KEY /
+# S3_* / CORS_ALLOWED_ORIGINS / HAMUNA_CERT_API_BASE
+nano .env
+docker compose up -d --build
+```
+
+暴露 `8080`，前面套一层 TLS（Caddy / Nginx / Cloudflare 都可以）。验证：
+
+```bash
+curl https://api.your-domain.com/health
+```
+
+### 3. 部署前端（Vercel）
+
+- 在 Vercel New Project，**Root Directory = `frontend`**
+- Framework Preset = Vite（自动检测）
+- **Environment Variables**（Production）：
+
+  | Name | Value |
+  |---|---|
+  | `VITE_API_BASE` | `https://api.your-domain.com` |
+
+> 不要加 `/api` 后缀。Vite 代理在生产构建里被移除；`VITE_API_BASE` 直接替换 `/api/*` 的前缀。
+
+部署成功后访问 Vercel 给你的 `*.vercel.app` 域名。
+
+### 4. CORS 与回调
+
+- 后端 `CORS_ALLOWED_ORIGINS` 必须包含 Vercel 域名：`https://your-app.vercel.app,https://hamuna.vercel.app`
+- 后端 `HAMUNA_CERT_API_BASE` = `https://api.your-domain.com`（导出 QMT shell 回拨的目标）
+- 修改 `.env` 后要 `docker compose up -d --force-recreate backend` 让后端重读环境变量
+
+### 5. 升级 / 回滚
+
+- 前端：Vercel Git 集成直接 `git push` 触发
+- 后端：`git pull && docker compose up -d --build backend`
+
+### 6. 调试清单
+
+| 现象 | 检查 |
+|---|---|
+| 前端 401 / 网络失败 | 浏览器 Network 看 `/api/v1/*` 请求 URL；Vercel env `VITE_API_BASE` 是否正确（不要 `/api` 后缀） |
+| CORS 报错 | 后端 `.env` 的 `CORS_ALLOWED_ORIGINS` 含 Vercel 域名；重启 backend |
+| `/health` OK 但 `/api/v1/*` 报 502 | 后端到 Mongo/Redis 不通：`docker compose logs backend` |
+| 数据集构建失败 | `S3_*` 凭证 / 桶名 / `S3_USE_SSL=true` 是否对（托管服务一般要 SSL） |
+
+## 项目结构
+
+```text
+backend/                 Go API、JWT、API Key 与 Mongo/Redis 访问
+frontend/                Vite + React + TypeScript + Tailwind
+frontend/app/exports/    Pencil 原始 HTML 导出，仅供设计对照
+scripts/smoke.mjs        前后端 API 闭环检查
+docker-compose.yml       完整本地运行栈
+```
+
+## 已接入 API
+
+| Method | Path | 鉴权 |
+|---|---|---|
+| GET | `/health` | 公开 |
+| POST | `/api/v1/auth/register` | 公开 |
+| POST | `/api/v1/auth/login` | 公开 |
+| GET | `/api/v1/strategies` | JWT |
+| GET | `/api/v1/strategies/:id` | JWT |
+| GET | `/api/v1/factors` | JWT |
+| GET | `/api/v1/factor-templates` | JWT |
+| GET | `/api/v1/datasets` | JWT |
+| POST / GET | `/api/v1/api-keys` | JWT |
+| GET | `/api/v1/cli/whoami` | API Key |
+
+当前后端尚未开放策略创建、运行回测和 API Key 删除接口，前端不会伪造这些操作的成功状态。

hamuna_quant_cli-0.1.0.dev93/hamuna_quant_cli/README.md

@@ -0,0 +1,117 @@
+# 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/`

hamuna_quant_cli-0.1.0.dev93/hamuna_quant_cli/__init__.py

@@ -0,0 +1,17 @@
+"""hamuna_quant_cli — A 股回测 + 实盘统一 CLI (akquant 0.3.x).
+
+Pip 包名: hamuna-quant-cli
+入口命令: hamuna_quant_cli (console_script) / python -m hamuna_quant_cli
+
+子命令:
+  回测:  run / check / upload / create / parity / qmt-translate / commit / dataset
+  实盘:  live run
+
+替代 v1 自建 driver (hamuna-strategy) + QMT 风格 (init/handlebar); 上接 hamuna
+server (13-key metrics schema). 全部走 akquant 0.3.x 引擎.
+"""
+from __future__ import annotations
+
+# 版本号由 scripts/bump_version.py 每次 build 自动更新 (基于 git 提交数).
+# 格式: 0.1.0.dev<git提交数> (PEP 440). 手动改这里会被下一次 build 覆盖.
+__version__ = "0.1.0.dev93"