2. 创建首个Jesse项目 - Jesse 速读教程

安装好 Jesse 之后，第一件事就是创建属于自己的交易项目。这个过程比想象中简单，几条命令就能生成一个完整的项目骨架，里面包含了策略开发所需的一切基础设施。

Jesse 的项目结构经过精心设计，把策略、配置、数据、日志等要素分门别类地组织起来。理解这个结构对后续开发至关重要，它能帮助我们快速定位文件，避免在混乱的目录中迷失方向。

Jesse 项目结构

创建新项目时，Jesse 会生成一个标准的目录树。这个结构在版本迭代中保持了高度稳定性，从 0.30.0 版本引入 GUI 仪表板以来，核心布局基本没有变化。

项目根目录下有几个关键文件和文件夹，各自承担不同职责：

my-bot/
├── .env                    # 环境变量配置
├── docker/                 # Docker 部署配置
├── storage/                # 运行时生成的文件
│   ├── logs/              # 日志文件
│   ├── charts/            # 回测图表
│   ├── temp/              # 临时文件
│   └── csv/               # 导出的交易数据
└── strategies/            # 策略代码目录
    ├── __init__.py
    ├── Strategy01/
    │   └── __init__.py    # 策略实现
    └── Strategy02/
        └── __init__.py

.env 文件是整个项目的配置中心。这里存放数据库连接信息、交易所 API 密钥、通知服务配置等敏感信息。默认模板提供了所有必要的变量，我们只需要按需修改即可。特别注意 PASSWORD 字段，这是访问仪表板的密码，务必设置为强密码。

strategies 目录是策略开发的主战场。每个策略独占一个子目录，里面包含 __init__.py 文件。这种设计让策略可以独立管理，方便版本控制和分享。策略类名必须与目录名保持一致，这是 Jesse 的约定。

storage 目录存放运行时的输出文件。回测生成的图表、交易记录、日志都会自动归类到这里。这个目录不需要手动管理，Jesse 会自动创建子文件夹。定期清理旧的日志和图表可以节省磁盘空间。

生成策略文件

Jesse 提供了两种创建策略的方式：通过 GUI 仪表板或命令行工具。对于初学者，GUI 方式更直观；对于习惯终端操作的开发者，命令行更高效。

通过 GUI 创建策略

打开浏览器访问 http://localhost:9000，输入 .env 文件中设置的密码登录。在左侧菜单栏找到"Strategies"选项，点击"New Strategy"按钮。

弹出的表单只需要填写一个字段：策略名称。命名建议采用驼峰式，比如 MovingAverageCross 或 RSIBreakout。名称会直接影响生成的类名和文件名，所以要有一定描述性。

提交表单后，Jesse 会在 strategies 目录下创建对应的子目录和 __init__.py 文件。生成的模板代码包含了策略所需的所有方法骨架：

from jesse.strategies import Strategy
from jesse import utils
import jesse.indicators as ta


class AwesomeStrategy(Strategy):
    def should_long(self):
        return False

    def should_short(self):
        return False

    def should_cancel_entry(self):
        return False

    def go_long(self):
        pass

    def go_short(self):
        pass

这个模板遵循了 Jesse 的策略执行流程。should_long 和 should_short 决定交易方向，go_long 和 go_short 定义具体的订单参数，should_cancel_entry 处理未成交订单的取消逻辑。每个方法都有明确的职责，这种设计让策略逻辑清晰易懂。

通过命令行创建策略

如果更喜欢终端操作，可以使用 jesse 命令行工具。在项目根目录执行：

jesse generate-strategy MyNewStrategy

命令会在 strategies 目录下创建 MyNewStrategy 文件夹和对应的 __init__.py 文件。生成的代码与 GUI 方式完全一致，区别在于操作路径不同。这种方式适合批量创建策略或集成到自动化脚本中。

无论采用哪种方式，生成的模板都是可运行的最小化策略。虽然它不会执行任何交易（所有方法都返回 False 或 pass），但可以通过回测验证项目配置是否正确。这是一个很好的起点，我们可以在此基础上逐步添加交易逻辑。

配置交易路由

路由（Routes）是 Jesse 的核心概念，它定义了"在哪个交易所、交易什么品种、使用什么时间周期、应用什么策略"。可以把路由理解为策略的执行蓝图，Jesse 根据路由配置来调度策略实例。

路由的基本结构

路由配置在 GUI 仪表板的"Routes"页面完成。点击"New Route"按钮，会看到一个表单，包含四个关键字段：

Exchange：选择交易所，比如 Binance Perpetual Futures
Symbol：交易对符号，格式为 BTC-USDT
Timeframe：时间周期，支持 1m、5m、15m、1h、4h、1D 等
Strategy：选择要应用的策略类名

一个典型的路由配置看起来像这样：

# 这行代码在后台自动生成，不需要手动编写
{'exchange': 'Binance Perpetual Futures', 'symbol': 'BTC-USDT', 'timeframe': '5m', 'strategy': 'AwesomeStrategy'}

Jesse 支持同时运行多个路由，这意味着可以在一个项目中交易多个品种或时间周期。比如同时交易 BTC-USDT 的 5 分钟周期和 ETH-USDT 的 1 小时周期：

# 后台自动生成的配置示例
routes = [
    {'exchange': 'Binance Perpetual Futures', 'symbol': 'BTC-USDT', 'timeframe': '5m', 'strategy': 'AwesomeStrategy'},
    {'exchange': 'Binance Perpetual Futures', 'symbol': 'ETH-USDT', 'timeframe': '1h', 'strategy': 'AnotherStrategy'}
]

多时间周期数据路由

专业交易者经常需要参考多个时间周期的数据。比如在 5 分钟图上交易，但用日线判断大趋势。Jesse 通过"Data Routes"（曾用名 Extra Routes）支持这种需求，而且完全避免了未来函数问题。

在 Routes 页面，除了 Trading Routes，还可以添加 Data Routes。Data Routes 不需要指定策略，只提供数据供 Trading Routes 中的策略使用。例如：

# 主交易路由：5m 周期
{'exchange': 'Binance Perpetual Futures', 'symbol': 'BTC-USDT', 'timeframe': '5m', 'strategy': 'AwesomeStrategy'}

# 数据路由：1D 周期用于趋势过滤
{'exchange': 'Binance Perpetual Futures', 'symbol': 'BTC-USDT', 'timeframe': '1D'}

在策略中，可以通过 self.get_candles() 方法访问数据路由的 K 线：

def should_long(self):
    # 获取日线数据
    daily_candles = self.get_candles('Binance Perpetual Futures', 'BTC-USDT', '1D')
    # 计算日线级别的趋势指标
    daily_sma = ta.sma(daily_candles, 20)
    
    # 结合日线趋势和 5m 信号做决策
    if daily_sma > daily_candles[-1][2]:  # 日线收盘价在均线上方
        return self.sma_fast > self.sma_slow  # 5m 金叉信号
    return False

这种设计确保了数据同步的正确性。Jesse 会自动处理不同时间周期之间的对齐问题，策略开发者不需要担心时间戳错位或未来数据泄露。

路由配置的注意事项

路由配置有几个硬性规则需要遵守：

唯一性约束：同一个交易所和交易对不能配置多个交易路由。比如不能同时交易 Binance 的 BTC-USDT 的 5m 和 15m 周期。如果需要多个时间周期，使用 Data Routes。
数量限制：虽然技术上可以配置很多路由，但实盘交易时建议不超过 5 个。每个路由都会建立独立的 WebSocket 连接，过多会导致网络不稳定和交易所限流。
策略匹配：策略类名必须与 strategies 目录下的子目录名完全一致，区分大小写。如果策略文件有语法错误，Jesse 会在启动时给出明确的错误提示。

配置完成后，建议先运行一次回测验证路由设置是否正确。如果策略文件或路由配置有问题，Jesse 会在回测开始前抛出异常，而不是在运行中途失败。

运行首次回测

完成策略生成和路由配置后，终于可以运行第一次回测了。这个过程分为三个步骤：导入历史数据、配置回测参数、执行回测并分析结果。

导入历史 K 线数据

回测需要历史 K 线数据作为输入。Jesse 内置了多个交易所的数据导入驱动，支持从 2018 年至今的数据。

在仪表板左侧菜单点击"Import Candles"，进入数据导入页面。表单需要填写三个字段：

Exchange：选择数据源交易所，通常与路由中的交易所保持一致
Symbol：交易对符号，比如 BTC-USDT
Start Date：数据起始日期，格式为 YYYY-MM-DD

对于 BTC-USDT，建议从 2018-06-01 开始导入，这个时间点有足够的市场深度和流动性。点击"Start"按钮后，Jesse 会开始从交易所 API 拉取数据并存储到 PostgreSQL 数据库。

导入过程可能需要几分钟到几小时，取决于数据量和网络速度。Jesse 会显示进度条和已导入的蜡烛数量。导入完成后，数据会永久存储在本地，后续回测不需要重复下载。

一个实用的技巧是：定期运行相同的导入任务来更新数据。Jesse 会自动跳过已存在的蜡烛，只下载新数据。这样可以在几秒钟内将数据库更新到最新状态。

配置回测参数

数据准备就绪后，进入"Backtest"页面。这里需要配置回测的运行时参数，分为几个部分：

基础配置

Start Date 和 Finish Date：定义回测的时间范围，必须在已导入的数据区间内
Initial Capital：起始资金，建议设置为 10,000 USDT 这样的整数，方便计算百分比收益
Fee：手续费率，Binance 永续合约通常是 0.04% 到 0.06%

高级选项

Debug Mode：启用后会记录详细的执行日志，适合调试策略逻辑，但会显著降低回测速度
Fast Mode：极速模式，跳过一些内部检查，速度提升明显，但不支持多路由回测
Export Charts：生成交易图表，可以直观看到买卖点
Export TradingView：生成 Pine Script 代码，可在 TradingView 查看信号
Export CSV/JSON：导出交易记录，用于外部分析

对于首次回测，建议启用 Export Charts 和 Fast Mode，这样既能看到可视化结果，又不会等待太久。Debug Mode 可以在策略逻辑出现问题时再开启。

执行回测并解读结果

配置完成后，点击"Start"按钮开始回测。Jesse 会创建独立进程执行计算，仪表板可以实时查看进度。回测完成后，结果会显示在多个标签页中。

Metrics 标签页展示核心绩效指标：

Total Net Profit：总净利润，扣除手续费后的绝对收益
Net Profit %：净收益率，相对于初始资金的百分比
Max Drawdown %：最大回撤，资金曲线的最大亏损幅度
Sharpe Ratio：夏普比率，风险调整后的收益指标
Win Rate：胜率，盈利交易占比
Profit Factor：盈亏比，总盈利除以总亏损

这些指标构成了策略评估的基础。一个好的策略应该具备正收益、可控的回撤（通常不超过 30%）、夏普比率大于 1、盈亏比大于 1.5。

Equity Curve 标签页显示资金曲线图。蓝色线条是策略的净值变化，橙色线条是买入持有基准。如果策略曲线平稳向上，且大部分时间高于基准，说明策略有效。

Trades 标签页列出所有交易记录，包括入场时间、价格、出场时间、盈亏等。点击任意一行可以查看该笔交易的详细图表，显示 K 线、指标、订单执行点。

Legacy Charts 提供两种传统图表：权益曲线图和交易分布图。这些图表在后续版本中会被整合到 Metrics 页面，但目前仍是独立的下载选项。

对于首次回测，重点关注以下几点：

策略是否有交易执行？如果交易数量为零，检查 should_long 或 should_short 是否始终返回 False
盈亏是否正常？如果出现异常大的亏损，检查止损逻辑是否正确
订单类型是否合理？Jesse 会自动选择 MARKET、LIMIT、STOP 订单，但可以在日志中确认

如果回测结果不符合预期，不要急于修改策略。先启用 Debug Mode 重新运行，下载日志文件查看每一步的执行细节。日志会记录每个蜡烛的指标值、决策逻辑、订单提交等信息，是定位问题的最佳工具。

完成首次回测后，我们已经走通了 Jesse 策略开发的完整流程。从项目创建到策略生成，从路由配置到回测执行，每个环节都清晰可循。接下来可以深入探索策略逻辑的编写，或者尝试优化参数、增加风险管理等高级功能。Jesse 的模块化设计让每一步扩展都自然流畅，不会破坏已有的工作成果。