BigQuant bq CLI 使用文档

由small_q创建，最终由small_q更新于2026-04-27 08:54 被浏览 4 用户

bq 是 BigQuant SDK 提供的命令行工具，安装 SDK 后自动可用。它涵盖认证管理、数据查询、策略监控、云端计算等功能，适合在终端、脚本和 AI Agent 中使用。

安装与验证
全局选项
auth — 认证管理
config — 配置管理
dai — 数据查询
strategy — 策略管理
aistudio — 云端计算（暂未开放）
marketdata — 行情数据
fileorder — 文件单管理
pkg — 依赖包管理
module — 模块管理
audit — 审计日志
输出格式控制
AI Agent 使用指南

1. 安装与验证

# 安装 SDK（包含 bq 命令）
pip install bigquant -i https://pypi.bigquant.com/simple/

# 验证安装
bq --version

# 查看帮助
bq --help

如果 bq 命令找不到，将 Python Scripts 目录加入 PATH：

# macOS / Linux
export PATH="$HOME/.local/bin:$PATH"

# Windows PowerShell
$env:PATH += ";$env:APPDATA\Python\Python311\Scripts"

2. 全局选项

所有命令都支持以下全局选项：

选项	说明
`--version`	显示版本号
`--help`	显示帮助信息
`--format`, `-f`	输出格式：`markdown`/`md`（默认）、`table`

--format 可以放在子命令前或后：

bq --format markdown dai query "SELECT ..."
bq dai query "SELECT ..." --format table

3. auth — 认证管理

3.1 配置 AK/SK（推荐）

方式一：直接传入

bq auth --apikey AK.SK

将 AK.SK 替换为您在 BigQuant 平台获取的凭证。

方式二：交互式输入（更安全，输入不回显）

bq auth configure
# 提示：请输入 AK.SK（输入时不显示）

3.2 用户名密码登录

bq auth login -u 用户名 -p 密码

# 或者交互式（不传参数会提示输入）
bq auth login

3.3 查看当前登录状态

bq auth status

输出示例：

|--------|--------------------------------------|
| 用户名 | shkey                                |
| ID     | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| Email  | N/A                                  |

3.4 退出登录

bq auth logout

4. config — 配置管理

配置文件位于 ~/.bigquant/config.json，存储认证信息和其他设置。

4.1 查看配置目录

bq config dir
# 输出：/Users/yourname/.bigquant

4.2 查看完整配置

bq config show

4.3 读取指定配置项

# 支持 dotted key 格式
bq config get auth.ak
bq config get telemetry.enabled
bq config get audit

4.4 设置配置项

# 字符串值
bq config set some.key some_value

# 布尔值（自动转换）
bq config set telemetry.enabled false

# 数值（自动转换）
bq config set audit.retention_days 30

注意：修改 auth.ak、auth.sk、auth.token 等敏感凭证时，建议使用 bq auth configure 代替 bq config set。

配置文件结构

{
  "auth": {
    "ak": "YOUR_AK",
    "sk": "YOUR_SK"
  },
  "telemetry": {
    "enabled": true
  },
  "audit": {
    "enabled": true,
    "retention_days": 90
  }
}

5. dai — 数据查询

5.1 执行 SQL 查询

bq dai query "SQL语句" [选项]

选项：

选项	默认值	说明
`--filters`	无	分区过滤，JSON 格式
`--full-db-scan`	`false`	允许全表扫描
`--limit`	`20`	最多显示行数，`0` 表示不限制
`--output`, `-o`	无	保存到文件（`.csv`/`.parquet`/`.json`）

示例：

# 基础查询（带 filters 避免全表扫描）
bq dai query "SELECT * FROM cn_stock_bar1d LIMIT 10" \
  --filters '{"date": ["2024-01-01", "2024-12-31"]}'

# 全表扫描（小表或有 LIMIT 时可用）
bq dai query "SELECT * FROM cn_stock_bar1d ORDER BY close DESC LIMIT 10" \
  --full-db-scan

# 显示更多行
bq dai query "SELECT date, instrument, close FROM cn_stock_bar1d LIMIT 50" \
  --filters '{"date": ["2024-01-01", "2024-01-31"]}' \
  --limit 50

# 保存结果到文件
bq dai query "SELECT * FROM cn_stock_bar1d" \
  --filters '{"date": ["2024-01-01", "2024-01-31"]}' \
  --output result.csv

# 保存为 Parquet（推荐大数据）
bq dai query "SELECT * FROM cn_stock_bar1d" \
  --filters '{"date": ["2024-01-01", "2024-03-31"]}' \
  --output result.parquet

5.2 预览数据表前 N 行

bq dai head cn_stock_bar1d
bq dai head cn_stock_bar1d --limit 5

5.3 查看数据表字段 schema

bq dai schema cn_stock_bar1d

输出示例：

cn_stock_bar1d  股票日线行情
┌──────────────┬──────────┬──────────────┬──────┐
│ 字段名        │ 类型     │ 描述         │ 主键 │
├──────────────┼──────────┼──────────────┼──────┤
│ date         │ string   │ 交易日期     │ 是   │
│ instrument   │ string   │ 标的代码     │ 是   │
│ open         │ float64  │ 开盘价       │ 否   │
│ close        │ float64  │ 收盘价       │ 否   │
│ ...          │ ...      │ ...          │ ...  │
└──────────────┴──────────┴──────────────┴──────┘
共 N 个字段

5.4 查看数据表详细文档

bq dai doc cn_stock_bar1d

5.5 查看数据表使用示例

bq dai example cn_stock_bar1d

5.6 查看数据表更新记录

bq dai updates cn_stock_bar1d
bq dai updates cn_stock_bar1d --size 50

5.7 搜索数据表

# 关键词搜索（支持中文）
bq dai search 股票日线

# 按分类过滤
bq dai search cn_stock --category /金融数据/股票

# 获取全部结果（自动翻页）
bq dai search cn_stock --all

# 指定每页数量
bq dai search bar1d --size 50

5.8 列出 DataSource

# 列出自己创建的（默认）
bq dai list

# 列出订阅的
bq dai list --scope subscribed

# 列出平台上架的
bq dai list --scope space --size 50

# 列出全部（自建 + 订阅 + 平台）
bq dai list --scope all

# 按分类过滤
bq dai list --category /我的数据/股票

6. strategy — 策略管理

6.1 列出策略

bq strategy list
bq strategy list --page 2 --size 20

输出示例：

┌──────────────────┬──────────────┬────────┬──────┬──────────────┬──────────────┐
│ ID               │ 名称         │ 状态   │ 频率 │ 创建时间     │ 最近运行     │
├──────────────────┼──────────────┼────────┼──────┼──────────────┼──────────────┤
│ abc123...        │ 我的策略     │ 运行中 │ 日频 │ 2024-01-01   │ 2024-12-31   │
└──────────────────┴──────────────┴────────┴──────┴──────────────┴──────────────┘
共 1 条策略

6.2 查看策略详情

bq strategy show <strategy_id>

6.3 查看策略持仓

bq strategy positions <strategy_id>

输出最新交易日的持仓，包含标的、方向、持仓量、成本价、最新价、市值、盈亏、收益率。

6.4 查看策略订单

bq strategy orders <strategy_id>

输出最新交易日的已成交订单。

6.5 查看待交易信号

bq strategy signals <strategy_id>

输出最新交易日的计划订单（待执行信号）。

6.6 查看策略绩效

bq strategy performance <strategy_id>

输出示例：

交易日      2024-12-31
累计收益    15.2300%
年化收益    12.5000%
最大回撤    -8.3400%
夏普比率    1.23
胜率        58.00%
总市值      1152300.00

7. aistudio — 云端计算

暂未开放：aistudio 子命令正在开发中，暂不可用。

7.1 列出资源规格

bq aistudio list
bq aistudio list --space-id <space_id>

输出示例：

┌──────────────────────────────────┬──────────────┬─────┬──────────┬─────┬────────────┐
│ ID                               │ 名称         │ CPU │ 内存(GB) │ GPU │ 价格(BQC/分)│
├──────────────────────────────────┼──────────────┼─────┼──────────┼─────┼────────────┤
│ 3fa85f64-5717-4562-b3fc-...      │ D0(1C/6G)    │ 1   │ 6        │ 0   │ 0          │
│ ...                              │ D1(4C/16G)   │ 4   │ 16       │ 0   │ 0.5        │
└──────────────────────────────────┴──────────────┴─────┴──────────┴─────┴────────────┘

7.2 在云端运行脚本

# 运行 Python 脚本（需要绝对路径）
bq aistudio run --file /absolute/path/to/script.py

# 运行 Jupyter Notebook
bq aistudio run --file /absolute/path/to/notebook.ipynb

# 指定超时时间（秒）
bq aistudio run --file /path/to/script.py --timeout 600

# 指定资源规格
bq aistudio run --file /path/to/script.py --resource-spec-id <spec_id>

# 显示详细输出
bq aistudio run --file /path/to/script.py --verbose

注意：文件路径必须是绝对路径。

8. marketdata — 行情数据

8.1 查询 K 线数据

bq marketdata bars <标的代码> --start-date <开始日期> --end-date <结束日期> [选项]

选项：

选项	默认值	说明
`--start-date`, `-s`	必填	开始日期，格式 `YYYY-MM-DD`
`--end-date`, `-e`	必填	结束日期，格式 `YYYY-MM-DD`，日期范围不能超过 30 天
`--period`	`1d`	K 线周期：`1d`（日线）、`1m`（分钟线）
`--asset-type`	`stock`	资产类型：`stock`/`index`/`fund`/`cbond`/`future`/`option`
`--columns`	全部	字段筛选（可多次指定）：`open`/`high`/`low`/`close`/`volume`/`amount`

示例：

# 查询平安银行日线数据（日期范围不超过 30 天）
bq marketdata bars 000001.SZ --start-date 2025-01-01 --end-date 2025-01-30

# 查询分钟线
bq marketdata bars 000001.SZ -s 2025-01-02 -e 2025-01-02 --period 1m

# 只看收盘价和成交量
bq marketdata bars 000001.SZ -s 2025-01-01 -e 2025-01-30 \
  --columns close --columns volume

# 查询指数
bq marketdata bars 000300.SH -s 2025-01-01 -e 2025-01-30 --asset-type index

注意：单次查询日期范围不能超过 30 天，否则返回 400 错误。如需更长时间段，请分批查询。

9. fileorder — 文件单管理

BigTrader 交易终端通过文件单目录与外部系统交互。bq fileorder 提供报单、撤单、查询持仓/资金/委托/成交的完整命令集。

所有子命令均需 --file-dir（文件单目录路径）参数。

9.1 报单

bq fileorder order \
  --file-dir /path/to/file_order \
  --account-id 123456789 \
  --instrument 000001.SZ \
  --direction buy \
  --quantity 200 \
  --price 10.50

选项：

选项	说明
`--file-dir`	文件单目录路径（必填）
`--account-id`	资金账号（必填）
`--instrument`	交易标的，如 `000001.SZ`
`--direction`	买卖方向：`buy` / `sell`
`--quantity`	委托数量
`--price`	委托价格（不填则为市价单）
`--offset`	开平标志：`none`/`open`/`close`/`closetoday`/`closeyesterday`（默认 `none`）
`--order-type`	订单类型：`limit` / `market`（默认由价格自动判断）
`--trading-day`	交易日，格式 `YYYYmmdd`（可选）
`--strategy-id`	策略标识（可选，需小于 16 字节）
`--input`, `-i`	JSON 文件路径，也支持 stdin pipe 输入
`--staging`	写入临时目录，之后用 `apply` 提交

也支持 JSON 输入方式：

# 从文件读取
bq fileorder order --file-dir /path/to/file_order --account-id 123 --input order.json

# 从 stdin pipe
echo '{"instrument":"000001.SZ","direction":"buy","quantity":200}' | \
  bq fileorder order --file-dir /path/to/file_order --account-id 123

9.2 批量报单

原子写入，全部成功或全部不写入：

bq fileorder batch-order \
  --file-dir /path/to/file_order \
  --account-id 123456789 \
  --input orders.json

JSON 格式为数组：

[
  {"instrument": "000001.SZ", "direction": "buy", "quantity": 200, "price": 10.5},
  {"instrument": "600900.SH", "direction": "sell", "quantity": 100}
]

也支持 stdin pipe：

echo '[{"instrument":"000001.SZ","direction":"buy","quantity":200}]' | \
  bq fileorder batch-order --file-dir /path/to/file_order --account-id 123

9.3 撤单

# 按 order-sysid 撤单
bq fileorder cancel \
  --file-dir /path/to/file_order \
  --account-id 123456789 \
  --instrument 000001.SZ \
  --order-sysid 456

# 按 order-key 撤单
bq fileorder cancel \
  --file-dir /path/to/file_order \
  --account-id 123456789 \
  --instrument 000001.SZ \
  --order-key 1_0_0

# 撤销所有挂单
bq fileorder cancel --file-dir /path/to/file_order --account-id 123456789 --all

# 撤销指定标的所有挂单
bq fileorder cancel --file-dir /path/to/file_order --account-id 123456789 --all --instrument 000001.SZ

--order-sysid 和 --order-key 可从 bq fileorder orders 查看委托数据获取。

9.4 提交文件单（apply）

将 --staging 写入的临时目录文件移动到目标目录，交由交易终端执行：

bq fileorder apply --file-dir /path/to/file_order

推荐工作流：先用 --staging 预览，确认后再 apply 提交。

9.5 查询账户资金

bq fileorder fund --file-dir /path/to/file_order

读取并展示 fund_data.txt（账户资金）。

9.6 查询持仓

bq fileorder position --file-dir /path/to/file_order

读取并展示 position_data.txt（账户持仓）。

9.7 查询当日委托

bq fileorder orders --file-dir /path/to/file_order

读取并展示 order_data.txt（当日委托），包含 order_key 字段，可用于撤单。

9.8 查询当日成交

bq fileorder trades --file-dir /path/to/file_order

读取并展示 trade_data.txt（当日成交）。

10. pkg — 依赖包管理

管理 BigQuant 编译依赖包（如 bigtradercpp）。

10.1 查看已安装包

bq pkg list

输出包含包名、版本约束、已安装版本、最新版本、状态、描述。

10.2 安装包

# 安装全部未安装的包
bq pkg install

# 安装指定包
bq pkg install bigtradercpp

# 安装指定版本
bq pkg install bigtradercpp==1.2.3
bq pkg install "bigtradercpp>=1.0.0,<2.0.0"

# 显示安装日志
bq pkg install bigtradercpp --verbose

10.3 升级包

# 升级全部
bq pkg upgrade

# 升级指定包
bq pkg upgrade bigtradercpp

10.4 卸载包

# 卸载指定包
bq pkg uninstall bigtradercpp

# 卸载全部（需确认）
bq pkg uninstall all

# 跳过确认
bq pkg uninstall all --yes

11. module — 模块管理

管理 BigQuant 自定义模块（策略模块开发）。

11.1 创建新模块

bq module init my_module
bq module init my_module -o /path/to/output

从模板创建模块目录结构，需要先安装 copier：

pip install 'copier>=9.0.0'

11.2 安装模块

# 正式安装
bq module install

# 开发模式安装（创建符号链接，修改即生效）
bq module install --dev

# 指定模块路径
bq module install --path /path/to/module

11.3 卸载模块

bq module uninstall --dev
bq module uninstall --dev --name my_module

11.4 发布模块

bq module publish
bq module publish --path /path/to/module

12. audit — 审计日志

bq 会自动记录所有命令的执行日志，audit 子命令用于查询和管理这些日志。

12.1 查看审计日志

# 查看最近 20 条（默认）
bq audit list

# 查看最近 50 条
bq audit list --last 50

# 查看指定日期的日志
bq audit list --date 2026-03-20

# 按命令名过滤
bq audit list --command fileorder

# 只显示失败的命令
bq audit list --errors

12.2 查看日志存储目录

bq audit path

12.3 清理过期日志

# 按配置的 retention_days 清理
bq audit clean

# 保留最近 30 天
bq audit clean --days 30

日志默认按日自动滚动，clean 用于手动按需清理。

13. 输出格式控制

bq 支持两种输出格式，通过 --format（或 -f）控制：

格式	说明	适用场景
`markdown`/`md`（默认）	原始 Markdown 文本，无 Rich 渲染，无颜色	脚本解析、管道处理、AI Agent
`table`	Rich 富文本表格，带颜色和边框	终端交互查看

# 默认 markdown 格式（适合脚本/AI Agent）
bq dai schema cn_stock_bar1d

# Rich 表格输出（适合终端交互）
bq --format table strategy list

# 简写
bq -f table auth status

14. AI Agent 使用指南

本节专为 AI Agent（如 Claude、GPT 等）提供使用 bq CLI 的最佳实践。

14.1 初始化认证

AI Agent 在使用 bq 前，需要确认认证状态：

# 检查是否已登录
bq auth status

# 如果未登录，使用 AK/SK 配置（AK.SK 由用户提供）
bq auth --apikey <AK.SK>

14.2 推荐使用默认 markdown 格式

bq 默认输出 markdown 格式，无颜色转义码，AI Agent 可直接解析：

bq dai schema cn_stock_bar1d
bq strategy list
bq auth status

如需明确指定：

bq --format markdown dai schema cn_stock_bar1d

14.3 数据探索流程

# 第一步：搜索相关数据表
bq dai search 股票日线

# 第二步：查看表结构
bq dai schema cn_stock_bar1d

# 第三步：预览数据
bq dai head cn_stock_bar1d --limit 3

# 第四步：查看使用示例
bq dai example cn_stock_bar1d

# 第五步：执行查询并保存
bq dai query "SELECT date, instrument, close FROM cn_stock_bar1d" \
  --filters '{"date": ["2024-01-01", "2024-01-31"]}' \
  --output /tmp/result.csv

14.4 策略监控流程

# 列出所有策略
bq strategy list

# 查看策略详情
bq strategy show <strategy_id>

# 查看策略持仓
bq strategy positions <strategy_id>

# 查看策略已成交订单
bq strategy orders <strategy_id>

# 查看待交易信号
bq strategy signals <strategy_id>

# 查看策略绩效
bq strategy performance <strategy_id>

14.5 云端执行脚本（暂未开放）

暂未开放：bq aistudio run 正在开发中，暂不可用。

14.6 常用命令速查

# 认证
bq auth status                          # 查看登录状态
bq auth --apikey AK.SK                  # 配置凭证
bq auth configure                       # 交互式配置

# 数据
bq dai search <关键词>                  # 搜索数据表
bq dai schema <表名>                    # 查看字段
bq dai head <表名>                      # 预览数据
bq dai query "<SQL>" --filters '<JSON>' # 执行查询
bq dai query "<SQL>" --output file.csv  # 保存结果

# 策略
bq strategy list                        # 列出策略
bq strategy show <id>                   # 查看详情
bq strategy positions <id>              # 查看持仓
bq strategy orders <id>                 # 查看已成交订单
bq strategy signals <id>                # 查看待交易信号
bq strategy performance <id>            # 查看绩效

# 云端（暂未开放）
# bq aistudio list                        # 查看资源规格
# bq aistudio run --file /abs/path.py     # 云端执行

# 行情
bq marketdata bars 000001.SZ -s 2025-01-01 -e 2025-01-30

# 文件单
bq fileorder order --file-dir <dir> --account-id <id> --instrument <code> --direction buy --quantity 200
bq fileorder batch-order --file-dir <dir> --account-id <id> --input orders.json
bq fileorder cancel --file-dir <dir> --account-id <id> --order-key <key>
bq fileorder cancel --file-dir <dir> --account-id <id> --all
bq fileorder apply --file-dir <dir>     # 提交文件单
bq fileorder fund --file-dir <dir>      # 查询资金
bq fileorder position --file-dir <dir>  # 查询持仓
bq fileorder orders --file-dir <dir>    # 查询当日委托
bq fileorder trades --file-dir <dir>    # 查询当日成交

# 包管理
bq pkg list                             # 查看依赖包

文档

BigQuant SDK 用户教程