pitbridge

PitBridge

面向 NinjaTrader 8 的本地优先 MCP 桥接工具，具备 AI 无法绕过的硬性风险限制。

PitBridge 通过一个运行在你自己设备上的守护进程，将 AI Agent（Claude Code、Claude Desktop 或你自己的脚本）连接到 NinjaTrader 8 期货账户。Agent 请求的每笔订单都会先经过一个确定性护栏引擎。护栏默认启用，规则写在代码中，而非提示词里；Agent 没有任何工具可以削弱护栏、解锁实盘交易或解除紧急停止开关。

我们构建的是护栏，不是超额收益。PitBridge 不会告诉你该交易什么。

它是什么

• 一个本地优先守护进程（Python 3.12），支持 MCP（stdio 和可流式传输的 HTTP）、REST API 和 WebSocket 事件流。可在 macOS、Linux 或 Windows 上运行。
• 一个确定性护栏引擎：执行纯同步检查（每日亏损熔断、持仓上限、交易时段、速率限制、紧急停止开关等），每笔订单在到达经纪商前都必须通过检查。
• 一个精简的 NinjaTrader 8 AddOn（C#），可连接到守护进程，并通过官方的 NinjaTrader.Cbi Account API 下单。该 AddOn 刻意设计得很简单：所有安全机制都由守护进程负责。
• 一个只追加、哈希链式审计日志，记录每个请求、决策和结果，并能准确说明任何订单获准或被拦截的原因。

它不是什么

请先阅读本节。

• 不是经纪商或交易所。 PitBridge 会将你（或你的 Agent）创建的订单转发到你现有的 NinjaTrader 账户。它不持有资金，也不会自行执行交易。
• 不是信号、策略或超额收益工具。 PitBridge 不附带任何交易逻辑。它不会告诉你交易什么、何时交易或交易多少。这是你的工作，或者是你的 Agent 的工作。
• 不是金融或投资建议。 它是交易基础设施。
• 不保证符合资管公司的规定。 你需要配置符合公司规则的限制。PitBridge 帮助你在本地编码并强制执行这些限制，但你仍有责任遵守公司的条款。我们不保证合规。
• 不是云端订单中继。 订单、密钥和持仓不会经过我们的服务器。订单路径中没有 PitBridge 账户。
• 不是自主运行的。 启用实盘执行需要由操作人员在命令行手动完成。Agent 无法启用实盘交易，也无法解除紧急停止。

架构

整个订单路径都在本地运行。PitBridge 自己的云服务（营销网站、文档、软件更新）不会介入其中。

   AI agent   (Claude Code / Claude Desktop / your own script)
      │
      │   MCP (stdio or HTTP)   REST /v1/*   WS events
      ▼
   PitBridge daemon                         ← runs on YOUR machine
      │
      │   frozen pipeline (no code path skips it):
      │   schema → permission → GUARDRAILS → confirm → submit → audit
      ▼
   Guardrail engine   (deterministic, default-on, not reconfigurable by the agent)
      │
      │   WebSocket on :8873   (the AddOn dials OUT; the NT8 box never listens)
      ▼
   NT8 AddOn   (C#, .NET 4.8, next to NinjaTrader 8 on Windows)
      │
      │   NinjaTrader.Cbi Account API   (close / flatten are strictly reduce-only)
      ▼
   NinjaTrader 8   →   your broker / prop account   (CQG, Rithmic, ...)

   PitBridge's own cloud is NOT on this path.
   Orders, keys, and positions never leave your machine(s).

两种运行模式：

• 本地主机（默认）：守护进程和 NinjaTrader 在同一台 Windows 设备上运行，并绑定到 127.0.0.1。
• 配对模式：守护进程运行在例如你的 Mac 上，NinjaTrader AddOn 则通过你自己的专用网络（Tailscale / LAN）连接到守护进程。这就是“在你的 Mac、Windows 设备或两者上运行”的配置。除非明确启用配对模式并配置配对令牌，否则会拒绝绑定到非本地主机地址。

安全模型简述

• 确定性防护措施。 引擎由一组纯函数组成，不执行 I/O，流程中也不涉及大模型：check(request, state, now) 会返回 Allow、Block（附带类型化原因代码）或 RequireConfirm。输入相同时，始终返回相同的决策，而且该决策可测试。
• 固定的处理流水线。 每笔订单都严格经过同一条路径：模式校验，然后是权限检查（只读／模拟／实盘），再经过防护链，然后是可选的人工确认关卡，接着提交订单，最后追加审计记录。Agent 入口没有任何绕过这条路径直达经纪商的路线。CI 中的结构测试会在任何代码尝试绕过时导致构建失败。
• Agent 无法重新配置安全设置。 限额保存在经过校验和验证的磁盘配置文件中。没有任何 MCP 工具可以编辑配置、提高限额、解除 kill 状态或启用实盘交易。这些控制只能通过操作员的命令行操作。
• 本地优先。 守护进程运行在你的机器上。订单、密钥和持仓永远不会传到 PitBridge 服务端。
• Kill 开关。 文件、CLI 或 REST 调用都可以立即启用该开关。只有 CLI（由操作员亲自在键盘上操作）才能解除。即使启用了 kill，降低风险的操作（取消、平仓、清仓）仍会有意允许执行，因此你始终可以清仓。
• 防篡改审计日志。 日志采用仅追加的哈希链式 JSONL 格式，并带有文件外锚点。pitbridge audit why <id> 会说明任何订单的原因；pitbridge audit verify 会验证哈希链是否完整，并检测编辑、截断或尾部被清除的情况。

防护措施

12 项 v0 防护措施，各自位于独立模块中，并且都经过表驱动测试。处理链按固定顺序运行：首先检查 kill 开关，最后检查人工确认关卡。

1. Kill 开关：可通过文件、CLI 或 REST 启用；只能通过 CLI 解除，绝不会提供 Agent 工具。
2. 每日亏损停机：按账户记录每日账本，并按纽约时间换日；一旦触及限额，可锁定至当天结束。
3. 盈利锁定：达到设定的盈利后，当天停止交易。
4. 每笔订单的最大合约数：拒绝任何超过上限的单笔订单。
5. 每种工具和每个账户的最大持仓：限制净敞口，并拒绝持仓超过上限后翻转至同样超过上限的相反方向。
6. 工具允许列表：只能交易已配置的合约。
7. 交易时段和假日日历：按账户设置时区，并考虑节假日和提前收市。
8. 冷却时间：亏损后和／或下单后必须间隔最低时长。
9. 订单频率限制：设置每分钟、每小时和每日的上限。
10. 重复订单防护：同一账户、工具、方向和数量在 N 秒内重复下单时会被拒绝。
11. 连接中断拦截：如果与 AddOn 的心跳超时，新订单将被直接拒绝，而不会排队等待已断开的连接恢复。
12. 人工确认关卡：将订单暂存为 PENDING_CONFIRM，通知提醒程序，并等待 pitbridge confirm <id>（或通过 REST 批准）；60 秒后自动拒绝。

开源核心的边界

PitBridge 采用开源核心模式。安全内核为开源，便于阅读和信任。实盘执行功能以及用于运营多个账户的套件属于付费层级。

开源（免费）	Pro（付费）
守护进程和完整的防护引擎	解锁实盘执行（私有的 LiveExecutionProvider 插件）
MCP、REST 和 WebSocket Agent 接口	高级防护套件和 prop firm 规则包
只读工具和模拟交易（通过虚假 AddOn／模拟器）	多账户分发（一项工具调用，N 个账户）
CLI 和哈希链式审计日志	人工确认 UI 和审计导出

这是通过许可证控制功能，而不是 DRM。核心本身可完整支持只读和模拟用途。实盘交易需要 Pro 插件，并且必须由操作员有意执行仅限操作员的 arm-live 步骤。

快速入门

今天，你可以在 Mac 上运行完整的守护进程，无需安装 NinjaTrader、无需 Windows 设备，也无需市场数据。一个仿真 AddOn模拟器代替真实的 C# AddOn，让你观察护栏如何放行合规订单、以明确的类型化原因拦截违规订单、通过紧急停止开关停止所有操作，并根据审计日志解释每项决策。

cd daemon
uv sync --extra dev
uv run pitbridge run --config ./config.toml     # terminal A
uv run python ../tools/fake_addon.py \           # terminal B
  --host 127.0.0.1 --port 8873 --token pb_pair_demo --account Sim101

然后，你可以通过 REST 下达一笔模拟订单，或者将 Claude 配置为 MCP 客户端，用自然语言向它提出请求。完整的操作指南、可直接粘贴的配置、Claude Desktop / Claude Code MCP 设置片段、五个测试场景，以及“尝试攻破它”部分，均见 docs/testing-on-mac.md。

快速入门中的所有内容都属于模拟 / 仿真。关于其真实能力边界，请参阅该指南中的“What this does and does not prove”部分。

状态与路线图

PitBridge 处于早期开发阶段，尚未发布。我们会如实说明已实现的功能与规划中的功能。

目前已构建并测试（仅限模拟 / 仿真）：

• 守护进程核心、完整的护栏引擎（全部 12 项护栏）、日账本和哈希链审计日志；
• MCP 服务（9 个工具）、REST API、WebSocket 事件流和 CLI；
• 用于端到端测试和混沌测试的脚本化仿真 AddOn；
• 表驱动测试套件（300 多项测试），可在 macOS、Linux 和 Windows 上通过 CI 运行，其中包括提示词注入和不可绕过测试。

正在开发：

• 真实的 C# NinjaTrader 8 AddOn（通过 Sim101 账户路由订单），其中平仓和全部平仓已实现为严格的仅减仓操作。

计划中：

• 影子模式验证：将 PitBridge 与我们自己的实盘自营交易业务并行运行，以验证订单意图的一致性，确认无误后才会路由实盘订单；
• 由操作员监督并授权的实盘迁移；
• 开源核心版本的公开发布、网站和完整文档；
• 通过轻量适配器支持更多平台（Tradovate、ProjectX / TopstepX）。

目前尚无账户通过 PitBridge 进行过交易。 实盘路由受仅限操作员执行的专门流程控制，不属于当前构建版本的一部分。

文档

• docs/architecture.md：权威架构与安全规范。
• docs/testing-on-mac.md：在 Mac 上针对仿真 AddOn 运行并测试守护进程。
• SECURITY.md：如何报告漏洞。
• CONTRIBUTING.md：如何参与贡献，以及安全关键变更的规则。

免责声明

商标。 NinjaTrader 是 NinjaTrader Group, LLC 的注册商标。CQG、Rithmic 以及任何自营交易公司的名称均为各自所有者的商标。PitBridge 是一个独立项目，与 NinjaTrader Group, LLC、任何数据或清算服务提供商或任何自营交易公司均无关联，也未获得其认可或赞助。平台名称仅用于说明兼容性。

非财务建议。 PitBridge 是交易基础设施，不提供财务、投资或交易建议，也不提供信号、策略或推荐。

风险。 期货交易存在重大亏损风险，并不适合所有投资者。你须对自己的交易决策以及遵守所用经纪商或自营交易公司的条款全权负责。

CFTC 第 4.41 条（假设和模拟业绩）。 PitBridge 展示的任何结果、示例或模拟数据均为假设或基于仿真。模拟业绩存在固有局限：与实盘记录不同，模拟结果并不代表实际交易；由于交易并未实际执行，模拟结果可能低估或高估流动性不足等因素的影响。我们不对任何账户实现或可能实现与所示结果相似的盈利或亏损作出任何声明。