# 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 或配置后仍需完整重启无限易。

## 安全模型

- `preview_trade` 与 `submit_trade_intent` 两阶段提交；
- 提交时重新执行完整硬风控并比较决策指纹；
- Worker 与 PythonGO Adapter 双端检查账号、模式、签名、时效和授权；
- `PRE_SUBMIT`、`SUBMIT_CALLED` 或未知结果不会自动重发；
- 熔断只能由本机 Console 解除，解除后强制回到 `OBSERVE_ONLY`；熔断期间只保留撤单和可由新鲜目标持仓严格证明的减仓；
- `LIMITED_AUTO` 需要限时、限合约、限动作、限策略版本和限额度的结构化许可；
- 密钥、真实投资者账号、数据库、队列、日志和签名 Profile 不进入源码或 Release。

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

| 模式 | 是否可能调用报单接口 | 额外条件 |
| --- | --- | --- |
| `OBSERVE_ONLY` | 普通流程不会 | 默认模式，可查询、同步、Preview 和空跑 |
| `SIM_SIGNAL` | 会 | 仅用于已经现场确认的模拟柜台 |
| `MANUAL_LIVE` | 会 | 逐笔批准或 1–60 分钟本机会话 |
| `LIMITED_AUTO` | 会 | readiness 通过并存在有效结构化许可 |

## 架构

```text
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、模式切换、日常运行和故障处理请阅读 [操作手册](docs/README-RELEASE.zh-CN.md)。

## 从源码开发

```powershell
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` 目录：

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

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

## 构建 Release

在 Windows PowerShell 7 中运行：

```powershell
.\tools\build_release.ps1
```

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

## 文档

从[文档导航](docs/README.md)按安装查询、交易准备、排障或开发目标选择阅读入口。

- [Python 接口参考（单文件 HTML）](https://peppaboar95.github.io/workbuddy-pythongo-bridge/python-api-reference.html) — 31 个 Bridge 方法的参数、响应、错误码、配额与模块 API
- [中文操作手册](docs/README-RELEASE.zh-CN.md)
- [设计与安全边界](docs/DESIGN.zh-CN.md)
- [0.3.9 发布说明](docs/RELEASE-v0.3.9.md)
- [P0 核对清单](examples/P0-CHECKLIST.zh-CN.md)

## 许可

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