技能介绍

解决的问题

构建基于 Alpaca 的交易机器人或自动化策略时，需同时处理自有账户交易（Trading API）与代客操作（Broker API）的不同逻辑，易混淆账户操作边界。
订单管理存在多种陷阱：qty 与 notional 同时提供触发 400 错误、碎股交易 TIF 限制不当导致失败、洗单行为引发 403 拒绝，以及订单状态跟踪不及时引发的替换订单失败等问题。
合规与安全风险：API 密钥硬编码、交易输出缺少免责声明，或依赖已废弃的 PDT/日内交易字段，导致流程不合规。

技能如何工作

核心能力：每个技能由 SKILL.md（工作流）与 reference.md（模式、公式、CLI 细节）组成文件对，分 Trading API 和 Broker API 两大模块。Trading API 面向自有账户交易，Broker API 面向代客操作，account_id 需在路径中明确。
关键步骤：

- 订单管理：Broker API 的交易订单管理技能定义 POST /v1/trading/accounts/{id}/orders 用法，强调 qty 与 notional 互斥、碎股交易 TIF 设为 day、client_order_id 作为幂等键等规则。
- 订单状态生命周期：跟踪 accepted（已接收未路由）、new（已路由）、partially_filled（部分成交）、filled（完全成交）等状态，异步等待终态。
- 陷阱处理：针对洗单拒绝（403），建议使用 bracket/oco/trailing_stop；名义订单取消后需重新提交；替换订单时需监听 SSE 事件流以防原始订单先成交。
- 扩展技能：涵盖市场数据（报价、K 线、交易流）、账户开通（KYC）、资金转账、对账与幂等性、速率限制弹性策略、金额精度处理等场景。

安全合规：API 密钥通过环境变量（ALPACA_API_KEY、ALPACA_SECRET_KEY）配置，交易技能输出强制包含免责声明，使用相对路径引用 reference.md。

适用边界与注意点

密钥安全：禁止硬编码 API 密钥，优先使用环境变量。
免责声明：所有交易技能必须在输出中明确风险提示。
路径规范：使用相对路径（如 reference.md），避免绝对安装路径。
常见问题：

- 订单 403 拒绝：检查是否触发洗单，改用 bracket/oco/trailing_stop。
- 碎股交易失败：确认 TIF 为 day，资产 fractionable: true。
- 替换订单后仍被取消：原始订单可能先成交，需监听 SSE 事件流。
- PDT/日内交易字段：自 2026-04-27 起废弃，不再依赖。
- 订单状态混淆：将 accepted、new、pending_new 视为“已存在但未完成”，异步等待终态。