pandaai-cli 0.1.0

PandaAI 因子分析 CLI 工具 — 传入 Python 因子代码或公式，自动完成登录、创建、执行、结果和余额查询

PandaAI 因子分析 CLI

供 AI Skill 调用的命令行工具，传入 Python 因子代码或公式，自动完成登录 → 创建 → 执行 → 轮询 → 结果 + 余额。

安装

# 方式一：源码安装
uv venv --python 3.12
uv pip install -r requirements.txt

# 方式二：whl 安装
uv pip install dist/pandaai_cli-0.1.0-py3-none-any.whl
# 安装后直接使用: pandaai-cli factor_list

快速开始

# 0. 激活虚拟环境
source .venv/bin/activate

# 1. 登录（token 自动保存到 config.yaml）
python cli.py login --phone [phone] --password 'your_password'

# 2. 创建因子分析
python cli.py factor_create --formula "close/ref(close,5)-1"
# → ✅ 因子分析已创建: 6a461b10...

# 3. 执行并拿结果
python cli.py factor_run 6a461b10... --download

# 4. 查看列表
python cli.py factor_list

命令一览

python cli.py <command> [options]

命令:
  login                                   登录并保存 token
  factor_create                           创建因子分析（不执行），返回 factor_id
  factor_info <factor_id>                 查看因子详情（代码/公式 + 所有参数）
  factor_update <factor_id> [options]     修改因子参数
  factor_run <factor_id>                  执行已有因子分析（启动 + 轮询 + 结果）
  factor_list                             列出所有因子分析
  balance                                 查询算力余额
  factor_result <run_id>                  查询运行结果（14 个因子分析接口）
  factor_delete <factor_id> [factor_id...] 删除因子分析

详细参数

login — 登录

python cli.py login [--phone PHONE] [--password PWD]

参数	说明
--phone	手机号（不传则交互式输入）
--password	密码（不传则隐藏输入，更安全）

登录成功后 token 自动保存到 config.yaml，后续命令无需再登录。token 过期时自动提示重新登录。

factor_create — 创建因子分析

python cli.py factor_create (--code | --formula | --file) CONTENT
  [--name NAME] [--start-date YYYYMMDD] [--end-date YYYYMMDD]

参数	默认值	说明
--code CODE	-	Python 因子代码（需继承 Factor 基类）
--formula FORMULA	-	因子公式字符串
--file FILE	-	从文件读取代码/公式
--name NAME	新建因子分析	因子分析名称
--start-date	昨天-60天	因子构建开始日期，格式 YYYYMMDD
--end-date	昨天	因子构建结束日期，格式 YYYYMMDD
--adjustment-cycle	1	调仓周期（1-10）
--factor-direction	1	因子方向：0=负向，1=正向

分组数量固定为 10，股票池固定为沪深全A，不可修改。

返回值（JSON）：

{"success": true, "factor_id": "6a46..."}

示例：

python cli.py factor_create --formula "close/ref(close,5)-1"
# → ✅ 因子分析已创建: 6a461b10...

python cli.py factor_create --code "$(cat factor.py)" --name "动量因子"
python cli.py factor_create --file ./factor.py --start-date 20240101 --end-date 20240630

# 自定义因子分析参数
python cli.py factor_create --formula "close/ref(close,5)-1" \
  --adjustment-cycle 3 --factor-direction 0

factor_info — 查看因子详情

python cli.py factor_info <factor_id>

参数	默认值	说明
factor_id	必填	因子分析 ID

展示内容：名称、ID、类型（Python 代码/因子公式）、创建时间、调仓周期、分组数量、因子方向、股票池、日期范围、代码/公式内容。

factor_update — 修改因子参数

python cli.py factor_update <factor_id> [options]

参数	默认值	说明
factor_id	必填	因子分析 ID
--name	-	新名称
--code / --formula / --file	-	新代码/公式（三选一）
--start-date	-	开始日期 YYYYMMDD
--end-date	-	结束日期 YYYYMMDD
--adjustment-cycle	-	调仓周期 1-10
--factor-direction	-	因子方向 0=负向 1=正向

约束：

• 调仓周期必须在 1-10 之间
• 分组数量固定为 10，不可修改
• 股票池固定为沪深全A，不可修改

factor_run — 执行因子分析

python cli.py factor_run <factor_id>
  [--download [PATH]] [--poll-interval SEC] [--timeout SEC]

参数	默认值	说明
factor_id	必填	要执行的因子分析 ID
--download [PATH]	不下载	下载结果 CSV，默认 ~/Downloads/
--poll-interval	2	状态轮询间隔（秒）
--timeout	600	超时时间（秒）

算力服务器固定使用 cpu=4, memory=8, gpu=4，无需手动选择。

返回值（JSON）：

成功：

{
  "success": true,
  "status": "SUCCESS",
  "factor_id": "6a46...",
  "factor_run_id": "6a46...",
  "duration_seconds": 6.5,
  "output": [{"node_title": "因子分析", "node_output": {"task_id": "..."}}],
  "billing": {"balance": 9451.51, "deducted": 2.0, "status": "ok"},
  "results": {
    "nodes": {...},
    "factor_analysis": {
      "query_factor_analysis_data": [...],
      "query_group_return_analysis": [...],
      ...
    }
  }
}

失败：

{
  "success": false,
  "status": "FAILED",
  "error": {"type": "WORKFLOW_FAILED", "message": "...", "node_errors": [...]},
  "billing": {"balance": 9449.51, "deducted": 2.0, "status": "ok"}
}

示例：

python cli.py factor_run 6a461b10... --download
python cli.py factor_run 6a461b10... --download /tmp/my_data.csv
python cli.py factor_run 6a461b10... --timeout 120

factor_list — 列出因子分析

python cli.py factor_list [--limit N] [--offset N] [--no-detail]

参数	默认值	说明
--limit	100	每页条数（最大 100）
--offset	0	偏移量
--no-detail	false	跳过获取分析摘要（更快）

列表列：名称、创建时间、最后一次运行时间、Run ID、分析摘要（14 个指标）

分析摘要包含：

• 核心绩效：因子收益、夏普比率、年化收益、最大回撤
• IC 系列：IC_mean、Rank_IC、IC_std、IC_IR、IR、P(IC<-0.02)、P(IC>0.02)、t统计量、p-value、单调性

返回值（JSON）：

{
  "success": true,
  "total": 180,
  "count": 100,
  "limit": 100,
  "offset": 0,
  "factors": [
    {"_id": "6a46...", "name": "动量因子", "create_at": 1782..., "last_run_id": "6a46...", "_last_run_time": "...", "_analysis_summary": "因子收益 20.90%  夏普比率 8.02  年化收益 175.58%  最大回撤 0.00%  IC_mean -0.06  Rank_IC -0.07  IC_std 0.11  IC_IR -0.50  IR -4.01  P(IC<-0.02) 83.33%  P(IC>0.02) 16.67%  t统计量 -1.22  p-value 0.28  单调性 0.73"}
  ]
}

示例：

python cli.py factor_list
python cli.py factor_list --limit 50 --offset 50
python cli.py factor_list --no-detail

balance — 查询算力余额

python cli.py balance

返回值（文本）：

算力: 9435.51

返回值（JSON）：

{"success": true, "balance": {"computingPower": 9435.51, ...}}

factor_result — 查询运行结果

python cli.py factor_result <run_id> [--download [PATH]]

参数	默认值	说明
run_id	必填	运行 ID
--download [PATH]	不下载	下载结果 CSV

调用全部 14 个因子分析接口，展示：

• 核心绩效：因子收益、夏普比率、年化收益、最大回撤
• 因子分析指标：IC_mean, Rank_IC, IC_std, IC_IR, IR, P(IC<-0.02), P(IC>0.02), t统计量, p-value, 单调性
• 分组收益：10 分组 + 多空组合的 年化收益/超额收益/夏普比率/最大回撤/月胜率
• Top 因子：最新日期因子值最高的 10 只股票
• 图表数据：IC 序列、IC 衰减、IC 密度分布等 10 个图表（完整 JSON，含全量数据点）

示例：

python cli.py factor_result 6a461b10...
python cli.py factor_result 6a461b10... --download

factor_delete — 删除因子分析

python cli.py factor_delete <factor_id> [factor_id...]
python cli.py factor_delete --pattern "quota-test" [--yes]

参数	默认值	说明
factor_id	至少一个	因子分析 ID（支持多个）
--pattern	-	按名称前缀批量匹配
--yes	false	跳过删除确认

示例：

python cli.py factor_delete 6a461b10...
python cli.py factor_delete abc123 def456 ghi789
python cli.py factor_delete --pattern "quota-test" --yes

通用参数

参数	默认值	说明
--config PATH	~/.pandaai/config.yaml	配置文件路径
--json	false	仅输出 JSON（不输出 INFO 日志）

注意：--config 和 --json 必须放在子命令前面：

python cli.py --json factor_create --formula "..."

因子代码规范

代码模式（--code / --file）

需继承 Factor 基类，实现 calculate(self, factors) 方法：

class CombinedFactor(Factor):
    def calculate(self, factors):
        volume = factors['volume']
        close = factors['close']

        # 大单比例信号
        large_order_volume = TS_MAX(volume, 20)
        buy_signal = (large_order_volume / volume > 0.01).astype(int)

        # OBV 突破信号
        obv = (volume * ((close - close.shift(1)) / close.shift(1))).cumsum()
        obv_signal = ((obv == obv.rolling(90).max()) & (obv > obv.rolling(30).mean())).astype(int)

        return buy_signal + obv_signal

公式模式（--formula）

直接写因子表达式，可用变量 open, close, high, low, volume, amount 等：

# 5日收益率
--formula "close/ref(close,5)-1"

# 对数市值排名
--formula "RANK(-LOG(MARKET_CAP))"

因子分析链路

CodeControl → FactorBuildProControl → FactorAnalysisControl → FactorAnalysisChartControl
(Python代码)   (线性因子构建)          (因子分析)             (结果展示)
                              → DataDownloadControl (数据下载)

配置

配置文件默认位置 ~/.pandaai/config.yaml，也可通过 --config 指定其他路径。

首次使用直接 login 会自动创建：

# 自动创建 ~/.pandaai/config.yaml
python cli.py login --phone [phone] --password 'xxx'

config.yaml 内容：

gateway_url: "https://www.pandaaiquant.com/pandaApi"
token: "eyJ..."
uid: "35981"

目录结构

pandaai_cli/
├── cli.py                   # 入口：argparse + 子命令 dispatch
├── template.py              # 因子分析模板构建
├── pyproject.toml           # Python 打包配置（whl/pypi）
├── config.yaml              # 配置文件（gateway_url + token）
├── config.example.yaml      # 配置示例
├── requirements.txt         # requests, pyyaml
├── README.md                # 本文件
└── pandaai/                 # 功能模块
    ├── __init__.py           # 统一导出
    ├── constants.py          # 状态常量
    ├── config.py             # 配置加载 & token 持久化
    ├── auth.py               # 登录 & token 验证
    ├── billing.py            # 算力余额查询
    ├── factor_core.py        # 因子分析 CRUD + 轮询（含 info/update）
    ├── output.py             # 运行结果查询
    ├── factor.py             # 因子分析格式化（14 指标 + 图表）
    ├── factor_list.py        # 因子列表 & 删除（14 指标摘要）
    ├── formatting.py         # 成功/失败 JSON 格式化
    └── download.py           # CSV 下载

打包

# 构建 whl
uv run python -m build --wheel
# → dist/pandaai_cli-0.1.0-py3-none-any.whl

# 安装
pip install dist/pandaai_cli-0.1.0-py3-none-any.whl

# 使用
pandaai-cli factor_list --limit 3

error.type 全集

type	说明
LOGIN_FAILED	登录失败
LOGIN_REQUIRED	未登录或 token 过期
CREATE_FAILED	因子分析创建失败（含限额 402）
RUN_FAILED	因子分析启动失败
WORKFLOW_FAILED	因子分析代码执行报错
LIST_FAILED	获取因子列表失败
DELETE_FAILED	删除因子分析失败
INFO_FAILED	查看因子详情失败
UPDATE_FAILED	修改因子失败
BALANCE_FAILED	查询算力余额失败
INSUFFICIENT_BALANCE	余额不足被终止
TIMEOUT	轮询超时
INPUT_ERROR	输入参数错误
CONFIG_ERROR	配置文件不存在
UNKNOWN	未知错误