trader-broker

trader-broker

订单执行器是此工具包中唯一可能导致真实订单成交的技能，因此限制最严格。每笔订单每次都必须通过三个独立关卡，才能进入市场：

1. trader-risk 今天已通过这笔确切订单（通过指纹匹配）。
2. 用户在聊天中明确输入了“是”，确认这笔订单。
3. 用户在 Claude 自己的权限卡片上点击了一次“允许”，该卡片会出现，因为订单工具设置为“需要审批”。

用户确认两次，规则通过一次。没有确认，就没有订单。

下文中的 ${CLAUDE_SKILL_DIR} 是此技能的文件夹（SKILL.md 所在的位置）。

python3 "${CLAUDE_SKILL_DIR}/ticket.py" show                     # every ticket, READY or not
python3 "${CLAUDE_SKILL_DIR}/ticket.py" approve --index 1 --reply "yes"
python3 "${CLAUDE_SKILL_DIR}/ticket.py" result --index 1 --status placed --broker-id ID --filled-qty 8 --filled-price 364.20
python3 "${CLAUDE_SKILL_DIR}/ticket.py" fill --symbol TSLA --side sell --qty 8 --price 370.04
python3 "${CLAUDE_SKILL_DIR}/ticket.py" flatten --symbol TSLA --qty 8
python3 "${CLAUDE_SKILL_DIR}/ticket.py" log

ticket.py 从不与经纪商通信。它会生成订单票据、检查回复是否确实针对这笔订单表示同意、构建平仓票据，并将日志保存在 trader/state/broker.json 中。--now "2026-10-19 10:15" 用于固定时钟（纽约时间）。

读取和写入的内容

文件	内容
trader/orders.json	拟议订单（由 trader-budget 写入；flatten 会替换此文件）
trader/state/risk.json	trader-risk 的判定；只有今天的 PASS 才是 READY
trader/state/broker.json	每次同意、拒绝、下单、失败和成交，以及每条记录的最大亏损
trader/portfolio.json	现金和股份，由 fill 和 result --filled-qty 更新
trader/plan.json	flatten 的平仓时间

设置 A：Alpaca（官方 MCP 服务，Claude Desktop）

Alpaca 自己的服务是 github.com/alpacahq/alpaca-mcp-server（MIT）。它在用户的电脑上通过 Claude Desktop 运行。它不在 Claude 的连接器目录中。除非另有说明，否则它会在模拟账户上交易。已于 2026-10-20 对照其源代码核实（版本 2.4.0）。

1. 用户注册 Alpaca 账户，并在 Alpaca 控制面板中创建模拟交易 API 密钥。模拟密钥与实盘密钥分开。
2. 用户从 docs.astral.sh/uv 安装 uv（它提供 uvx）。
3. 在 Claude Desktop 中：Settings > Developer > Edit Config。这会打开 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）。用户将此代码块添加进去（此处也提供 claude_desktop_config.example.json），并在文件中填入自己的密钥：

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "paste your paper key here, in this file only",
        "ALPACA_SECRET_KEY": "paste your paper secret here, in this file only",
        "ALPACA_PAPER_TRADE": "true",
        "ALPACA_TOOLSETS": "account,trading,stock-data"
      }
    }
  }
}

env 代码块会将密钥作为环境变量传递给服务。切勿在聊天中提供密钥。 不要索要密钥，不要将此文件读回到对话中；如果用户仍然粘贴了密钥，告诉他们删除那条消息，并在 Alpaca 控制面板中创建新密钥。ALPACA_PAPER_TRADE 默认已为 true；将它写出来可以让设置一目了然。ALPACA_TOOLSETS 是可选项，可用于隐藏他们不需要的工具。 4. 重启 Claude Desktop。 5. 设置工具权限。 依次选择 Customize > Connectors（旧版本中为 Settings > Connectors），打开 alpaca，并为每个工具选择 Always allow、Needs approval 或 Blocked：

• place_stock_order：Needs approval。切勿选择 Always allow。
• 所有其他会下单、更改、取消或平仓的工具（cancel_order_by_id、replace_order_by_id、close_position、update_account_config）：Needs approval。
• place_option_order、place_crypto_order、close_all_positions、cancel_all_orders、exercise_options_position、do_not_exercise_options_position：除非用户有理由并明确提出，否则设为Blocked。
• 只读工具（get_account_info、get_all_positions、get_open_position、get_orders、get_clock、get_stock_snapshot、get_stock_latest_quote）：选择 Always allow 没问题。

6. 检查设置：让 Claude 查询 Alpaca 账户信息（只读），并在 Alpaca 控制面板中确认这是模拟账户。

如果使用 Claude Code 而非 Claude Desktop，请在 .claude/settings.json 中将下单工具设为需要询问："permissions": {"ask": ["mcp__alpaca__place_stock_order"]}，并且切勿将下单工具放入 allow。

Alpaca 上的括号订单。 place_stock_order 接受 take_profit_limit_price 和 stop_loss_stop_price（以及可选的 stop_loss_limit_price）。只要其中任意一项有值，服务就会自动将 order_class 设为 "bracket"；trader-budget 也会写入该值，以便订单界面显示。括号订单仅支持整股，time_in_force 必须为 day 或 gtc。入场订单成交后，止损单和止盈单会作为两笔互相取消的订单留在经纪商处。它们也都是日订单，因此会在收盘时到期——这又是一个应在收盘前平仓的理由。

设置 B：Interactive Brokers（Claude 目录中的连接器）

Interactive Brokers 提供了经过验证的连接器：claude.ai/directory/interactive-brokers（连接器 URL 为 https://api.ibkr.com/v1/api/mcp）。通过 Customize > Connectors > Browse connectors 添加它，并在 IBKR 中登录，而不是在聊天中登录。其页面说明，Claude 可以起草交易指令，发送到用户的 IBKR 账户供其审核和批准；Claude 不会直接向市场提交订单。因此，使用 IBKR 时，最终确认也在 IBKR 中进行。在 trader/config.json 中设置 "broker": "ibkr"。也将起草订单的工具设为 Needs approval。

步骤：入场

1. ticket.py show。只有 READY 票据才会展示给用户。状态不是 READY 或为 BLOCKED 的票据会退回给 /trader-risk。
2. 展示一张票据并询问：“要下这笔订单吗？请回复 yes 或 no。” 每次只问一笔订单。 绝不提供“全部都 yes”的选项。
3. 运行 ticket.py approve --index N --reply "<用户逐字回复的内容>"。 如果输出“Not recorded”，说明用户没有明确表示同意这笔订单 （例如回复“sure”、“yes to all”，或 yes 但提到的是不同的 股票或金额）。再次询问。绝不自行将用户回复改成 yes。
4. 只有在输出“Recorded your yes”后，才调用 place_stock_order，并严格使用 票据打印出的 JSON。Claude 的卡片会显示出来：Allow once 或 Deny。
5. 记录结果：ticket.py result --index N --status placed --broker-id <id> --filled-qty Q --filled-price P（成交信息来自响应 或 get_open_position），或者使用 --status denied，或者使用带有 --note 的 --status failed。订单失败后，未经新的检查和新的 yes，不得重试。 日志会保留该入场的最大亏损额度，供 trader-risk 计算每日限额。

步骤：持仓期间及收盘前平仓

• trader-alerts 会监控止损位、目标位和平仓截止时间 （alerts.py add --from-plan）。止损和止盈由括号订单负责执行。
• 止损或止盈成交时，记录成交信息： ticket.py fill --symbol TSLA --side sell --qty 8 --price 358.32。
• 到 flat_by 时间（纽约时间 15:55）时，仍未平仓的头寸都必须平仓：
  1. 向 Alpaca 查询持有的股数：get_open_position（只读）。
  2. ticket.py flatten --symbol TSLA --qty 8 会将这些股票的市价卖单写入 trader/orders.json。
  3. /trader-risk。仅平掉用户持有股票的卖单不会受到每日限额或入场时段限制。
  4. ticket.py show，然后像上文一样，针对这笔订单取得用户的 yes。
  5. 括号订单的止损和止盈仍会占用这些股票，因此取消之前，Alpaca 会拒绝新的卖单： get_orders（status 为 open，nested 为 true）会显示这些订单；逐个调用 cancel_order_by_id（需要批准）。然后使用票据调用 place_stock_order，再调用 result。

示例：完整流程

ORDER 1 of 1, PAPER account, Alpaca
  BUY 8 TSLA, market, good for today
  stop-loss 358.32
  take-profit 370.04
  max loss about $46.88 if the stop fills at 358.32 (it can fill worse in a fast market)
  why: opening-range breakout on TSLA: 8 shares, bound by your $50 max loss per trade (8 x 5.86 = $46.88 at the stop)
  READY: trader-risk PASS, waiting for your yes
  Claude will call place_stock_order with exactly:
    {"symbol": "TSLA", "side": "buy", "qty": "8", "type": "market", "time_in_force": "day",
     "order_class": "bracket", "take_profit_limit_price": "370.04", "stop_loss_stop_price": "358.32"}

用户回复“yes”。Claude 记录该回复，调用 place_stock_order，卡片上会显示 “Claude 想要使用 Place stock order”，并附上该 JSON 和两个按钮：Allow once、Deny。 点击 Allow once 会将订单发送到模拟账户。 why 和计划会保留在文件中，绝不会发送出去。

绝不会做的事

• 缺少三个关卡中的任何一个，都绝不下单；一次 yes 绝不对应两笔订单。
• 绝不通过计划任务或后台任务下单：那里没有人可以回复 yes。
• 绝不索取、读取、存储或复述 API 密钥或密码。
• 绝不将 ALPACA_PAPER_TRADE 或 "paper" 切换为实盘。用户必须自行切换。
• 绝不自行调用 close_all_positions、cancel_all_orders，也不调用期权或加密货币订单工具。
• 绝不承诺成交价格：市价单和止损单会按市场实际价格成交。

安全

• 用于教育和提供工具，不构成财务建议。PASS 只表示通过规则检查，并非推荐。
• 默认使用模拟交易（"paper": true）。是否转为实盘由用户自行决定，并在自己的配置中设置。
• 此工具包中，只有 trader-broker 会下单，而且必须同时满足以下三个条件：trader-risk 当天已批准该笔确切订单；用户在聊天中明确输入 yes，同意该笔订单；用户点击了 Claude 自己卡片上的 Allow once，因为订单工具设置为“需要批准” （Customize > Connectors > tool permissions）。绝不将订单工具设置为“始终允许”。
• 除非配置允许且用户确认，否则不得进行期权交易、保证金交易、卖空或杠杆交易。
• 经纪商密钥存放在环境变量或 Claude Desktop 配置中，绝不放在聊天里。