setup

为 VectorBT + OpenAlgo 设置完整的 Python 回测环境。

参数

• $0 = Python 版本（可选，默认：python3）。示例：python3.12、python3.13

步骤

步骤 1：检测操作系统

运行以下命令来检测操作系统：

uname -s 2>/dev/null || echo "Windows"

将结果对应为：

• Darwin = macOS
• Linux = Linux
• MINGW* 或 CYGWIN* 或 Windows = Windows

向用户显示检测到的操作系统。

步骤 2：创建虚拟环境

在当前工作目录中创建 Python 虚拟环境：

macOS / Linux：

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip

Windows：

python -m venv venv
venv\Scripts\activate
pip install --upgrade pip

如果用户指定了 Python 版本参数，请使用该版本代替 python3：

$PYTHON_VERSION -m venv venv

步骤 3：TA-Lib 系统依赖（可选）

OpenAlgo ta（from openalgo import ta）是此项目默认的指标库，内置 100 多种指标，无需单独安装系统依赖。 只有用户希望在特定回测中能够指定「使用 talib」时，才需要 TA-Lib。

通过 AskUserQuestion 询问用户：

• 「您还想安装 TA-Lib，以便在回测中明确要求使用时调用吗？（可选——OpenAlgo ta 已涵盖相同的指标，另外还多出 90 多种）」
  • 是，同时安装 TA-Lib
  • 否，跳过（推荐——如有需要，之后再安装）

如果用户选择跳过，则跳过整个步骤，并在步骤 4 的 pip 安装中省略 ta-lib。如果用户希望安装，必须先在操作系统级别安装 C 库，然后才能执行 pip install ta-lib。

macOS：

brew install ta-lib

Linux（Debian/Ubuntu）：

sudo apt-get update
sudo apt-get install -y build-essential wget
wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz
tar -xzf ta-lib-0.4.0-src.tar.gz
cd ta-lib/
./configure --prefix=/usr
make
sudo make install
cd ..
rm -rf ta-lib ta-lib-0.4.0-src.tar.gz

Linux（RHEL/CentOS/Fedora）：

sudo yum groupinstall -y "Development Tools"
wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz
tar -xzf ta-lib-0.4.0-src.tar.gz
cd ta-lib/
./configure --prefix=/usr
make
sudo make install
cd ..
rm -rf ta-lib ta-lib-0.4.0-src.tar.gz

Windows：

pip install ta-lib

如果失败，请从 https://github.com/cgohlke/talib-build/releases 下载适用的 .whl 文件，并使用以下命令安装：

pip install TA_Lib-0.4.32-cp312-cp312-win_amd64.whl

步骤 4：安装 Python 包

安装所有必需的包（最新版本）。openstatz 用于替代 QuantStats 生成收益分析报告——始终安装它，切勿安装 quantstats：

pip install openalgo vectorbt plotly anywidget nbformat pandas numpy yfinance python-dotenv tqdm scipy numba nbformat ipywidgets openstatz ccxt duckdb psutil

如果用户在步骤 3 中选择安装 TA-Lib，请在此安装命令末尾追加 ta-lib（确保已安装 C 库）。

步骤 5：创建回测文件夹

只创建顶层回测目录。生成回测脚本时（由 /backtest 技能负责），再按需创建策略子文件夹。

mkdir -p backtesting

不要预先创建策略子文件夹。

第 6 步：配置 .env 文件

6a. 检查项目根目录下是否存在 .env.sample。 如果存在，请将其用作模板。

6b. 使用 AskUserQuestion 询问用户要回测哪些市场：

• 印度市场（OpenAlgo）——需要 OpenAlgo API 密钥
• 印度市场（DuckDB）——直接加载数据库，无需 API
• 美国市场（yfinance）——无需 API 密钥
• 加密货币市场（CCXT）——私有数据需要 API 密钥（可选）

6c. 如果用户选择了印度市场，请询问其 OpenAlgo API 密钥：

• 询问：“请输入你的 OpenAlgo API 密钥（可在 OpenAlgo 仪表板中获取）：”
• 如果用户提供了密钥，将其存入 .env
• 如果用户跳过，则写入占位符

6d. 如果用户选择了印度市场（DuckDB），请询问 DuckDB 数据库路径：

• 询问：“请输入 DuckDB 数据库文件的路径（例如：D:/data/market_data.duckdb）：”
• 自动检测格式：如果数据库中有一个 market_data 表，且该表包含 symbol, exchange, interval, timestamp 列，则属于 OpenAlgo Historify 格式（存为 HISTORIFY_DB_PATH）。否则存为 DUCKDB_PATH。
• 如果用户也有 OpenAlgo Historify，请询问：“这是 OpenAlgo Historify 数据库吗？（y/n）”

6e. 如果用户选择了加密货币市场，请询问其是否要配置交易所 API 密钥：

• 询问：“你有用于认证数据的交易所 API 密钥吗？（可选——无需密钥即可获取公开的 OHLCV 数据）”
• 如果有，请询问 API 密钥和密钥密码，并存入 .env
• 如果没有，请在 .env 中留空

6f. 在项目根目录下写入 .env 文件。 使用此模板，并填入用户提供的任何密钥／路径：

# Indian Markets (OpenAlgo)
OPENALGO_API_KEY={user_provided_key or "your_openalgo_api_key_here"}
OPENALGO_HOST=http://127.0.0.1:5000

# DuckDB Data Sources (direct database loading - fastest)
# Custom DuckDB (user-created with OHLCV table)
DUCKDB_PATH={user_provided_path or ""}
# OpenAlgo Historify DuckDB (market_data table with epoch timestamps)
HISTORIFY_DB_PATH={user_provided_path or ""}

# Crypto Markets (CCXT) - Optional
CRYPTO_API_KEY={user_provided_key or ""}
CRYPTO_SECRET_KEY={user_provided_key or ""}

6g. 如果 .gitignore 存在，则将 .env 添加到其中（绝不要提交机密）：

脚本使用 find_dotenv() 自动向上查找唯一的根目录 .env 文件，因此无需在子目录中复制文件。

grep -qxF '.env' .gitignore 2>/dev/null || echo '.env' >> .gitignore

第 7 步：验证安装

快速验证：

python -c "
import vectorbt as vbt
from openalgo import ta
import plotly
import duckdb
import anywidget
import nbformat
import openstatz
from dotenv import load_dotenv
print('All packages installed successfully')
print(f'  vectorbt: {vbt.__version__}')
print(f'  plotly: {plotly.__version__}')
print(f'  duckdb: {duckdb.__version__}')
print(f'  nbformat: {nbformat.__version__}')
print(f'  openstatz: {openstatz.__version__}')
print(f'  OpenAlgo ta: available (default indicator library)')
print(f'  python-dotenv: available')
"

如果用户选择安装 TA-Lib，还要使用 python -c "import talib; print('TA-Lib available')" 进行验证。如果导入失败，请告知用户必须先安装 C 库（参见第 3 步）。

第 8 步：打印摘要

打印一份摘要，显示：

• 检测到的操作系统
• 使用的 Python 版本
• 虚拟环境路径
• 已安装的软件包及其版本
• 已创建的回测文件夹（策略子文件夹会由 /backtest 按需创建）
• .env 文件状态（已配置密钥／占位符）——项目根目录下的单个文件
• 提醒：“如果跳过配置，请运行 cp .env.sample .env 并填写 API 密钥”

重要说明

• 绝不要全局安装软件包——始终使用虚拟环境
• 在 Linux 上安装 TA-Lib C 库需要管理员／sudo 权限
• 在 macOS 上，运行 brew install ta-lib 需要先安装 Homebrew
• 如果用户已有虚拟环境，请在创建新环境前征求其同意
• backtesting/ 文件夹用于保存所有生成的回测脚本
• 绝不要提交 .env 文件——其中包含机密。务必使用 .gitignore。
• 如果用户在设置过程中提供了 API 密钥，请直接将其写入 .env——不要要求用户手动编辑文件
• python-dotenv 已包含在 pip 安装中，所有脚本都必须使用它来加载 .env