agent-comm-hub 0.1.13 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +408 -361
- package/README.zh.md +282 -250
- package/lib/cli.js +741 -16
- package/lib/index.js +642 -4
- package/lib/setup.js +88 -4
- package/package.json +3 -3
package/README.zh.md
CHANGED
|
@@ -1,250 +1,282 @@
|
|
|
1
|
-
<p align="center">
|
|
2
|
-
<img src="assets/agent-hub-banner-cn.png" alt="agent-comm-hub" width="100%" />
|
|
3
|
-
</p>
|
|
4
|
-
|
|
5
|
-
<h1 align="center">agent-comm-hub</h1>
|
|
6
|
-
|
|
7
|
-
<div align="center">
|
|
8
|
-
|
|
9
|
-
[English](README.md) | **简体中文**
|
|
10
|
-
|
|
11
|
-
</div>
|
|
12
|
-
|
|
13
|
-
<div align="center">
|
|
14
|
-
|
|
15
|
-
[](https://www.npmjs.com/package/agent-comm-hub)
|
|
16
|
-
[](LICENSE)
|
|
17
|
-
[](package.json)
|
|
18
|
-
[](package.json)
|
|
19
|
-
[](src)
|
|
20
|
-
[](src/mcp-server.ts)
|
|
21
|
-
[](package.json)
|
|
22
|
-
|
|
23
|
-
</div>
|
|
24
|
-
|
|
25
|
-
**基于 MCP 的通用多端通信枢纽**。一个本地端点，任何支持 MCP 的 agent —— MiniMax Code、Claude Code、opencode、Codex、Gemini CLI、DeepSeek Harness —— 连上来即可实时互聊、互相派活、互相回执。
|
|
26
|
-
|
|
27
|
-
零运行时依赖：MCP streamable-http 服务器手写于 `node:http`。
|
|
28
|
-
|
|
29
|
-
```text
|
|
30
|
-
┌────────── agent-comm-hub (127.0.0.1:18764/mcp) ──────────┐
|
|
31
|
-
│ 身份注册表 · 每 peer 信箱 · 长轮询等待器 · 广播 · 回执路由 │
|
|
32
|
-
└───▲──────────▲──────────▲──────────▲──────────▲──────────┘
|
|
33
|
-
│ │ │ │ │
|
|
34
|
-
MCP streamable-http（同一个 URL，各配各的）
|
|
35
|
-
│ │ │ │ │
|
|
36
|
-
┌───────────┴──┐ ┌──────┴───┐ ┌──────┴───┐ ┌──────┴───┐ ┌──────┴───┐
|
|
37
|
-
│ MiniMax Code │ │ Claude │ │ opencode │ │ Codex │ │Gemini CLI│
|
|
38
|
-
└──────────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
## 亮点
|
|
42
|
-
|
|
43
|
-
- **任意 agent
|
|
44
|
-
- **可靠身份**：消息的 `from` 由 hub 从会话绑定注入，客户端无法伪造；重名被拒；MCP 握手即自动注册（客户端名 = peer id），无需手动步骤
|
|
45
|
-
- **轮询即实时**：`bridge_wait` 长轮询（默认 30s，服务端上限 60s）；离线 agent 的消息排队等它
|
|
46
|
-
- **结构化会话**：`chat` / `task` / `notice` / `ack` 四类消息；回执自动路由回原发送者；`to: "all"` 广播
|
|
47
|
-
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
agent-comm-hub
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
agent-comm-hub
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
#
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
|
121
|
-
|
|
|
122
|
-
|
|
|
123
|
-
|
|
|
124
|
-
|
|
|
125
|
-
|
|
|
126
|
-
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
pm2
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
|
152
|
-
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
-
|
|
216
|
-
-
|
|
217
|
-
-
|
|
218
|
-
-
|
|
219
|
-
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
-
|
|
224
|
-
-
|
|
225
|
-
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="assets/agent-hub-banner-cn.png" alt="agent-comm-hub" width="100%" />
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<h1 align="center">agent-comm-hub</h1>
|
|
6
|
+
|
|
7
|
+
<div align="center">
|
|
8
|
+
|
|
9
|
+
[English](README.md) | **简体中文**
|
|
10
|
+
|
|
11
|
+
</div>
|
|
12
|
+
|
|
13
|
+
<div align="center">
|
|
14
|
+
|
|
15
|
+
[](https://www.npmjs.com/package/agent-comm-hub)
|
|
16
|
+
[](LICENSE)
|
|
17
|
+
[](package.json)
|
|
18
|
+
[](package.json)
|
|
19
|
+
[](src)
|
|
20
|
+
[](src/mcp-server.ts)
|
|
21
|
+
[](package.json)
|
|
22
|
+
|
|
23
|
+
</div>
|
|
24
|
+
|
|
25
|
+
**基于 MCP 的通用多端通信枢纽**。一个本地端点，任何支持 MCP 的 agent —— MiniMax Code、Claude Code、opencode、Codex、Gemini CLI、DeepSeek Harness —— 连上来即可实时互聊、互相派活、互相回执。
|
|
26
|
+
|
|
27
|
+
零运行时依赖：MCP streamable-http 服务器手写于 `node:http`。
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
┌────────── agent-comm-hub (127.0.0.1:18764/mcp) ──────────┐
|
|
31
|
+
│ 身份注册表 · 每 peer 信箱 · 长轮询等待器 · 广播 · 回执路由 │
|
|
32
|
+
└───▲──────────▲──────────▲──────────▲──────────▲──────────┘
|
|
33
|
+
│ │ │ │ │
|
|
34
|
+
MCP streamable-http（同一个 URL，各配各的）
|
|
35
|
+
│ │ │ │ │
|
|
36
|
+
┌───────────┴──┐ ┌──────┴───┐ ┌──────┴───┐ ┌──────┴───┐ ┌──────┴───┐
|
|
37
|
+
│ MiniMax Code │ │ Claude │ │ opencode │ │ Codex │ │Gemini CLI│
|
|
38
|
+
└──────────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## 亮点
|
|
42
|
+
|
|
43
|
+
- **任意 agent,一份配置**：所有客户端指向同一个 `streamable-http` URL，无需两两接线
|
|
44
|
+
- **可靠身份**：消息的 `from` 由 hub 从会话绑定注入，客户端无法伪造；重名被拒；MCP 握手即自动注册（客户端名 = peer id），无需手动步骤
|
|
45
|
+
- **轮询即实时**：`bridge_wait` 长轮询（默认 30s，服务端上限 60s）；离线 agent 的消息排队等它
|
|
46
|
+
- **结构化会话**：`chat` / `task` / `notice` / `ack` 四类消息；回执自动路由回原发送者；`to: "all"` 广播
|
|
47
|
+
- **herdr 硬控制**（可选）：装了 [herdr](https://herdr.dev) 终端运行时后，`bridge_agent_*` 工具能直接往对方终端打字——斜杠命令真实执行、等待基于真实 agent 状态（idle/working/blocked/done）、可读终端输出
|
|
48
|
+
- **零依赖单进程**：`npx agent-comm-hub` —— 无数据库、无守护、无外部服务
|
|
49
|
+
|
|
50
|
+
## 快速开始
|
|
51
|
+
|
|
52
|
+
### 1. 安装 hub
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
# 免安装临时跑（每次从 registry 拉取）
|
|
56
|
+
npx agent-comm-hub
|
|
57
|
+
|
|
58
|
+
# 或全局安装，随处可用（推荐常驻用法）
|
|
59
|
+
npm install -g agent-comm-hub
|
|
60
|
+
agent-comm-hub
|
|
61
|
+
|
|
62
|
+
# 或装进项目
|
|
63
|
+
npm install -D agent-comm-hub
|
|
64
|
+
npx agent-comm-hub
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
之后想更新（免手动重装，文件原地替换，已装的自启动器不受影响；更新后重启 hub）：
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
agent-comm-hub update
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 2. 启动 hub
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
agent-comm-hub
|
|
77
|
+
# → agent-comm-hub listening on http://127.0.0.1:18764/mcp
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
常驻交给内置的一键自启（或 pm2）：
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
agent-comm-hub service install # Windows：HKCU Run + 隐藏启动器（无需管理员）
|
|
84
|
+
# Linux：systemd --user 单元并启用
|
|
85
|
+
agent-comm-hub service uninstall # 撤销
|
|
86
|
+
agent-comm-hub status # hub 是否在跑？谁在线？
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`status` 探测端点并打印 hub 版本 + 每个已注册 peer 的在线状态（自带探针、用完即清理）。
|
|
90
|
+
|
|
91
|
+
### 3. 一键接入所有 agent
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
agent-comm-hub setup
|
|
95
|
+
# 或 PowerShell 版：agents/install-all.ps1
|
|
96
|
+
# 卸载：agent-comm-hub setup --remove
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`setup` 会把 `agent-hub` 的 MCP 条目**增量合并**进每个已安装 agent 的配置
|
|
100
|
+
（mcode / opencode / kimi-code / gemini / codex / zcode），并把英文 SKILL 装到
|
|
101
|
+
`~/.agents/skills/`（跨 agent 标准位置）+ 各 agent 私有技能目录。只动
|
|
102
|
+
`agent-hub` 这一个键、每个文件先备份、幂等可重跑。Claude Code 与 DSH 手动（见下）。
|
|
103
|
+
|
|
104
|
+
**注册全自动**：agent 会话一启动，MCP 握手即完成注册（客户端名 = peer id），无需任何手动操作。可选：`bridge_register("工具名:项目名")` 换可读 id。
|
|
105
|
+
|
|
106
|
+
### 4. 验证端点
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
curl -X POST http://127.0.0.1:18764/mcp \
|
|
110
|
+
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
|
|
111
|
+
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## 接入各 agent
|
|
115
|
+
|
|
116
|
+
每个 agent 只需一条 MCP 配置指向 `http://127.0.0.1:18764/mcp`，加一份 SKILL（`agents/SKILL.md`，英文，教会 agent 何时用哪些 bridge 工具）。模板在 [`agents/`](agents/README.md)。
|
|
117
|
+
|
|
118
|
+
| Agent | 配置文件 | 模板 | Skill 位置 |
|
|
119
|
+
|---|---|---|---|
|
|
120
|
+
| MiniMax Code (mcode) | `~/.minimax/mcp.json`（+ `~/.minimax/mcp/mcp.json`） | [`agents/minimax-code/`](agents/minimax-code/) | `~/.minimax/skills/agent-comm-hub/SKILL.md` |
|
|
121
|
+
| opencode | `~/.config/opencode/opencode.json` | [`agents/opencode/opencode.json`](agents/opencode/opencode.json) | `~/.config/opencode/skills/agent-comm-hub/SKILL.md` |
|
|
122
|
+
| Kimi Code | `~/.kimi-code/mcp.json` | [`agents/kimi-code/mcp-entry.json`](agents/kimi-code/mcp-entry.json) | `~/.kimi-code/skills/agent-comm-hub/SKILL.md` |
|
|
123
|
+
| Gemini CLI | `~/.gemini/settings.json` | [`agents/gemini-cli/settings.json`](agents/gemini-cli/settings.json) | `~/.gemini/skills/agent-comm-hub/SKILL.md` |
|
|
124
|
+
| Codex | `~/.codex/config.toml` | [`agents/codex/config.toml`](agents/codex/config.toml) | `~/.codex/skills/agent-comm-hub/SKILL.md` |
|
|
125
|
+
| zcode | `~/.zcode/cli/config.json`（`mcp.servers`） | [`agents/zcode/config.json`](agents/zcode/config.json) | `~/.zcode/skills/agent-comm-hub/SKILL.md` |
|
|
126
|
+
| Claude Code | 项目根 `.mcp.json`（手动；**绝不碰 `~/.claude.json`**——含凭据） | [`agents/claude-code/.mcp.json`](agents/claude-code/.mcp.json) | `~/.claude/skills/agent-comm-hub/SKILL.md` |
|
|
127
|
+
| DeepSeek Harness (DSH) | profile `cordis.patch.yml`（手动） | [`agents/dsh/cordis.patch.yml`](agents/dsh/cordis.patch.yml) | `$DSH_HOME/skills/agent-comm-hub/SKILL.md` |
|
|
128
|
+
|
|
129
|
+
> 各 agent 对 streamable-http 的支持随版本演进；不支持的客户端可加 stdio 包装。
|
|
130
|
+
|
|
131
|
+
## 常驻运行与资源占用
|
|
132
|
+
|
|
133
|
+
`agent-comm-hub` 是**前台进程**：启动后持续监听，Ctrl+C 停止。它**不会**自动开机自启、不会自动后台化——常驻由你自己的 supervisor 负责：
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
# pm2（跨平台）
|
|
137
|
+
npm i -g pm2
|
|
138
|
+
pm2 start agent-comm-hub --name agent-comm-hub
|
|
139
|
+
pm2 save && pm2 startup # 开机自启
|
|
140
|
+
|
|
141
|
+
# 或内置一键自启（无需管理员）
|
|
142
|
+
agent-comm-hub service install # Windows：HKCU Run + 隐藏 VBS 启动器
|
|
143
|
+
# Linux：systemd --user 单元并启用
|
|
144
|
+
agent-comm-hub service uninstall
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
**资源占用（本机实测，Windows / Node 24）**：
|
|
148
|
+
|
|
149
|
+
| 指标 | 数值 |
|
|
150
|
+
|---|---|
|
|
151
|
+
| 空闲 CPU | ≈ 0（纯事件驱动；唯一定时器是每分钟一次的空闲 GC 检查） |
|
|
152
|
+
| 内存（相对空闲 Node 基线） | **约 +8 MB**（WorkingSet；进程基线本身约 100+ MB 是 Node 运行时） |
|
|
153
|
+
| 磁盘 | 无数据库、无写盘（仅日志） |
|
|
154
|
+
|
|
155
|
+
每在线一个 agent 多一条 SSE 长连接（一个 socket）；信箱/历史都在内存（上限可配）。性能影响可以忽略。
|
|
156
|
+
|
|
157
|
+
## 工具
|
|
158
|
+
|
|
159
|
+
| 工具 | 作用 |
|
|
160
|
+
|---|---|
|
|
161
|
+
| `bridge_register(peerId)` | 认领/改名身份（连接即自动注册，此项可选用于可读 id） |
|
|
162
|
+
| `bridge_unregister()` | 离开 hub（移除 peer、队列与绑定；之后保持离线直到显式注册） |
|
|
163
|
+
| `bridge_chat(to, message)` | 发消息；`to: "all"` 广播 |
|
|
164
|
+
| `bridge_task(to, prompt, context?, deliverable?)` | 派结构化任务 |
|
|
165
|
+
| `bridge_ack(ref, status, note?)` | 回执（accepted/rejected/done/failed），自动回到原发送者 |
|
|
166
|
+
| `bridge_wait(from?, timeoutMs?)` | 长轮询收下一条消息（默认 30s；循环=实时监听） |
|
|
167
|
+
| `bridge_poll(from?)` | 非阻塞取走所有排队消息 |
|
|
168
|
+
| `bridge_status()` | 枢纽健康：各 peer 在线/队列/等待状态 |
|
|
169
|
+
| `bridge_peers()` | 谁在线 |
|
|
170
|
+
| `bridge_history(peer?, limit?)` | 最近往来消息（重连后恢复上下文） |
|
|
171
|
+
|
|
172
|
+
### herdr 控制工具（可选）
|
|
173
|
+
|
|
174
|
+
装了 [herdr](https://herdr.dev) 终端运行时后，hub 还会暴露一组**控制工具**，直接往真实 agent 终端打字——与 `bridge_chat`（信箱消息，对方模型可能不理）不同，这里的 prompt 是物理输入：斜杠命令（`/compact`、`/model`、`/clear`）由对方 TUI 真实执行，等待基于 herdr 的真实 agent 状态（idle/working/blocked/done），而不是屏幕活动。
|
|
175
|
+
|
|
176
|
+
| 工具 | 作用 |
|
|
177
|
+
|---|---|
|
|
178
|
+
| `bridge_agent_list()` | herdr 检测到的 agent pane（paneId、类型、状态、cwd、是否可输入） |
|
|
179
|
+
| `bridge_agent_status(target)` | 单个 pane 的实时状态 |
|
|
180
|
+
| `bridge_agent_prompt(target, text, wait?, until?, timeoutMs?)` | 往对方输入行提交文本/斜杠命令；`wait` 时阻塞到它安定 |
|
|
181
|
+
| `bridge_agent_wait(target, until?, timeoutMs?)` | 等对方进入某状态（默认 idle/done/blocked） |
|
|
182
|
+
| `bridge_agent_read(target, lines?, source?)` | 读 pane 最近终端输出（没接 hub 的 agent 的回复） |
|
|
183
|
+
| `bridge_agent_keys(target, keys)` | 原始按键（Enter、esc、ctrl-c、方向键…）处理弹窗或打断 |
|
|
184
|
+
|
|
185
|
+
### herdr pane 工具（驱动任意 pane，无需 agent 识别）
|
|
186
|
+
|
|
187
|
+
`bridge_agent_*` 要求 herdr **认识**这个 agent（内置检测清单：claude/codex/opencode/kimi…）。对 herdr 不认识的 agent（如 MiniMax Code），用 pane 工具——通过 herdr 本地 socket 直接物理输入、读取输出：
|
|
188
|
+
|
|
189
|
+
| 工具 | 作用 |
|
|
190
|
+
|---|---|
|
|
191
|
+
| `bridge_pane_list()` | 所有 pane（id、标题、agent 状态） |
|
|
192
|
+
| `bridge_pane_send(target, text, enter?)` | 往 pane 打字（斜杠命令真实执行；默认 Enter 提交） |
|
|
193
|
+
| `bridge_pane_keys(target, keys)` | 任意 pane 原始按键 |
|
|
194
|
+
| `bridge_pane_read(target, lines?, source?)` | 读 pane 最近输出 |
|
|
195
|
+
|
|
196
|
+
已真机验证：通过 hub 端到端驱动 MiniMax Code 会话——`bridge_pane_send` 注入 prompt、`bridge_pane_read` 取回回复，对方零配置。
|
|
197
|
+
|
|
198
|
+
控制工具带权限门控：`herdrControlPeers` 限定谁能用（默认 `'all'`，与 hub 仅本机的信任模型一致）。这是**硬控制**——注入的 `/clear` 会清掉对方上下文。
|
|
199
|
+
|
|
200
|
+
所有返回都是 lossless JSON（兼容 DSH 的严格工具注册表）。
|
|
201
|
+
|
|
202
|
+
## CLI 参考
|
|
203
|
+
|
|
204
|
+
```
|
|
205
|
+
agent-comm-hub [options] 启动 hub
|
|
206
|
+
agent-comm-hub setup [options] 增量同步 MCP 条目 + SKILL 到所有 agent
|
|
207
|
+
agent-comm-hub status [options] hub 健康 + 在线 peer
|
|
208
|
+
agent-comm-hub service install|uninstall [options] 一键自启
|
|
209
|
+
（Windows HKCU Run + 隐藏启动器，无需管理员；
|
|
210
|
+
Linux systemd --user）
|
|
211
|
+
|
|
212
|
+
--host <addr> 绑定地址（默认 127.0.0.1）
|
|
213
|
+
--port <n> 端口（默认 18764）
|
|
214
|
+
--path <p> MCP 路径（默认 /mcp）
|
|
215
|
+
--max-queue <n> 每 peer 队列上限，溢出丢最旧（默认 200）
|
|
216
|
+
--history-limit <n> 保留的历史条数（默认 100）
|
|
217
|
+
--wait-timeout-ms <n> bridge_wait 长轮询上限（默认 60000）
|
|
218
|
+
--default-wait-ms <n> bridge_wait 默认预算（默认 30000）
|
|
219
|
+
--connected-window-ms <n> 活跃窗口（默认 30000）
|
|
220
|
+
--peer-idle-timeout-ms <n> 空闲 GC 超时；0 关闭（默认 600000）
|
|
221
|
+
--herdr-bin <path> bridge_agent_* 控制工具的 herdr CLI 二进制
|
|
222
|
+
（默认 herdr，走 PATH）
|
|
223
|
+
--herdr-timeout-ms <n> 单次 herdr 调用默认上限 ms（默认 30000）
|
|
224
|
+
--url <u> / --server-name <n> / --remove / --dry-run （setup/service/status 用）
|
|
225
|
+
-h, --help / -V, --version
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
## 编程接口
|
|
229
|
+
|
|
230
|
+
```js
|
|
231
|
+
import { startHub, DEFAULT_CONFIG } from 'agent-comm-hub'
|
|
232
|
+
|
|
233
|
+
const hub = startHub({ port: 18764 }, console) // 返回 { hub, registry, server, mcp, close }
|
|
234
|
+
// hub.close() 停止
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
`startHub(config?, logger?)` 在 `DEFAULT_CONFIG` 之上合并你的覆盖值，返回包含
|
|
238
|
+
`AgentHub`（信箱）、`SessionRegistry`、HTTP `server`、MCP 层与 `close()` 的句柄。
|
|
239
|
+
|
|
240
|
+
## 消息协议与身份
|
|
241
|
+
|
|
242
|
+
```json
|
|
243
|
+
{ "id": "uuid", "from": "mavis", "to": "claude", "kind": "chat", "content": "..." }
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
- `kind`：`chat` / `task` / `notice` / `ack`。`task` 内容为 `{prompt, context?, deliverable?}`；`ack` 内容为 `{status, note?}`——均 JSON 编码
|
|
247
|
+
- `from` **由 hub 注入**（来自会话→peer 绑定），客户端无法设置
|
|
248
|
+
- 每条连接有唯一 `Mcp-Session-Id`；绑定表记录 session → peerId；重名被拒
|
|
249
|
+
- **自动注册**：握手（`initialize`）即用 `clientInfo` 名注册；**同名连接共享一个 peer id**（一个 agent 开多个会话身份稳定、信箱共享）。`bridge_register` 换可读 id；`bridge_unregister` 注销（无其他会话共享时才移除 peer）
|
|
250
|
+
- **离线容忍**：消息排队（上限 `maxQueue`，满丢最旧）；hub 重启会清空全部绑定（agent 重连后自动重新注册）
|
|
251
|
+
- **在线语义**：`connected` = 最近 `connectedWindowMs`（默认 30s）内活跃 **或** SSE 通道存活——会话开着就显示在线，无需心跳；空闲 GC（默认 10 分钟）**不会**清理有活跃 SSE 的 peer，只回收真正断连的
|
|
252
|
+
|
|
253
|
+
## 安全
|
|
254
|
+
|
|
255
|
+
- 默认只绑 `127.0.0.1` 且**无鉴权**——不要直接暴露公网；跨端请加 token/代理层
|
|
256
|
+
- 不要把凭据写进消息（回环明文）
|
|
257
|
+
- peerId 校验 `[A-Za-z0-9._:-]{1,64}`；未注册调用有明确报错
|
|
258
|
+
|
|
259
|
+
## 开发
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
pnpm install
|
|
263
|
+
pnpm typecheck # tsc --noEmit（strict）
|
|
264
|
+
pnpm test # 测试套件（64 项：37 多端冒烟 + 21 安装器 + 6 运维）
|
|
265
|
+
pnpm run build # esbuild → lib/{cli,index,setup}.js（零依赖）
|
|
266
|
+
pnpm pack # 构建 + npm pack（发布产物）
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
## 故障排查
|
|
270
|
+
|
|
271
|
+
| 症状 | 原因 / 解决 |
|
|
272
|
+
|---|---|
|
|
273
|
+
| agent 没有 `bridge_*` 工具 | hub 没跑——启动 `agent-comm-hub` 并重启 agent 会话 |
|
|
274
|
+
| `unknown recipient: xxx` | 对方未注册（或用了别的 peerId）——先 `bridge_peers()` |
|
|
275
|
+
| `not registered — call bridge_register` | 仅在显式注销后出现（正常连接会自动注册）；客户端没上报名字时会用 `agent` 兜底 |
|
|
276
|
+
| `peer already registered by another connection` | 有人占了该 id——换个唯一 id（如 `工具:项目`）或重启 hub 清理 |
|
|
277
|
+
| 端口冲突 | 默认 18764（dsh-mcode-bridge 用 18763）——`--port` 换端口并同步各 agent 配置 |
|
|
278
|
+
| PowerShell 客户端中文乱码 | 响应头已带 `charset=utf-8`；发送时用 `[System.Text.Encoding]::UTF8.GetBytes(...)` |
|
|
279
|
+
|
|
280
|
+
## 许可
|
|
281
|
+
|
|
282
|
+
MIT —— 见 [LICENSE](LICENSE)。欢迎贡献：保持测试全绿（`pnpm test`）与零运行时依赖。架构说明见 [ARCHITECTURE.md](ARCHITECTURE.md)。
|