@vibek/cli 0.1.0

package/.env.example

@@ -0,0 +1,9 @@
+# Vibek 的持久配置位于平台配置目录中的 config.toml：
+#   Linux/macOS: ~/.config/vibek/config.toml
+#   Windows:     %APPDATA%\vibek\config.toml
+#
+# 仅在需要使用另一份配置文件（例如隔离的开发实例）时设置：
+# VIBEK_CONFIG_PATH=D:/path/to/config.toml
+#
+# VIBEK_PASS 与 VIBEK_AUTH_CODE 由 `vibek daemon start/restart` 每次交互输入，
+# 不要写入 .env 或 config.toml。其他 VIBEK_* 变量仅供内部测试和子进程使用。

package/README.md

@@ -0,0 +1,210 @@
+# Vibek CLI 用户指南
+
+Vibek 是一个面向个人的 CTP 量化交易工具，提供后台行情与交易服务、策略管理、离线回测，
+以及浏览器中的 AI 策略工作台。npm 包安装后注册全局命令 `vibek`。
+
+> Vibek 会连接真实期货账户。首次使用请保持 `live_enabled = false`，先完成配置校验、
+> Paper 模式运行和风险参数检查，再考虑启用实盘。
+
+## 运行环境
+
+- [Bun](https://bun.sh/) 1.4.0 或更高版本
+- Windows x64，或 Ubuntu 24.04 x86_64
+- 可用的 CTP 账号、行情/交易前置地址和 App ID
+- 使用 Web 工作台时需要本机浏览器
+
+原生 CTP gateway 不包含在 npm 包中。Vibek 会通过 `vibek gateway` 下载并校验与当前应用兼容的版本。
+
+## 安装
+
+```bash
+bun install -g @vibek/cli
+vibek --version
+```
+
+如果终端找不到 `vibek`，请确认 Bun 的全局 bin 目录 `~/.bun/bin` 已加入 `PATH`。
+
+## 快速开始
+
+### 1. 生成配置
+
+Windows PowerShell：
+
+```powershell
+New-Item -ItemType Directory -Force "$env:APPDATA\vibek" | Out-Null
+vibek --default-config | Set-Content -Encoding UTF8 "$env:APPDATA\vibek\config.toml"
+notepad "$env:APPDATA\vibek\config.toml"
+```
+
+Linux：
+
+```bash
+mkdir -p ~/.config/vibek
+vibek --default-config > ~/.config/vibek/config.toml
+${EDITOR:-vi} ~/.config/vibek/config.toml
+```
+
+填写账号时，账号表名必须是 `<broker_id>-<user>`。下面是一份最小起步配置：
+
+```toml
+version = 1
+active_account = "9999-account"
+
+[accounts."9999-account".identity]
+broker_id = "9999"
+user = "account"
+
+[accounts."9999-account".ctp]
+market_front = "tcp://行情前置地址:端口"
+trader_front = "tcp://交易前置地址:端口"
+app_id = "你的-app-id"
+production_mode = true
+
+[accounts."9999-account".trading]
+live_enabled = false
+max_order_volume = 1
+max_position = 2
+max_active_orders = 2
+allow_short = true
+```
+
+`production_mode` 选择 CTP API 的生产/评测模式；它不等于允许实盘交易。
+`live_enabled` 是独立的实盘总闸，默认应保持关闭。
+
+### 2. 校验配置
+
+```bash
+vibek config
+vibek account current
+```
+
+配置有未知字段、类型错误、账号引用错误或风控值越界时，`vibek config` 会直接指出问题。
+
+### 3. 安装 CTP gateway
+
+```bash
+vibek gateway
+```
+
+该命令会安装或校验当前应用兼容的最新稳定 gateway。也可以安装明确版本或本地归档：
+
+```bash
+vibek gateway 0.1.0
+vibek gateway ./gateway.tar.gz
+```
+
+### 4. 启动后台服务
+
+```bash
+vibek daemon start
+vibek status
+```
+
+`daemon start` 会在终端中询问交易密码和 CTP 授权码。这些凭证只传给本次后台进程，
+不会写入 `config.toml`。查看运行状态和日志：
+
+```bash
+vibek daemon status
+vibek daemon logs --follow
+vibek daemon stop
+```
+
+### 5. 打开 Web 工作台
+
+```bash
+vibek
+```
+
+无参数运行等价于 `vibek web`。命令会启动本机 Web 工作台并打印浏览器地址；默认端口为 `3211`：
+
+```bash
+vibek web --port 3211
+```
+
+Web 工作台本身不会自动启动交易 daemon。需要行情、账户或策略运行能力时，请先执行
+`vibek daemon start`。
+
+## 常用命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `vibek status` | 汇总账号、daemon、行情、交易连接和策略状态 |
+| `vibek account list` | 列出本机配置的账号 |
+| `vibek account use <名称>` | 切换当前账号 |
+| `vibek account show` | 查询当前柜台资金 |
+| `vibek positions` | 查询实时持仓 |
+| `vibek orders` | 查询当前交易日委托 |
+| `vibek trades` | 查询当前交易日成交 |
+| `vibek contract <合约>` | 查询合约规格和当前账户手续费率 |
+| `vibek front test` | 测试候选 CTP 前置并按稳定性、延迟排名 |
+| `vibek front check` | 检查当前行情和交易前置 |
+| `vibek daemon restart` | 重新输入凭证并重启后台服务 |
+
+查询命令默认输出终端表格。需要脚本消费时可添加全局 `--json`：
+
+```bash
+vibek positions --json
+vibek --json status
+```
+
+## 策略与回测
+
+先在 Paper 模式加载策略：
+
+```bash
+vibek strategy load ./my-strategy.ts --mode paper
+vibek strategy list
+vibek strategy start <策略实例ID>
+```
+
+停止或卸载策略：
+
+```bash
+vibek strategy stop <策略实例ID>
+vibek strategy unload <策略实例ID>
+```
+
+离线回测接受 mock 或 CSV 数据，并要求明确提供合约乘数、保证金和手续费参数：
+
+```bash
+vibek backtest ./my-strategy.ts --help
+```
+
+Live 模式必须显式使用 `--mode live`，并同时通过账号配置中的 `live_enabled`、委托限制和持仓核对。
+不要用尚未在 Paper 和回测中验证的策略直接连接实盘。
+
+## 配置和数据位置
+
+| 内容 | Windows | Linux |
+| --- | --- | --- |
+| 配置文件 | `%APPDATA%\vibek\config.toml` | `~/.config/vibek/config.toml` |
+| 默认数据根 | `%USERPROFILE%\.vibek` | `~/.vibek` |
+| 账号数据 | `<数据根>\accounts\<账号>` | `<数据根>/accounts/<账号>` |
+
+可在配置的 `[storage]` 中修改 `data_root`。数据库、日志、策略产物和 gateway 都位于数据根目录，
+不会写入 npm 包安装目录。
+
+## 升级与回退
+
+实盘机器建议安装明确版本，不要自动跟随 `latest`：
+
+```bash
+bun install -g @vibek/cli@0.1.0
+vibek --version
+vibek gateway
+vibek daemon restart
+```
+
+回退时安装旧的 npm 版本，再用 `vibek gateway <version>` 激活对应 gateway，最后重启 daemon。
+
+## 排查问题
+
+```bash
+vibek config                # 检查配置文件和当前账号
+vibek gateway               # 校验 gateway 安装
+vibek front check           # 检查 CTP 网络连通性
+vibek daemon status         # 检查后台进程
+vibek daemon logs --follow  # 查看运行日志
+vibek --help                # 查看全部命令
+vibek help <command>        # 查看某个命令的帮助
+```

package/config.example.toml

@@ -0,0 +1,58 @@
+# Vibek configuration
+# 复制到平台配置目录，或运行 `vibek --default-config` 输出同等模板。
+# 修改后运行 `vibek config` 校验；daemon 配置重启后生效。
+version = 1
+
+# active_account = "9999-account"
+
+[storage]
+# data_root = "~/.vibek"
+
+[server]
+# daemon_port = 3111
+# webui_port = 3211
+
+[network]
+# telegram_proxy = "http://127.0.0.1:7890"
+
+# [accounts."9999-account".identity]
+# broker_id = "9999"
+# user = "account"
+
+# [accounts."9999-account".ctp]
+# market_front = "tcp://host:port"
+# trader_front = "tcp://host:port"
+# front_candidates = ["主线@1.2.3.4", "备用@1.2.3.5"]
+# app_id = "client-id"
+# production_mode = true
+
+# [accounts."9999-account".logging]
+# level = "info" # trace | debug | info | warn | error
+
+# [accounts."9999-account".market]
+# db_path = ""
+# record_instruments = ["NI2609.SHFE", "IF2609.CFFEX"]
+# max_future_tick_ms = 5000
+
+# [accounts."9999-account".trading]
+# live_enabled = false
+# max_order_volume = 10
+# max_position = 20
+# max_active_orders = 5
+# allow_short = true
+
+# [accounts."9999-account".schedule]
+# enabled = true
+# day_start = "08:45"
+# day_stop = "15:15"
+# night_start = "20:45"
+# night_stop = "02:35"
+# max_start_attempts = 4
+# retry_base_ms = 30000
+# tick_ms = 30000
+
+# [accounts."9999-account".notifications]
+# bark_key = ""
+# bark_signal_keys = []
+# telegram_bot_token = ""
+# telegram_chat_id = ""