mirror of
https://github.com/discountry/ritmex-bot.git
synced 2026-09-09 08:18:07 +00:00
DisneyandGitHub
4014a86223
- Introduced a new command mode for `ritmex-bot`, allowing agent-friendly structured trading operations without entering the Ink interactive menu. - Updated `package.json` to include versioning and set the project as public with a new CLI entry point. - Enhanced documentation in both English and Chinese to provide comprehensive usage instructions for the new command mode. - Added a new executable script for `ritmex-bot` to facilitate command execution. - Improved error handling and command parsing for better user experience and clarity in command execution.
389 lines
9.3 KiB
Markdown
389 lines
9.3 KiB
Markdown
# ritmex-bot CLI 使用手册（中文）
|
||
|
||
本文档介绍 `ritmex-bot` 的命令模式（Agent 友好模式），用于在不进入 Ink 菜单的情况下执行结构化交易操作。
|
||
|
||
## 1. 适用范围
|
||
|
||
`ritmex-bot` CLI 命令模式覆盖以下能力：
|
||
|
||
- 交易所列表与能力查询
|
||
- 行情（ticker/depth/kline）
|
||
- 账户与仓位查询
|
||
- 订单查询、下单、撤单、全撤
|
||
- 策略启动（支持 dry-run）
|
||
|
||
这套命令适合：
|
||
|
||
- 直接在终端手动执行
|
||
- 通过 `npx` / `bunx` 调用
|
||
- 被 AI Agent / 自动化系统程序化调用（推荐配合 `--json`）
|
||
|
||
## 2. 安装与运行方式
|
||
|
||
### 2.1 全局安装（推荐）
|
||
|
||
```bash
|
||
npm install -g ritmex-bot
|
||
ritmex-bot doctor
|
||
```
|
||
|
||
### 2.2 无需安装直接运行
|
||
|
||
```bash
|
||
npx ritmex-bot doctor
|
||
bunx ritmex-bot doctor
|
||
```
|
||
|
||
### 2.3 作为项目依赖
|
||
|
||
```bash
|
||
npm install ritmex-bot
|
||
npx ritmex-bot doctor
|
||
```
|
||
|
||
### 2.4 在仓库源码中运行
|
||
|
||
```bash
|
||
bun run index.ts doctor
|
||
bun run index.ts market ticker --exchange binance --symbol BTCUSDT
|
||
```
|
||
|
||
> 注意：`bin/ritmex-bot` 会调用 `bun run` 启动入口文件，因此运行环境需要可用的 Bun。
|
||
|
||
## 3. 命令结构
|
||
|
||
```bash
|
||
ritmex-bot <root-command> <action> [options]
|
||
```
|
||
|
||
支持的根命令：
|
||
|
||
- `help`
|
||
- `doctor`
|
||
- `exchange`
|
||
- `market`
|
||
- `account`
|
||
- `position`
|
||
- `order`
|
||
- `strategy`
|
||
|
||
快速帮助：
|
||
|
||
```bash
|
||
ritmex-bot help
|
||
ritmex-bot market ticker --help
|
||
```
|
||
|
||
## 4. 全局参数
|
||
|
||
| 参数 | 短参数 | 说明 | 默认值 |
|
||
| --- | --- | --- | --- |
|
||
| `--exchange` | `-e` | 指定交易所 ID | 走现有环境变量解析 |
|
||
| `--symbol` | - | 指定交易对，原样透传 | 走现有环境变量解析 |
|
||
| `--json` | `-j` | 以 JSON 输出结果 | `false` |
|
||
| `--dry-run` | `-d` | 模拟执行（不发真实写操作） | `false` |
|
||
| `--timeout` | `-t` | 超时毫秒数 | `25000` |
|
||
| `--help` | `-h` | 显示命令帮助 | `false` |
|
||
|
||
## 5. 环境变量与 Symbol 规则
|
||
|
||
`ritmex-bot` 命令模式遵循以下约束：
|
||
|
||
- 不新增环境变量，不修改任何已有变量名称。
|
||
- 从当前 CLI 执行环境读取已有配置（例如 `.env` 已加载到进程环境后）。
|
||
- `--exchange` 未指定时，按现有逻辑解析交易所（例如 `EXCHANGE` / `TRADE_EXCHANGE`）。
|
||
- `--symbol` 未指定时，按现有逻辑从对应交易所配置中解析符号。
|
||
- 对 `symbol` 不做统一、不做改写、不做跨交易所映射。你传什么就用什么。
|
||
|
||
这意味着像 Binance 的 `BTCUSDT`、`BTCUSDC`、现货/永续等差异，全部由你通过现有配置自行决定。
|
||
|
||
## 6. 命令详解
|
||
|
||
### 6.1 `doctor`
|
||
|
||
用于检查当前交易所/交易对配置与适配器能力。
|
||
|
||
```bash
|
||
ritmex-bot doctor
|
||
ritmex-bot doctor --exchange binance --symbol BTCUSDT --json
|
||
```
|
||
|
||
### 6.2 `exchange`
|
||
|
||
### 列出支持的交易所
|
||
|
||
```bash
|
||
ritmex-bot exchange list
|
||
```
|
||
|
||
### 查询交易所能力
|
||
|
||
```bash
|
||
ritmex-bot exchange capabilities --exchange standx
|
||
```
|
||
|
||
如果运行时无法构建适配器，会返回静态能力信息（`source: "static"`）及警告。
|
||
|
||
### 6.3 `market`
|
||
|
||
### `market ticker`
|
||
|
||
```bash
|
||
ritmex-bot market ticker --exchange binance --symbol BTCUSDT
|
||
```
|
||
|
||
### `market depth`
|
||
|
||
```bash
|
||
ritmex-bot market depth --exchange binance --symbol BTCUSDT --levels 10
|
||
```
|
||
|
||
`--levels` 为可选，指定后会截断返回档位数量。
|
||
|
||
### `market kline`
|
||
|
||
```bash
|
||
ritmex-bot market kline --exchange binance --symbol BTCUSDT --interval 1m --limit 50
|
||
```
|
||
|
||
参数说明：
|
||
|
||
- `--interval` 必填
|
||
- `--limit` 可选（仅保留最后 N 条）
|
||
|
||
### 6.4 `account` 与 `position`
|
||
|
||
### 账户快照
|
||
|
||
```bash
|
||
ritmex-bot account snapshot --exchange standx
|
||
ritmex-bot account summary --exchange standx
|
||
```
|
||
|
||
`summary` 是 `snapshot` 的别名。
|
||
|
||
### 仓位列表
|
||
|
||
```bash
|
||
ritmex-bot position list --exchange standx
|
||
ritmex-bot position list --exchange standx --symbol BTC-USD
|
||
```
|
||
|
||
传 `--symbol` 时会在返回结果中做符号过滤。
|
||
|
||
### 6.5 `order`
|
||
|
||
### 查询当前挂单
|
||
|
||
```bash
|
||
ritmex-bot order open --exchange binance --symbol BTCUSDT
|
||
```
|
||
|
||
### 创建订单
|
||
|
||
```bash
|
||
ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000
|
||
```
|
||
|
||
创建订单参数：
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `--side` | 是 | `buy` / `sell` |
|
||
| `--type` | 是 | `limit` / `market` / `stop` / `trailing-stop` / `close` |
|
||
| `--quantity` 或 `--qty` | 是 | 下单数量 |
|
||
| `--price` | `limit` 必填 | 限价单价格 |
|
||
| `--stop-price` | `stop` 必填 | 触发价 |
|
||
| `--activation-price` | `trailing-stop` 必填 | 激活价 |
|
||
| `--callback-rate` | `trailing-stop` 必填 | 回调比例 |
|
||
| `--time-in-force` | 否 | `GTC` / `IOC` / `FOK` / `GTX` |
|
||
| `--reduce-only` | 否 | `true/false` |
|
||
| `--close-position` | 否 | `true/false` |
|
||
| `--trigger-type` | 否 | `UNSPECIFIED` / `TAKE_PROFIT` / `STOP_LOSS` |
|
||
| `--sl-price` | 否 | 止损价（路由层按交易所能力处理） |
|
||
| `--tp-price` | 否 | 止盈价（路由层按交易所能力处理） |
|
||
|
||
示例：
|
||
|
||
```bash
|
||
# 市价单
|
||
ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type market --qty 0.01
|
||
|
||
# 止损单
|
||
ritmex-bot order create --exchange binance --symbol BTCUSDT --side sell --type stop --qty 0.01 --stop-price 86000
|
||
|
||
# 移动止损单
|
||
ritmex-bot order create --exchange binance --symbol BTCUSDT --side sell --type trailing-stop --qty 0.01 --activation-price 91000 --callback-rate 0.2
|
||
|
||
# close 语义单（默认会补全 reduceOnly/closePosition）
|
||
ritmex-bot order create --exchange binance --symbol BTCUSDT --side sell --type close --qty 0.01
|
||
```
|
||
|
||
### 撤单
|
||
|
||
```bash
|
||
ritmex-bot order cancel --exchange binance --symbol BTCUSDT --order-id 123456
|
||
```
|
||
|
||
### 全撤
|
||
|
||
```bash
|
||
ritmex-bot order cancel-all --exchange binance --symbol BTCUSDT
|
||
```
|
||
|
||
若交易所支持 `forceCancelAllOrders`，会优先走该能力；否则回退普通批量撤单逻辑。
|
||
|
||
### 6.6 `strategy`
|
||
|
||
### 启动策略
|
||
|
||
```bash
|
||
ritmex-bot strategy run --strategy maker --exchange standx --silent
|
||
```
|
||
|
||
支持策略 ID：
|
||
|
||
- `trend`
|
||
- `swing`
|
||
- `guardian`
|
||
- `maker`
|
||
- `maker-points`
|
||
- `offset-maker`
|
||
- `liquidity-maker`
|
||
- `basis`
|
||
- `grid`
|
||
|
||
常用别名：
|
||
|
||
- `offset` -> `offset-maker`
|
||
- `makerpoints` / `maker_points` -> `maker-points`
|
||
- `liquidity` / `liquiditymaker` / `liquidity_maker` -> `liquidity-maker`
|
||
|
||
额外参数：
|
||
|
||
- `--silent`（短参数 `-q`）静默运行
|
||
- `--dry-run` 传递到策略运行器，启用策略级模拟
|
||
|
||
## 7. `--dry-run` 模拟执行
|
||
|
||
当开启 `--dry-run`：
|
||
|
||
- `order create` / `order cancel` / `order cancel-all` 不会发送真实写操作。
|
||
- 返回结果包含 `dryRunActions`，用于观察本次模拟会执行什么操作。
|
||
- `strategy run` 会将 dry-run 模式传入策略执行链路。
|
||
- 只读类命令（行情、查询）不会改变行为。
|
||
|
||
示例：
|
||
|
||
```bash
|
||
ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000 --dry-run --json
|
||
```
|
||
|
||
## 8. 不支持能力的处理
|
||
|
||
不同交易所能力不完全一致。对于未实现或不支持的功能，CLI 会直接返回 `UNSUPPORTED` 错误，而不是静默忽略。
|
||
|
||
常见场景：
|
||
|
||
- 某些交易所不支持 `queryOpenOrders`
|
||
- 某些交易所不支持 `queryAccountSnapshot`
|
||
- 某些交易所不支持特定委托类型
|
||
|
||
建议调用方按错误码降级处理。
|
||
|
||
## 9. 输出格式与退出码
|
||
|
||
### 9.1 文本输出（默认）
|
||
|
||
成功：
|
||
|
||
```text
|
||
[OK] market-ticker
|
||
time: 2026-02-27T12:00:00.000Z
|
||
exchange: binance
|
||
symbol: BTCUSDT
|
||
dryRun: false
|
||
...
|
||
```
|
||
|
||
失败：
|
||
|
||
```text
|
||
[ERROR] order-open
|
||
time: 2026-02-27T12:00:00.000Z
|
||
code: UNSUPPORTED
|
||
message: queryOpenOrders is not supported on exchange 'aster'
|
||
retryable: false
|
||
```
|
||
|
||
### 9.2 JSON 输出（`--json`）
|
||
|
||
成功结构：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"command": "market-ticker",
|
||
"exchange": "binance",
|
||
"symbol": "BTCUSDT",
|
||
"dryRun": false,
|
||
"ts": "2026-02-27T12:00:00.000Z",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
失败结构：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"command": "order-open",
|
||
"exchange": "aster",
|
||
"symbol": "BTCUSDT",
|
||
"dryRun": false,
|
||
"ts": "2026-02-27T12:00:00.000Z",
|
||
"error": {
|
||
"code": "UNSUPPORTED",
|
||
"message": "queryOpenOrders is not supported on exchange 'aster'",
|
||
"retryable": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 9.3 退出码
|
||
|
||
| 退出码 | 含义 |
|
||
| --- | --- |
|
||
| `0` | 成功 |
|
||
| `2` | 参数错误（`INVALID_ARGS`） |
|
||
| `3` | 缺少环境配置（`MISSING_ENV`） |
|
||
| `5` | 功能不支持（`UNSUPPORTED`） |
|
||
| `6` | 交易所执行错误（`EXCHANGE_ERROR`） |
|
||
| `7` | 超时（`TIMEOUT`） |
|
||
|
||
## 10. AI Agent 推荐调用流程
|
||
|
||
```bash
|
||
# 1) 确认交易所能力
|
||
ritmex-bot exchange capabilities --exchange binance --json
|
||
|
||
# 2) 拉取行情
|
||
ritmex-bot market ticker --exchange binance --symbol BTCUSDT --json
|
||
|
||
# 3) dry-run 验证下单参数
|
||
ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000 --dry-run --json
|
||
|
||
# 4) 确认后执行真实下单（去掉 --dry-run）
|
||
ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000 --json
|
||
```
|
||
|
||
## 11. 与现有功能兼容性
|
||
|
||
命令模式不会破坏现有 Ink 交互模式与原有参数入口：
|
||
|
||
- `bun run index.ts` 仍进入交互菜单
|
||
- `bun run index.ts --strategy trend --silent` 仍可直接跑策略
|
||
- 仅当首参数匹配命令模式根命令时，才进入 `ritmex-bot` 命令执行路径
|
||
|
||
如果你已在使用现有环境变量与策略配置，可直接增量接入命令模式，无需迁移变量名。
|