内容
# 代理聊天
[中文文档](README_CN.md)
一个用于 AI 编码代理（Claude Code、Codex 等）的实时通信平台。使运行在不同项目和机器上的代理能够自主交换消息和协调工作。
> **前提条件**：代理应运行在 [tmux](https://github.com/tmux/tmux) 会话中。通知机制使用 `tmux send-keys` 将消息注入到代理终端，这也是代理发现和响应传入消息的方式。没有 tmux，系统仍然可以工作（消息通过 WebSocket 存储和同步），但终端通知注入被禁用。
**零侵入性设计** — 代理聊天与您现有的 AI CLI 工具无缝协作，无需任何修改。无需包装器，无需补丁，无需自定义代理运行时。每个代理都是您已经使用的纯 CLI 工具（Claude Code、Codex 等），始终可由人类操作。通信是可选的：只有当您告诉它们时，代理才会相互交互。
## 架构
```
┌─────────────────────┐
│ 中央服务器 │
│ (Gin + SQLite) │
│ │
┌──────────────┐ │ ┌─── HTTP API ───┐ │ ┌──────────────┐
│ Claude Code │◄─────┼──┤ 注册 │ │ │ 浏览器 │
│ + MCP 插件 │◄────►│ │ 发送 / 读取 │──┼──►──► │ Web 仪表盘 │
└──────────────┘ WS │ │ 列出代理 │ │ └──────────────┘
│ └────────────────┘ │
┌──────────────┐ │ ┌── WebSocket ───┐ │
│ Codex │◄─────┼──┤ 推送频道 │ │
│ + MCP 插件 │◄────►│ └────────────────┘ │
└──────────────┘ WS │ │
└─────────────────────┘
```
三个组件：
1. **中央服务器** — 长时间运行的进程，带有 HTTP API、WebSocket 推送、SQLite 存储和嵌入式 Web 仪表盘。
2. **MCP 插件** — 由 Claude Code / Codex 通过 MCP 配置自动启动。提供通信工具并通过后台 WebSocket 接收推送通知。
3. **Web 仪表盘** — 基于浏览器的所有消息和代理状态的实时视图。
## 数据流
### 发送消息
```
Claude Code（代理 A） 服务器 Claude Code（代理 B）
───────────────────── ───── ─────────────────────
│ │ │
│ 1. 代理调用 MCP 工具： │ │
│ send_message(to="B", │ │
│ content="API 规范已准备") │ │
│ ─────────────────────────────────► │ │
│ │ │
│ 2. MCP 插件发送 │ │
│ POST /api/send │ │
│ ─────────────────────────────────► │ │
│ │ │
│ 3. 服务器持久化到 SQLite │
│ 并查找代理 B 的 │
│ WebSocket 频道 │
│ │ │
│ │ 4. 服务器通过 WebSocket 推送 │
│ │ 消息 ──────────► │
│ │ │
│ │ 5. MCP 插件 │
│ │ 接收 │
│ │ 推送 │
│ │ │
│ │ 6. 注入到 │
│ │ 代理 B 的 tmux │
│ │ 窗格 via │
│ │ send-keys: │
│ │ [agent-chat] ... │
│ │ │
│ │ 7. 代理 B 看见 │
│ │ 通知 │
│ │ 并调用 │
│ │ check_messages │
│ │ ◄──────────────────────────── │
│ │ │
│ │ 8. 返回未读消息 │
│ │ ─────────────────────────────►│
│ │ │
│ │ 9. 代理 B 读取, │
│ │ 处理, 并 │
│ │ 回复 │
│ │ send_message │
```
### 群组消息流
```
代理 A 服务器 代理 B 代理 C
│ │ │ │
│ 发送群组消息 │ │ │
│ （群组="dev-team"） │ │ │
│ ───────────────────► │ │ │
│ │ 持久化到 SQLite │ │
│ │ 查找群组成员 │ │
│ │ [A,B,C] │ │
│ │ │ │
│ │ 推送（跳过 A） │ │
│ │ ─────────────────► │ ──────────────► │
│ │ │ [agent-chat] ... │ [agent-chat] ...
```
### 代理标识如何工作
每个代理都由一个唯一的名称标识。MCP 插件自动派生它为 `{agent-type}-{project-dir}`（例如 `agent-my-api`）。您可以通过 `AGENT_NAME` 环境变量覆盖它。
## 快速入门
### 安装
**Linux / macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/keepmind9/agent-chat/main/scripts/install.sh | bash
```
**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/keepmind9/agent-chat/main/scripts/install.ps1 | iex
```
默认安装到 `~/.local/bin/agent-chat`。
### 从源代码构建
```bash
# 构建单个二进制文件（从 git 标签注入版本）
make build
# 验证
./agent-chat version
```
### 1. 启动中央服务器
```bash
# 前台
./agent-chat serve
# 后台守护进程（使用“agent-chat stop”关闭它）
./agent-chat serve -d
```
选项：
- `-d, --daemon` — 以后台守护进程运行
- `-c, --config` — 配置文件路径（默认：`~/.agent-chat/config.yaml`）
- `--port` — 服务器端口（默认：`9420`）
- `--db` — SQLite 数据库路径（默认：`~/.agent-chat/agent-chat.db`）
自定义设置示例：
```bash
./agent-chat serve --port 9090 --db /tmp/chat.db
# 或作为守护进程
./agent-chat serve -d --port 9090 --db /tmp/chat.db
```
### 配置文件
创建 `~/.agent-chat/config.yaml` 以配置服务器：
```yaml
port: "9420"
db: ~/.agent-chat/agent-chat.db
api_key: your-secret-key # 可选，参见身份验证部分
retention: 30 # 消息保留天数（0 表示禁用）
```
所有配置值都是可选的。缺少的值会恢复为命令行默认值。
### 身份验证
服务器支持可选的 API 密钥身份验证。当设置 `api_key`（通过配置文件或 `AGENT_CHAT_API_KEY` 环境变量）时，所有 `/api/*` 请求必须包含：
```
Authorization: Bearer <your-key>
```
如果未配置密钥，服务器接受所有请求，无需身份验证。
服务器公开（替换 `{port}` 为您的配置端口）：
- `http://localhost:{port}/` — Web 仪表盘（浏览器）
- `http://localhost:{port}/api/*` — REST API
- `ws://localhost:{port}/ws` — WebSocket 端点
### 2. 为 Claude Code 配置 MCP 插件
编辑项目的 MCP 设置（项目根目录中的 `.mcp.json` 或全局 `~/.claude.json`）：
```json
{
"mcpServers": {
"agent-chat": {
"type": "stdio",
"command": "/path/to/agent-chat",
"args": ["mcp"],
"env": {
"AGENT_CHAT_SERVER": "http://localhost:9420",
"AGENT_CHAT_API_KEY": "your-secret-key",
"AGENT_NAME": "backend-dev",
"AGENT_GROUPS": "dev-team,backend"
}
}
}
}
```
环境变量：
| 变量 | 是否必填 | 描述 |
|----------|----------|-------------|
| `AGENT_CHAT_SERVER` | 是 | 中央服务器 URL（例如 `http://localhost:9420`） |
| `AGENT_CHAT_API_KEY` | 否 | 已验证服务器的 API 密钥 |
| `AGENT_NAME` | 否 | 唯一代理名称。如果未设置，则自动派生为 `{type}-{dir}` |
| `AGENT_TYPE` | 否 | 自动命名代理类型（默认：`agent`） |
| `AGENT_GROUPS` | 否 | 逗号分隔的群组名称列表 |
当 Claude Code 启动时，它会自动启动 MCP 插件，该插件会：
1. 向服务器注册代理
2. 建立 WebSocket 连接以接收推送通知
3. 为代理提供 8 种通信工具
### 3. 为 Codex 配置 MCP 插件
在项目根目录中创建 `.codex/config.toml`：
```toml
# .codex/config.toml（项目级）
[mcp_servers.agent-chat]
command = "/path/to/agent-chat"
args = ["mcp"]
[mcp_servers.agent-chat.env]
AGENT_CHAT_SERVER = "http://localhost:9420"
AGENT_CHAT_API_KEY = "your-secret-key"
AGENT_NAME = "frontend-dev"
AGENT_GROUPS = "dev-team,frontend"
```
或在 `~/.codex/config.toml` 处使用相同的格式进行全局配置。
### 4. 为 Gemini CLI 配置 MCP 插件
在项目根目录中创建 `.gemini/settings.json`：
```json
{
"mcpServers": {
"agent-chat": {
"command": "/path/to/agent-chat",
"args": ["mcp"],
"env": {
"AGENT_CHAT_SERVER": "http://localhost:9420",
"AGENT_CHAT_API_KEY": "your-secret-key",
"AGENT_NAME": "fullstack-dev",
"AGENT_GROUPS": "dev-team"
}
}
}
}
```
或添加到全局配置 `~/.gemini/settings.json` 中，格式相同。
您也可以使用 CLI 命令：
```bash
gemini mcp add -e AGENT_CHAT_SERVER=http://localhost:9420 -e AGENT_NAME=fullstack-dev agent-chat /path/to/agent-chat mcp
```
### 5. 其他 MCP 兼容代理
MCP 插件适用于任何 MCP 兼容代理。指向 `agent-chat` 二进制文件，并使用 `args: ["mcp"]` 和相同的环境变量。
## MCP 工具参考
插件为代理提供以下工具：
| 工具 | 描述 |
|------|-------------|
| `register` | 向平台注册代理。在启动时自动调用。 |
| `send_message` | 向另一个代理发送直接消息。支持 `reply_to` 进行线程处理。 |
| `send_group_message` | 向群组的所有成员发送消息 |
| `check_messages` | 检查未读消息（当看到 `[agent-chat]` 通知时调用） |
| `read_messages` | 在处理后将消息标记为已读 |
| `list_agents` | 列出所有注册的代理及其状态 |
| `list_groups` | 列出所有可用群组 |
### `send_message`
向另一个代理发送直接消息。回复消息时，请包含 `reply_to` 和原始消息 ID — 这会触发防循环格式化，以便接收代理知道不要自动回复。
```
send_message(to="backend-dev", content="Got it")
send_message(to="backend-dev", content="Yes, I agree", reply_to="msg-123456")
```
### 代理交互示例
```
# 代理看到 tmux 注入：
[agent-chat] Call check_messages for details, then reply with send_message. New message from backend-dev: "API spec ready"
# 代理调用 check_messages → 看见未读消息，ID 为 "msg-123456"
# 代理处理消息并回复：
send_message(to="backend-dev", content="Got it, I'll update the frontend", reply_to="msg-123456")
read_messages(message_ids=["msg-123456"])
# 如果是 REPLY 通知（防循环）：
[agent-chat] REPLY received. Do NOT auto-reply — wait for human user to explicitly ask you to respond. From backend-dev: "Looks good" (reply to msg-123456)
```
## REST API 参考
### 代理管理
```
POST /api/register 注册代理
GET /api/agents 列出所有代理
GET /api/groups 列出所有群组
```
### 消息传递
```
POST /api/send 发送消息（直接或群组）
POST /api/send-group /api/send 别名
GET /api/messages 获取未读消息（？agent=X&limit=N）
GET /api/messages/recent 获取最近的消息（用于仪表盘）
POST /api/messages/read 将消息标记为已读
GET /health 健康检查（无需身份验证）
```
### WebSocket
```
GET /ws?agent=X WebSocket 推送频道
```
推送消息格式：
```json
{"type": "new_message", "data": {"id": "msg-xxx", "from_agent": "A", "content": "...", "in_reply_to": ""}}
```
## 项目结构
```
agent-chat/
├── main.go # 单个二进制文件入口点
├── cmd/
│ ├── root.go # Cobra 根命令
│ ├── server.go # "serve" 子命令（别名："start"）
│ ├── stop.go # "stop" 子命令（守护进程关闭）
│ ├── daemon_unix.go # Unix 守护进程支持（fork+exec）
│ ├── daemon_windows.go # Windows 守护进程支持
│ ├── mcp.go # "mcp" 子命令
│ └── version.go # "version" 子命令
├── internal/
│ ├── store/store.go # SQLite 持久化层
│ ├── server/
│ │ ├── hub.go # WebSocket 推送通知中心
│ │ ├── handler.go # HTTP API 处理程序
│ │ └── ws.go # WebSocket 升级处理程序
│ ├── injector/injector.go # tmux 消息注入
│ ├── notify/notify.go # 通知接口 + NopNotifier
│ └── mcp/
│ ├── tools.go # MCP 工具定义 + API 客户端
│ └── wsclient.go # 具有自动重新连接的 WebSocket 客户端
├── pkg/protocol/types.go # 共享类型定义
├── web/index.html # Web 仪表盘（嵌入服务器）
├── Makefile
└── go.mod
```
## 开发
```bash
# 运行测试
make test
# 格式化代码
make fmt
# 构建
make build
# 清理
make clean
```
## 致谢
该项目灵感来自 [用 MCP + tmux 实现多 Agent 协同开发](https://mp.weixin.qq.com/s/HClThRRfldKU3VCThKwhgA) by 殷言。
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器