HyperView

将 TradingView 的想法转化为可测试、终端级速度的交易系统。

HyperView 旨在解决这样一个时刻：当 TradingView 策略不再仅仅是图表实验，而是需要确凿证据时。它直接从 TradingView 的 websocket (Web 套接字) 获取历史 K 线，在 Python 中运行你的策略逻辑，并以紧密模仿 Pine Script (TradingView 脚本语言) 的成交行为进行回测，这样你在本地 Python 中调优的结果将与你在 TradingView 策略测试器中看到的结果一致。

无需在 Pine 脚本、CSV 导出和临时笔记本之间来回切换，HyperView 提供了一个简洁的流程：获取多达 40K 根 K 线，基于 TA-Lib (技术分析库) 的 150+ 指标构建，模拟真实的止损/止盈 (SL/TP) 执行，并让贝叶斯优化 (Bayesian optimization) (Optuna TPE) 搜索更好的参数范围。无需 API 密钥。无需浏览器自动化。无需清理电子表格。只需更快的迭代、更精准的验证，以及专为希望像工程师一样开发策略的交易者打造的流程。

前置要求

• Python 3.11+
• TA-Lib — 由 pip install 自动安装。Windows、macOS 和 Linux 上提供 Python 3.9–3.14 的预编译 wheel (Python 包格式) 包。
• rich — 自动安装。用于驱动样式化的终端输出（彩色表格、进度指示器、面板）。
• Firefox (可选) — 如果你有 TradingView 付费计划，HyperView 可以读取你的 Firefox 会话 cookie (会话凭证) 以下载多达 40K 根 K 线。如果没有，websocket 仍匿名下载多达 5K 根 K 线。要使用此功能，只需在下载数据前在 Firefox 中登录 tradingview.com。

快速开始

# Install in editable mode (creates the `hyperview` CLI command, installs all dependencies including TA-Lib)
pip install -e .

# Download data for specific pairs
hyperview download-data --pairs NASDAQ:NFLX NASDAQ:AAPL --timeframe 1h --session extended

# Or define your pairs in config.json and download multiple timeframes at once:
hyperview download-data --timeframe 1h 15m

# Run a single backtest (uses config pairlist)
hyperview backtest --sl 3.23 --tp 13.06 --mode long

# Or target a specific symbol using values from a hyperopt preset file
hyperview backtest --symbol NASDAQ:NFLX --preset-file results/adx_stochastic_presets.json

# Hyper-optimize SL/TP across all pairs in config
hyperview hyperopt --mode long

# List cached data and registered strategies
hyperview list-data
hyperview list-strategies

你也可以通过 python -m hyperview 运行，而不是使用 hyperview 命令。

Python 字节码 (bytecode) 被重定向到项目级别的 .pycache/ 目录，因此运行时导入不会在 hyperview/ 或 strategy/ 下创建分散的 __pycache__ 文件夹。

工作原理

1. 下载 — 使用现有的 Firefox 会话 cookie 连接到 TradingView 的 websocket。付费计划支持多达 40K 根历史 K 线，并支持自动回填。
2. 信号 — 在纯 Python 中运行可插拔策略（例如包含的 MACD+RSI 或 ADX+Stochastic），并与 TA-Lib 指标保持对等。
3. 回测 — 使用 TradingView 对等的成交假设逐根 K 线模拟交易（次根 K 线开盘入场，根内止损/止盈出场顺序）。多对交易会产生真正的 PORTFOLIO 聚合行，包含合并后的权益曲线统计信息。
4. 超优化 — 在 SL/TP 组合上运行贝叶斯优化 (Optuna TPE)，然后更新策略预设文件，为每对/上下文保存最佳结果。

终端输出

回测和超优化命令均使用 rich 生成样式化的终端输出：

• 回测摘要 — 带有边框的表格，在收益率、回撤、期望值和最大单笔亏损上使用彩色方向箭头（▲ 绿色代表盈利，▼ 红色代表亏损），使用适合正常终端宽度的易读简短标签。当运行多个交易对时，会追加一个 PORTFOLIO 行，其中包含从合并权益曲线计算出的数学正确的聚合统计信息（而非简单平均值）。
• 超优化结果 — 面板标题显示策略/模式/时间框架，每个交易对的要点数据和信号摘要，以及一个顶部 N 结果表，其中参数列（SL/TP）用青色高亮显示，并在视觉上与指标列分开。

仓库布局

pyproject.toml              Package metadata & CLI entry point
config.json                 Default configuration (timeframe, pairlist, opt ranges)
config.schema.json          JSON Schema for editor validation & autocompletion
data/                       Cached candle CSVs (auto-generated)
results/                    Optimization presets & reports (auto-generated)

strategy/ — 可插拔策略框架

strategy/
├── __init__.py             Plugin registry & auto-discovery
├── base.py                 BaseStrategy ABC & prepare_candles()
├── indicators.py           TA-Lib wrappers, conversion helpers & signal toolkit
├── adx_stochastic.py       ADX+Stochastic strategy
└── macd_rsi.py             MACD+RSI strategy

hyperview/ — 核心引擎

hyperview/
├── __main__.py             Module entry point (python -m hyperview)
├── config.py               Config loader (JSON + CLI overrides + env vars)
├── models.py               Shared dataclasses (CandleRequest, Trade, BacktestMetrics, …)
├── presets.py              Preset load/save for optimized SL/TP parameters
├── validators.py           Configuration & preset validation rules
├── runtime.py              Bytecode cache redirection
│
├── cli/                    CLI router & subcommand handlers
│   ├── __init__.py         Argument parser & main() dispatcher
│   ├── formatting.py       Shared formatting helpers (rich tables, arrow decorators)
│   ├── backtest.py         backtest command
│   ├── download.py         download-data command
│   ├── hyperopt.py         hyperopt command
│   └── list.py             list-data & list-strategies commands
│
├── backtest/
│   └── engine.py           TradingView-parity OHLC simulator
│
├── downloader/
│   ├── client.py           TradingView websocket downloader & cache orchestration
│   ├── cache.py            CSV-backed local candle cache
│   ├── credentials.py      Firefox credential extraction
│   ├── session.py          WebSocket chart session manager
│   └── timeframes.py       Timeframe constants & utilities
│
└── hyperopt/
    └── optimizer.py        Bayesian optimizer (Optuna TPE)

配置

HyperView 从项目根目录的 config.json 加载默认值。CLI（命令行界面）标志位始终覆盖配置值。

下方示例展示了自定义设置；如果省略某个键，HyperView 将回退到运行时默认值。

{
    "timeframe": "1h",
    "session": "regular",
    "mode": "long",
    "strategy": "adx_stochastic",
    "initial_capital": 100000,
    "data_dir": "data",
    "output_dir": "results",
    "pairlist": [
        "NASDAQ:NFLX",
        "NASDAQ:TSLA",
        "COINBASE:BTCUSD",
        "COINBASE:ETHUSD"
    ],
    "optimization": {
        "n_trials": 200,
        "objective": "net_profit_pct",
        "top_n": 10,
        "sl_range": { "min": 1.0, "max": 15.0 },
        "tp_range": { "min": 1.0, "max": 15.0 }
    }
}

使用 --config /path/to/custom.json 加载不同的文件。

交易对列表 (Pairlist)

pairlist（交易对列表）数组定义了你想要处理的目标符号。每个条目必须使用 EXCHANGE:SYMBOL 格式——这允许你在单个配置中混合来自不同交易所的交易对：

"pairlist": [
    "NASDAQ:NFLX",
    "NASDAQ:TSLA",
    "NASDAQ:AAPL",
    "COINBASE:BTCUSD"
]

当你运行命令时未指定 --pairs 或 --symbol，HyperView 会自动使用配置中的 pairlist（交易对列表）——按顺序下载、回测 (backtesting) 或优化每个交易对。如果你在 CLI 上传递了 --pairs 或 --symbol，则本次运行将忽略配置中的 pairlist。

你可以为不同的资产类别维护单独的配置文件：

hyperview --config stocks.json download-data
hyperview --config crypto.json hyperopt --mode long

CLI 参考

download-data — 获取 K 线数据

# 下载配置 pairlist 中的所有交易对
hyperview download-data

# 或直接指定交易对，包括多个时间周期
hyperview download-data --pairs NASDAQ:NFLX NASDAQ:AAPL NASDAQ:TSLA --timeframe 1h 15m --start 2023-01-03

标志位	必填	默认值	描述
--pairs	否	配置中的交易对列表	一个或多个 EXCHANGE:SYMBOL 交易对（覆盖 pairlist）
--timeframe	否	配置	一个或多个 K 线间隔 (timeframe)：1m 5m 15m 1h 4h 1d 等
--start / --end	否	—	日期范围（ISO 格式）
--session	否	配置	常规或盘后 (session)
--adjustment	否	splits	价格调整 (adjustment)（拆股、股息、无）

backtest — 单一策略评估

# 回测配置 pairlist 中的所有交易对
hyperview backtest --sl 5.0 --tp 5.0 --mode long --start 2023-01-03

# 或使用 hyperopt 创建的预设文件针对特定符号
hyperview backtest --symbol NASDAQ:NFLX --preset-file results/adx_stochastic_presets.json --start 2023-01-03

如果省略了 --sl 和 --tp，HyperView 会使用 pair + timeframe + session + adjustment + mode 在提供的 --preset-file（预设文件）中查找匹配的条目。CLI 值仍然优先于 preset-file 的值。

标志位	必填	默认值	描述
--symbol	否	配置中的交易对列表	EXCHANGE:SYMBOL 交易对（覆盖 pairlist）
--sl	否*	—	止损百分比 (%) (*除非存在匹配的 --preset-file 条目，否则必填)
--tp	否*	—	止盈百分比 (%) (*除非存在匹配的 --preset-file 条目，否则必填)
--preset-file	否	自动检测	策略预设 JSON 路径（自动检测输出目录中的 <strategy>_presets.json）
--strategy	否	配置	策略名称（例如 macd_rsi, adx_stochastic）
--mode	否	long	做多、做空或双向 (long, short, or both)
--timeframe, --session, --adjustment, --start, --end	否	配置 / 默认值	标准过滤器

hyperopt — 超参数优化 (hyperopt) SL/TP

# 优化配置 pairlist 中的所有交易对（每个交易对运行一次优化）
hyperview hyperopt --n-trials 300

# 或针对特定符号
hyperview hyperopt --symbol NASDAQ:NFLX --n-trials 300

标志位	必填	默认值	描述
--symbol	否	配置中的交易对列表	EXCHANGE:SYMBOL 交易对（覆盖 pairlist）
--sl-min, --sl-max	否	配置	止损百分比 (%) 搜索范围
--tp-min, --tp-max	否	配置	止盈百分比 (%) 搜索范围
--n-trials	否	配置	贝叶斯优化 (Bayesian optimization) 试验次数（默认：200）
--objective	否	配置	net_profit_pct profit_factor win_rate_pct max_drawdown_pct trade_count
--top-n	否	配置	保留的前 N 个候选数量
--strategy, --mode, --timeframe, --adjustment, 等	否	配置 / 默认值	标准过滤器

list-data — 显示缓存数据集

hyperview list-data

list-strategies — 显示可用策略

hyperview list-strategies

指标

HyperView 附带了 20 个由 TA-Lib（技术分析库）支持的封装指标，以及 4 个信号辅助函数。你还可以通过 to_numpy / wrap 转换辅助函数直接访问所有 150+ 个 TA-Lib 函数。

封装指标

类别	函数
移动平均线	ema, sma, wma
动量	rsi, macd, stochastic, stochastic_rsi, cci, williams_r, momentum, roc
趋势	adx (返回 ADX, +DI, −DI), aroon (返回 down, up), psar
波动率	atr, bollinger_bands (返回 upper, middle, lower)
成交量	obv, mfi, ad, vwap

信号辅助函数

函数	描述
crossed_above(a, b)	当 a 上穿 b 的 K 线上返回 True
crossed_below(a, b)	当 a 下穿 b 的 K 线上返回 True
barssince(cond)	条件上次为 True 以来的 K 线数
to_unix_timestamp(dt)	将 ISO 日期字符串转换为 UTC Unix 时间戳

直接使用 TA-Lib

对于上述未封装的 TA-Lib 150+ 函数中的任何一个，直接调用 talib 并使用转换辅助函数：

import talib
from strategy.indicators import to_numpy, wrap

df["cci"] = wrap(talib.CCI(to_numpy(df["high"]),
                            to_numpy(df["low"]),
                            to_numpy(df["close"]), timeperiod=20), df.index)

添加自定义策略

1. 在 strategy/ 目录下创建一个新文件（例如 my_strategy.py）
2. 继承 BaseStrategy（基础策略）类并实现 generate_signals()、default_settings() 以及 required_columns() 方法
3. 使用 @register_strategy 装饰器装饰该类

策略会在启动时自动发现——无需手动导入。

from strategy import register_strategy
from strategy.base import BaseStrategy
from strategy.indicators import ema, crossed_above

@register_strategy
class MyStrategy(BaseStrategy):
    strategy_name = "my_strategy"

    def default_settings(self):
        return {"fast_period": 10, "slow_period": 20}

    def required_columns(self):
        return ["time", "open", "high", "low", "close"]

    def generate_signals(self, candles, settings):
        df = self.prepare_candles(candles)

        fast = ema(df["close"], settings["fast_period"])
        slow = ema(df["close"], settings["slow_period"])

        df["buy_signal"] = crossed_above(fast, slow)
        df["sell_signal"] = crossed_above(slow, fast)
        df["in_date_range"] = True
        df["enable_long"] = True
        df["enable_short"] = False

        return df

然后使用它：hyperview backtest --symbol NASDAQ:NFLX --strategy my_strategy --sl 5 --tp 5

输出文件

Hyperopt（超参数优化）会更新 results/ 目录下的策略预设文件：

results/macd_rsi_presets.json

每个文件为该策略存储每个精确的 pair + timeframe + session + adjustment + mode 组合的一个最佳预设。重新运行 Hyperopt 仅替换匹配的条目，并保留文件中已保存的其他上下文。

回测假设

模拟器近似模拟 TradingView（交易平台）的 intrabar（K 线内）填充行为：

• 入场：由信号生成的市价单将在下一根 K 线开盘时成交
• K 线内路径：如果一根 K 线开盘价更接近其最高价，路径是 open → high → low → close；更接近其最低价，路径是 open → low → high → close
• 仓位管理：每笔交易使用 100% 权益，无 pyramiding（金字塔式加仓）
• SL/TP（止损/止盈）离场：在同一根 K 线内根据 intrabar 价格路径进行检查

HyperView 快速上手指南

HyperView（原 TradingView-Machine-Learning-GUI）是一个将 TradingView 策略转化为可测试、终端速度的交易系统工具。它通过 WebSocket 获取历史 K 线，在 Python 中运行策略逻辑，并提供与 Pine Script 高度一致的回测行为。

环境准备

• Python: 版本需为 3.11+。
• 依赖库: TA-Lib 和 rich 将在安装时自动处理。
• 浏览器: 推荐使用 Firefox。
  • 若拥有 TradingView 付费计划，需在 Firefox 中登录 tradingview.com，以便读取 Cookie 下载高达 40K 根 K 线。
  • 未登录或免费账户可通过 WebSocket 匿名下载最多 5K 根 K 线。

安装步骤

建议使用国内镜像源以加快依赖下载速度：

# 使用清华源进行安装（推荐）
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e .

安装完成后，项目根目录将生成 hyperview 命令行工具。你也可以直接使用模块方式运行：python -m hyperview。

基本使用

1. 下载数据

从 TradingView 获取特定交易对的历史 K 线数据。

# 下载指定交易对的数据（例如 NASDAQ:NFLX）
hyperview download-data --pairs NASDAQ:NFLX --timeframe 1h --session extended

# 或者在 config.json 中定义交易对列表后批量下载
hyperview download-data --timeframe 1h 15m

2. 单策略回测

基于预设参数或手动指定的止损/止盈进行回测。

# 使用默认配置中的交易对列表进行回测
hyperview backtest --sl 3.23 --tp 13.06 --mode long

# 针对特定符号并使用超优化生成的预设文件
hyperview backtest --symbol NASDAQ:NFLX --preset-file results/adx_stochastic_presets.json

3. 超参数优化 (Hyperopt)

使用贝叶斯优化算法自动寻找最佳的止损/止盈参数组合。

# 对所有配置中的交易对进行优化
hyperview hyperopt --mode long

# 针对特定符号优化
hyperview hyperopt --symbol NASDAQ:NFLX --n-trials 300

4. 查看缓存与策略

# 列出已缓存的数据
hyperview list-data

# 列出可用的内置策略
hyperview list-strategies

提示: 所有命令均可通过 --config /path/to/custom.json 加载自定义配置文件来覆盖默认设置。