mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 12:55:51 +00:00
e0e4ee41c2
- Add docs/features/all-features-guide.md — comprehensive guide covering all 18 features across 13 PRs (Buddy, Remote Control, Voice, Chrome, Computer Use, GrowthBook, Ultraplan, Daemon, Pipe IPC, LAN Pipes, Monitor, Workflow, Coordinator, Proactive, History/Snip, Fork, etc.) - Rewrite docs/features/lan-pipes.md — user-facing guide with step-by-step quickstart, firewall config (Windows/macOS/Linux), command reference, keyboard shortcuts, routing modes, permission forwarding, FAQ - Rewrite docs/features/lan-pipes-implementation.md — developer reference with updated architecture (hook extraction, ndjsonFramer, module singletons), corrected code references, NDJSON protocol spec, attach flow sequence Co-authored-by: unraid <local@unraid.local>
194 lines
6.0 KiB
Markdown
194 lines
6.0 KiB
Markdown
# LAN Pipes — 局域网多机器群控指南
|
||
|
||
## 什么是 LAN Pipes
|
||
|
||
LAN Pipes 让多台机器上的 Claude Code 实例通过局域网自动发现并协作。你可以在一台机器（main）上操控其他机器（sub）上的 Claude Code，发送 prompt、查看执行结果、审批权限请求——全程零配置。
|
||
|
||
基于本机 Pipe IPC（`UDS_INBOX`）扩展，新增 TCP 传输层 + UDP Multicast 发现。
|
||
|
||
## 前置条件
|
||
|
||
- 两台或以上机器在同一局域网
|
||
- 每台机器安装了 CCB 并能 `bun run dev`
|
||
- Feature flag `LAN_PIPES`（dev/build 默认开启）
|
||
- 防火墙允许 UDP 7101 + TCP 动态端口（见下方配置）
|
||
|
||
## 快速开始
|
||
|
||
### 第一步：配置防火墙
|
||
|
||
**每台机器都需要执行。**
|
||
|
||
**Windows**（管理员 PowerShell）：
|
||
```powershell
|
||
New-NetFirewallRule -DisplayName "CCB LAN Beacon (UDP)" -Direction Inbound -Protocol UDP -LocalPort 7101 -Action Allow -Profile Private
|
||
New-NetFirewallRule -DisplayName "CCB LAN Pipes (TCP)" -Direction Inbound -Protocol TCP -LocalPort 1024-65535 -Program (Get-Command bun).Source -Action Allow -Profile Private
|
||
New-NetFirewallRule -DisplayName "CCB LAN Beacon Out (UDP)" -Direction Outbound -Protocol UDP -RemotePort 7101 -Action Allow -Profile Private
|
||
```
|
||
|
||
验证网络为"专用"（非公共）：`Get-NetConnectionProfile`
|
||
|
||
**macOS**：
|
||
首次运行时系统弹出"允许接受传入连接"对话框，点击"允许"。
|
||
|
||
如果使用 pf 防火墙：
|
||
```bash
|
||
echo "pass in proto udp from any to any port 7101" | sudo pfctl -ef -
|
||
```
|
||
|
||
**Linux**（firewalld）：
|
||
```bash
|
||
sudo firewall-cmd --zone=trusted --add-port=7101/udp --permanent
|
||
sudo firewall-cmd --zone=trusted --add-port=1024-65535/tcp --permanent
|
||
sudo firewall-cmd --reload
|
||
```
|
||
|
||
**Linux**（iptables）：
|
||
```bash
|
||
sudo iptables -A INPUT -p udp --dport 7101 -j ACCEPT
|
||
sudo iptables -A INPUT -p tcp --dport 1024:65535 -m owner --uid-owner $(id -u) -j ACCEPT
|
||
```
|
||
|
||
### 第二步：启动
|
||
|
||
```bash
|
||
# 机器 A（例如 192.168.50.22）
|
||
bun run dev
|
||
|
||
# 机器 B（例如 192.168.50.27）
|
||
bun run dev
|
||
```
|
||
|
||
启动后等待 3-5 秒（beacon 广播间隔），两边自动发现并连接。
|
||
|
||
### 第三步：查看和操作
|
||
|
||
在任一台机器上：
|
||
```
|
||
/pipes
|
||
```
|
||
|
||
输出示例：
|
||
```
|
||
pipe: cli-a91bad56 (main) 192.168.50.22 2/3 selected
|
||
|
||
Main machine: 205d6c3a... (this machine)
|
||
[main] cli-a91bad56 XC/192.168.50.22 [alive] (you)
|
||
☑ [sub-1] cli-da029538 XC/192.168.50.22 [alive] [connected]
|
||
|
||
LAN Peers:
|
||
☐ [main] cli-04d67950 vmwin11/192.168.50.27 tcp:192.168.50.27:58853 [LAN]
|
||
```
|
||
|
||
### 第四步：选中目标并发送任务
|
||
|
||
1. 按 `Shift+↓` 展开选择面板
|
||
2. `↑↓` 移动到 LAN peer
|
||
3. `Space` 选中
|
||
4. `Enter` 确认
|
||
5. 输入 prompt，自动路由到远端执行
|
||
|
||
远端执行结果会流式回传到你的消息列表：
|
||
```
|
||
[main vmwin11/192.168.50.27 / cli-04d67950] 正在检查 git status...
|
||
[main vmwin11/192.168.50.27 / cli-04d67950] Completed
|
||
```
|
||
|
||
## 完整命令参考
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `/pipes` | 显示所有实例（本机 + LAN），Shift+↓ 展开选择面板 |
|
||
| `/pipes select <name>` | 选中某实例 |
|
||
| `/pipes all` | 全选 |
|
||
| `/pipes none` | 取消全选 |
|
||
| `/attach <name>` | 手动 attach（自动识别 LAN peer 并通过 TCP 连接） |
|
||
| `/detach <name>` | 断开连接 |
|
||
| `/send <name> <msg>` | 向指定 pipe 发送消息 |
|
||
| `/send tcp:host:port <msg>` | 直接通过 TCP 地址发送 |
|
||
| `/claim-main` | 强制声明为 main |
|
||
| `/pipe-status` | 显示详细状态 |
|
||
| `/peers` | 列出所有已发现的 peer |
|
||
|
||
## 快捷键
|
||
|
||
| 快捷键 | 场景 | 作用 |
|
||
|--------|------|------|
|
||
| `Shift+↓` | 状态栏可见时 | 展开/收起选择面板 |
|
||
| `↑ / ↓` | 面板展开时 | 移动光标 |
|
||
| `Space` | 面板展开时 | 选中/取消 |
|
||
| `Enter` | 面板展开时 | 确认关闭 |
|
||
| `Esc` | 面板展开时 | 取消关闭 |
|
||
| `← / →` | 有选中 pipe 时 | 切换路由模式 |
|
||
| `M` | 面板展开时 | 同 ←/→ 切换路由模式 |
|
||
|
||
## 路由模式
|
||
|
||
| 模式 | 显示 | 行为 |
|
||
|------|------|------|
|
||
| `selected pipes only` | 绿色 | prompt 仅发送到选中的 pipe，本地不执行 |
|
||
| `local main` | 灰色 | prompt 仅在本地执行，不转发 |
|
||
|
||
切换路由模式不会清空选择。
|
||
|
||
## 权限转发
|
||
|
||
当远端 slave 执行需要权限的工具（如 BashTool）时：
|
||
1. slave 发送 `permission_request` 到 main
|
||
2. main 弹出权限确认对话框，显示 `[role hostname/ip / pipeName]`
|
||
3. 用户确认/拒绝
|
||
4. 结果发回 slave，继续或中断
|
||
|
||
## 工作原理
|
||
|
||
### 发现机制
|
||
|
||
- 每台机器启动时创建 UDP multicast beacon
|
||
- 组地址 `224.0.71.67`，端口 `7101`，TTL=1（不跨路由器）
|
||
- 每 3 秒广播一次自身信息（pipeName、IP、TCP 端口、角色）
|
||
- 15 秒未收到广播则标记 peer 丢失
|
||
|
||
### 通信机制
|
||
|
||
- 本机实例：UDS（Unix Domain Socket / Named Pipe）
|
||
- 跨机器：TCP（动态端口，通过 beacon 发现）
|
||
- 协议：NDJSON（每行一个 JSON 对象）
|
||
- 消息类型：ping/pong、attach/detach、prompt/stream/done/error、permission
|
||
|
||
### 角色模型
|
||
|
||
| 角色 | 说明 |
|
||
|------|------|
|
||
| `main` | 首个启动的实例 |
|
||
| `sub` | 同机后续启动的实例 |
|
||
| `master` | attach 了至少一个 slave 的实例 |
|
||
| `slave` | 被 master attach 的实例 |
|
||
|
||
跨机器 attach 时，两边都可以是 main——不要求对方必须是 sub。
|
||
|
||
## 常见问题
|
||
|
||
### 看不到 LAN peer
|
||
|
||
1. 检查防火墙是否放行 UDP 7101
|
||
2. `Get-NetConnectionProfile`（Windows）确认网络为"专用"
|
||
3. 确认两台机器在同一子网（`ping` 能通）
|
||
4. 路由器未开启 AP 隔离
|
||
|
||
### 连接超时
|
||
|
||
1. 检查 TCP 入站防火墙规则
|
||
2. 确认没有 VPN 劫持流量
|
||
3. 尝试 `/send tcp:ip:port hello` 直接测试
|
||
|
||
### beacon 绑到了错误网卡
|
||
|
||
Windows 上 WSL/Docker 虚拟网卡可能劫持 multicast。beacon 会自动选择非内部 IPv4 接口。如果选错，检查 `getLocalIp()` 返回值。
|
||
|
||
## 安全说明
|
||
|
||
- TCP 连接当前**无认证**——同 LAN 内知道端口号即可连接
|
||
- Multicast TTL=1，不跨路由器
|
||
- AI 通过 `SendMessageTool` 发送 `tcp:` 消息时需**用户显式确认**
|
||
- 建议仅在信任的局域网中使用
|