1. 项目定位与用途
WorkBuddy ACP Bridge 是一款零依赖的 Python 命令行桥接工具，核心定位是打通外部 AI Agent 与 WorkBuddy 桌面客户端的实时消息通道，支持将外部 Agent 的指令、结论直接投递到 WorkBuddy 中已打开的活跃会话，同时可获取 WorkBuddy 的回复，实现多 Agent 协作时的上下文无缝复用，避免新开会话带来的上下文缺失问题。
项目档案命令行工具
Kxiandaoyan/workbuddy-acp-bridge CLI 工具：安装、命令与使用场景
WorkBuddy ACP Bridge 是一款零依赖Python命令行工具，可打通外部AI Agent与WorkBuddy桌面客户端的实时会话通道，支持消息投递、忙闲检测、空闲会话自动激活，适用于多Agent协作、人工在环等场景，本文档包含安装与使用说明。
AI 总结
WorkBuddy ACP Bridge 是一款零依赖的 Python 命令行工具，可打通外部 AI Agent 与 WorkBuddy 桌面客户端的实时会话通道，实现多 Agent 协作时的上下文无缝复用，无需手动跨窗口复制粘贴。
中文项目介绍
WorkBuddy ACP Bridge 是一款专为多 Agent 协作场景设计的轻量桥接工具，核心用途是让 Claude、Codex、Hermes、OpenClaw 等外部 AI Agent 直接将消息投递到 WorkBuddy 桌面客户端中已打开的活跃会话，消息可在 PC 客户端界面实时显示，同时可获取 WorkBuddy 的回复，无需手动切换窗口或复制粘贴内容。
它解决的核心痛点是：多 Agent 协作时，外部 Agent 新开的 WorkBuddy 会话没有完整项目上下文、工具权限和历史记录，所有内容需要重述，效率极低。该工具通过复用桌面上已有的“懂行”WorkBuddy 会话，避免了上下文冗余传递的问题。
技术层面，工具仅依赖 Python 3 标准库，零第三方依赖，全部流量走本地 127.0.0.1 回环，无需密码、令牌或登录，不读写任何凭证文件，安全性高。
适用场景包括多 Agent 分工协作、人工在环协作、无人值守自动投递等典型多 Agent 协作流程。
详细信息与使用说明
2. 解决的问题
解决多 Agent 协作场景下的核心痛点：外部 Agent 新开 WorkBuddy 会话时无完整项目上下文、工具权限与历史记录，需要重述所有背景信息，效率极低；同时消除手动跨窗口复制粘贴消息的繁琐流程，避免上下文传递的遗漏与错误。
3. 适用场景
1. 多 Agent 分工协作：外部 Agent 完成数据采集、回测等任务后，将结论投递至 WorkBuddy 会话，由其基于完整上下文继续执行代码编写、策略调整等任务；2. 人工在环协作：外部 Agent 投递前可先检查 WorkBuddy 会话忙闲状态，避免打断其正在执行的任务，消息不会静默丢失；3. 无人值守自动投递：通过 --ensure 参数自动激活空闲的 WorkBuddy 会话，实现外部 Agent 完全无人值守的消息投递。
4. 安装方式
安装方式极为简单：仅需本地已安装 Python 3 运行环境，下载或克隆仓库文件到本地即可直接使用，无需安装任何第三方依赖，无额外配置步骤。
5. 使用方式
核心使用方式包括：1. 执行 python acp_live_send.py --list 可列出当前 WorkBuddy PC 客户端已激活的活跃会话，获取目标会话的 sessionId 或对应项目路径 cwd；2. 通过 --session-id 指定目标会话 ID 搭配 --msg 参数发送消息，添加 --ensure 参数可自动激活空闲会话；3. 通过 --check 参数检查会话忙闲状态，添加 --wait-idle 参数可在会话忙时每 2 秒轮询等待至空闲或超时后再发送；4. 执行 python acp_live_test.py <端口> <sessionId> <cwd> <消息> 可手动验证 ACP 四步调用链的正确性。
6. 补充说明与实现特点
实现层面，全部流量走本地 127.0.0.1 回环，WorkBuddy ACP 主通道对回环流量豁免，POST /api/v1/acp/connect 可直接下发一次性 connectionId 与 sessionToken，无需长期密钥、登录或配置，工具也不读写任何凭证文件。核心 ACP 调用链为四步：connect 获取临时凭证 → initialize 完成握手 → session/load 加载目标会话 → session/prompt 发送消息。已知限制包括：仅支持投递到 PC 客户端已打开过的会话，同一会话一次仅能处理一条消息，忙闲判断存在几秒延迟，目前仅在 Windows + WorkBuddy PC 客户端环境下验证过。
思维导图
WorkBuddy ACP Bridge
核心工具 acp_live_send.py
活跃会话自动发现
免密ACP连接建立
会话加载
消息发送
忙闲状态检测
空闲会话自动激活
冒烟测试 acp_live_test.py
四步调用链验证
项目文档
README说明
MIT许可
常见问题
WorkBuddy ACP Bridge 需要安装第三方依赖吗？
不需要，该工具仅使用 Python 3 标准库实现，零第三方依赖，下载仓库文件即可直接使用。
使用该工具需要登录 WorkBuddy 账号或配置密钥吗？
不需要，全部流量走本地 127.0.0.1 回环，WorkBuddy ACP 主通道对回环流量豁免，connect 接口可直接下发一次性临时凭证，无需长期密钥、登录或配置。
如果 WorkBuddy 会话空闲被回收了，还能发送消息吗？
可以，添加 --ensure 参数即可自动激活空闲会话，工具会通过 workbuddy:// 协议链接唤醒 WorkBuddy 客户端，重新激活目标会话为活端点。
该工具支持哪些外部 Agent？
支持所有能运行 Python 进程的外部 Agent，包括 Claude、Codex、Hermes、OpenClaw 等，也可集成到自定义的 Agent 工作流中。
发送消息时 WorkBuddy 会话正忙怎么办？
可添加 --wait-idle 参数，工具会每 2 秒轮询会话忙闲状态，直到会话空闲或超时后再发送消息，避免打断 WorkBuddy 正在执行的任务。