alpaca-trading-backtest

交易 API 回测

当你希望 AI Agent 使用 Alpaca CLI 和本地工作区代码运行特定的历史回测时，请使用此技能。此版本针对单次运行进行了优化：你的 Agent 会为已确认的策略编写最少且易读的代码，保存准确的产物，并向你报告结果。

此技能面向通过 AI Agent 调用它的你。你指的是要求 Agent 运行回测的交易者、开发者、研究人员或操作人员。你的 Agent 应直接与你沟通，清楚地重述假设，并明确展示每项解读选择。

strategy idea -> formalized rules -> confirmed assumptions -> CLI data fetch -> local script -> artifacts -> report

这并不意味着策略在实盘市场中一定有效。这是一套可复现的研究工作流。

必要披露

每份报告、notes.md、report.md、笔记本、仪表板或导出结果都应包含：

重要披露
此回测是历史假设模拟，不代表实际交易表现。回测结果不保证未来表现。结果取决于市场数据质量、数据源选择、公司行动处理、费用、滑点、流动性、税费、执行假设和实现细节。此材料仅用于研究和教育目的，不构成投资建议、推荐、要约，也不构成买卖证券、期权、加密货币或任何其他金融产品的招揽。所有投资均涉及风险，且可能贬值。请查看 Alpaca 的披露和协议：alpaca.markets/disclosures。

如果工作流中涉及模拟交易，请添加：

模拟交易是在模拟环境中进行的，不涉及真实资金或实际证券交易。模拟结果可能与实盘交易不同，原因包括成交假设、市场影响、流动性、延迟、数据差异、订单处理、费用和其他市场状况。

当回测对 Alpaca 证券交易活动费用进行建模时，notes.md、summary.json 和 report.md 应链接到 Alpaca Brokerage Fee Schedule PDF：

https://files.alpaca.markets/disclosures/library/BrokFeeSched.pdf

记录 PDF 修订日期、提取时间戳、建模的费用类别，以及有意排除的任何费用项目。

CLI 先决条件

Alpaca CLI

你的 Agent 应使用 Alpaca CLI 访问市场数据。

检查是否已安装：

alpaca version

需要时使用 Go 安装：

go install github.com/alpacahq/cli/cmd/alpaca@latest

在 macOS 或 Linux 上使用 Homebrew：

brew install alpacahq/tap/cli

确保二进制文件目录位于 PATH 中；Go 安装通常使用 ~/go/bin。

本地执行权限

Alpaca CLI 命令应在你的本地工作区中运行，以便访问 Alpaca 配置文件、环境变量、网络连接和已保存的产物。一些 Agent 运行时会将其表示为：

required_permissions: ["all"]

在你的 Agent 环境中使用等效的权限模型，以便 CLI 能访问本地身份验证和配置，并写入运行产物。

连接和身份验证检查

运行任何回测前，请验证 CLI 和凭据：

alpaca doctor

如果身份验证失败，你的 Agent 应停止运行，并向你显示可用的登录或帮助命令：

alpaca profile login --help

交互式模拟账户设置：

alpaca profile login

API 密钥设置：

alpaca profile login --api-key

自动化场景优先使用环境变量，因为这样无需将密钥写入生成的代码：

export ALPACA_API_KEY=PK...
export ALPACA_SECRET_KEY=...
export ALPACA_QUIET=1

你的 Agent 绝不能打印你的密钥、将其提交到文件中、将其包含在报告里，或以会暴露密钥的方式将其传入命令，导致其出现在 shell 历史记录中。

机器可读输出

对于输出将由代码解析的命令，请使用 --quiet：

alpaca account get --quiet
alpaca data bars --symbol SPY --start 2024-01-01 --end 2024-12-31 --timeframe 1Day --quiet

使用已安装 CLI 的帮助信息和架构作为标志及响应字段的准确信息来源：

alpaca --help-all
alpaca data bars --help
alpaca data bars --schema
alpaca data quotes --schema

由于 CLI 根据 API 规范生成且可能发生变化，你的 Agent 应优先采用当前的 --help、--schema 和 alpaca doctor 输出，而不是过时示例。

必需工作流

你的 Agent 应遵循以下工作流：

1. 收集必需输入：开始日期、结束日期、策略概念或策略文件。
2. 收集或推断其余信息：资产类别、标的或范围、时间周期、初始现金、仓位规模、数据源、复权模式、执行假设、基准。
3. 逐项处理运行注意事项：订单模拟、指标、股息、拆股、费用、滑点、价差、市场时段、日历处理和验证。
4. 将你的自由形式想法转换为精确的数学规则。
5. 在编写代码前，向你展示形式化后的解释，除非你的请求已经足够精确地用数学表述。
6. 检查工作区中可复用的数据、先前运行记录和现有工具。
7. 创建一个独立的运行文件夹。
8. 编写 notes.md、strategy_spec.json、config.json 和一个可读的、针对本次运行的脚本。
9. 通过 Alpaca CLI 获取历史数据，保存 CLI 原始输出，筛选所选市场时段内的数据，并计算数据指纹。
10. 运行本地模拟。
11. 写入产物。
12. 返回 Teaching Five、首笔和末笔交易、假设、注意事项、数据指纹和产物路径。

工作区感知

在生成新代码或获取数据之前，你的 Agent 应检查工作区。

数据复用

查找符合以下条件的先前原始数据文件或缓存的标准化数据：

symbol
asset class
feed
adjustment mode
timeframe
start/end range
calendar filter
regular-hours or extended-hours setting

只有在数据指纹匹配时才复用数据。如果指纹不同，你的 Agent 应将这些运行视为使用了不同的输入数据。

运行沿袭

如果本次运行是先前运行的变体，notes.md 应说明变更内容：

changed RSI threshold from 30/70 to 25/75
changed fill model from next_open bar proxy to quote-aware fill
changed slippage from 5 bps to 10 bps
extended date range from 2020-2024 to 2018-2025

现有代码

如果工作区中已有符合策略要求的回测引擎或共享工具，你的 Agent 可以复用。否则，默认在运行文件夹中创建一个易读的 run.py。

运行文件夹和产物规范

此技能中的产物路径使用 raw/ 和 normalized/ 作为规范名称。

每次运行都应创建类似以下结构的文件夹：

runs/YYYY-MM-DD_symbol_strategy_timeframe/
  notes.md
  strategy_spec.json
  config.json
  run.py
  requirements.txt or pyproject.toml when needed
  raw/
    bars_SYMBOL.json
    quotes_SYMBOL.json
    trades_SYMBOL.json
    calendar.json
    corporate_actions.json
  normalized/
    bars_SYMBOL.csv
    quotes_SYMBOL.csv
  summary.json
  report.md
  trades.csv
  round_trips.csv
  equity.csv
  benchmark_equity.csv
  data_fingerprint.json
  warnings.json
  fee_source.json

notes.md

notes.md 应包含你的原始请求、已确认的策略解释、每项推断或设为默认值的假设、指标定义、成交模型、费用模型、数据源和复权模式、股息和拆股处理、基准定义、日历和市场时段处理、警告和注意事项，以及 Alpaca 披露信息和费用表链接。

其他产物

请参阅 reference.md，了解 summary.json、strategy_spec.json、data_fingerprint.json 和 fee_source.json 的架构。

代码生成规则

对于针对单次运行的 CLI 回测，你的 Agent 应生成脚本，而不是可复用的框架。默认使用单文件 run.py。

代码应易于阅读：

fill_price = bar_open * (1 + friction_pct)

而不要使用难以审计产物的压缩表达式。

生成的代码应：

• 从运行文件夹读取原始文件或标准化文件；
• 精确实现已确认的策略；
• 精确实现所选指标定义（参见 指标公式）；
• 将信号时间与成交时间分开处理；
• 根据已确认的假设计算费用、滑点、价差和结算；
• 生成所有必需的产物；
• 包含确定性排序和时区处理；
• 除非明确记录，否则在获取数据后避免隐藏的网络调用。

默认使用 Python 3。如果可用，优先使用标准库以及 pandas/numpy。只有在能显著提升正确性或可读性时才添加依赖。

策略转换

你的 Agent 应在生成代码前将你的想法形式化。

每条规则都应明确：数据字段、触发条件、上下界是否包含端点、指标变体和参数、预热行为、仓位规模和舍入方式、现金处理、订单类型、成交模型和基准。

确认示例：

I interpreted your strategy as:
- Symbol: SPY
- Timeframe: 1Day
- Data: Alpaca CLI bars, feed=sip, adjustment=split
- Indicator: SMA(50) and SMA(200), simple arithmetic mean of completed daily closes
- Entry: fast SMA crosses above slow SMA
- Exit: fast SMA crosses below slow SMA
- Signal timing: completed bar close
- Fill timing: next trading day's open
- Fill model: next_open bar proxy with 5 bps slippage unless quotes are available
- Sizing: invest 100% of available cash, fractional shares allowed when supported
- Benchmark: SPY buy-and-hold with same assumptions

确认后，代码应与已确认的解释一致。

成交模型

在确认信息和 notes.md 中使用这些模型名称。实现细节见 Fill model rules。

• next_open（默认）：在 T 日 K 线收盘时发出信号；在 T+1 日开盘时成交，或在 T+1 日开盘时间戳对应的报价上成交。
• time_based：在确认的某个时刻成交；有报价时使用买入价／卖出价。
• same_bar：仅在明确请求时使用；在 notes.md 和报告中说明前视风险。
• 限价单和止损单：适用 OHLC K 线的成交资格规则；当止损价和目标价在同一根 K 线上都被触及时，采用保守的盘中冲突处理策略。

报告格式

report.md 应以 Performance vs Benchmarks 开篇：

| | Total Return | Ann. Return | Max Drawdown | Sharpe | Final Equity |
|---|---:|---:|---:|---:|---:|
| **Strategy** | ...% | ...% | ...% | ... | $... |
| Benchmark | ...% | ...% | ...% | ... | $... |

表格之后，应包含策略配置、标的／时间周期／数据源／复权方式、成交模型和摩擦成本、首笔和末笔交易、详细指标、基准说明、假设、数据指纹、注意事项，以及披露部分。

指标定义见 reference.md。

聊天回复标准

先给出 Teaching Five：

1. 相对于基准的总回报；
2. 最大回撤；
3. 交易次数；
4. 胜率；
5. 相对于基准的夏普比率。

然后包括：年化回报、盈利因子、已支付费用、首笔交易、末笔交易、所作假设、数据指纹摘要、产物路径，以及最重要的注意事项。

如果没有发生交易，应直接说明，并解释原因是预热期、没有信号、现金不足、数据缺失，还是日历筛选。

运行注意事项清单

运行前，Agent 应逐项确定：

• 订单模拟和成交时机；
• 是否使用感知报价的成交，还是 K 线代理成交；
• 股息处理；
• 拆股和反向拆股处理；
• 执行摩擦成本；
• 从 PDF 得出的交易活动费用；
• 市场交易时段及是否纳入盘前盘后时段；
• 基于日历的决策；
• 基准选择；
• 前视偏差；
• 幸存者偏差；
• 参数调优的样本外或滚动验证；
• 多次尝试不同变体带来的过拟合风险。

对于订单模拟、股息、拆股、费用、日历和基准，如你未指定，应在 notes.md 中记录所作选择。

安全与质量防护要求

Agent 必须避免：

• 在信号生成中使用未来数据；
• 在没有记录 same_bar 模型并发出警告的情况下，使用同一根 K 线做出决策并成交；
• 隐瞒执行假设；
• 将复权 K 线与单独的拆股调整混用；
• 假装含糊的规则已得到完整说明；
• 运行后丢弃生成的代码；
• 除非你提出要求，否则纳入盘前盘后时段的 K 线；
• 悄悄替换指标变体；
• 将开盘价、收盘价、最高价、最低价、VWAP 和报价推导出的价格视为可互换的成交代理价格；
• 报告标注为日夏普比率，却使用每根 K 线的回报来计算；
• 在要求使用样本标准差（N-1）计算夏普比率时，使用总体标准差；
• 将实盘订单作为历史回测的一部分提交；
• 声称支持不受支持的产品——期权需要明确选择合约并制定成交逻辑；
• 绕过 Alpaca CLI，改用直接 HTTP 调用；
• 在没有本地身份验证和文件系统访问权限的沙盒中运行 Alpaca CLI 命令；
• 实现偏离 Fill model rules 的成交逻辑，却不在 notes.md 中记录偏差；
• 对信号触发条件中的 close、high 和 low 混用；
• 悄悄在交叉逻辑和阈值信号逻辑之间自行选择；
• 在单文件脚本足以满足需求时生成多模块引擎。

可选的模拟盘前向验证交接

历史回测完成后，如果你提出要求，Agent 可以准备模拟盘前向验证套件：

paper_config.json
strategy_runtime.py
risk_limits.json
alpaca_order_adapter.py
reconciliation_plan.md

这与历史回测相互独立。该套件应使用明确的风险限额、供自动化使用的客户端订单 ID，并核对预期与实际模拟盘成交情况。

故障排除

command not found: alpaca
  Check PATH and Go install location, commonly ~/go/bin.

alpaca doctor reports auth failure
  Re-run alpaca profile login or set ALPACA_API_KEY and ALPACA_SECRET_KEY.

CLI output includes non-data text
  Use --quiet or set ALPACA_QUIET=1.

Parsed fields changed
  Run <command> --schema and update the parser for the current CLI response.

Rate limited
  Respect Retry-After, reduce request frequency, and use cached data where fingerprints match.

Pagination missing data
  Check next_page_token and fetch all pages.

相关参考

实用命令：

alpaca version
alpaca update --check --quiet
alpaca doctor
alpaca --help-all
alpaca data bars --help
alpaca data bars --schema
alpaca data quotes --schema
alpaca calendar --help

披露链接：

https://alpaca.markets/disclosures
https://files.alpaca.markets/disclosures/library/BrokFeeSched.pdf

CLI 数据采集、指标公式、费用模型、指标、基准和 JSON 架构：reference.md。

相关文件

• reference.md