Enhance CLI command mode for ritmex-bot

- 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.
2026-09-09 08:18:07 +00:00 · 2026-02-27 12:40:41 +08:00
parent d6399b92aa
commit 7fdc3b6c8f
22 changed files with 3319 additions and 53 deletions
@@ -0,0 +1,389 @@
+# ritmex-bot CLI User Guide (English)
+
+This guide documents the `ritmex-bot` command mode (agent-friendly mode), which lets you run structured trading operations without entering the Ink interactive menu.
+
+## 1. Scope
+
+`ritmex-bot` CLI command mode covers:
+
+- Exchange listing and capability checks
+- Market data (`ticker` / `depth` / `kline`)
+- Account and position queries
+- Open/create/cancel/cancel-all order operations
+- Strategy execution (including dry-run)
+
+This mode is suitable for:
+
+- Manual terminal usage
+- `npx` / `bunx` invocation
+- Programmatic AI-agent workflows (recommended with `--json`)
+
+## 2. Installation and Run Modes
+
+### 2.1 Global install (recommended)
+
+```bash
+npm install -g ritmex-bot
+ritmex-bot doctor
+```
+
+### 2.2 Quick run without install
+
+```bash
+npx ritmex-bot doctor
+bunx ritmex-bot doctor
+```
+
+### 2.3 Local dependency
+
+```bash
+npm install ritmex-bot
+npx ritmex-bot doctor
+```
+
+### 2.4 Run from repository source
+
+```bash
+bun run index.ts doctor
+bun run index.ts market ticker --exchange binance --symbol BTCUSDT
+```
+
+> Note: `bin/ritmex-bot` launches the entrypoint via `bun run`, so Bun must be available in the runtime environment.
+
+## 3. Command Shape
+
+```bash
+ritmex-bot <root-command> <action> [options]
+```
+
+Supported root commands:
+
+- `help`
+- `doctor`
+- `exchange`
+- `market`
+- `account`
+- `position`
+- `order`
+- `strategy`
+
+Quick help:
+
+```bash
+ritmex-bot help
+ritmex-bot market ticker --help
+```
+
+## 4. Global Options
+
+| Option | Short | Description | Default |
+| --- | --- | --- | --- |
+| `--exchange` | `-e` | Exchange ID override | Existing env resolution |
+| `--symbol` | - | Trading symbol (pass-through) | Existing env resolution |
+| `--json` | `-j` | JSON output | `false` |
+| `--dry-run` | `-d` | Simulate write operations | `false` |
+| `--timeout` | `-t` | Timeout in milliseconds | `25000` |
+| `--help` | `-h` | Show command help | `false` |
+
+## 5. Environment Variables and Symbol Rules
+
+Command mode follows these constraints:
+
+- No new environment variables are introduced.
+- No existing environment-variable names are modified.
+- Runtime values are read directly from the current CLI environment.
+- If `--exchange` is not provided, exchange resolution follows the existing logic (for example `EXCHANGE` / `TRADE_EXCHANGE`).
+- If `--symbol` is not provided, symbol resolution follows the existing exchange-specific env logic.
+- Symbols are never normalized or rewritten by command mode.
+
+That means symbol variants such as `BTCUSDT`, `BTCUSDC`, spot/perp pairs, and venue-specific naming are fully controlled by your existing environment configuration.
+
+## 6. Command Reference
+
+### 6.1 `doctor`
+
+Checks effective exchange/symbol setup and runtime adapter capabilities.
+
+```bash
+ritmex-bot doctor
+ritmex-bot doctor --exchange binance --symbol BTCUSDT --json
+```
+
+### 6.2 `exchange`
+
+### List supported exchanges
+
+```bash
+ritmex-bot exchange list
+```
+
+### Inspect exchange capabilities
+
+```bash
+ritmex-bot exchange capabilities --exchange standx
+```
+
+If runtime adapter initialization fails, CLI falls back to static capability metadata (`source: "static"`) and includes a warning.
+
+### 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` is optional; when provided, depth levels are truncated to that value.
+
+### `market kline`
+
+```bash
+ritmex-bot market kline --exchange binance --symbol BTCUSDT --interval 1m --limit 50
+```
+
+Arguments:
+
+- `--interval` is required
+- `--limit` is optional (keeps the latest N candles)
+
+### 6.4 `account` and `position`
+
+### Account snapshot
+
+```bash
+ritmex-bot account snapshot --exchange standx
+ritmex-bot account summary --exchange standx
+```
+
+`summary` is an alias of `snapshot`.
+
+### Position list
+
+```bash
+ritmex-bot position list --exchange standx
+ritmex-bot position list --exchange standx --symbol BTC-USD
+```
+
+If `--symbol` is provided, result positions are filtered by that symbol.
+
+### 6.5 `order`
+
+### Open orders
+
+```bash
+ritmex-bot order open --exchange binance --symbol BTCUSDT
+```
+
+### Create order
+
+```bash
+ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000
+```
+
+Create-order arguments:
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--side` | Yes | `buy` / `sell` |
+| `--type` | Yes | `limit` / `market` / `stop` / `trailing-stop` / `close` |
+| `--quantity` or `--qty` | Yes | Order quantity |
+| `--price` | Required for `limit` | Limit price |
+| `--stop-price` | Required for `stop` | Stop trigger price |
+| `--activation-price` | Required for `trailing-stop` | Trailing-stop activation price |
+| `--callback-rate` | Required for `trailing-stop` | Trailing-stop callback rate |
+| `--time-in-force` | No | `GTC` / `IOC` / `FOK` / `GTX` |
+| `--reduce-only` | No | `true/false` |
+| `--close-position` | No | `true/false` |
+| `--trigger-type` | No | `UNSPECIFIED` / `TAKE_PROFIT` / `STOP_LOSS` |
+| `--sl-price` | No | Stop-loss price (router applies venue capability rules) |
+| `--tp-price` | No | Take-profit price (router applies venue capability rules) |
+
+Examples:
+
+```bash
+# Market order
+ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type market --qty 0.01
+
+# Stop order
+ritmex-bot order create --exchange binance --symbol BTCUSDT --side sell --type stop --qty 0.01 --stop-price 86000
+
+# Trailing-stop order
+ritmex-bot order create --exchange binance --symbol BTCUSDT --side sell --type trailing-stop --qty 0.01 --activation-price 91000 --callback-rate 0.2
+
+# Close intent order (defaults reduceOnly/closePosition in route layer)
+ritmex-bot order create --exchange binance --symbol BTCUSDT --side sell --type close --qty 0.01
+```
+
+### Cancel order
+
+```bash
+ritmex-bot order cancel --exchange binance --symbol BTCUSDT --order-id 123456
+```
+
+### Cancel all orders
+
+```bash
+ritmex-bot order cancel-all --exchange binance --symbol BTCUSDT
+```
+
+If `forceCancelAllOrders` is available on the adapter, CLI uses it first; otherwise it falls back to standard cancel-all behavior.
+
+### 6.6 `strategy`
+
+### Run strategy
+
+```bash
+ritmex-bot strategy run --strategy maker --exchange standx --silent
+```
+
+Supported strategy IDs:
+
+- `trend`
+- `swing`
+- `guardian`
+- `maker`
+- `maker-points`
+- `offset-maker`
+- `liquidity-maker`
+- `basis`
+- `grid`
+
+Supported aliases:
+
+- `offset` -> `offset-maker`
+- `makerpoints` / `maker_points` -> `maker-points`
+- `liquidity` / `liquiditymaker` / `liquidity_maker` -> `liquidity-maker`
+
+Extra options:
+
+- `--silent` (short form `-q`) for quieter strategy startup logs
+- `--dry-run` to propagate simulation mode into strategy execution
+
+## 7. `--dry-run` Behavior
+
+With `--dry-run` enabled:
+
+- `order create` / `order cancel` / `order cancel-all` do not send real write operations.
+- Response includes `dryRunActions` so you can inspect the simulated intent.
+- `strategy run` receives dry-run mode in the strategy runner.
+- Read-only commands (market/account/position queries) keep normal behavior.
+
+Example:
+
+```bash
+ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000 --dry-run --json
+```
+
+## 8. Unsupported Features
+
+Exchange capabilities are intentionally not forced into a fake unified surface. If a venue does not support a feature, CLI returns `UNSUPPORTED` directly.
+
+Typical cases:
+
+- Exchange does not implement `queryOpenOrders`
+- Exchange does not implement `queryAccountSnapshot`
+- Exchange-specific order type limitations
+
+Callers should handle `UNSUPPORTED` as a first-class outcome.
+
+## 9. Output and Exit Codes
+
+### 9.1 Human-readable output (default)
+
+Success:
+
+```text
+[OK] market-ticker
+time: 2026-02-27T12:00:00.000Z
+exchange: binance
+symbol: BTCUSDT
+dryRun: false
+...
+```
+
+Failure:
+
+```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 output (`--json`)
+
+Success payload:
+
+```json
+{
+  "success": true,
+  "command": "market-ticker",
+  "exchange": "binance",
+  "symbol": "BTCUSDT",
+  "dryRun": false,
+  "ts": "2026-02-27T12:00:00.000Z",
+  "data": {}
+}
+```
+
+Failure payload:
+
+```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 Exit codes
+
+| Exit Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `2` | Invalid arguments (`INVALID_ARGS`) |
+| `3` | Missing environment setup (`MISSING_ENV`) |
+| `5` | Unsupported feature (`UNSUPPORTED`) |
+| `6` | Exchange execution error (`EXCHANGE_ERROR`) |
+| `7` | Timeout (`TIMEOUT`) |
+
+## 10. Recommended AI-Agent Flow
+
+```bash
+# 1) Check venue capabilities
+ritmex-bot exchange capabilities --exchange binance --json
+
+# 2) Fetch market state
+ritmex-bot market ticker --exchange binance --symbol BTCUSDT --json
+
+# 3) Validate order parameters with dry-run
+ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000 --dry-run --json
+
+# 4) Submit live order after validation (remove --dry-run)
+ritmex-bot order create --exchange binance --symbol BTCUSDT --side buy --type limit --quantity 0.01 --price 90000 --json
+```
+
+## 11. Compatibility With Existing Features
+
+Command mode does not break existing interactive or legacy startup flows:
+
+- `bun run index.ts` still opens the Ink menu
+- `bun run index.ts --strategy trend --silent` still starts strategy directly
+- Command mode is used only when the first argument matches command roots (for example `market`, `order`, `strategy`)
+
+If you already run the project with current env variables and strategy configs, command mode can be adopted incrementally with no env-key migration.
@@ -0,0 +1,388 @@
+# 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` 命令执行路径
+
+如果你已在使用现有环境变量与策略配置，可直接增量接入命令模式，无需迁移变量名。