tqx-cli 0.1.6

TQX 港股/美股因子分析与策略回测 CLI

TQX CLI

tqx-cli 是面向 TQX 港股和美股量化工作流的命令行工具：

• 使用邮箱和密码登录，支持 token 持久化、自动刷新和多环境会话隔离。
• 支持港股、美股因子的创建、详情、修改、运行、结果查询、列表和删除。
• 支持港股、美股策略回测及账户、持仓、收益、成交和日志查询。
• 支持工作流运行、停止、导入、导出和运行状态检查。

安装

在你的 Windows 项目目录安装

下面的绝对路径是当前电脑上的源码位置，可以直接在 PowerShell 中执行：

cd .\clis\tqx_cli
python -m pip install -e .
tqx-cli --help

pip install -e . 是可编辑安装。以后修改此目录中的 Python 源码通常不需要重新安装。 如果 tqx-cli 无法识别，先确认安装和运行使用的是同一个 Python 环境：

python -m pip show tqx-cli
python -m tqx_cli.cli --help

通用源码安装写法

cd <tqx_cli源码目录>
python -m pip install -e .

尖括号表示占位内容，实际执行时不要输入 < 或 >。

快速开始

# 1. 登录，密码将隐藏输入
tqx-cli login --email [e-mail]

# 2. 创建美股因子分析
tqx-cli factor_create --market us `
  --formula "close" `
  --name "美股成交量" `
  --start-date "20260101" `
  --end-date "20260131"

# 3. 运行因子分析
tqx-cli factor_run <factor_id> --timeout 1200

# 4. 使用运行 ID 再次查询结果
tqx-cli factor_result <run_id>

# 5. 查看和删除因子工作流
tqx-cli factor_list --market us
tqx-cli factor_delete <factor_id>

命令一览

tqx-cli <command> [options]

认证与账户:
  login                                      邮箱密码登录并保存 token
  balance                                    查询算力余额

因子分析:
  factor_create                              创建港股/美股因子分析
  factor_info <factor_id>                    查看因子详情
  factor_update <factor_id>                  修改因子和分析参数
  factor_run <factor_id>                     运行、轮询并返回结果
  factor_stop <factor_id>                    停止因子工作流最近一次运行
  factor_result <run_id>                     查询一次运行的 14 类分析结果
  factor_list                                列出因子分析
  factor_delete <factor_id> [factor_id...]   删除因子分析

策略回测:
  strategy_create                            创建港股/美股策略回测
  strategy_info <strategy_id>                查看策略详情
  strategy_update <strategy_id>              修改策略和回测参数
  strategy_run <strategy_id>                 运行、轮询并返回结果
  strategy_stop <strategy_id>                停止策略工作流最近一次运行
  strategy_result <run_id>                   查询一次工作流运行结果
  strategy_list                              列出策略回测
  strategy_delete <strategy_id> [...]        删除策略回测
  backtest_result <backtest_id>              查询账户、持仓、收益、成交和日志

通用工作流:
  workflow_list                              同时列出因子和策略工作流
  workflow_pending_list [--limit 100]        列出等待中和运行中的工作流
  workflow_delete <workflow_id> [...]        删除任意支持的工作流
  workflow_export <workflow_id> [目录]        导出完整 JSON 工作流
  workflow_import <JSON文件或目录>             从本地 JSON 导入工作流
  workflow_stop <workflow_id>                停止任意工作流最近一次运行

ID 的区别

CLI 中有三种 ID，不能混用：

ID	产生位置	用途
factor_id / strategy_id	*_create	查看、修改、运行、删除工作流
run_id	factor_run / strategy_run	查询某一次工作流运行及节点输出
backtest_id	成功的策略运行结果	查询回测账户、持仓、收益、成交和日志

例如：

tqx-cli factor_run 6a5db5eb6184ad1f1be83cdf
# 返回 run_id: 6a5dbffc6184ad1f1be83ce1

tqx-cli factor_result 6a5dbffc6184ad1f1be83ce1

登录与配置

默认配置文件为 ~/.tqx/config.yaml。Windows 通常对应：

C:\Users\<你的用户名>\.tqx\config.yaml

登录成功后保存 accessToken 和 refreshToken。access token 过期时会自动刷新； 只有 refresh token 也失效时才需要重新登录。

tqx-cli login --email [e-mail]
tqx-cli balance

默认服务配置：

site_url: https://www.tqx.trade
gateway_url: https://www.tqx.trade/pandaApi
email_login_path: /tqxApi/auth/login
login_payload_style: tqx
login_password_encoding: md5_upper
user_info_path: /tqxApi/user/info

使用环境变量设置 site_url

site_url 可以通过 TQX_SITE_URL 环境变量覆盖，不需要修改配置文件：

# 当前 PowerShell 窗口生效
$env:TQX_SITE_URL = "https://www.tqx.trade"
tqx-cli login --email [e-mail] --password xxxx

# 查看当前值
$env:TQX_SITE_URL

# 取消覆盖，恢复 config.yaml 的 site_url
Remove-Item Env:TQX_SITE_URL

TQX_SITE_URL 是整套 TQX 环境的基础地址。设置后会在当前进程中同时覆盖认证基础地址， 并将 gateway_url 派生为 <TQX_SITE_URL>/pandaApi，因此登录、用户信息、token 刷新、 工作流、因子、钱包和回测接口会一起切换。配置文件中的 URL 不会被环境变量改写。

CLI 会按 TQX_SITE_URL 分别保存该环境的 uid、access token 和 refresh token。每个环境 首次使用时分别登录一次；之后切换环境变量会自动选择对应会话，不会覆盖或复用另一环境的凭证：

$env:TQX_SITE_URL = "http://192.168.x.x:xxxx"
tqx-cli login --email [e-mail] --password xxxx


$env:TQX_SITE_URL = "https://www.tqx.trade"
tqx-cli login --email [e-mail] --password xxxx
tqx-cli factor_list --market us

使用临时配置文件时，--config 必须放在子命令前：

$cfg = Join-Path $env:TEMP "tqx-cli-debug.yaml"
tqx-cli --config $cfg login --email [e-mail]
tqx-cli --config $cfg factor_list

因子命令

factor_create

tqx-cli factor_create --market hk|us (--formula FORMULA | --code CODE | --file FILE) `
  [--name NAME] [--start-date YYYYMMDD] [--end-date YYYYMMDD] `
  [--adjustment-cycle N] [--group-number N] [--factor-direction DIRECTION]

--code 可以直接接 Python 文件的完整内容。

Bash：

python cli.py factor_create --market hk \
  --code "$(cat factor.py)" \
  --name "港股动量因子"

PowerShell：

python cli.py factor_create --market hk `
  --code "$(Get-Content .\factor.py -Raw)" `
  --name "港股动量因子"

也可以先读取变量。变量在传给 --code 时必须使用双引号：

$code = Get-Content .\factor.py -Raw
python cli.py factor_create --market us --code "$code" --name "美股动量因子"

等价的简化方式是直接使用 --file：

# TQX 因子必须明确指定市场
python cli.py factor_create --market hk --file ./factor.py `
  --start-date 20240101 --end-date 20240630

python cli.py factor_create --market us --file ./factor.py `
  --start-date 20240101 --end-date 20240630 `
  --name "美股动量因子"

--file ./factor.py 表示 CLI 自己读取 UTF-8 文件并将内容放进 Python 代码节点。它与 --code "$(Get-Content ./factor.py -Raw)" 效果相同，但更适合多行代码，也不会遇到 PowerShell 将换行拆成多个命令参数的问题。

TQX 同时支持港股和美股，因此必须明确提供 --market hk 或 --market us。

以下示例已经实际运行验证：

tqx-cli factor_create --market hk `
  --formula "close" `
  --name "港股动量" `
  --start-date "20260101" `
  --end-date "20260131"

tqx-cli factor_create --market us `
  --formula "close" `
  --name "美股成交量" `
  --start-date "20260101" `
  --end-date "20260131"

参数映射：

CLI 参数	后端字段	TQX 页面名称	允许值
--market	market	Market	hk、us
--adjustment-cycle	adjustment_cycle	Position Adjustment Cycle	1/3/5/10/20/30
--group-number	group_number	Number of Groups	2 到 20
--factor-direction	factor_direction	Factor Direction	Positive/Negative、正向/负向、1/0

--number-of-groups 是 --group-number 的别名； --position-adjustment-cycle 是 --adjustment-cycle 的别名。

factor_info 和 factor_update

tqx-cli factor_info <factor_id>

tqx-cli factor_update <factor_id> `
  --formula "volume/MAX(ref(volume,5),1)"

更新后 CLI 会重新读取工作流并验证字段。服务端未实际保存时返回 UPDATE_NOT_APPLIED。

factor_run 和 factor_result

tqx-cli factor_run <factor_id> [--poll-interval SEC] [--timeout SEC] `
  [--server-cpu N] [--server-memory N] [--server-gpu N]

tqx-cli factor_result <run_id>

两者用途不同：

• factor_run 使用 factor_id 启动并轮询工作流，成功后返回新的 run_id。
• factor_result 使用已有 run_id 查询结果，不会重新运行工作流。
• 结果状态为 SUCCESS、NOT_READY、FAILED、INCOMPLETE 或 PARTIAL_SUCCESS； 未完成或部分失败不会再返回普通成功。

# 运行，不保存文件
tqx-cli factor_run 6a5db5eb6184ad1f1be83cdf --timeout 1200

# 使用 run_id 查询，不重新运行
tqx-cli factor_result 6a5dbffc6184ad1f1be83ce1

factor_result 会根据 run_id 查询节点输出，再使用 task_id 请求 14 个因子分析接口。

默认算力规格按 TQX_SITE_URL 自动选择：测试环境（例如 http://192.168.xxxx）使用 CPU=2、memory=4 GB、GPU=2；生产环境 https://www.tqx.trade 使用 CPU=4、memory=8 GB、GPU=4。可使用 --server-cpu、--server-memory 和 --server-gpu 显式覆盖。

停止因子工作流最近一次运行：

tqx-cli factor_stop <factor_id>

CLI 会读取工作流的 last_run_id，再调用后端停止接口。只有等待中或运行中的任务可以停止。

factor_list 和 factor_delete

tqx-cli factor_list [--market all|hk|us] [--limit 100] [--offset 0]
tqx-cli factor_list --market hk --include-content

tqx-cli factor_delete <factor_id> [factor_id...] [--yes]
tqx-cli factor_delete --pattern "debug-factor" --yes

factor_delete 删除前会检查目标确实是因子工作流，避免误删策略。未提供 --yes 时会要求确认。

策略命令

港股策略代码应导入：

from panda_backtest.api.api import *
from panda_backtest.api.stock_hk_api import *

美股策略代码应导入：

from panda_backtest.api.api import *
from panda_backtest.api.stock_us_api import *

以下港股和美股策略创建命令已经实际运行验证：

tqx-cli strategy_create --market hk --file ./tests/hk_ma.py `
  --name "港股均线策略" `
  --start-date 20250101 --end-date 20250220 --frequency 1d

tqx-cli strategy_create --market us --file ./tests/us_ma.py `
  --name "美股均线策略" `
  --start-date 20250101 --end-date 20250220 --frequency 1d

# 可选：市场 API 导入错误或缺失时直接拒绝创建
tqx-cli strategy_create --market us --file ./tests/us_ma.py --strict-market-api

tqx-cli strategy_run <strategy_id> --timeout 1200

# 以下命令使用运行成功后返回的 ID
tqx-cli strategy_result <run_id>
tqx-cli backtest_result <backtest_id> --section all
tqx-cli backtest_result <backtest_id> --section all --all-pages
tqx-cli backtest_result <backtest_id> --section trade --page 1 --page-size 100
tqx-cli backtest_result <backtest_id> --section log

tqx-cli strategy_list --market hk
tqx-cli strategy_delete <strategy_id>
tqx-cli strategy_delete --pattern "debug-strategy" --yes

strategy_run、strategy_result 与下载

tqx-cli strategy_run <strategy_id> [--download [PATH]] `
  [--poll-interval SEC] [--timeout SEC] `
  [--server-cpu N] [--server-memory N] [--server-gpu N]

tqx-cli strategy_result <run_id> [--download [PATH]]

• strategy_run 使用 strategy_id 启动一次新运行，成功后返回 run_id 和 backtest_id。
• strategy_result 使用已有 run_id 查询结果，不重新执行策略。
• backtest_result 使用 backtest_id 查询账户、持仓、收益、成交或日志。

策略命令的 --download 保存完整回测结果 JSON。因子工作流不提供 CSV 下载节点。

# 运行，不保存文件
tqx-cli strategy_run <strategy_id> --timeout 1200

# 运行并将 JSON 保存到 Downloads
tqx-cli strategy_run <strategy_id> --download --timeout 1200

# 运行并保存为指定 JSON 文件
tqx-cli strategy_run <strategy_id> `
  --download .\results\strategy-result.json --timeout 1200

# 使用 run_id 查询已有运行，不重新运行
tqx-cli strategy_result <run_id>

# 查询并保存到 Downloads
tqx-cli strategy_result <run_id> --download

# 查询并保存为指定 JSON 文件
tqx-cli strategy_result <run_id> --download .\results\strategy-result.json

--download [PATH] 规则：省略 --download 时不保存；只写 --download 时保存到当前用户 Downloads；PATH 是文件时使用指定文件名；PATH 是已有目录或以反斜杠结尾时使用默认文件名。

停止策略工作流最近一次运行：

tqx-cli strategy_stop <strategy_id>

<factor_id>、<strategy_id>、<run_id>、<backtest_id> 和 <workflow_id> 都是占位符。 执行时替换成真实 ID，不要输入 < 和 >。

workflow 管理命令

workflow 命令管理保存的工作流，不负责下载运行结果：

tqx-cli workflow_list
tqx-cli workflow_list --kind factor --market hk
tqx-cli workflow_list --kind strategy --market us
tqx-cli workflow_pending_list
tqx-cli workflow_pending_list --limit 100
tqx-cli workflow_stop <workflow_id>
tqx-cli workflow_delete <workflow_id> [workflow_id...] --yes

workflow_pending_list 只列出 PENDING 和 RUNNING 任务，并显示 duration_seconds 与可直接执行的 stop_command。workflow_stop 接收工作流 ID，读取该工作流的 last_run_id，并停止最近一次等待或运行中的任务。

HTTP 409 会返回 RUN_CONFLICT 和检查、停止命令。TIMEOUT 只结束 CLI 等待，不会自动停止 后端任务；返回结果会包含 stop_command 和 next_steps。

长时间回测可以只提交任务，不占用当前终端：

tqx-cli strategy_run <strategy_id> --no-wait
tqx-cli workflow_pending_list
tqx-cli strategy_result <run_id>

workflow_export

导出当前账号拥有的完整工作流 JSON。JSON 包含 nodes、links、litegraph 等画布结构， 可以作为备份或导入文件使用。

# 导出到当前目录，自动生成“工作流名称-ID.json”
tqx-cli workflow_export <workflow_id>

# 导出到指定目录
tqx-cli workflow_export <workflow_id> .\workflow-backup

# 使用绝对目录
tqx-cli workflow_export <workflow_id> C:\PythonAIProject\workflow-backup

workflow_import

从本地 JSON 文件创建一个新的工作流。导入时会删除原工作流的 _id、owner、运行记录和 输出记录，服务端会生成新的 workflow_id；节点、连线和 litegraph 结构会保留。

# 导入一个 JSON 文件
tqx-cli workflow_import .\workflow-backup\港股策略-6a5d....json

# 目录中只有一个 JSON 文件时，也可以传目录
tqx-cli workflow_import .\workflow-backup

导入成功后返回新的 ID：

{
  "success": true,
  "workflow_id": "new-workflow-id",
  "source": ".\\workflow-backup\\workflow.json"
}

导出、导入和前端的工作流 JSON 选项使用同一套工作流结构；导入后建议先执行 workflow_list 或 factor_info/strategy_info 检查市场和节点参数，再运行工作流。

回测结果 --section 支持：

summary, account, position, profit, trade, log, all

工作流结构

因子分析：

CodeControl
  -> FactorBuildTQXControl(HK/US)
  -> FactorAnalysisTQXControl
  -> FactorAnalysisChartControl

FactorBuildTQXControl

策略回测固定使用以下三节点链路：

Python 代码节点 (CodeControl)
  -> 港股: HkStockBacktestControl
     或美股: UsStockBacktestControl
  -> BackTestResultControl

实际字段连线为：

CodeControl.code
  -> HkStockBacktestControl.code / UsStockBacktestControl.code

HkStockBacktestControl.backtest_id / UsStockBacktestControl.backtest_id
  -> BackTestResultControl.task_id

workflow_list/workflow_delete 是底层通用命令；factor_* 和 strategy_* 是更适合日常使用、 带类型检查的命令。

通用参数

参数	默认值	说明
--config PATH	~/.tqx/config.yaml	指定配置文件
--json	false	输出 JSON，适合脚本或 Agent 调用

通用参数必须写在子命令前：

tqx-cli --json factor_list --market us
tqx-cli --config .\debug.yaml --json factor_result <run_id>

后端要求

目标服务必须提供：

• FactorBuildTQXControl
• FactorAnalysisTQXControl
• HkStockBacktestControl
• UsStockBacktestControl
• /quantflow/api/workflow/*
• /quantflow/api/factor/*
• /quantflow/api/backtest/*

后端运行环境还必须正确配置港美股数据，例如 PARQUET_ROOT_PATH。

开发测试

cd C:\PythonAIProject\clis\tqx_cli
python -m compileall -q tqx_cli tests
python -m unittest discover -s tests -v
python -m tqx_cli.cli --help

主要错误类型

type	说明
LOGIN_FAILED	登录失败
LOGIN_REQUIRED	access token 和 refresh token 均不可用
CREATE_FAILED	创建工作流失败
UPDATE_NOT_APPLIED	服务端保存后的参数与请求不一致
RUN_FAILED	启动工作流失败
RUN_CONFLICT	已有等待中或运行中的任务
RUN_QUERY_FAILED	查询运行状态失败
RUN_LIST_FAILED	查询运行中工作流失败
QUERY_FAILED	查询工作流失败
LIST_FAILED	查询工作流列表失败
LOG_QUERY_FAILED	查询运行日志失败
OUTPUT_QUERY_FAILED	查询节点输出失败
FACTOR_RESULT_FAILED	查询因子分析结果失败
BACKTEST_RESULT_FAILED	查询策略回测结果失败
AUTH_NETWORK_ERROR	认证服务连接或读取超时
STOP_FAILED	停止工作流失败
DELETE_FAILED	删除工作流失败
TIMEOUT	轮询超时
INPUT_ERROR	参数或代码输入错误
CONFIG_ERROR	配置文件不存在或内容错误