内容
# agent-bridge
**English** | [简体中文](README.zh-CN.md)
<p align="center">
<img src="https://img.shields.io/badge/version-1.3.0-blue" alt="version">
<img src="https://img.shields.io/badge/python-3.9+-green" alt="python">
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey" alt="platform">
<img src="https://img.shields.io/badge/license-MIT-brightgreen" alt="license">
<img src="https://img.shields.io/badge/dependencies-zero-success" alt="dependencies">
</p>
**让您的 AI 编程代理协同工作。本地运行。无需配置。无需云服务。**
您拥有 Codex、Claude Code、Reasonix、ZCode — 但它们彼此无法通信。 **agent-bridge** 为它们提供了一个共享任务板，位于您的机器上。委托工作，提问，审查代码 — 无需离开终端。只需一个命令即可安装，无需依赖，数据不会离开您的机器。
> CLI 命令为 `bridge`。所有内容都存放在 `~/.agent-bridge/` 目录中。就是这样。
---
## 为什么使用 agent-bridge？
| | 没有 agent-bridge | 使用 agent-bridge |
|---|---|---|
| **任务交接** | 在终端之间复制粘贴 | `bridge send --to codex "设计身份验证"` |
| **状态跟踪** | "你完成了吗？" | `bridge board` — 一目了然 |
| **代码审查** | Slack、PR、上下文切换 | `bridge review <id> --verdict approve` |
| **上下文共享** | 分散在聊天中 | `bridge context --add "决定使用 JWT"` |
| **维护** | 手动清理 | 自动清理过期任务，存档旧任务 |
---
## 快速开始
```bash
# 1. 安装 — 自动检测此机器上的所有代理
# Windows:
.\install.ps1 -Auto
# macOS / Linux:
./install.sh --auto
# 2. 发送任务（自动唤醒目标代理）
bridge send --to codex --subject "设计身份验证模块" --body "JWT + 刷新"
# 3. 另一个代理接收任务
bridge inbox # 查看指派给我的任务
bridge claim <id> # 我正在处理
bridge done <id> --result "参见 auth/design.md"
bridge board # 查看所有任务
```
整个流程：**发送 → 领取 → 完成**。其他功能都是额外的。
---
## 需求
- **Windows 10/11**，配备 PowerShell 5.1+，或 **macOS / Linux**，配备 Bash
- **Python 3.9+**（仅标准库 — 无需 pip 安装）
- 一个或多个支持的代理应用程序
## 支持的代理
| 代理 | 桌面版 | CLI | 如何签到 |
|---|:---:|:---:|---|
| **Codex** | ✅ | ✅ | AGENTS.md 指令 + MCP |
| **Claude Code** | ✅ | ✅ | UserPromptSubmit 钩子（自动） |
| **ZCode** | ✅ | — | 插件钩子（自动） |
| **Reasonix** | ✅ | ✅ | system_prompt + MCP，或 `--wake` |
---
## 工作原理
```mermaid
flowchart TB
subgraph Agents["您的 AI 代理 — 一台机器"]
C["Codex<br/>AGENTS.md + MCP"]
L["Claude Code<br/>UserPromptSubmit 钩子"]
Z["ZCode<br/>插件钩子"]
R["Reasonix<br/>system_prompt + MCP"]
end
subgraph Transport["传输层"]
CLI["bridge CLI<br/>终端代理"]
MCP["bridge_mcp<br/>MCP 服务器 · 桌面应用程序"]
end
subgraph Board["共享状态 — ~/.agent-bridge/"]
BJ["board.json<br/>任务状态"]
AJ["activity.jsonl<br/>审计日志"]
AR["archive.json<br/>旧任务"]
end
C --> CLI
L --> CLI
Z --> CLI
C -.-> MCP
L -.-> MCP
R -.-> MCP
CLI --> BJ
MCP --> BJ
BJ --> AJ
BJ --> AR
Agents -.->|"通知 + 唤醒"| Agents
```
### 交付状态机
```mermaid
stateDiagram-v2
[*] --> queued: bridge send
queued --> wake_launched: 唤醒进程已启动
queued --> unavailable: 无可用通知通道
wake_launched --> acknowledged: 目标代理签到
wake_launched --> failed: 交付错误
unavailable --> [*]
failed --> [*]
acknowledged --> [*]
```
### 任务生命周期
```mermaid
stateDiagram-v2
[*] --> pending: bridge send
pending --> working: bridge claim
working --> completed: bridge done
working --> input_required: bridge question
input_required --> working: bridge answer
working --> review_requested: bridge review
review_requested --> completed: bridge review --verdict approve
review_requested --> changes_requested: bridge review --verdict changes
changes_requested --> working: bridge claim
completed --> [*]
```
## 主要功能
### 跨平台文件锁定
使用 `fcntl.flock`（Unix），`O_CREAT|O_EXCL`（Windows）进行可移植锁定。通过 PID 验证进行过期锁定检测，防止死锁。已测试并验证了 40 个进程的并发写入。
### 智能路由
每个代理都宣传其优势（`bridge agents`）。协调器读取团队配置文件并决定谁来执行任务 — 无需固定的路由表。使用 `--skill` 作为路由提示。
### 自动推送：发送唤醒目标
每个 `bridge send` 都自动唤醒目标代理。桌面通知 + 无头执行 — 无需手动终端切换。使用 `--no-wake` 进行非紧急任务。
### 交付跟踪
每次通知尝试都可在 `task.delivery.status` 中观察到：
| 状态 | 含义 |
|---|---|
| `queued` | 已存储，等待交付尝试 |
| `wake_launched` | 唤醒进程已启动（非接收确认） |
| `acknowledged` | 目标代理通过 `status`、`inbox` 或 `claim` 签到 |
| `unavailable` | 无可用通知或唤醒通道 |
| `failed` | 交付尝试本身失败 |
`bridge send` 永远不会将启动的进程报告为确认。
### 自动清理
板块自行维护：已完成的任务（7 天后）会被静默清理，卡住的任务（>24 小时）会被自动标记为失败，溢出的已完成任务会被存档到 `archive.json`。
### 100% 本地，100% 私有
无需云服务，无需服务器，无需账户。所有内容都存放在 `~/.agent-bridge/` 目录中。一台机器 = 一个团队。通过 Syncthing、Dropbox 或 git 进行多机器同步。
---
## 安装
**Windows（PowerShell）：**
```powershell
.\install.ps1 -Auto
.\install.ps1 -Agent codex -As codex
.\install.ps1 -Auto -Uninstall
```
**macOS / Linux:**
```bash
./install.sh --auto
./install.sh --agent codex --as codex
./install.sh --auto --uninstall
```
两个安装程序都是幂等的。安装后重启代理应用程序以加载 MCP 和钩子配置。
---
## 核心命令
```text
bridge status [--oneliner] bridge inbox
bridge send --to NAME --subject TEXT [--body TEXT] [--no-wake] [--skill TAG]
bridge claim ID bridge done ID --result TEXT
bridge show ID bridge board
bridge question ID --body TEXT bridge answer ID --body TEXT
bridge review ID [--verdict approve|changes] [--body TEXT]
bridge agents bridge activity [--since TS]
bridge project init|list|show bridge context --show|--add TEXT
bridge clean --days N|--all [--dry-run] bridge doctor [--strict]
bridge whoami bridge wake AGENT
bridge who-coordinates bridge log --what TEXT
```
MCP 服务器公开了与 MCP 工具相同的 20 个工作流程（`bridge_send`、`bridge_inbox` 等）。
### 任务生命周期
```
send → pending → claim → working → done → completed
↘ question → input_required → answer → pending
↘ review → review_requested → approve → completed
↘ changes → changes_requested → claim → working
```
只有受托人可以领取、提问、审查或完成。只有发送者可以回答问题和发出裁决。
---
## 故障排除
```bash
bridge doctor --strict # 完整健康检查
bridge status --oneliner # 快速查看收件箱计数
bridge agents # 查看可用代理
```
如果任务保持 `wake_launched` 状态，代理已启动但未签到。请重启目标应用程序并验证其钩子/MCP 配置。
---
## 测试
```bash
python -m unittest discover -s tests -v # 29 个测试
python -m compileall -q scripts tests # 语法检查
```
Windows 覆盖范围包括隔离的安装/重新安装/卸载、无依赖通知、GBK 输出、MCP 调用和 40 个进程的并发写入。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE)
