Skip to content

README.zh-CN.md

Latest commit

 

History

History
173 lines (129 loc) · 4.39 KB

README.zh-CN.md

File metadata and controls

173 lines (129 loc) · 4.39 KB
Raw

Codex Buddy Bridge

Codex Buddy Bridge 是一个本地 Codex 插件和 BLE bridge，用来把 Codex 的工作状态同步到 ESP32 桌面硬件搭子。它完全兼容 Claude Code Buddy 硬件和 Nordic UART BLE 协议。

快速上手请先看：QUICKSTART.md

架构

flowchart LR
  subgraph Codex["Codex Desktop"]
    S1["Session A"]
    S2["Session B"]
    MCP["MCP 工具"]
    Hooks["插件 Hooks"]
  end

  subgraph Files["共享状态文件"]
    State["bridge/state.json"]
    Activity["bridge/activity.json"]
    Command["bridge/command.json"]
    Usage["bridge/usage_state.json"]
  end

  subgraph Bridge["单个常驻 bridge.py 进程"]
    Heartbeat["Heartbeat loop"]
    Commands["Command loop"]
    Tokens["Token tracker"]
    BLE["Nordic UART BLE client"]
  end

  Hardware["兼容 Claude Code Buddy 的 ESP32 硬件"]
  CodexDB["%USERPROFILE%/.codex/state_5.sqlite"]

  S1 --> MCP
  S2 --> MCP
  MCP --> State
  MCP --> Command
  Hooks --> Activity
  CodexDB --> Tokens
  Activity --> Heartbeat
  State --> Heartbeat
  Command --> Commands
  Tokens --> Usage
  Tokens --> State
  Heartbeat --> BLE
  Commands --> BLE
  BLE <-->|"NUS: RX write / TX notify"| Hardware
Loading

功能

  • 一个全局常驻 bridge 进程，不随 Codex session 重复启动。
  • 通过 BLE Nordic UART Service 向硬件发送状态。
  • 支持 Codex 工作中、空闲、等待确认、错误等状态。
  • 支持硬件权限确认，硬件按键 approve/deny 后回传给 bridge。
  • 支持插件 hook，把低层工具活动写入硬件状态。
  • 支持从 Codex 本地 sqlite 只读统计 token。
  • 支持 Windows BLE 6 位 PIN 交互配对。

日常启动

首次安装依赖：

cd D:\EspProjects\codex-buddy
npm install

日常只需要启动一次 bridge：

buddy_start_bridge

如果已经启动，会返回：

{
  "ok": true,
  "alreadyRunning": true
}

不要为每个 Codex session 单独启动 bridge。多个 session 会共享同一个 bridge/state.json 和同一个 BLE bridge 进程。

首次配对

只有首次配对、删除 Windows 蓝牙设备后，或者遇到认证失败时才需要 pairing 模式：

buddy_start_bridge_pairing

这会打开一个可见控制台。硬件显示 6 位数字时，在控制台输入并回车。配对完成后，日常使用普通 buddy_start_bridge。

状态文件

bridge/state.json              当前发给硬件的状态快照
bridge/activity.json           hook 写入的最近工具活动
bridge/command.json            MCP 写入的待发送命令
bridge/command_response.json   硬件命令回包
bridge/permission_response.json 硬件权限确认结果
bridge/usage_state.json        token 统计游标
bridge/status.json             bridge 进程和 BLE 状态

Token 统计

bridge 默认只读：

%USERPROFILE%\.codex\state_5.sqlite

它读取最新活跃线程的 threads.tokens_used，按正向增量累计。为了避免硬件在 coding 时被高频 token 更新冲爆，token 写入 state.json 前会限流。

默认配置：

"tokenPollSeconds": 2,
"tokenFlushSeconds": 60,
"tokenFlushMinDelta": 5000,
"tokenMaxDeltaPerFlush": 5000

BLE 协议

使用 Nordic UART Service：

Service:   6e400001-b5a3-f393-e0a9-e50e24dcca9e
RX write:  6e400002-b5a3-f393-e0a9-e50e24dcca9e
TX notify: 6e400003-b5a3-f393-e0a9-e50e24dcca9e

这组 UUID 是和 Claude Code Buddy 兼容的关键部分。

验证

npm run check
python -m py_compile bridge\bridge.py
Get-Content .codex-plugin\plugin.json | ConvertFrom-Json
Get-Content .mcp.json | ConvertFrom-Json
Get-Content hooks.json | ConvertFrom-Json

查看 bridge 状态：

buddy_get_bridge_status

查看硬件状态：

buddy_get_device_status

常见问题

  • No matching BLE device found：硬件未开机、距离太远、未广播，或被其他设备占用。
  • Insufficient Authentication：删除 Windows 蓝牙设备后重新运行 buddy_start_bridge_pairing。
  • 硬件显示 pairing/discover：先确认 bridge 是否在运行，再用普通 buddy_start_bridge 重连。
  • token 不增长：查看 bridge/usage_state.json 和 status.last_usage_error。
  • hook 不生效：重启 Codex，让插件重新加载 hooks.json。
  • 硬件按键后重启：优先检查供电和 buddy_get_device_status 中的 data.sys.reset 字段。

License

MIT