agent-comm-hub 0.1.6

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.
Files changed (21) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +353 -0
  3. package/README.zh.md +243 -0
  4. package/agents/README.md +49 -0
  5. package/agents/SKILL.md +62 -0
  6. package/agents/claude-code/.mcp.json +8 -0
  7. package/agents/codex/config.toml +3 -0
  8. package/agents/dsh/cordis.patch.yml +7 -0
  9. package/agents/gemini-cli/settings.json +8 -0
  10. package/agents/install-all.ps1 +177 -0
  11. package/agents/kimi-code/mcp-entry.json +10 -0
  12. package/agents/minimax-code/SKILL.md +62 -0
  13. package/agents/minimax-code/install-mcode.ps1 +121 -0
  14. package/agents/minimax-code/mcp-entry.json +10 -0
  15. package/agents/opencode/opencode.json +9 -0
  16. package/assets/agent-hub-banner-cn.png +0 -0
  17. package/assets/agent-hub-banner.png +0 -0
  18. package/lib/cli.js +1239 -0
  19. package/lib/index.js +798 -0
  20. package/lib/setup.js +168 -0
  21. package/package.json +46 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 agent-comm-hub contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,353 @@
1
+ <p align="center">
2
+ <img src="assets/agent-hub-banner.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.zh.md)
10
+
11
+ </div>
12
+
13
+ <div align="center">
14
+
15
+ [![npm version](https://img.shields.io/npm/v/agent-comm-hub?style=flat-square&logo=npm&label=npm)](https://www.npmjs.com/package/agent-comm-hub)
16
+ [![license MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
17
+ [![node >=22](https://img.shields.io/badge/Node-%3E%3D22-339933?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
18
+ [![zero dependencies](https://img.shields.io/badge/Dependencies-0-2ea44f?style=flat-square)](package.json)
19
+ [![TypeScript strict](https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white)](src)
20
+ [![MCP streamable-http](https://img.shields.io/badge/MCP-streamable--http-1F6FEB?style=flat-square)](src/mcp-server.ts)
21
+ [![platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-6f42c1?style=flat-square)](package.json)
22
+
23
+ </div>
24
+
25
+ **Generic multi-peer communication hub over MCP.** One local endpoint, any MCP-capable agent — MiniMax Code, Claude Code, opencode, Codex, Gemini CLI, DeepSeek Harness — connects, claims an identity, and chats with, delegates tasks to, and acknowledges every other connected agent in real time.
26
+
27
+ Zero runtime dependencies: the MCP streamable-http server is hand-rolled over `node:http`.
28
+
29
+ ```text
30
+ ┌────────── agent-comm-hub (127.0.0.1:18764/mcp) ──────────┐
31
+ │ peer registry (bridge_register) · per-peer mailboxes · │
32
+ │ long-poll waiters · broadcast · task/ack routing │
33
+ └───▲──────────▲──────────▲──────────▲──────────▲──────────┘
34
+ │ │ │ │ │
35
+ mcp.json │ .mcp.json │ opencode.json │ config.toml │ settings.json
36
+ ┌──────────┴──┐ ┌───────┴───┐ ┌───────┴───┐ ┌──────┴───┐ ┌───────┴───┐
37
+ │ MiniMax Code│ │ Claude Code│ │ opencode │ │ Codex │ │Gemini CLI │
38
+ └─────────────┘ └───────────┘ └───────────┘ └──────────┘ └───────────┘
39
+ ```
40
+
41
+ ## Highlights
42
+
43
+ - **Any agent, one config**: every client points at the same `streamable-http` URL — no per-pair wiring.
44
+ - **Reliable identity**: the sender of every message is derived from the connection's session binding, never caller-supplied — peers cannot impersonate each other; duplicate ids are rejected. Connecting the MCP auto-registers your client name — no manual setup.
45
+ - **Real-time by polling**: `bridge_wait` long-polls (default 30 s, server ceiling 60 s); messages queue for offline peers.
46
+ - **Structured conversations**: `chat` / `task` / `notice` / `ack` message kinds, acks auto-routed back to the original sender, `to: "all"` broadcast.
47
+ - **Zero dependencies, one process**: `npx agent-comm-hub` — no database, no daemon, no external services.
48
+
49
+ ## Quickstart
50
+
51
+ ### 1. Install the hub
52
+
53
+ ```bash
54
+ # run without installing (fetches from the npm registry each time)
55
+ npx agent-comm-hub
56
+
57
+ # or install globally and run anywhere
58
+ npm install -g agent-comm-hub
59
+ agent-comm-hub
60
+
61
+ # or install into a project
62
+ npm install -D agent-comm-hub
63
+ npx agent-comm-hub
64
+ ```
65
+
66
+ ### 2. Start the hub
67
+
68
+ ```bash
69
+ agent-comm-hub
70
+ # → agent-comm-hub listening on http://127.0.0.1:18764/mcp
71
+ ```
72
+
73
+ For long-running setups use your preferred supervisor (systemd unit, pm2,
74
+ Task Scheduler on Windows) — or the built-in one-shot auto-start:
75
+
76
+ ```bash
77
+ agent-comm-hub service install # Windows: HKCU Run + hidden launcher (no admin)
78
+ # Linux: systemd --user unit, enabled
79
+ agent-comm-hub service uninstall # undo
80
+ agent-comm-hub status # is the hub up? who is online?
81
+ ```
82
+
83
+ `status` probes the endpoint and prints the hub version plus every registered
84
+ peer with its online state (it registers a throwaway probe and cleans up after
85
+ itself).
86
+
87
+ ### 3. Connect your agents (one command)
88
+
89
+ ```bash
90
+ agent-comm-hub setup
91
+ # or: agents/install-all.ps1 (PowerShell equivalent)
92
+ # undo: agent-comm-hub setup --remove
93
+ ```
94
+
95
+ `setup` incrementally merges the `agent-hub` MCP entry into every installed
96
+ agent's own config (mcode, opencode, Kimi Code, Gemini CLI, Codex) and installs
97
+ the English skill into `~/.agents/skills/` (the cross-agent standard) plus each
98
+ agent's private skills dir. Only the `agent-hub` key is touched, every file is
99
+ backed up first, and re-running is a no-op. Claude Code and DSH stay manual
100
+ (see below).
101
+
102
+ **Registration is automatic**: once an agent session starts, the MCP handshake
103
+ registers it with the hub (client name becomes the peer id) — no manual step.
104
+ Optional: `bridge_register("tool:project")` for a readable id.
105
+
106
+ ### 4. Verify the endpoint
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
+ ## Connect your agents
115
+
116
+ Each agent gets **one MCP server entry** pointing at `http://127.0.0.1:18764/mcp`, plus the shared English skill (`agents/SKILL.md`) that teaches it when and how to use the bridge tools. Templates live in [`agents/`](agents/README.md).
117
+
118
+ **One-shot incremental sync** (recommended): `agents/install-all.ps1` merges the
119
+ `agent-hub` entry into every installed agent's MCP config (mcode, opencode,
120
+ Kimi Code, Gemini CLI, Codex) and installs the skill — it only touches the
121
+ `agent-hub` key, backs up each file, and is idempotent. Claude Code and DSH are
122
+ manual (below).
123
+
124
+ | Agent | Config file | Template | Skill location |
125
+ |---|---|---|---|
126
+ | MiniMax Code (mcode) | `~/.minimax/mcp.json` (+ `~/.minimax/mcp/mcp.json`) | [`agents/minimax-code/`](agents/minimax-code/) | `~/.minimax/skills/agent-comm-hub/SKILL.md` |
127
+ | opencode | `~/.config/opencode/opencode.json` | [`agents/opencode/opencode.json`](agents/opencode/opencode.json) | `~/.config/opencode/skills/agent-comm-hub/SKILL.md` |
128
+ | 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` |
129
+ | Gemini CLI | `~/.gemini/settings.json` | [`agents/gemini-cli/settings.json`](agents/gemini-cli/settings.json) | `~/.gemini/skills/agent-comm-hub/SKILL.md` |
130
+ | Codex | `~/.codex/config.toml` | [`agents/codex/config.toml`](agents/codex/config.toml) | `~/.codex/skills/agent-comm-hub/SKILL.md` |
131
+ | Claude Code | project `.mcp.json` (manual; `~/.claude.json` is never touched) | [`agents/claude-code/.mcp.json`](agents/claude-code/.mcp.json) | `~/.claude/skills/agent-comm-hub/SKILL.md` |
132
+ | DeepSeek Harness (DSH) | profile `cordis.patch.yml` (manual) | [`agents/dsh/cordis.patch.yml`](agents/dsh/cordis.patch.yml) | `$DSH_HOME/skills/agent-comm-hub/SKILL.md` |
133
+
134
+ > Streamable-http support varies by agent version; the templates use the fields each agent documents. If a client lacks HTTP MCP, wrap the endpoint with a stdio shim.
135
+
136
+ ### MiniMax Code (mcode)
137
+
138
+ Run the installer (backs up both config files first, writes UTF-8 without BOM):
139
+
140
+ ```powershell
141
+ powershell -ExecutionPolicy Bypass -File agents/minimax-code/install-mcode.ps1
142
+ ```
143
+
144
+ It registers `agent-hub` in `~/.minimax/mcp.json` (read by the CLI runtime) and `~/.minimax/mcp/mcp.json` (desktop app), and installs the skill. Restart your mcode session, then ask the agent:
145
+
146
+ ```text
147
+ 先调用 bridge_register("mavis:myproject")，然后 bridge_peers 看看谁在线
148
+ ```
149
+
150
+ ### Claude Code
151
+
152
+ Copy `agents/claude-code/.mcp.json` into your project root (or merge `mcpServers.agent-hub` into `~/.claude.json`):
153
+
154
+ ```json
155
+ {
156
+ "mcpServers": {
157
+ "agent-hub": {
158
+ "type": "http",
159
+ "url": "http://127.0.0.1:18764/mcp"
160
+ }
161
+ }
162
+ }
163
+ ```
164
+
165
+ Copy `agents/SKILL.md` to `~/.claude/skills/agent-comm-hub/SKILL.md`, restart Claude, and have it `bridge_register("claude-code:myproject")`.
166
+
167
+ ### opencode
168
+
169
+ Merge into `~/.config/opencode/opencode.json`:
170
+
171
+ ```json
172
+ {
173
+ "mcp": {
174
+ "agent-hub": {
175
+ "type": "remote",
176
+ "url": "http://127.0.0.1:18764/mcp",
177
+ "enabled": true
178
+ }
179
+ }
180
+ }
181
+ ```
182
+
183
+ ### Codex
184
+
185
+ Append to `~/.codex/config.toml`:
186
+
187
+ ```toml
188
+ [mcp_servers.agent-hub]
189
+ type = "streamable-http"
190
+ url = "http://127.0.0.1:18764/mcp"
191
+ ```
192
+
193
+ ### Gemini CLI
194
+
195
+ Merge into `~/.gemini/settings.json`:
196
+
197
+ ```json
198
+ {
199
+ "mcpServers": {
200
+ "agent-hub": {
201
+ "type": "http",
202
+ "url": "http://127.0.0.1:18764/mcp"
203
+ }
204
+ }
205
+ }
206
+ ```
207
+
208
+ ### DeepSeek Harness (DSH)
209
+
210
+ Merge `agents/dsh/cordis.patch.yml` into the profile patch layer; DSH's built-in `@deepseek-ai/dsh-mcp-client` connects and exposes the tools as `mcp__agent-hub__bridge_*`:
211
+
212
+ ```yaml
213
+ - insert:
214
+ - id: agent-comm-hub
215
+ name: '@deepseek-ai/dsh-mcp-client'
216
+ config:
217
+ serverName: agent-hub
218
+ transport: streamable-http
219
+ url: http://127.0.0.1:18764/mcp
220
+ ```
221
+
222
+ ## Tools
223
+
224
+ | Tool | Purpose |
225
+ |---|---|
226
+ | `bridge_register(peerId)` | Claim or rename your identity (auto-registered at connect with the client name; optional for a readable id like `opencode:myproject`) |
227
+ | `bridge_unregister()` | Leave the hub (removes peer, queue, and session binding; stays off until an explicit register) |
228
+ | `bridge_chat(to, message)` | Send a chat message; `to: "all"` broadcasts |
229
+ | `bridge_task(to, prompt, context?, deliverable?)` | Delegate a structured task |
230
+ | `bridge_ack(ref, status, note?)` | Acknowledge a task (`accepted`/`rejected`/`done`/`failed`), routed back to the original sender |
231
+ | `bridge_wait(from?, timeoutMs?)` | Long-poll for the next message (default 30 s) |
232
+ | `bridge_poll(from?)` | Non-blocking drain of queued messages |
233
+ | `bridge_status()` | Hub health: peers with connected/queued/waiting state |
234
+ | `bridge_peers()` | Who is online |
235
+ | `bridge_history(peer?, limit?)` | Recent messages (context refresh after reconnect) |
236
+
237
+ Every result is lossless JSON (compatible with DSH's strict tool registry).
238
+
239
+ ## CLI reference
240
+
241
+ ```
242
+ agent-comm-hub [options] start the hub
243
+ agent-comm-hub setup [options] sync MCP entry + skill to all agents
244
+ agent-comm-hub status [options] hub health + online peers
245
+ agent-comm-hub service install|uninstall [options] one-shot auto-start
246
+ (Windows HKCU Run + hidden launcher,
247
+ no admin; Linux systemd --user)
248
+
249
+ --host <addr> Bind address (default 127.0.0.1)
250
+ --port <n> Listen port (default 18764)
251
+ --path <p> MCP endpoint path (default /mcp)
252
+ --max-queue <n> Queued messages per peer before dropping oldest (default 200)
253
+ --history-limit <n> Retained history messages (default 100)
254
+ --wait-timeout-ms <n> Long-poll ceiling for bridge_wait (default 60000)
255
+ --default-wait-ms <n> bridge_wait default budget (default 30000)
256
+ --connected-window-ms <n> Peer counts as active within this window (default 30000)
257
+ --peer-idle-timeout-ms <n> Auto-unregister idle peers after this; 0 disables (default 600000)
258
+ --url <u> / --server-name <n> / --remove / --dry-run (setup/service/status)
259
+ -h, --help Show help
260
+ -V, --version Show version
261
+ ```
262
+
263
+ ## Running & resource usage
264
+
265
+ `agent-comm-hub` is a **foreground process**: it keeps listening once started
266
+ and stops on Ctrl+C. It does NOT auto-start at boot or daemonize — keep it
267
+ alive with your own supervisor:
268
+
269
+ ```bash
270
+ # pm2 (cross-platform)
271
+ npm i -g pm2
272
+ pm2 start agent-comm-hub --name agent-comm-hub
273
+ pm2 save && pm2 startup # boot persistence
274
+
275
+ # or the built-in one-shot auto-start (no admin needed)
276
+ agent-comm-hub service install # Windows: HKCU Run + hidden VBS launcher
277
+ # Linux: systemd --user unit, enabled
278
+ agent-comm-hub service uninstall
279
+ ```
280
+
281
+ **Measured footprint (Windows / Node 24, idle):**
282
+
283
+ | Metric | Value |
284
+ |---|---|
285
+ | Idle CPU | ≈ 0 (event-driven; the only timer is a once-a-minute idle-GC check) |
286
+ | Memory over an idle Node baseline | **~ +8 MB** WorkingSet (the ~100+ MB baseline is the Node runtime itself) |
287
+ | Disk | None (no database; nothing written besides logs) |
288
+
289
+ Each online agent adds one SSE keep-alive socket; mailboxes/history are
290
+ in-memory with configurable caps. Negligible impact.
291
+
292
+ ## Programmatic API
293
+
294
+ ```js
295
+ import { startHub, DEFAULT_CONFIG } from 'agent-comm-hub'
296
+
297
+ const hub = startHub({ port: 18764 }, console) // returns { hub, registry, server, mcp, close }
298
+ // hub.close() to stop
299
+ ```
300
+
301
+ `startHub(config?, logger?)` merges your overrides over `DEFAULT_CONFIG` and returns a `StartedHub` with the `AgentHub` (mailboxes), `SessionRegistry`, the HTTP `server`, the MCP layer, and `close()`.
302
+
303
+ ## Message protocol & identity
304
+
305
+ ```json
306
+ { "id": "uuid", "from": "mavis", "to": "claude", "kind": "chat", "content": "..." }
307
+ ```
308
+
309
+ - `kind`: `chat` | `task` | `notice` | `ack`. `task` content is `{prompt, context?, deliverable?}`; `ack` content is `{status, note?}` — both JSON-encoded.
310
+ - `from` is **injected by the hub** from the session→peer binding; clients cannot set it.
311
+ - Each connection gets a unique `Mcp-Session-Id`; the binding table maps session → peerId; duplicate peerIds are rejected.
312
+ - **Auto-registration**: connecting the MCP is enough to join — the session
313
+ registers at the handshake (`initialize`) using the `clientInfo` name.
314
+ **Same-name connections share one peer id** (an agent that opens a new
315
+ session per chat keeps a stable identity and its sessions share the
316
+ mailbox). `bridge_register` upgrades the id to something readable;
317
+ `bridge_unregister` detaches (dropping the peer when no other session shares
318
+ it) and suppresses auto-registration until an explicit register.
319
+ - Peers are offline-tolerant: messages queue (max `maxQueue`, oldest dropped) until the peer polls; a peer must re-register after its agent restarts (bindings are per-session and in-memory; restarting the hub clears everything).
320
+ - **Liveness**: `connected` means activity within `connectedWindowMs` (default 30 s) **or** a live SSE channel — an open agent session stays online without heartbeat calls. The idle GC (default 10 min) never evicts a peer with a live SSE channel; only peers whose channel is gone are recycled, freeing their names.
321
+
322
+ ## Security
323
+
324
+ - Binds to `127.0.0.1` by default and has **no authentication** — do not expose the port publicly without adding a token/proxy layer.
325
+ - Never put credentials in bridge messages (plaintext on loopback).
326
+ - Peer ids are validated `[A-Za-z0-9._:-]{1,64}`; unregistered callers get a clear error.
327
+
328
+ ## Development
329
+
330
+ ```bash
331
+ pnpm install
332
+ pnpm typecheck # tsc --noEmit (strict)
333
+ pnpm test # test suite (64 checks: 37 multi-peer smoke + 21 installer + 6 ops)
334
+ pnpm run build # esbuild → lib/{cli,index,setup}.js (zero deps)
335
+ pnpm pack # build + npm pack (publishing artifact)
336
+ ```
337
+
338
+ Tests cover registration, duplicate rejection, chat routing, sender-filtered waits, task+ack routing back to the sender, broadcast, status/peers/history, unregister/re-register, and error paths.
339
+
340
+ ## Troubleshooting
341
+
342
+ | Symptom | Cause / fix |
343
+ |---|---|
344
+ | Agent has no `bridge_*` tools | Hub not running — start `agent-comm-hub` and restart the agent session |
345
+ | `unknown recipient: xxx` | The peer hasn't registered (or used a different peerId) — check `bridge_peers()` |
346
+ | `not registered — call bridge_register` | Only appears after an explicit `bridge_unregister` (normal connections auto-register at connect); clients without a client name fall back to `agent` |
347
+ | `peer already registered by another connection` | Another live connection holds the id — pick a unique peerId (e.g. `tool:project`) or restart the hub to clear stale bindings |
348
+ | Port conflict | 18764 is the default; `dsh-mcode-bridge` uses 18763. Change with `--port` and update every agent config |
349
+ | Chinese garbled in PowerShell clients | Response headers carry `charset=utf-8`; send request bodies as UTF-8 bytes (`[System.Text.Encoding]::UTF8.GetBytes(...)`) |
350
+
351
+ ## License
352
+
353
+ MIT — see [LICENSE](LICENSE). Contributions welcome: keep the 64-check suite green (`pnpm test`) and zero runtime dependencies. Architecture: [ARCHITECTURE.md](ARCHITECTURE.md).
package/README.zh.md ADDED
@@ -0,0 +1,243 @@
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
+ [![npm version](https://img.shields.io/npm/v/agent-comm-hub?style=flat-square&logo=npm&label=npm)](https://www.npmjs.com/package/agent-comm-hub)
16
+ [![license MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
17
+ [![node >=22](https://img.shields.io/badge/Node-%3E%3D22-339933?style=flat-square&logo=nodedotjs&logoColor=white)](package.json)
18
+ [![zero dependencies](https://img.shields.io/badge/Dependencies-0-2ea44f?style=flat-square)](package.json)
19
+ [![TypeScript strict](https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white)](src)
20
+ [![MCP streamable-http](https://img.shields.io/badge/MCP-streamable--http-1F6FEB?style=flat-square)](src/mcp-server.ts)
21
+ [![platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-6f42c1?style=flat-square)](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
+ - **零依赖单进程**：`npx agent-comm-hub` —— 无数据库、无守护、无外部服务
48
+
49
+ ## 快速开始
50
+
51
+ ### 1. 安装 hub
52
+
53
+ ```bash
54
+ # 免安装临时跑（每次从 registry 拉取）
55
+ npx agent-comm-hub
56
+
57
+ # 或全局安装，随处可用（推荐常驻用法）
58
+ npm install -g agent-comm-hub
59
+ agent-comm-hub
60
+
61
+ # 或装进项目
62
+ npm install -D agent-comm-hub
63
+ npx agent-comm-hub
64
+ ```
65
+
66
+ ### 2. 启动 hub
67
+
68
+ ```bash
69
+ agent-comm-hub
70
+ # → agent-comm-hub listening on http://127.0.0.1:18764/mcp
71
+ ```
72
+
73
+ 常驻交给内置的一键自启（或 pm2）：
74
+
75
+ ```bash
76
+ agent-comm-hub service install # Windows：HKCU Run + 隐藏启动器（无需管理员）
77
+ # Linux：systemd --user 单元并启用
78
+ agent-comm-hub service uninstall # 撤销
79
+ agent-comm-hub status # hub 是否在跑？谁在线？
80
+ ```
81
+
82
+ `status` 探测端点并打印 hub 版本 + 每个已注册 peer 的在线状态（自带探针、用完即清理）。
83
+
84
+ ### 3. 一键接入所有 agent
85
+
86
+ ```bash
87
+ agent-comm-hub setup
88
+ # 或 PowerShell 版：agents/install-all.ps1
89
+ # 卸载：agent-comm-hub setup --remove
90
+ ```
91
+
92
+ `setup` 会把 `agent-hub` 的 MCP 条目**增量合并**进每个已安装 agent 的配置
93
+ （mcode / opencode / kimi-code / gemini / codex），并把英文 SKILL 装到
94
+ `~/.agents/skills/`（跨 agent 标准位置）+ 各 agent 私有技能目录。只动
95
+ `agent-hub` 这一个键、每个文件先备份、幂等可重跑。Claude Code 与 DSH 手动（见下）。
96
+
97
+ **注册全自动**：agent 会话一启动，MCP 握手即完成注册（客户端名 = peer id），无需任何手动操作。可选：`bridge_register("工具名:项目名")` 换可读 id。
98
+
99
+ ### 4. 验证端点
100
+
101
+ ```bash
102
+ curl -X POST http://127.0.0.1:18764/mcp \
103
+ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
104
+ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'
105
+ ```
106
+
107
+ ## 接入各 agent
108
+
109
+ 每个 agent 只需一条 MCP 配置指向 `http://127.0.0.1:18764/mcp`，加一份 SKILL（`agents/SKILL.md`，英文，教会 agent 何时用哪些 bridge 工具）。模板在 [`agents/`](agents/README.md)。
110
+
111
+ | Agent | 配置文件 | 模板 | Skill 位置 |
112
+ |---|---|---|---|
113
+ | MiniMax Code (mcode) | `~/.minimax/mcp.json`（+ `~/.minimax/mcp/mcp.json`） | [`agents/minimax-code/`](agents/minimax-code/) | `~/.minimax/skills/agent-comm-hub/SKILL.md` |
114
+ | opencode | `~/.config/opencode/opencode.json` | [`agents/opencode/opencode.json`](agents/opencode/opencode.json) | `~/.config/opencode/skills/agent-comm-hub/SKILL.md` |
115
+ | 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` |
116
+ | Gemini CLI | `~/.gemini/settings.json` | [`agents/gemini-cli/settings.json`](agents/gemini-cli/settings.json) | `~/.gemini/skills/agent-comm-hub/SKILL.md` |
117
+ | Codex | `~/.codex/config.toml` | [`agents/codex/config.toml`](agents/codex/config.toml) | `~/.codex/skills/agent-comm-hub/SKILL.md` |
118
+ | Claude Code | 项目根 `.mcp.json`（手动；**绝不碰 `~/.claude.json`**——含凭据） | [`agents/claude-code/.mcp.json`](agents/claude-code/.mcp.json) | `~/.claude/skills/agent-comm-hub/SKILL.md` |
119
+ | 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` |
120
+
121
+ > 各 agent 对 streamable-http 的支持随版本演进；不支持的客户端可加 stdio 包装。
122
+
123
+ ## 常驻运行与资源占用
124
+
125
+ `agent-comm-hub` 是**前台进程**：启动后持续监听，Ctrl+C 停止。它**不会**自动开机自启、不会自动后台化——常驻由你自己的 supervisor 负责：
126
+
127
+ ```bash
128
+ # pm2（跨平台）
129
+ npm i -g pm2
130
+ pm2 start agent-comm-hub --name agent-comm-hub
131
+ pm2 save && pm2 startup # 开机自启
132
+
133
+ # 或内置一键自启（无需管理员）
134
+ agent-comm-hub service install # Windows：HKCU Run + 隐藏 VBS 启动器
135
+ # Linux：systemd --user 单元并启用
136
+ agent-comm-hub service uninstall
137
+ ```
138
+
139
+ **资源占用（本机实测，Windows / Node 24）**：
140
+
141
+ | 指标 | 数值 |
142
+ |---|---|
143
+ | 空闲 CPU | ≈ 0（纯事件驱动；唯一定时器是每分钟一次的空闲 GC 检查） |
144
+ | 内存（相对空闲 Node 基线） | **约 +8 MB**（WorkingSet；进程基线本身约 100+ MB 是 Node 运行时） |
145
+ | 磁盘 | 无数据库、无写盘（仅日志） |
146
+
147
+ 每在线一个 agent 多一条 SSE 长连接（一个 socket）；信箱/历史都在内存（上限可配）。性能影响可以忽略。
148
+
149
+ ## 工具
150
+
151
+ | 工具 | 作用 |
152
+ |---|---|
153
+ | `bridge_register(peerId)` | 认领/改名身份（连接即自动注册，此项可选用于可读 id） |
154
+ | `bridge_unregister()` | 离开 hub（移除 peer、队列与绑定；之后保持离线直到显式注册） |
155
+ | `bridge_chat(to, message)` | 发消息；`to: "all"` 广播 |
156
+ | `bridge_task(to, prompt, context?, deliverable?)` | 派结构化任务 |
157
+ | `bridge_ack(ref, status, note?)` | 回执（accepted/rejected/done/failed），自动回到原发送者 |
158
+ | `bridge_wait(from?, timeoutMs?)` | 长轮询收下一条消息（默认 30s；循环=实时监听） |
159
+ | `bridge_poll(from?)` | 非阻塞取走所有排队消息 |
160
+ | `bridge_status()` | 枢纽健康：各 peer 在线/队列/等待状态 |
161
+ | `bridge_peers()` | 谁在线 |
162
+ | `bridge_history(peer?, limit?)` | 最近往来消息（重连后恢复上下文） |
163
+
164
+ 所有返回都是 lossless JSON（兼容 DSH 的严格工具注册表）。
165
+
166
+ ## CLI 参考
167
+
168
+ ```
169
+ agent-comm-hub [options] 启动 hub
170
+ agent-comm-hub setup [options] 增量同步 MCP 条目 + SKILL 到所有 agent
171
+ agent-comm-hub status [options] hub 健康 + 在线 peer
172
+ agent-comm-hub service install|uninstall [options] 一键自启
173
+ （Windows HKCU Run + 隐藏启动器，无需管理员；
174
+ Linux systemd --user）
175
+
176
+ --host <addr> 绑定地址（默认 127.0.0.1）
177
+ --port <n> 端口（默认 18764）
178
+ --path <p> MCP 路径（默认 /mcp）
179
+ --max-queue <n> 每 peer 队列上限，溢出丢最旧（默认 200）
180
+ --history-limit <n> 保留的历史条数（默认 100）
181
+ --wait-timeout-ms <n> bridge_wait 长轮询上限（默认 60000）
182
+ --default-wait-ms <n> bridge_wait 默认预算（默认 30000）
183
+ --connected-window-ms <n> 活跃窗口（默认 30000）
184
+ --peer-idle-timeout-ms <n> 空闲 GC 超时；0 关闭（默认 600000）
185
+ --url <u> / --server-name <n> / --remove / --dry-run （setup/service/status 用）
186
+ -h, --help / -V, --version
187
+ ```
188
+
189
+ ## 编程接口
190
+
191
+ ```js
192
+ import { startHub, DEFAULT_CONFIG } from 'agent-comm-hub'
193
+
194
+ const hub = startHub({ port: 18764 }, console) // 返回 { hub, registry, server, mcp, close }
195
+ // hub.close() 停止
196
+ ```
197
+
198
+ `startHub(config?, logger?)` 在 `DEFAULT_CONFIG` 之上合并你的覆盖值，返回包含
199
+ `AgentHub`（信箱）、`SessionRegistry`、HTTP `server`、MCP 层与 `close()` 的句柄。
200
+
201
+ ## 消息协议与身份
202
+
203
+ ```json
204
+ { "id": "uuid", "from": "mavis", "to": "claude", "kind": "chat", "content": "..." }
205
+ ```
206
+
207
+ - `kind`：`chat` / `task` / `notice` / `ack`。`task` 内容为 `{prompt, context?, deliverable?}`；`ack` 内容为 `{status, note?}`——均 JSON 编码
208
+ - `from` **由 hub 注入**（来自会话→peer 绑定），客户端无法设置
209
+ - 每条连接有唯一 `Mcp-Session-Id`；绑定表记录 session → peerId；重名被拒
210
+ - **自动注册**：握手（`initialize`）即用 `clientInfo` 名注册；**同名连接共享一个 peer id**（一个 agent 开多个会话身份稳定、信箱共享）。`bridge_register` 换可读 id；`bridge_unregister` 注销（无其他会话共享时才移除 peer）
211
+ - **离线容忍**：消息排队（上限 `maxQueue`，满丢最旧）；hub 重启会清空全部绑定（agent 重连后自动重新注册）
212
+ - **在线语义**：`connected` = 最近 `connectedWindowMs`（默认 30s）内活跃 **或** SSE 通道存活——会话开着就显示在线，无需心跳；空闲 GC（默认 10 分钟）**不会**清理有活跃 SSE 的 peer，只回收真正断连的
213
+
214
+ ## 安全
215
+
216
+ - 默认只绑 `127.0.0.1` 且**无鉴权**——不要直接暴露公网；跨端请加 token/代理层
217
+ - 不要把凭据写进消息（回环明文）
218
+ - peerId 校验 `[A-Za-z0-9._:-]{1,64}`；未注册调用有明确报错
219
+
220
+ ## 开发
221
+
222
+ ```bash
223
+ pnpm install
224
+ pnpm typecheck # tsc --noEmit（strict）
225
+ pnpm test # 测试套件（64 项：37 多端冒烟 + 21 安装器 + 6 运维）
226
+ pnpm run build # esbuild → lib/{cli,index,setup}.js（零依赖）
227
+ pnpm pack # 构建 + npm pack（发布产物）
228
+ ```
229
+
230
+ ## 故障排查
231
+
232
+ | 症状 | 原因 / 解决 |
233
+ |---|---|
234
+ | agent 没有 `bridge_*` 工具 | hub 没跑——启动 `agent-comm-hub` 并重启 agent 会话 |
235
+ | `unknown recipient: xxx` | 对方未注册（或用了别的 peerId）——先 `bridge_peers()` |
236
+ | `not registered — call bridge_register` | 仅在显式注销后出现（正常连接会自动注册）；客户端没上报名字时会用 `agent` 兜底 |
237
+ | `peer already registered by another connection` | 有人占了该 id——换个唯一 id（如 `工具:项目`）或重启 hub 清理 |
238
+ | 端口冲突 | 默认 18764（dsh-mcode-bridge 用 18763）——`--port` 换端口并同步各 agent 配置 |
239
+ | PowerShell 客户端中文乱码 | 响应头已带 `charset=utf-8`；发送时用 `[System.Text.Encoding]::UTF8.GetBytes(...)` |
240
+
241
+ ## 许可
242
+
243
+ MIT —— 见 [LICENSE](LICENSE)。欢迎贡献：保持测试全绿（`pnpm test`）与零运行时依赖。架构说明见 [ARCHITECTURE.md](ARCHITECTURE.md)。
package/agents/README.md ADDED
@@ -0,0 +1,49 @@
1
+ # 接入指南（per-agent install）
2
+
3
+ 枢纽默认监听 `http://127.0.0.1:18764/mcp`（streamable-http）。先把 hub 跑起来：
4
+
5
+ ```bash
6
+ npx agent-comm-hub # 或 npm i -g agent-comm-hub && agent-comm-hub
7
+ ```
8
+
9
+ ## 一键增量安装（推荐）
10
+
11
+ ```powershell
12
+ powershell -ExecutionPolicy Bypass -File install-all.ps1
13
+ # 卸载：install-all.ps1 -Remove
14
+ ```
15
+
16
+ `install-all.ps1` 会把 `agent-hub` 条目**增量合并**进每个已安装 agent 的 MCP 配置
17
+ （只动 `agent-hub` 这个键，其余内容原样保留；每个文件先备份、幂等可重跑），并同步
18
+ 英文 SKILL 到各 agent 的技能目录。覆盖：mcode / opencode / kimi-code / Gemini CLI /
19
+ Codex（TOML 追加）。Claude Code 和 DSH 需手动（见下表）。
20
+
21
+ 接入即自动上线（MCP 握手时用客户端名注册，无需手动 register）；想要可读的 peerId
22
+ 可以让 agent 调一次 `bridge_register(peerId)`。
23
+
24
+ | Agent | 配置文件 | 片段 | Skill 位置 |
25
+ |---|---|---|---|
26
+ | MiniMax Code (mcode) | `~/.minimax/mcp.json` + `~/.minimax/mcp/mcp.json` | `minimax-code/mcp-entry.json` | `~/.minimax/skills/agent-comm-hub/SKILL.md`（或跑 `minimax-code/install-mcode.ps1`） |
27
+ | opencode | `~/.config/opencode/opencode.json` | `opencode/opencode.json` | `~/.config/opencode/skills/agent-comm-hub/SKILL.md` |
28
+ | Kimi Code | `~/.kimi-code/mcp.json` | `kimi-code/mcp-entry.json`（`transport: "http"`，url 自动推断为 http） | `~/.kimi-code/skills/agent-comm-hub/SKILL.md` |
29
+ | Gemini CLI | `~/.gemini/settings.json` | `gemini-cli/settings.json` | `~/.gemini/skills/agent-comm-hub/SKILL.md` |
30
+ | Codex | `~/.codex/config.toml` | `codex/config.toml` | `~/.codex/skills/agent-comm-hub/SKILL.md` |
31
+ | Claude Code | 项目根 `.mcp.json`（手动复制；**不碰 `~/.claude.json`**——含凭据且无法安全往返） | `claude-code/.mcp.json` | `~/.claude/skills/agent-comm-hub/SKILL.md` |
32
+ | DeepSeek Harness (DSH) | profile `cordis.patch.yml`（手动合并） | `dsh/cordis.patch.yml`（用 `@deepseek-ai/dsh-mcp-client`，工具名为 `mcp__agent-hub__bridge_*`） | `$DSH_HOME/skills/agent-comm-hub/SKILL.md` |
33
+
34
+ > 各 agent 对 streamable-http MCP 的支持随版本演进，模板里的字段以官方文档为准；
35
+ > 不支持的版本可退化为 stdio 包装（见下）。
36
+
37
+ ## 快速验证
38
+
39
+ ```text
40
+ mcode / claude / opencode 各开一个会话，问它们：
41
+ 「bridge_peers 看看谁在线，然后用 bridge_chat 给 claude-code:xxx 打个招呼」
42
+ ```
43
+
44
+ ## 故障排查
45
+
46
+ - hub 没起 → agent 工具列表里没有 `bridge_*`（MCP 连接失败会在 agent 日志里报错）。
47
+ - 端口被占（如 dsh-mcode-bridge 用了 18763）→ `--port` 换端口，并同步各 agent 配置。
48
+ - agent 报 "not registered" → 先调 `bridge_register(peerId)`。
49
+ - 改完配置记得重启 agent 会话。