# Codex ↔ WorkBuddy 桥接（MCP server）

让 OpenAI Codex 在执行任务时把子任务"交接"给 WorkBuddy（生成文档 / PPT / 数据分析 / 研究报告等）。

## 为什么需要桥接

调查结论（已在本机核实）：

- **Codex 支持 MCP**：配置在 `~/.codex/config.toml`，用 `[mcp_servers.xxx]` 表，STDIO 模式（`command` + `args` + `env`）。你机器上已在用 `tradingview`、`node_repl` 等 server。
- **WorkBuddy 目前不原生作为 MCP server**，也没有对外"提交任务并带回结果"的公开 API。它内部的 `createTask / submitTask / runAgent` 是 Electron 主进程私有方法，外部不可达。
- WorkBuddy 的 `workbuddy://` Deep Link（`workbuddy://home`、`workbuddy://chat/<id>`、`workbuddy://my-files?tab=cloudFiles` 等）**只做 UI 导航，不提交任务**。

因此采用 **handoff（任务交接）** 模式：Codex 调 MCP 工具 → 打开 WorkBuddy + 把任务写进共享收件箱 + 复制到剪贴板 → WorkBuddy 在界面里执行。待 WorkBuddy 未来暴露 MCP server / 任务 API 后，可无缝升级为"直接调用并拿回结果"。

## 文件

- `server.js` —— stdio MCP server，暴露两个工具：
  - `workbuddy_handoff(prompt, title?)`：交接一项子任务给 WorkBuddy。
  - `workbuddy_open(target)`：打开 WorkBuddy 的某个界面（home / my-files）。
- `test-client.mjs` —— 本机冒烟测试（`node test-client.mjs <node路径>`）。
- `node_modules/` —— 依赖（已装在隔离环境，不污染系统）。

## 在 Codex 中注册

把下面这段加进 `~/.codex/config.toml`（与现有 `[mcp_servers.tradingview]` 并列）：

```toml
[mcp_servers.workbuddy]
command = "/Users/zhaoxiangyu/.workbuddy/binaries/node/versions/22.22.2/bin/node"
args = ["/Users/zhaoxiangyu/WorkBuddy/2026-07-20-17-51-22/codex-workbuddy-bridge/server.js"]
env = { WORKBUDDY_INBOX_DIR = "/Users/zhaoxiangyu/WorkBuddy/inbox" }
```

重启 Codex（或在 TUI 里 `/mcp`）后，Codex 就多了 `workbuddy_handoff` / `workbuddy_open` 两个工具。
也可改用 CLI：`codex mcp add workbuddy -- /Users/zhaoxiangyu/.workbuddy/binaries/node/versions/22.22.2/bin/node /Users/zhaoxiangyu/WorkBuddy/2026-07-20-17-51-22/codex-workbuddy-bridge/server.js`

## 在 Codex 里怎么用

让 Codex 在合适时机调用，例如：

> 把这个项目跑完单测后，用 workbuddy_handoff 让 WorkBuddy 生成一份发布说明文档。

Codex 会：打开 WorkBuddy、把任务落到 `~/WorkBuddy/inbox/`，并把任务文本复制到剪贴板，方便在 WorkBuddy 里直接粘贴执行。

## 环境变量

- `WORKBUDDY_INBOX_DIR`（默认 `~/WorkBuddy/inbox`）：交接任务落盘目录。
- `WORKBUDDY_SUBMIT_DEEPLINK`（可选）：若你发现 WorkBuddy 支持"打开即提交"的深链（如 `workbuddy://chat/new?prompt={prompt}`），设上它即可让 handoff 直接尝试自动提交，无需手动粘贴。

## 验证

```bash
cd codex-workbuddy-bridge
/Users/zhaoxiangyu/.workbuddy/binaries/node/versions/22.22.2/bin/node test-client.mjs /Users/zhaoxiangyu/.workbuddy/binaries/node/versions/22.22.2/bin/node
```

应看到 `CONNECTED`、两个工具名、handoff 返回的收件箱路径，并在 `~/WorkBuddy/inbox/` 生成对应 `.md`。

## 反向方案（可选）

若你更想"WorkBuddy 调 Codex"：WorkBuddy 能消费 MCP / 运行 CLI，可把 Codex 的能力（或 `codebuddy` CLI，位于 WorkBuddy.app 内的 `cli/bin/codebuddy`）接成 WorkBuddy 的 MCP 连接器。本仓库聚焦 Codex→WorkBuddy 方向。