WorkBuddy-PythonGO Bridge

WorkBuddy/MCP 与无限易 PythonGO v2 之间的本机、失败关闭型期货交易桥接器。

📖 在线阅读接口文档：https://peppaboar95.github.io/workbuddy-pythongo-bridge/python-api-reference.html （31 个 Bridge 方法的参数、响应、错误码、配额与模块 API，侧栏导航 + 深色代码卡）

重要风险提示

本项目能够触发模拟或真实资金账户的委托，不构成投资建议，也不保证盈利。默认模式为 OBSERVE_ONLY。任何非观察模式都必须先在目标无限易、PythonGO、柜台和账户组合上完成 P0 现场验收；模式名称本身不能证明当前连接的是模拟柜台。

当前版本

• 版本：0.3.9

• Python：Worker 需要 3.10 或更高版本

• 客户端：无限易 PythonGO v2

• MCP 工具：31 个

• 网络边界：Worker 仅绑定 127.0.0.1

• 默认状态：OBSERVE_ONLY，交易关闭

0.3.9 重点改善可靠性和开箱体验：恢复崩溃遗留的 .processing 命令，确保 TICK_DISPATCH 只由目标合约 Tick 触发；熔断或自动暂停时保留严格减仓和撤单；陈旧交易快照拒绝前主动同步；风控同时采用绝对值、账户权益比例、百分比和 Tick 上限；首次配置提供三套风控预设。

PythonGO 桥接与无限易中的 WorkBuddy Adapter 可按任意顺序启动。Worker 自动等待新鲜心跳，并在首次连接或重连后同步账户和持仓；首次使用仍选择 OBSERVE_ONLY，交易保护和授权按原有流程处理。更改模式、Profile 或配置后仍需完整重启无限易。

Related MCP server: otto

安全模型

• preview_trade 与 submit_trade_intent 两阶段提交；

• 提交时重新执行完整硬风控并比较决策指纹；

• Worker 与 PythonGO Adapter 双端检查账号、模式、签名、时效和授权；

• PRE_SUBMIT、SUBMIT_CALLED 或未知结果不会自动重发；

• 熔断只能由本机 Console 解除，解除后强制回到 OBSERVE_ONLY；熔断期间只保留撤单和可由新鲜目标持仓严格证明的减仓；

• LIMITED_AUTO 需要限时、限合约、限动作、限策略版本和限额度的结构化许可；

• 密钥、真实投资者账号、数据库、队列、日志和签名 Profile 不进入源码或 Release。

四种运行模式均与独立熔断状态并存：

架构

WorkBuddy MCP
    │ 本机 HTTP + Bearer token
    ▼
Worker ── SQLite / 签名文件队列 ── PythonGO Adapter
                                      │
                                      ▼
                                无限易交易接口

Worker 负责状态、预览、风控、许可、审计和队列；内嵌 Adapter 负责账户与 Profile 复核、行情和账户快照、最终风控以及报撤单调用。两侧任一状态不可信时都应拒绝新开仓。

当前源码的低延迟路径使用 100–200ms 自适应队列扫描；Adapter 启动时预订阅账户 instrument_allowlist 中的精确合约。TICK_DISPATCH 只在命令目标合约的 Tick 到达时执行；崩溃遗留的 .json.processing-* 会在重启后恢复并继续走验签、执行日记和幂等处理。交易前同步应使用 request_sync(..., purpose="TRADE")，只同步资金、持仓和行情，不把 K 线查询放进报单热路径；Preview 遇到陈旧交易快照时会先主动同步一次。submit_trade_intent 只等待可靠落库和入队，随后立即返回 async_status；柜台进度通过 get_trade_intent 异步读取。

安装

普通用户应从 GitHub Releases 下载同一版本的 ZIP 与哈希文件：

• workbuddy-pythongo-bridge-0.3.9.zip

• workbuddy-pythongo-bridge-0.3.9.zip.sha256

• SHA256SUMS.txt

校验后完整解压 ZIP，双击 首次安装与配置.cmd。安装器会检查 Python 3.10+、把包内 wheel 安装到当前用户的默认 Python 环境，并启动全中文向导。运行数据默认保存在 %LOCALAPPDATA%\WorkBuddyPythonGO\runtime，换一个解压目录升级也会复用原环境；向导会尝试发现 WorkBuddy MCP 配置和无限易策略目录，并在用户选定后安全部署。它不会启动无限易、Worker 或 WorkBuddy，也不会签名 Profile 或开放交易。投资者账号会明文显示，便于输入时核对；它不是登录密码。

首次需要交易时，完成 P0/Profile 验证后，先在启动入口选择 1 运行观察模式并保持窗口打开，在无限易中启动 Adapter，再另开状态入口检查。前置条件不足时会列出具体步骤；全部通过后才显示 T：确认首次启用交易，明确确认后解除首次安装保护，仍保持观察模式。Worker 已运行时，再次打开启动入口也可查看这项检查。完整安装、P0、模式切换、日常运行和故障处理请阅读 操作手册。

从源码开发

git clone https://github.com/peppaboar95/workbuddy-pythongo-bridge.git
cd workbuddy-pythongo-bridge
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
python -m unittest discover -s tests -v
python -m ruff check src tests

本地初始化默认写入单独的 runtime 目录：

python -m workbuddy_pythongo.desktop setup --root .\runtime

不要提交 runtime、密钥、Worker token、真实账号、签名 Profile、数据库、日志、队列或现场证据；.gitignore 已覆盖常见路径，但提交前仍须人工检查。

构建 Release

在 Windows PowerShell 7 中运行：

.\tools\build_release.ps1

脚本从 pyproject.toml 读取版本，构建 wheel、安装 ZIP、ZIP 独立哈希和总哈希清单，并校验发布包必需文件。结果位于 dist\。

文档

从文档导航按安装查询、交易准备、排障或开发目标选择阅读入口。

• Python 接口参考（单文件 HTML） — 31 个 Bridge 方法的参数、响应、错误码、配额与模块 API

• 中文操作手册

• 设计与安全边界

• 0.3.9 发布说明

• P0 核对清单

许可

本项目使用专有许可。公开可见不等于授予复制、修改或再发布权；具体条款见 LICENSE。