@wings006/agent-link 0.1.2 → 0.1.3

package/README.md

@@ -2,16 +2,6 @@
 
 多 Agent 聊天系统 — 连接多台电脑上的 Claude Code，实现 Agent 间互相通信。支持局域网自动发现和跨网络中继通信。
 
-## 工作原理
-
-每台电脑运行一个 `agent-link` 进程，同时承担：
-
-- **MCP Server** — 给本地 Claude Code 提供 `agent_list`、`agent_send`、`agent_inbox`、`agent_reply`、`agent_mark_read`、`agent_clear_inbox`、`agent_task_status` 工具
-- **A2A Server** — 接收其他电脑 Agent 发来的任务（HTTP JSON-RPC）
-- **A2A Client** — 向其他电脑的 Agent 发送任务
-- **mDNS 广播** — 零配置自动发现局域网内所有 Agent
-- **中继客户端** — 通过公网中继服务器发现和通信跨网络 Agent
-
 ```
 局域网                                          远程
 电脑A (dev-macbook)        电脑B (office-pc)              电脑C (home-pc)
@@ -29,7 +19,9 @@
 
 ## 快速开始
 
-无需安装，直接在 Claude Code 的 MCP 配置中添加：
+在 Claude Code 的 MCP 配置中添加：
+
+**局域网模式（同一网络内自动发现）：**
 
 ```json
 {
@@ -42,280 +34,82 @@
 }
 ```
 
-重启 Claude Code 即可使用。每台电脑使用不同的 `--name`。
-
-> 需要跨网络通信？添加 `"--relay", "ws://你的中继服务器:3458"`，详见[跨网络通信](#跨网络通信中继模式)。
-
-## 从源码安装（可选）
-
-如果需要开发或自定义：
-
-```bash
-git clone <repo-url> agent-link
-cd agent-link
-npm install
-npm run build
-npm link
-```
-
-执行 `npm link` 后，`agent-link` 命令全局可用，MCP 配置可改为：
+**中继模式（跨网络通信）：**
 
 ```json
 {
   "mcpServers": {
     "agent-link": {
-      "command": "agent-link",
-      "args": ["--name", "你的Agent名称"]
+      "command": "npx",
+      "args": ["-y", "@wings006/agent-link", "--name", "你的Agent名称", "--relay", "ws://中继服务器IP:3458"]
     }
   }
 }
 ```
 
-### 参数说明
+重启 Claude Code 即可。每台电脑使用不同的 `--name`。
+
+## 参数说明
 
 | 参数 | 简写 | 说明 | 默认值 |
 |------|------|------|--------|
 | `--name` | `-n` | Agent 名称（全局唯一） | 随机生成 |
 | `--port` | `-p` | A2A Server 监听端口 | 3456 |
 | `--relay` | `-r` | 中继服务器地址（跨网络通信） | 无 |
-| `--no-mdns` | | 禁用局域网 mDNS 发现，仅使用中继模式 | false |
+| `--no-mdns` | | 禁用局域网发现，仅用中继 | false |
 | `--skills` | `-s` | 能力标签，逗号分隔 | general |
 
-### 配置示例
-
-**电脑 A（开发机，局域网）：**
-```json
-{
-  "mcpServers": {
-    "agent-link": {
-      "command": "npx",
-      "args": ["-y", "@wings006/agent-link", "--name", "dev-macbook", "--skills", "code,test"]
-    }
-  }
-}
-```
-
-**电脑 B（办公电脑，跨网络）：**
-```json
-{
-  "mcpServers": {
-    "agent-link": {
-      "command": "npx",
-      "args": ["-y", "@wings006/agent-link", "--name", "office-pc", "--relay", "ws://your-server:3458", "--skills", "report,doc"]
-    }
-  }
-}
-```
-
 ## 使用
 
-配置完成后重启 Claude Code，agent-link 会自动启动。直接用自然语言和 Claude Code 对话即可：
-
-### 查看在线 Agent
-
-```
-你: 有哪些 agent 在线？
-Claude Code → 调用 agent_list
-Claude Code: 当前在线 Agent:
-  - dev-macbook (192.168.1.50:3456) [code, test]
-  - office-pc (192.168.1.100:3456) [report, doc]
-```
-
-### 发送任务
-
-```
-你: 告诉 office-pc 帮我生成本周周报
-Claude Code → 调用 agent_send(to: "office-pc", message: "帮我生成本周周报")
-Claude Code: 任务已发送，等待 office-pc 处理...
-```
-
-对方电脑的 Claude Code 会收到消息，询问用户是否执行。
-
-### 查看收件箱
-
-```
-你: 看看有没有人给我发消息
-Claude Code → 调用 agent_inbox
-Claude Code: 收到 1 条消息:
-  - 来自 dev-macbook: "帮我检查一下测试覆盖率" (待处理)
-```
-
-### 回复任务
+配置完成后直接用自然语言和 Claude Code 对话：
 
-```
-你: 回复这个任务，告诉他测试覆盖率是 85%
-Claude Code → 调用 agent_reply(task_id: "xxx", message: "测试覆盖率 85%", status: "completed")
-Claude Code: 已回复 dev-macbook
-```
-
-## 消息流转
-
-完整的一次跨机器任务流程：
-
-```
-1. A 用户 → A Claude Code: "告诉 office-pc 生成周报"
-2. A Claude Code 调用 agent_list 确认 office-pc 在线
-3. A Claude Code 调用 agent_send → A 的 agent-link 发送 HTTP 请求到 B
-4. B 的 agent-link 收到任务，存入 inbox
-5. B 的 Claude Code 通过 agent_inbox 看到新消息
-6. B 的 Claude Code 询问 B 用户: "收到 dev-macbook 的请求，是否执行？"
-7. B 用户确认 → B Claude Code 执行任务
-8. B Claude Code 调用 agent_reply 回复结果
-9. A Claude Code 收到结果，展示给 A 用户
-```
+- **"有哪些 agent 在线？"** → 调用 `agent_list`
+- **"告诉 office-pc 帮我生成周报"** → 调用 `agent_send`
+- **"看看有没有人给我发消息"** → 调用 `agent_inbox`
+- **"回复这个任务"** → 调用 `agent_reply`
+- **"标记全部已读"** → 调用 `agent_mark_read`
+- **"清理已读消息"** → 调用 `agent_clear_inbox`
 
-## MCP 工具一览
+## 部署中继服务器
 
-| 工具 | 说明 |
-|------|------|
-| `agent_list` | 列出所有在线 Agent（局域网 + 中继） |
-| `agent_send` | 向目标 Agent 发送消息/任务 |
-| `agent_inbox` | 查看收到的消息（显示已读/未读状态） |
-| `agent_reply` | 回复任务（完成/拒绝/需要更多信息） |
-| `agent_mark_read` | 标记消息已读（单条或全部） |
-| `agent_clear_inbox` | 清理收件箱（已读/全部/最早N条） |
-| `agent_task_status` | 查询已发出任务的状态和回复 |
-
-## 跨网络通信（中继模式）
-
-当 Agent 不在同一局域网时，可通过公网中继服务器实现通信。
-
-### 部署中继服务器
-
-在公网服务器上：
+跨网络通信需要一台公网服务器作为中继：
 
 ```bash
-# 创建目录
 mkdir -p /opt/agent-link-relay && cd /opt/agent-link-relay
-
-# 复制中继服务器文件
-scp dist/relay-server.js user@server:/opt/agent-link-relay/
-
-# 安装依赖
 npm init -y
 sed -i 's/"type": "commonjs"/"type": "module"/' package.json
 npm install ws
 
+# 从项目中复制中继服务器
+scp dist/relay-server.js user@server:/opt/agent-link-relay/
+
 # 启动
 node relay-server.js --port 3458
 ```
 
-建议用 systemd 管理：
-
-```ini
-# /etc/systemd/system/agent-link-relay.service
-[Unit]
-Description=Agent Link Relay Server
-After=network.target
-
-[Service]
-Type=simple
-WorkingDirectory=/opt/agent-link-relay
-ExecStart=/usr/bin/node relay-server.js --port 3458
-Restart=always
-RestartSec=5
-
-[Install]
-WantedBy=multi-user.target
-```
-
-```bash
-systemctl enable agent-link-relay && systemctl start agent-link-relay
-```
-
-> 注意：需要在云服务商安全组中放行 3458 端口（TCP 入方向）。
-
-### 配置 Agent 连接中继
-
-在 MCP 配置中添加 `--relay` 参数：
-
-```json
-{
-  "mcpServers": {
-    "agent-link": {
-      "command": "agent-link",
-      "args": ["--name", "my-agent", "--relay", "ws://your-server-ip:3458"]
-    }
-  }
-}
-```
-
-### 工作原理
-
-```
-电脑A (家里)                   公网中继服务器                    电脑B (公司)
-┌───────────┐    WebSocket    ┌──────────────┐    WebSocket    ┌───────────┐
-│ agent-link├──────────────►│ relay-server │◄──────────────┤agent-link │
-└───────────┘                 └──────────────┘                 └───────────┘
-```
-
-- 双方通过 WebSocket 长连接到中继服务器
-- 中继服务器维护在线 Agent 列表，推送给所有客户端
-- 消息通过中继转发，中继不存储数据
-- 局域网 mDNS 发现照常工作，同网络内优先直连
-
-## 本机测试
-
-在同一台机器上模拟多 Agent 通信（使用不同端口）：
-
-**终端 1：**
-```bash
-agent-link --name agent-a --port 3456
-```
-
-**终端 2：**
-```bash
-agent-link --name agent-b --port 3457
-```
-
-两个进程会通过 mDNS 自动发现对方。
+> 需要在云服务商安全组中放行 3458 端口（TCP 入方向）。
 
 ## 故障排查
 
-### mDNS 发现调试
-
-如果两台电脑都配置了 agent-link 但 `agent_list` 看不到对方，使用调试脚本排查：
-
-**电脑 A：**
-```bash
-npx tsx tests/mdns-debug.ts pc-a
-```
-
-**电脑 B：**
-```bash
-npx tsx tests/mdns-debug.ts pc-b
-```
-
-脚本会广播自身并监听局域网内的其他 Agent。如果 10 秒内双方都能看到 `[mDNS] 发现服务: ...` 输出，说明 mDNS 工作正常。
-
-如果发现不了对方，常见原因：
-
-| 原因 | 排查方法 |
+| 问题 | 解决方法 |
 |------|---------|
-| macOS 防火墙阻止 UDP 5353 | 系统设置 → 网络 → 防火墙，关闭或添加例外 |
-| 两台电脑不在同一子网 | 确认 IP 在同一网段（如都是 192.168.1.x） |
-| 路由器禁用多播转发 | 检查路由器设置，启用 mDNS/Bonjour 转发 |
-| 企业网络隔离 | 部分企业 WiFi 会隔离客户端间通信 |
+| `agent_list` 看不到对方 | 确认双方在同一局域网，或都配置了相同的 `--relay` |
+| 发送消息失败 `fetch failed` | 检查是否有代理拦截，`.local` 域名需加入 `no_proxy` |
+| daemon 参数不生效 | 完全退出 Claude Code 重新打开（不只是 `/mcp`） |
+| 中继连接失败 | 确认中继服务器端口已放行，`ws://IP:端口` 格式正确 |
+| mDNS 发现不到 | macOS 检查防火墙；确认同一子网；路由器启用多播转发 |
+| 同机多实例冲突 | 不同实例使用不同的 `--port` 和 `--api-port` |
 
-## 开发
+## 从源码开发
 
 ```bash
-npm run build      # 编译 TypeScript
-npm run dev        # 开发模式运行（tsx）
-npm test           # 运行测试
-npm run test:watch # 测试监听模式
+git clone https://github.com/l3wingsgg/agent_link.git
+cd agent_link
+npm install
+npm run build
+npm test
 ```
 
-## 技术栈
-
-- TypeScript + Node.js
-- [A2A 协议](https://github.com/a2aproject/A2A) — Agent 间通信（JSON-RPC over HTTP）
-- [MCP 协议](https://modelcontextprotocol.io/) — Claude Code 工具集成
-- [bonjour-service](https://www.npmjs.com/package/bonjour-service) — mDNS 零配置局域网发现
-- [ws](https://www.npmjs.com/package/ws) — WebSocket 中继通信
-- [better-sqlite3](https://www.npmjs.com/package/better-sqlite3) — SQLite 持久化存储
-- [Vitest](https://vitest.dev/) — 测试框架
-
 ## 许可证
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wings006/agent-link",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "多 Agent 聊天系统 - 连接多台电脑上的 Claude Code，支持局域网发现和跨网络中继通信",
   "type": "module",
   "main": "dist/index.js",