agent-bus

多端 / 多 CLI agent 协作总线。解决"服务器 A 一个会话、电脑 B 一个会话、同项目几个会话、还可能是不同 CLI"之间无法配合的问题。

不改你的工作流：代码照常走 git，agent-bus 只管协调——谁拥有什么工作、谁在改什么文件、谁跟谁说好了什么、做了一半的工作怎么交给别人。单文件、Python 3.8+ 标准库、零依赖。

Peer      身份 / rank 权限次序 / 心跳
Claim     工作声明："这件事此刻归谁管"（运行时协调状态，不是任务管理）
Lock      资源排他：目录 / 文件 / 行区域，租约自动续期，--wait 排队
Message   公聊 + 私聊（阻塞型：回合制协商 → 高权限方裁决）
Handoff   两阶段工作交接：claim + 锁 + 上下文 capsule 原子转移
Takeover  对方掉线时的被动接管（从事件流合成事故现场 capsule）
Change    改动小历史（类似 git log 的"谁改了什么"）
Board     共享黑板（结论性信息，决策自动归档）
EventLog  events.jsonl：一切状态变更的事实源，可审计可回溯

边界声明：agent-bus 是 coordination layer，不是任务管理器（那是 beads / Jira 的地盘）、不是 orchestrator（不 spawn、不调度 agent）、不替代 git（代码内容永远走 git）。

# 第一个端（主机）：在项目根目录启动 hub
python3 bus.py serve            # 打印 hub 地址 http://<ip>:8977#<token>

# 每个端加入（同项目多会话务必各起 --name）
python3 bus.py join --hub 'http://<ip>:8977#<token>' --name A --cli kimi

# 典型工作循环
python3 bus.py claim auth-v2 --note "迁移登录接口" --scope src/auth/
python3 bus.py lock src/auth/ --note "改认证"
# ... 干活 ...
python3 bus.py done "登录接口迁到 /v2/auth" --files src/auth/api.ts
python3 bus.py unlock --all && python3 bus.py sync

# 收工交接给另一台机器上的 B
python3 bus.py handoff B auth-v2 --state "实现80%" --next "改 tests" --patch

• Tailscale（首选，零配置）：bus net setup 一条命令引导安装（macOS Homebrew / Linux 官方脚本，只需 sudo 密码与浏览器登录 tailnet 授权），bus net status 查看状态。所有机器装好并登录同一 tailnet 后：bus serve 自动探测 Tailscale IPv4 并作为首选广告地址（100.x），流量走 WireGuard 加密（顺带解决明文 HTTP 问题）；bus join（不带 --hub，读 hub.json）会逐个探测候选地址、自动选路，主地址不通自动换备选——在公司局域网 join 过一次，回家切 Tailscale 无需改配置。
• 没有 Tailscale 时用内网穿透：
  • Cloudflare Tunnel：hub 机 cloudflared tunnel --url http://localhost:8977，得到 https://xxxx.trycloudflare.com，对端 bus join --hub 'https://xxxx.trycloudflare.com#<token>'（零对端安装、白送 TLS）；
  • SSH 反向隧道：hub 机 autossh -R 8977:localhost:8977 user@vps，对端用 vps 公网地址 join；
  • frp：hub 机跑 frpc 连你的 frps，对端用 frps 映射的地址 join。
• ⚠ agent-bus 是明文 HTTP + token，只适合可信网络（Tailscale / VPN / 内网穿透隧道），不要裸暴露到公网。

agent-bus 的隔离单位是 hub：黑板、公聊、私聊、声明、锁、改动历史全部挂在单个 hub 数据目录（默认 .bus/）下。每个项目开自己的 hub，上下文（对话框 + 黑板）天然隔离：

cd ~/proj-A && python3 bus.py serve --dir .bus --port 8977   # 项目 A
cd ~/proj-B && python3 bus.py serve --dir .bus --port 8978   # 项目 B（同机另一端口）

• 数据目录 .bus/ 提交进项目 git：clone 项目后 bus join（读 hub.json）自动发现地址与 token，直接加入该项目自己的总线；黑板与事件流顺带随仓库持久化。
• 同时参与多个 hub：每个 hub 各存一份身份文件，用 BUS_PEER_FILE=/path/<hub>.<名字>.json 切换。
• 同一项目内多人/多会话：不同 --name 加入同一 hub，靠 claim/lock 协作；不要把多项目混进一个 hub。

• 权限：rank 0 = 主机；掉线后在线 rank 最小者接任。强制解锁、超时裁决、强制接管都按此次序判权限。
• 锁租约：默认 15 分钟，持锁者任何操作自动续期；停止续期（掉线）即自动过期，等待队列按序递补。
• 阻塞私聊：默认 6 回合 / 30 分钟，任一耗尽转"待裁决"，权限高者 decide 一锤定音，自动归档黑板「决策记录」。
• Handoff：offer 期间锁被保护（不可 unlock/force）；accept 时 claim + 锁原子转移；reject/超时（30 分钟）自动还原。工作区有未提交改动时必须 --patch 打包或先 commit。
• Takeover：对方在线→仅更高权限者可强制接管；异常掉线→20 分钟内仅更高权限者/主机，之后任何人；主动 leave→任何人立即可接管。salvage capsule 标记 partial，先核对 git 现场再动手。
• 心跳：任何命令都算心跳；10 分钟无操作视为掉线。
• 同项目多会话：join --name 不同名字，身份存为 .bus-peer.<名字>.json；BUS_PEER_FILE 环境变量切换当前会话身份。

state.json     状态快照
events.jsonl   事件流（事实源）：peer.joined / lock.acquired / handoff.accepted / ...
board.md       共享黑板
hub.json       hub 地址与 token（可随 git 同步，供对端自动发现）
changes/       改动详情 md
capsules/      交接携带的 wip patch

纯文本，可整个提交进项目 git 做持久化与审计。hub 单点故障时，任一端可用同一数据目录重新 serve，其余端改 --hub 重新 join。

mkdir -p ~/.agents/skills/agent-bus
cp bus.py ~/.agents/skills/agent-bus/
cp skill/SKILL.md ~/.agents/skills/agent-bus/
install -m755 bus.py ~/.local/bin/bus   # 可选：让 bus 直接在 PATH 上

其他 CLI（Claude Code、Codex 等）同理，把 skill/SKILL.md 放进它们的指令/技能目录即可——契约是纯文本，与 CLI 无关。

skill 契约靠 agent 自觉，hooks 把它升级为半强制：写文件前自动加锁、锁冲突直接拦截这次工具调用、回合结束自动心跳并提醒未处理事项。

bus install-hooks claude            # ~/.claude/settings.json
bus install-hooks kimi              # ~/.kimi-code/config.toml
bus install-hooks codex             # ~/.codex/config.toml
bus install-hooks opencode          # ~/.config/opencode/plugins/agent-bus.ts
bus install-hooks pi                # ~/.pi/agent/extensions/agent-bus/index.ts
bus install-hooks all               # 全部
# claude/opencode/pi 支持 --scope project（装到当前项目目录）

• 原理：bus hook <cli> 从 stdin 读各 CLI 的 hook payload，exit 0 放行 / exit 2 拦截（stderr 即拦截原因，会回灌给模型）。
• 覆盖：Edit/Write 类工具自动锁；Bash 类工具嗅探 >、tee、sed -i 的写入目标做冲突拦截（尽力而为，允许漏判）；Stop/idle 事件自动心跳，有阻塞私聊或待接收交接时拦截收工；SessionStart 时列出未读消息提醒先处理（v0.4.1+）。
• 已实测：Claude Code 与 Kimi Code 的 payload 协议（exit 2 / stderr / JSON 语义）。Codex 的 hooks 配置按其官方"Claude 风格"文档生成，OpenCode/PI 按官方插件文档生成——这三家请以实际版本实测为准。
• hub 不可达时默认 fail-open（放行）；BUS_HOOK_ENFORCE=1 切换为 fail-closed。

不同 agent 的 hook 注册方式不一样：配置文件格式、挂载事件、以及"回合开始"支持情况都有区别，别跨 CLI 套用。

友情链接： Linux.do——新的理想型社区