alpaca-trading-paper-trading-cli

Name: alpaca-trading-paper-trading-cli
Author: alpacahq

github.com/alpacahq其他157101 次安装1 周前更新

代码仓库

关于 alpaca-trading-paper-trading-cli

面向使用 Alpaca 纸面交易账户的用户，指导 AI Agent 通过 Alpaca CLI 预览、提交和管理交易订单。流程要求先确认策略与订单配置，并通过 alpaca doctor 验证命令行连接到纸面端点。

主要功能

01确认交易策略和订单配置
02使用 alpaca doctor 核验纸面端点
03预览订单并展示将执行的命令
04提交并检查订单状态
05覆盖股票、期权及加密货币交易

适用场景

01在纸面账户测试交易策略
02提交前检查订单参数与风险控制
03独立核验订单编号、状态和提交内容
04跟踪成交、拒绝及取消情况

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/alpacahq/alpaca-skills --skill alpaca-trading-paper-trading-cli

安装后在 Claude Code 中输入/alpaca-trading-paper-trading-cli确认已加载。

附带文件reference.md

详细介绍

Alpaca 纸面交易 — CLI 版本

当你希望 AI Agent 使用 Alpaca CLI 预览、提交、检查和管理纸面交易订单时，请使用此技能。

此技能面向你——一位使用自己的 Alpaca 纸面交易账户、CLI 配置和本地工作区的 Trading API 用户。你的 Agent 通过 alpaca 命令行工具执行所有操作，让你可以全面查看每条命令及其输出。

这是 CLI 专用版本。另有通用（与实现无关）版本和 MCP 服务版本作为配套技能提供。

0 - AI Agent 应如何使用此技能

从信号来源入手。 确定交易想法的来源——回测结果、手动想法、计划触发器或策略输出。
重述策略逻辑并与你确认。 总结交易论点、预期行为以及订单执行的条件。继续之前先等待你的确认。
收集并确认所有配置。 时间、资产类别、标的、方向、数量/名义金额、订单类型、有效时间、限价/止损价、延长交易时段标志、风险控制和保证金使用情况——必须逐一说明并确认每个参数。
确认 CLI 指向纸面交易端点。 运行 alpaca doctor，并要求其 Trading: 行显示 https://paper-api.alpaca.markets。如果显示实盘端点，立即停止并提醒你。
使用格式化表格展示完整的订单预览。 包含将要运行的确切 CLI 命令。
询问你是否希望在每笔订单前获得明确确认（默认：开启）。在本次会话中遵从你的偏好。
使用纸面交易配置通过 alpaca order submit 提交订单。
返回订单 ID、状态、已提交的载荷以及后续检查命令，以便你独立核实。
使用 alpaca order get 监控订单生命周期。 报告成交、拒绝、取消情况及其对投资组合的影响。
绝不进行实盘交易。 每次提交前都要确认解析出的纸面交易端点。如果环境存在任何歧义，立即停止。

1 - 前提条件

已安装 Alpaca CLI 且位于 PATH 中

alpaca version

如有需要，请安装：

# Homebrew (macOS / Linux)
brew install alpacahq/tap/cli

# Or with Go — requires $GOPATH/bin (typically ~/go/bin) on your PATH
go install github.com/alpacahq/cli/cmd/alpaca@latest

CLI 目前处于 Alpha Preview 阶段。命令、标志和输出格式可能会随版本发布而变化，因此你的 Agent 会在运行时发现标志，而不是依赖此文件中的列表。

已配置纸面交易配置

alpaca profile login
# or with API key
alpaca profile login --api-key

查看登录选项：

alpaca profile login --help

已验证连接

alpaca doctor

你的 Agent 会在每个交易时段开始前运行此检查。如果失败，则不会提交任何订单。

资产类别要求

资产类别	要求
美国股票	纸面交易账户已激活
期权	纸面交易账户已启用期权交易
加密货币	纸面交易账户已启用加密货币交易

环境

Go 工具链，仅在通过 go install 安装时需要；Homebrew formula 提供预构建二进制文件，无需 Go
uuidgen 或等效工具（用于客户端订单 ID）

不需要外部 jq。CLI 内置 --jq 标志，可筛选其自身的 JSON 输出。

2 - 收集输入

在继续构建订单之前，你的 Agent 会收集以下信息：

参数	说明	默认值	必填
`signal_source`	交易想法的来源（回测、手动、定时、策略）	—	是
`symbol`	股票代码（例如，AAPL、BTC/USD、AAPL250718C00200000）	—	是
`asset_class`	`us_equity`、`us_option`、`crypto`	`us_equity`	是
`side`	`buy` 或 `sell`	—	是
`qty`	股票 / 合约 / 代币数量	—	是（或填写名义金额）
`notional`	美元金额（适用于零碎股）。仅限 TIF 为 `day` 的市价单；不能与 `qty` 同时使用	—	是（或填写 `qty`）
`order_type`	`market`、`limit`、`stop`、`stop_limit`、`trailing_stop` — 支持的值因资产类别而异	`market`	是
`time_in_force`	`day`、`gtc`、`ioc`、`fok`、`opg`、`cls` — 支持的值因资产类别而异	股票和期权为 `day`；加密货币为 `gtc`	是
`order_class`	`simple`、`bracket`、`oco`、`oto`（股票）；`simple`、`mleg`（期权）；`simple`（加密货币）	`simple`	否
`limit_price`	限价单 / 限价止损单必填	—	视情况而定
`stop_price`	止损单 / 限价止损单必填	—	视情况而定
`trail_percent`	用于 `trailing_stop`	—	视情况而定
`trail_price`	用于 `trailing_stop`	—	视情况而定
`extended_hours`	允许盘前 / 盘后成交	`false`	否
`client_order_id`	幂等键，最多 128 个字符	若省略，由 Alpaca 自动生成	否
`profile`	Alpaca CLI 配置文件名称。在整个会话中通过 `ALPACA_PROFILE` 环境变量设置 — 切勿使用 `-p` / `--profile` 标志。参见第 10 步中的警告	当前处于活动状态的模拟交易配置文件	否
`output_format`	默认为 JSON；使用 `--csv` 输出 CSV，使用 `--jq '<expr>'` 进行筛选	JSON	否
`confirmation_mode`	每次下单前都需要明确确认	`ON`	否
`max_position_pct`	单个持仓占投资组合的最大百分比	无	否
`max_order_value`	单笔订单名义金额的硬性上限	无	否

策略确认清单

构建订单之前，你的 Agent 会确认：

策略逻辑已清楚说明
你了解订单将产生的效果
已满足入场条件（若来自回测 / 信号）
已讨论出场条件 / 止损计划
持仓规模经过审慎确定
已检查风险控制措施

3 - 事实来源参考

你的 Agent 会使用以下权威来源进行验证：

来源	URL	用途
创建订单	https://docs.alpaca.markets/us/reference/postorder	订单参数、各资产类别的限制、状态代码
Alpaca CLI 文档	https://docs.alpaca.markets/us/docs/alpacas-cli	CLI 命令、标志、语法
订单类型	https://docs.alpaca.markets/us/docs/orders-at-alpaca	订单类型的行为和要求
模拟交易	https://docs.alpaca.markets/us/docs/paper-trading	模拟环境的具体信息
期权交易	https://docs.alpaca.markets/us/docs/options-trading	期权订单要求和审批级别
加密货币交易	https://docs.alpaca.markets/us/docs/crypto-trading	加密货币订单的具体信息
Alpaca 披露信息	https://alpaca.markets/disclosures	披露声明内容

CLI 发现规则

你的 Agent 会在运行时验证标志，而不是盲目依赖此文件：

alpaca --help-all              # full command tree with every flag
alpaca order submit --help     # flags for one command
alpaca order submit --schema   # response shape, without calling the API

CLI 目前处于 Alpha 预览阶段，因此不同版本之间的标志和输出格式可能会发生变化。本技能中的任何内容若与 --help 输出矛盾，均视为过时；以 CLI 为准。

4 - 工作流

阶段 1：策略确认

步骤 1 — 确认信号来源。

Agent 会询问：“这个交易想法来自哪里？”选项包括：

已完成的回测（如有，请提供运行文件夹的链接）
你描述的手动交易想法
预定或定期触发的策略
其他技能或系统的输出

步骤 2 — 重述策略逻辑。

Agent 会总结：

交易论点（为何进行这笔交易）
预期结果
时间范围
退出条件或止损计划

步骤 3 — 确认理解。

Agent 会询问：“我的理解正确吗？要继续配置订单吗？”

阶段 2：配置确认

步骤 4 — 确认资产类别和符号。

你的 Agent 会验证符号格式：

股票：AAPL、MSFT
期权：OCC 格式 AAPL250718C00200000
加密货币：BTC/USD、ETH/USD

格式正确是必要条件，但并非充分条件——格式规范的符号仍可能无法交易或已退市。你的 Agent 会根据资产记录进行确认：

alpaca asset get --symbol-or-asset-id AAPL

它要求 status = active 且 tradable = true，并在提出名义金额或零股数量订单前检查 fractionable。对于期权，它会使用 alpaca option contracts --underlying-symbols AAPL 查询真实合约，而不是手动拼接 OCC 字符串。

步骤 5 — 确认方向、数量和订单类型。

步骤 6 — 确认有效期和定价参数。

不同资产类别的有效期并不统一。你的 Agent 会在构建命令前验证参数组合，因为 API 会拒绝无效组合：

资产类别	订单类型	有效期	订单类别
美国股票	`market`、`limit`、`stop`、`stop_limit`、`trailing_stop`	`day`、`gtc`、`opg`、`cls`、`ioc`、`fok`	`simple`、`bracket`、`oco`、`oto`
美国期权	`market`、`limit`、`stop`、`stop_limit`（`stop` 类型仅适用于单腿订单）	`day`、`gtc`	`simple`、`mleg`
加密货币	`market`、`limit`、`stop_limit`	`gtc`、`ioc`——但 `stop_limit` 仅支持 `gtc`，且 `ioc` 仅适用于 `market` 和 `limit`	`simple`

CLI 会根据符号形式自动提供有效期默认值：包含 / 的符号（即加密货币交易对）默认使用 gtc，其他符号默认使用 day。因此，提交加密货币订单时若未指定 --time-in-force，会发送 gtc，而不是 day。

Alpaca 自身的资料对期权这一行存在分歧，因此应将其视为指南，而非硬性限制。OpenAPI 规范中的 TimeInForce/OrderType 描述指出，期权支持 market/limit，且仅支持 day；期权交易页面和下单矩阵则都允许 gtc，也都允许单腿订单使用 stop/stop_limit。两个产品页面彼此一致，但与规范文档不一致，因此本表遵循这两个页面。你的 Agent 仍会默认使用较为保守的 day，并允许 Alpaca 拒绝订单，而不会预先拦截矩阵允许的订单。

以下限制适用于多种订单类型：

延长交易时段要求订单类型为 limit，且有效期为 day 或 gtc。其他所有类型和有效期都会被直接拒绝。
追踪止损仅支持 day 和 gtc。
名义金额订单仅限有效期为 day 的市价订单，不能与 qty 同时使用，且不可替换——应取消后重新提交。
Bracket、OCO 和 OTO类别要求有效期为 day 或 gtc，不支持延长交易时段，且仅适用于股票。
期权完全不支持延长交易时段。多腿策略使用 mleg 订单类别，最多包含 4 条腿；stop/stop_limit 类型仅适用于单腿订单。

步骤 7 — 确认延长交易时段和客户端订单 ID 偏好设置。

Alpaca 支持常规交易时段之外的三个时段，这些时段都要求限价订单设置 extended_hours: true：

时段	时间范围（ET）	日期
隔夜	8:00pm – 4:00am	周日至周五
盘前	4:00am – 9:30am	周一至周五
盘后	4:00pm – 8:00pm	周一至周五

并非所有资产都支持隔夜交易；你的 Agent 会根据资产记录确认资格，而不是想当然。

步骤 8 — 检查风险控制措施。

你的 Agent 会展示任何仓位规模或最大价值限制，并验证：

订单名义金额是否超过购买力
新仓位相对于投资组合的集中度
同一符号的现有风险敞口

步骤 9 — 最终配置摘要。

你的 Agent 会显示完整的参数表，并询问：“所有参数都确认了吗？”

阶段 3：通过 CLI 验证模拟账户

步骤 10 — 确认 CLI 解析到模拟账户端点：

alpaca doctor

alpaca doctor 会在 Connectivity: 下方打印完全解析后的交易端点：

Connectivity:
  Trading:  https://paper-api.alpaca.markets

你的 Agent 要求该行显示 https://paper-api.alpaca.markets。配置文件名称不能替代此检查。CLI 会按照固定顺序解析模拟账户还是实盘账户：先检查 ALPACA_LIVE_TRADE，然后检查当前配置文件的 live_trade 字段，最后默认为模拟账户。因此，导出的 ALPACA_LIVE_TRADE=true 会让名为 "paper" 的配置文件直接指向实盘端点。alpaca doctor 会报告整个解析链的结果。

⚠️ alpaca doctor 会忽略 -p/--profile 标志。 它会接受该标志，但静默丢弃其值，始终报告默认配置文件。其他所有命令都会遵循 -p。因此，alpaca doctor -p live 会报告模拟账户端点，而 alpaca order submit -p live 会使用实盘账户进行交易，导致检查通过，但订单却发到了实盘。

因此，你的 Agent 绝不会向任何命令传递 -p/--profile。 若要指定非默认配置文件，它会为整个会话设置一次 ALPACA_PROFILE，而 doctor 也会遵循该设置，因此检查和订单会解析到相同的端点。如果会话中的任何命令即将收到 -p，你的 Agent 就会停止。

如果 Trading: 行显示 https://api.alpaca.markets，你的 Agent 会立即停止：

⚠️ 检测到实盘端点。你的 Agent 不会继续操作。请取消设置 ALPACA_LIVE_TRADE（或将其设为 false，即使使用实盘配置文件也会强制使用模拟账户），使用 alpaca profile switch <paper-profile-name> 选择模拟账户配置文件，然后重新启动。

步骤 11 — 确认同一份 alpaca doctor 输出中的连接状态。

你的 Agent 会确认所有检查均已通过。如果任何检查失败，它会报告失败原因并停止操作。它不会再次运行 alpaca doctor；一次调用即可涵盖此步骤和步骤 10。所有检查均通过时，alpaca doctor 退出码为 0；任一检查失败时，退出码为 1。

步骤 12 — 获取账户状态：

alpaca account get

你的 Agent 会解析并验证：

status = ACTIVE
account_blocked = false
trading_blocked = false
trade_suspended_by_user = false
multiplier — 保证金分类，也是账户对象携带的唯一 PDT 信号：1 表示受限保证金的现金型账户，2 表示 Reg T 保证金账户，4 表示具有 4 倍日内购买力的 PDT 账户

Trading API 账户对象不包含 pattern_day_trader 或 daytrade_count 字段。你的 Agent 不得读取这些字段，而应根据 multiplier 推断 PDT 状态。

步骤 13 — 检查购买力：

alpaca account get --jq '.buying_power'

你的 Agent 会将预估订单价值与可用购买力进行比较。如果购买力不足，它会在继续操作前向你发出警告。

步骤 14 — 对于期权订单，检查审批级别：

alpaca account get --jq '{options_approved_level, options_trading_level, options_buying_power}'

你的 Agent 会依据 options_trading_level 进行限制。该值表示有效级别，即 options_approved_level 与账户配置中的 max_options_trading_level 两者中的较低值。即使已获审批，如果配置将级别限制得更低，也无权进行交易。

级别	允许的操作
`0`	禁止期权交易
`1`	备兑看涨期权、现金担保看跌期权
`2`	买入看涨期权和看跌期权（在级别 1 的基础上增加）
`3`	价差和跨式组合（在级别 2 的基础上增加）

价差交易要求级别为 3，而非级别 2。

步骤 15 — 显示账户摘要。

你的 Agent 会展示：

┌─────────────────────────────────────┐
│ Paper Account Summary               │
├─────────────────────────────────────┤
│ Endpoint:      paper-api (PAPER)    │
│ Profile:       my-paper             │
│ Status:        ACTIVE               │
│ Equity:        $50,000.00           │
│ Buying Power:  $100,000.00          │
│ Multiplier:    2 (Reg T margin)     │
│ Options Level: 2 (effective)        │
│ Crypto:        ACTIVE               │
└─────────────────────────────────────┘

第 4 阶段：订单预览

步骤 16 — 构建 CLI 命令，但暂不执行。

你的 Agent 构建完整命令并显示出来，然后使用 --dry-run 验证。该选项会打印 CLI 将发送的请求正文，但不会提交任何内容：

alpaca order submit \
  --symbol AAPL \
  --side buy \
  --qty 10 \
  --type limit \
  --limit-price 185.50 \
  --time-in-force day \
  --client-order-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --dry-run

你的 Agent 在预览中展示的命令，必须与之后实际执行的命令逐字节相同，唯一的区别是去掉 --dry-run。

步骤 17 — 显示格式化的订单预览表：

┌─────────────────────────────────────────────┐
│ ORDER PREVIEW — NOT YET SUBMITTED           │
├─────────────────────────────────────────────┤
│ Symbol:         AAPL                        │
│ Side:           BUY                         │
│ Quantity:       10 shares                   │
│ Order Type:     LIMIT                       │
│ Limit Price:    $185.50                     │
│ Time in Force:  DAY                         │
│ Extended Hours: No                          │
│ Est. Value:     $1,855.00                   │
│ Buying Power:   $100,000.00 → $98,145.00   │
│ Client ID:      a1b2c3d4-...               │
│ Endpoint:       paper-api (PAPER)           │
├─────────────────────────────────────────────┤
│ ⚠️  This is a PAPER trade — no real money   │
└─────────────────────────────────────────────┘

步骤 18 — 如果确认模式为 ON：等待明确回复“yes”后再继续。

步骤 19 — 如果确认模式为 OFF：显示预览，然后自动提交。

第 5 阶段：订单提交

步骤 20 — 执行 CLI 命令：

CLIENT_ORDER_ID="$(uuidgen)"

alpaca order submit \
  --symbol AAPL \
  --side buy \
  --qty 10 \
  --type limit \
  --limit-price 185.50 \
  --time-in-force day \
  --client-order-id "$CLIENT_ORDER_ID"

你的 Agent 会在提交前捕获 CLIENT_ORDER_ID，这样即使命令在打印响应前退出，也能恢复订单。

步骤 21 — 将 CLI 原始输出保存到运行文件夹：

# Output saved to runs/<timestamp>-paper-trading-cli/raw/order_submit_response.json

步骤 22 — 解析响应中的关键字段：

id（订单 ID）
status（预期值：new 或 accepted）
created_at
filled_at（待处理时为 null）
filled_qty
filled_avg_price

步骤 23 — 发生失败时：

从 stderr 中捕获结构化 JSON 错误以及 CLI 退出代码——0 表示成功，1 表示错误，2 表示身份验证失败
提供解决问题的指导（例如“购买力不足”“未找到交易品种”“市场已休市”）
将错误保存到 runs/<timestamp>/raw/error.json
建议纠正措施

如果失败情况不明确——例如超时、进程被终止，或任何无法判断订单是否已到达 Alpaca 的情况——则绝不能重新提交。你的 Agent 会通过其在步骤 20 中生成的客户端订单 ID 查询订单：

alpaca order get-by-client-id --client-order-id "$CLIENT_ORDER_ID"

查询到订单意味着订单已存在，重新提交会造成重复。只有确认未找到订单时，才有理由重试。

第 6 阶段：提交后监控

步骤 24 — 检查订单状态：

alpaca order get --order-id {order_id}

你的 Agent 会报告：

当前状态
成交进度（部分成交情况）
平均成交价格

步骤 25 — 列出近期订单以供参考：

alpaca order list --status open

步骤 26 — 向你返回订单摘要：

┌─────────────────────────────────────────────┐
│ ORDER SUBMITTED ✓                           │
├─────────────────────────────────────────────┤
│ Order ID:      abc-123-def-456              │
│ Status:        NEW                          │
│ Symbol:        AAPL                         │
│ Side/Qty:      BUY 10                       │
│ Type:          LIMIT @ $185.50              │
│ Submitted:     2026-07-26T14:30:00Z         │
├─────────────────────────────────────────────┤
│ Next commands:                              │
│  alpaca order get --order-id abc-123      │
│  alpaca order cancel --order-id abc-123     │
│  alpaca position list                     │
└─────────────────────────────────────────────┘

步骤 27 — 订单生命周期更新：

事件	Agent 操作
`filled`	报告成交价格，计算相对于限价的滑点，并显示持仓影响
`partially_filled`	报告已成交数量、剩余数量和平均价格
`rejected`	显示拒绝原因，并建议修正方法
`canceled`	确认取消，并显示最终状态
`expired`	报告订单过期（TIF 已到期），并建议重新入场
`replaced`	确认替换参数，并显示新订单 ID

第 7 阶段：投资组合影响

步骤 28 — 获取持仓：

alpaca position list

或获取特定交易品种的持仓：

alpaca position get --symbol-or-asset-id AAPL

步骤 29 — 获取更新后的账户信息：

alpaca account get

步骤 30 — 显示投资组合风险摘要：

┌─────────────────────────────────────────────┐
│ PORTFOLIO IMPACT                            │
├─────────────────────────────────────────────┤
│ New Position:   AAPL — 10 shares @ $185.30  │
│ Position Value: $1,853.00                   │
│ Portfolio %:    0.74%                       │
│ Buying Power:   $98,147.00 (was $100,000)   │
│ Total Equity:   $250,000.00                 │
│ Open Orders:    1                           │
└─────────────────────────────────────────────┘

第 8 阶段：订单管理

步骤 31 — 取消特定订单：

alpaca order cancel --order-id {order_id}

你的 Agent 会确认取消，并报告订单最终状态。

步骤 32 — 取消所有未结订单。

cancel-all 不限定范围：它会取消账户中的每一笔未结订单，包括本次会话未创建的订单。CLI 会立即执行，不会自行提示确认，因此需要由你的 Agent 设置确认关卡。它会先准确显示将被取消的订单：

alpaca order list --status open --jq '[.[] | {id, symbol, side, qty, type, limit_price}]'

你的 Agent 会列出这些订单并说明数量，且要求明确回复“yes”——即使 confirmation_mode 为 OFF 也不例外，因为该设置控制的是订单提交，而非批量取消。只有得到确认后，才会执行：

alpaca order cancel-all

你的 Agent 会确认取消总数，并列出受影响的订单。同样的确认关卡也适用于会清空整个投资组合的 alpaca position close-all。

步骤 33 — 替换订单（修改价格/数量）：

先查看可用标志：

alpaca order replace --help

然后执行：

alpaca order replace --order-id {order_id} --qty 5 --limit-price 186.00

你的 Agent 会报告新订单 ID 和更新后的参数。

阶段 9：部署指南（按需提供）

当你询问自动化时，Agent 会为你提供以下指导：

Bash 脚本包装器。 自动提交必须通过一个包装器，该包装器会在下单前验证论文端点。任何计划任务都不会直接调用 alpaca order submit，因此无论由哪个调度器调用，都无法绕过这项防护：

#!/bin/bash
# /usr/local/bin/paper-trade.sh
set -euo pipefail

SYMBOL="${1:?usage: $0 SYMBOL SIDE QTY}"
SIDE="${2:?usage: $0 SYMBOL SIDE QTY}"
QTY="${3:?usage: $0 SYMBOL SIDE QTY}"

# Verify the CLI resolves to the paper endpoint
if ! alpaca doctor | grep -q 'Trading:.*https://paper-api\.alpaca\.markets'; then
  echo "ERROR: CLI is not pointed at the paper endpoint. Exiting." >&2
  exit 1
fi

alpaca order submit \
  --symbol "$SYMBOL" \
  --side "$SIDE" \
  --qty "$QTY" \
  --type market \
  --time-in-force day \
  --client-order-id "$(uuidgen)"

Cron 作业。 Cron 调用包装器，而不是原始 CLI：

# /etc/cron.d/paper-trade
SHELL=/bin/bash
PATH=/usr/local/bin:/usr/bin:/bin
ALPACA_PROFILE=paper
0 9 * * 1-5 root /usr/local/bin/paper-trade.sh AAPL buy 1 >> /var/log/paper-trades.log 2>&1

Cron 运行时几乎没有环境变量，也不会加载你的 shell 配置文件，因此必须显式设置 PATH、ALPACA_PROFILE 和凭据——可以像上文一样写在 crontab 中，也可以在包装器中从仅作业用户可读取的文件加载。计划作业在不继承任何环境变量的情况下运行时，未经防护的提交最为危险：没有操作员监看，也没有提示词，因此端点检查应放在脚本中，而不是调度配置中。

systemd 计时器 / launchd plist： Agent 会为你的操作系统生成相应的服务文件，并让它指向同一个包装器。

CI/CD 流水线。 安装 CLI，从运行器的密钥存储进行身份验证，然后调用同一个包装器——绝不能把 alpaca order submit 作为单独步骤直接调用：

- name: Submit paper order
  env:
    ALPACA_API_KEY: ${{ secrets.ALPACA_PAPER_API_KEY }}
    ALPACA_SECRET_KEY: ${{ secrets.ALPACA_PAPER_SECRET_KEY }}
    ALPACA_PROFILE: paper
  run: ./scripts/paper-trade.sh AAPL buy 1

CI 是最容易意外连接到实盘的地方：运行器没有你的配置文件，密钥来自某人配置的密钥，而调用时，名为 paper 的密钥和正确密钥看起来完全一样。把密钥命名为 PAPER 并不能证明任何事，因此，能够确认端点的是包装器中的 alpaca doctor 检查，而不是变量名。

自动化注意事项：

CLI 从不显示提示。无论在自动化流程中还是交互使用时，都没有需要抑制的“确定吗？”对话框——这正是为什么本技能中的确认关卡应由 Agent 负责，而不是交给 CLI。
--quiet 会抑制警告、提示和颜色。它并不是让输出变得适合机器读取的原因；无论是否使用该选项，默认输出格式都是 JSON。在 cron 和 CI 中使用它可让日志保持整洁。
ALPACA_OUTPUT=json|csv 可为整个脚本设置默认输出格式。
所有无人值守的执行路径——cron、systemd、launchd、CI——都必须通过受防护的包装器提交。任何调度器或流水线都不会直接调用 alpaca order submit，因此即使添加新的触发器，也无法跳过端点检查。
记录所有输出，以便审计。
在重试场景中使用 --client-order-id 实现幂等性。

5 - 执行规则

通用规则

仅限 Paper。 绝不向实盘端点提交订单。每次提交前都要验证解析后的端点。
提交前确认。 默认启用明确确认。遵循用户偏好。
保持原意。 未经你明确同意，绝不修改订单参数。
原子操作。 每次订单提交相互独立。一次失败不会影响其他订单。
完全透明。 执行前后都要展示每条 CLI 命令。
幂等性。 始终生成 --client-order-id，以防重试时重复提交。
不提供财务建议。 Agent 按照你的指示执行，不会推荐交易。

CLI 特定规则

切勿向任何命令传递 -p/--profile。 alpaca doctor 会忽略此参数，因此纸面交易检查和订单可能会解析到不同的配置文件。请改用 ALPACA_PROFILE 设置当前会话。
解析默认 JSON 输出。 每个命令都会直接返回结构化 JSON。使用 --jq '<expr>' 进行筛选，仅在面向用户的表格中使用 --csv。--quiet 会抑制警告、提示和颜色；不会改变数据格式。
切勿将输出通过管道传给外部 jq。 内置的 --jq 标志可完成相同工作，且少一个依赖项。
在假定语法之前，务必使用 --help、--help-all 和 --schema 查看标志。 CLI 处于 Alpha Preview 阶段，版本之间可能会有变化。
将所有原始 CLI 输出保存到运行文件夹。 每个命令的标准输出和标准错误都应写入 raw/。
如果 alpaca doctor 失败，请勿继续。 报告失败并停止。
在摘要中对配置文件详细信息和令牌进行脱敏。 切勿在输出文件中泄露 API 密钥或机密。
处理 CLI 退出代码。 0 表示成功，1 表示错误，2 表示身份验证失败。捕获标准错误并将其呈现出来。
不要自行添加速率限制重试循环。 CLI 已会对 429 和 5xx 响应最多重试三次，并遵循 Retry-After。在此基础上再增加一层退避机制，会让一次受速率限制的调用变成更长时间的停滞。如果命令在 CLI 重试后仍失败，请呈现错误并停止。
提交前使用 --dry-run 预览。 该选项会打印确切的请求正文，而不会发送订单。
对未限定范围的破坏性命令设置门槛。 order cancel-all 和 position close-all 会影响整个账户。无论 confirmation_mode 如何，都必须获得明确确认。

6 - 输出约定

每次纸面交易会话都会生成一个运行文件夹：

runs/<YYYYMMDD-HHMMSS>-paper-trading-cli/
  notes.md                        # Session narrative: strategy, decisions, outcomes
  raw/                            # Saved raw CLI outputs
    account.json                  # Account state at session start
    order_submit_response.json    # Raw submission response
    order_status.json             # Order status checks
    positions.json                # Position state after fills
    clock.json                    # Market clock at submission time
    error.json                    # Error output (if any)
  orders.json                     # Structured order records
  order_log.csv                   # Tabular log: timestamp, action, order_id, status, details
  positions_snapshot.json         # Position state post-trade
  portfolio_summary.md            # Human-readable portfolio impact
  review.md                       # Session review: what worked, issues, next steps

notes.md 结构

# Paper Trading Session — <timestamp>

## Signal Source
<origin of trade idea>

## Strategy
<strategy logic as confirmed>

## Orders Submitted
| # | Symbol | Side | Qty | Type | Status | Fill Price |
|---|--------|------|-----|------|--------|-----------|

## Portfolio Impact
<post-trade portfolio state>

## Issues / Notes
<any errors, warnings, or observations>

order_log.csv 列

timestamp,action,order_id,symbol,side,qty,type,limit_price,stop_price,tif,status,fill_price,fill_qty,error

7 - 验证和测试

你的 Agent 会在执行期间运行以下检查。

提交前验证

检查项	命令	通过条件
CLI 已安装	`alpaca version`	退出代码为 0
连通性	`alpaca doctor`	所有检查均通过
纸面交易端点	`alpaca doctor`	`Trading:` 行显示 `https://paper-api.alpaca.markets`
账户处于活动状态	`alpaca account get`	status=ACTIVE，且未被封锁
购买力	`alpaca account get --jq '.buying_power'`	足以满足订单要求
市场开放	`alpaca clock`	`is_open=true`（除非为延长交易时段或 GTC）
标的有效且可交易	`alpaca asset get --symbol-or-asset-id X`	`status=active`，`tradable=true`

提交后验证

检查项	命令	通过条件
订单已接受	`alpaca order get --order-id X`	状态 != rejected
已收到成交	同上	filled_qty > 0
持仓已更新	`alpaca position get --symbol-or-asset-id X`	反映新的持仓

8 - 披露、安全和数据处理

披露事项

仅限模拟交易。 此技能仅在 Alpaca 模拟交易环境中运行，不涉及真实资金风险。
不构成财务建议。 你的 Agent 会执行你的指令，但不会提供投资建议、市场预测或交易建议。
模拟交易 ≠ 实盘交易。 由于成交模拟经过简化，模拟交易的成交情况可能与实盘执行不同。不要假设模拟交易的结果能够预测实盘表现。
由你负责。 你要对选择进行模拟交易的策略负责。你的 Agent 是工具，不是顾问。
完整披露。 请查看 Alpaca 的披露文件和协议：alpaca.markets/disclosures。

重要披露： 本材料仅用于提供信息、教育和研究，不构成投资建议、推荐、购买或出售证券、期权、加密货币或任何其他金融产品的要约或招揽。所有投资和交易都涉及风险，包括可能损失本金。模拟交易属于模拟操作，在成交、市场影响、流动性、费用、延迟和其他方面可能与实盘交易不同。请查看 Alpaca 的披露文件：https://alpaca.markets/disclosures。

安全控制

控制项	实现方式
防止实盘交易	每次提交前检查解析后的端点
确认关卡	默认开启 — 必须明确确认
购买力检查	提交前验证
连接验证	在会话开始时运行 `alpaca doctor`
错误隔离	记录失败，不让错误级联
幂等性	`--client-order-id` 可防止重复

数据处理

仅限本地。 所有运行数据都保留在 runs/ 下的本地工作区中。
无遥测。 除 Alpaca API 外，你的 Agent 不会向外部服务发送交易数据。
凭证安全。 API 密钥绝不会被记录、显示或写入文件。共享输出中会隐藏配置文件名称。
审计跟踪。 每条 CLI 命令及其响应都会保存到 raw/，供你审查。

9 - 反模式

你的 Agent 绝不能：

反模式	原因	正确做法
向实盘端点提交请求	有资金损失风险	始终先确认 `alpaca doctor` 报告的是模拟交易端点
在模式开启时跳过确认	你会失去控制权	始终遵循确认偏好
悄悄修改订单参数	违背你的意图	参数有任何变更都要重新确认
提供交易建议	这会带来责任风险，而且不属于 Agent 的职责	执行指令，不要提出建议
将 CLI 标志硬编码	Alpha Preview — 标志可能随版本变化	使用 `--help`、`--help-all` 和 `--schema` 探查
将输出通过管道传给外部 `jq`	增加了 CLI 已自带的依赖	使用内置的 `--jq` 标志
将 `--quiet` 当作 JSON 开关	JSON 是默认格式；`--quiet` 只会隐藏警告、提示和颜色	直接解析默认输出
读取 `pattern_day_trader` 或 `daytrade_count`	这两个字段都不存在于 Trading API 账户对象中	根据 `multiplier` = `4` 推断 PDT
为 429 错误添加重试循环	CLI 已自动重试 3 次并遵循 `Retry-After`	重试失败后报告错误
未经提示运行 `cancel-all` 或 `close-all`	未限定范围——会影响本次会话未创建的订单和持仓	列出受影响的内容，并要求明确确认
绕过 Alpaca CLI，直接调用 HTTP	这是 CLI 版本	只使用 `alpaca` 命令
忽略 CLI 退出代码	可能漏掉错误	检查退出代码并捕获 stderr
`alpaca doctor` 失败后仍继续	尚未验证连通性	停止并报告失败
在运行文件夹中存储 API 密钥	存在安全风险	对所有凭据进行脱敏
假设市场交易时段	可能有延长时段／加密货币市场全天候交易	检查 `alpaca clock`
未检查购买力就提交	订单会被拒绝	先验证购买力
使用 `--csv` 输出进行程序化解析	结构化程度不如 JSON	解析默认 JSON，并使用 `--jq` 过滤

10 - 相关文件

文件	用途
`reference.md`	详细参考：订单类型、TIF、生命周期、资产类别、错误

配套技能

技能	说明
`alpaca-trading-backtest`	通过 Alpaca CLI 进行历史回测——生成此技能可以执行的信号
`alpaca-trading-paper-trading`	通用且与实现方式无关的模拟交易技能
`alpaca-trading-paper-trading-mcp`	此技能的 MCP 服务版本

支持 Markdown

登录后评论

基本信息

作者: alpacahq
仓库: alpacahq/alpaca-skills
分类: 其他
安装次数: 101
GitHub Stars: 157

报告问题