Metadata-Version: 2.4
Name: tqx-cli
Version: 0.1.6
Summary: TQX 港股/美股因子分析与策略回测 CLI
Author: PandaAI
License: MIT
Project-URL: Homepage, https://www.tqx.trade
Keywords: tqx,pandaai,factor,backtest,quant,cli,港股,美股
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: pyyaml>=6.0

# TQX CLI

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

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

## 安装

### 在你的 Windows 项目目录安装

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

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

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

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

### 通用源码安装写法


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

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

## 快速开始

```powershell
# 1. 登录，密码将隐藏输入
tqx-cli login --email user@example.com

# 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>
```

## 命令一览

```text
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` | 成功的策略运行结果 | 查询回测账户、持仓、收益、成交和日志 |

例如：

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

tqx-cli factor_result 6a5dbffc6184ad1f1be83ce1
```

## 登录与配置

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

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

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

```powershell
tqx-cli login --email user@example.com
tqx-cli balance
```

默认服务配置：

```yaml
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
# 当前 PowerShell 窗口生效
$env:TQX_SITE_URL = "https://www.tqx.trade"
tqx-cli login --email user@example.com --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。每个环境
首次使用时分别登录一次；之后切换环境变量会自动选择对应会话，不会覆盖或复用另一环境的凭证：

```powershell
$env:TQX_SITE_URL = "http://192.168.x.x:xxxx"
tqx-cli login --email user@example.com --password xxxx


$env:TQX_SITE_URL = "https://www.tqx.trade"
tqx-cli login --email user@example.com --password xxxx
tqx-cli factor_list --market us
```

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

```powershell
$cfg = Join-Path $env:TEMP "tqx-cli-debug.yaml"
tqx-cli --config $cfg login --email user@example.com
tqx-cli --config $cfg factor_list
```

## 因子命令

### factor_create

```powershell
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：

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

PowerShell：

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

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

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

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

```powershell
# 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`。

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

```powershell
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

```powershell
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

```powershell
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`；
  未完成或部分失败不会再返回普通成功。

```powershell
# 运行，不保存文件
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` 显式覆盖。

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

```powershell
tqx-cli factor_stop <factor_id>
```

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

### factor_list 和 factor_delete

```powershell
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` 时会要求确认。

## 策略命令

港股策略代码应导入：

```python
from panda_backtest.api.api import *
from panda_backtest.api.stock_hk_api import *
```

美股策略代码应导入：

```python
from panda_backtest.api.api import *
from panda_backtest.api.stock_us_api import *
```

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

```powershell
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 与下载

```powershell
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 下载节点。

```powershell
# 运行，不保存文件
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 是已有目录或以反斜杠结尾时使用默认文件名。

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

```powershell
tqx-cli strategy_stop <strategy_id>
```

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

### workflow 管理命令

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

```powershell
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`。

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

```powershell
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` 等画布结构，
可以作为备份或导入文件使用。

```powershell
# 导出到当前目录，自动生成“工作流名称-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` 结构会保留。

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

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

导入成功后返回新的 ID：

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

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

回测结果 `--section` 支持：

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

## 工作流结构

因子分析：

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

FactorBuildTQXControl
```

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

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

实际字段连线为：

```text
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 调用 |

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

```powershell
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`。

## 开发测试

```powershell
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` | 配置文件不存在或内容错误 |
