Skip to main content
Glama
README.md
# OpenBot ↔ WorkBuddy 桌面桥接

把**已安装、已登录的 WorkBuddy 桌面程序**接到 OpenBot,通过 MCP 交给 WorkBuddy 执行任务、读取回复,并继续同一段对话。

这不是模型 API 中转,也不是把 `WorkBuddy.exe` 填进 OpenBot 的“自定义 ACP 助手”。本项目提供的是 **MCP STDIO 服务**,通过 WorkBuddy 桌面运行时中的 SDK 调用现有账号、模型和连接器。

> 非官方、本地实验性适配。已在 **Windows + WorkBuddy 5.11.3** 验证。WorkBuddy 升级可能改变接口;其他版本、macOS 和 Linux 尚未验证。

**当前验证状态:**原桌面适配已完成对话、续聊和重启恢复实测;公开整理版的安装、6 项单元测试与 MCP 连接检查通过,但最近一轮模型调用出现超时。请先在自己的环境执行端到端测试,完整范围见 [验证记录](docs/verification.md)。

## 能做什么

- 检查 WorkBuddy 是否可连接。
- 从 OpenBot 发出提示,等待 WorkBuddy 执行结果。
- 保存桥接会话 ID,后续调用保留聊天上下文,不自动 `/clear`。
- WorkBuddy 退出再启动后,重新加载原会话。
- 请求取消任务。
- 沿用 WorkBuddy 自身的登录状态和模型配置,无需向桥接器填写账号密码或模型 API Key。

WorkBuddy 中具体技能、连接器、订阅和配额是否可用,取决于桌面程序自身。**本项目验证过模型回答、上下文记忆和重启后续聊;没有验证所有连接器,也没有把外部消息发送或用户文档写入当成测试。**

## 工作原理

```mermaid
flowchart LR
    A[OpenBot 中支持 MCP 的助手] -->|MCP STDIO| B[Python 桥接服务]
    B -->|仅本机 CDP / WebSocket| C[WorkBuddy 桌面 SDK]
    C --> D[WorkBuddy 现有会话与模型]
    C --> E[WorkBuddy 自身的技能和连接器]
```

WorkBuddy 5.11.3 的新后台不再提供旧社区桥接器所需的 Host Gateway。本项目改为在 WorkBuddy 的 renderer 页面中,通过 CDP 调用 `wb.conversations.create/get`、`runPrompt` 和 `cancelByUser`,再把结果转成 MCP 工具返回。

没有打包、分发或修改 WorkBuddy 程序;也不提取账号访问令牌。调试端口默认仅监听 `127.0.0.1:19389`。

## 环境要求

- Windows,已安装并登录 WorkBuddy。
- Python **3.11 或更高版本**,命令 `python --version` 能正常工作。
- OpenBot,且要使用支持 MCP 的助手。已知界面提示 Codex、Claude 会使用这里配置的 MCP 服务;其他提供商需按其实际能力确认。
- 安装 Python 依赖时需要网络;运行模型仍需 WorkBuddy 的网络和账号配额。

## 安装

下载本仓库的 ZIP 并解压,或者克隆后进入项目目录:

```powershell
git clone https://github.com/yummyyyyyyyyyyyyyyyyyyy/openbot-workbuddy-bridge.git
cd openbot-workbuddy-bridge
```

使用当前 PowerShell 会话允许执行安装脚本(仅当本机脚本策略阻止运行时需要):

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1
```

也可以不用脚本,直接执行:

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```

安装程序位于项目内 `.venv`,不会替换系统 Python。项目安装在什么盘都可以,下面的路径请换成自己的真实路径。

## 启动 WorkBuddy 桥接模式

先保存当前任务并**正常退出 WorkBuddy**。普通方式启动后再运行另一个带参数的实例,调试参数可能不会生效。

找到 `WorkBuddy.exe` 的真实位置,然后执行:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-workbuddy.ps1 `
  -WorkBuddyPath 'D:\Apps\WorkBuddy\WorkBuddy.exe' -CreateShortcut
```

脚本会在系统桌面创建 **WorkBuddy(OpenBot桥接)** 快捷方式。以后用这个快捷方式启动,并保持登录。若 WorkBuddy 已运行,脚本不会强杀或自动重启。

如果不用脚本,可以在 WorkBuddy 快捷方式的“目标”中加入以下参数:

```text
"D:\Apps\WorkBuddy\WorkBuddy.exe" --remote-debugging-address=127.0.0.1 --remote-debugging-port=19389
```

**调试接口具有控制该桌面程序的能力,不要对外网开放端口,也不要使用 `0.0.0.0` 监听。** 桥接客户端只接受固定本机地址,不把调试页面 URL、登录凭据或页面快照写入日志。

## 在 OpenBot 中填写

进入 **设置 → MCP → 连接自定义 MCP**,选择 **STDIO**。

| 项目 | 填写内容 |
| --- | --- |
| 名称 | `workbuddy` |
| 启动命令 | `D:\Projects\openbot-workbuddy-bridge\.venv\Scripts\openbot-workbuddy-bridge.exe` |
| 参数 | 留空 |
| 环境变量 | 默认留空 |
| 环境变量透传 | 留空 |
| 工作目录 | 留空 |

启动命令只填写程序路径,不要把参数拼在路径后面。工作目录留空可避免 OpenBot 因提供商的目录能力限制而跳过服务。

点击 **测试连接**,应看到 **4 个工具**,再保存并启用。注意:发现工具仅证明 MCP 服务启动成功,还要调用 `workbuddy_status` 才能检查 WorkBuddy 端。

通用 MCP JSON 示例(适用于支持这种配置格式的客户端;OpenBot 界面不一定有 JSON 导入):

```json
{
  "mcpServers": {
    "workbuddy": {
      "command": "D:\\Projects\\openbot-workbuddy-bridge\\.venv\\Scripts\\openbot-workbuddy-bridge.exe",
      "args": []
    }
  }
}
```

## 开始使用

在 OpenBot 新开一段支持 MCP 的聊天,输入:

> 调用 workbuddy_status 检查连接,然后调用 workbuddy_run,让 WorkBuddy 只回复“连接正常”,不要调用其他工具。

实际任务示例:

> 用 workbuddy_run,让 WorkBuddy 只读分析指定项目并总结结构。不要修改文件。

连续对话:

> 用 workbuddy_continue,使用上一条返回的 session_id,继续解释刚才总结中的第二点。

OpenBot 中的主助手负责调用工具;WorkBuddy 会话是被调用的一方。它不会自动变成 OpenBot 内一个单独的模型提供商,也不会自动绑定你当前打开的任意 WorkBuddy 聊天。

## 四个 MCP 工具

| 工具 | 用途 |
| --- | --- |
| `workbuddy_status` | 检查本机桌面调试端点,返回保存的桥接会话 ID;不调用模型 |
| `workbuddy_run` | 新建或复用桥接会话,发送任务并等待回复 |
| `workbuddy_continue` | 指定 `session_id` 续聊,保留上下文 |
| `workbuddy_cancel` | 请求取消指定会话的当前任务,不撤销已发生的操作 |

详细参数和返回示例见 [工具接口](docs/tools.md)。

## 权限、会话和数据

- `permission_mode="deny"` 是默认值:提示只读,并拒绝出现的交互授权请求。**它不是沙箱,不保证阻止 WorkBuddy 已经获得权限的所有写操作。**
- `permission_mode="allow_once"` 表示任务允许交给 WorkBuddy 的正常授权流程。桥接器不会自动点击授权;需要时请在 WorkBuddy 桌面人工确认。它也不保证执行全过程恰好只产生一次副作用。
- 用户提示通过 JSON 序列化传入脚本,不直接拼成可执行 JavaScript。
- 超时或断线不会自动重新发送任务;原任务可能仍在执行,应先查看桌面状态或明确取消。
- 默认数据目录为 `%LOCALAPPDATA%\openbot-workbuddy-bridge`。会话 ID 存在 `desktop-session.json`,默认任务目录为其下 `workspace`;聊天正文由 WorkBuddy 管理。
- 本仓库不含账号、Cookie、API Key、用户聊天记录、WorkBuddy 安装包或提取的程序源码。

配置环境变量:

| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `WORKBUDDY_BRIDGE_PORT` | `19389` | 本机调试端口,必须与 WorkBuddy 启动参数一致 |
| `WORKBUDDY_BRIDGE_HOME` | `%LOCALAPPDATA%\openbot-workbuddy-bridge` | 会话状态和默认任务目录,可用于隔离多个桥接实例 |

多个 OpenBot 助手默认复用一个桥接会话;同一页面内同时执行会被拒绝。多个进程首次同时创建会话不提供全局事务保证。需要相互独立的上下文时,为不同实例配置不同 `WORKBUDDY_BRIDGE_HOME`,或明确使用不同 `session_id`。

## 验证和测试

不发送模型提示的 MCP 连接检查:

```powershell
.\.venv\Scripts\python.exe .\scripts\check_connection.py
```

自动化单元测试,不需要启动 WorkBuddy,不消耗模型额度:

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
```

端到端测试会发送两条简短提示,**消耗少量 WorkBuddy 配额**,并使用保存的桥接会话:

```powershell
.\.venv\Scripts\python.exe .\scripts\smoke_test.py --send-test-prompts
```

本机实测记录和已知限制见 [验证记录](docs/verification.md)。

## 涉及哪些文件

```text
src/openbot_workbuddy_bridge/
  __init__.py             包版本
  desktop.py              本机 CDP 连接、桌面 SDK 调用和会话保存
  server.py               四个 MCP 工具及 STDIO 入口
scripts/
  install.ps1             创建虚拟环境并安装
  start-workbuddy.ps1      启动 WorkBuddy / 创建桥接快捷方式
  check_connection.py     不调用模型的 MCP 检查
  smoke_test.py           显式启用的端到端对话测试
tests/                    参数校验、序列化和错误处理测试
docs/
  tools.md                工具参数和返回结构
  troubleshooting.md      常见问题及排查步骤
  verification.md         已验证范围和限制
pyproject.toml            包信息、依赖及命令入口
LICENSE                   仅本项目原创代码的 MIT 许可
THIRD_PARTY_NOTICES.md    依赖和相关项目说明
```

## 常见问题

“已连接 4 个工具,但执行失败”、普通启动没有端口、超时、会话失效等情况,请看 [故障排查](docs/troubleshooting.md)。

## 项目关系与许可

本项目由一次 OpenBot 接入现有 WorkBuddy 的实际适配工作整理而来。早期评估参考了 [jie023/workbuddy-acp-bridge](https://github.com/jie023/workbuddy-acp-bridge) 的 MCP 工具形式;该项目的旧 Host Gateway 路线与此次验证环境不兼容。此公开仓库不复制其客户端、服务端实现或提交历史。

本仓库原创代码按 [MIT License](LICENSE) 发布。WorkBuddy、OpenBot、模型服务、连接器及其商标属于各自权利方。本项目与其官方团队无隶属或合作关系;使用相关产品仍需遵守各自条款。

TDQS

A3.5/5.0

Scored across 4 tools

Disambiguation4/5

The tools map to distinct lifecycle actions: status, run, continue, and cancel. run and continue could be confused because both can reuse a saved conversation, but the descriptions clarify that continue targets a specific existing conversation while run executes a task.

Naming Consistency5/5

All tools use a consistent snake_case workbuddy_verb pattern. The names are predictable and immediately indicate the action.

Tool Count5/5

Four tools are well-scoped for a narrow desktop bridge: check status, run, continue, and cancel. There is no obvious bloat, and each tool has a clear role.

Completeness4/5

The surface covers the core lifecycle of checking status, running, continuing, and cancelling a WorkBuddy conversation. A minor gap is the lack of an explicit tool to list or discover existing conversations, which may be needed before continue can be used confidently.