docs: 文档大重组,对齐 README 入口

以 README 为单一事实来源,重构整个 docs/ 目录。

最终结构(3 大组、15 篇文档):
- 开始: installation / quickstart / model-providers
- 核心功能: pipes-and-lan、acp、channels、chrome-control、computer-use、
  voice-mode、web-browser-tool、auto-dream、remote-control-self-hosting、
  langfuse-monitoring
- 内部机制: growthbook-adapter、sentry-setup

主要变更:
- 删除 56 个 README 未提及的文档(architecture 全部 / guides 全部 /
  features 中未在 README 出现的 20 篇 / internals 中的 5 篇)
- 合并 6 组重复文档(pipes-and-lan、chrome-control、acp、computer-use、
  auto-dream、coordinator-mode 简化为入口)
- features 子组从 5 → 4,ui/ 合并入 tools/
- 所有保留文档加上人性化 frontmatter(title/description/keywords)
- docs.json navigation 简化为 3 大组,redirects 重新过滤为 7 条合并跳转
- 新增 docs.md 工作大纲与验证脚本(verify-docs / check-docs-orphans /
  dump-docs-outline)

总计 130 文件改动,从约 35000 行精简到约 2000 行。

Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
This commit is contained in:
claude-code-best
2026-06-14 20:42:51 +08:00
parent 2714bbf812
commit 37dac682b9
130 changed files with 2074 additions and 33533 deletions

View File

@@ -0,0 +1,420 @@
---
title: "群控:本机 + 局域网多实例协作"
description: "多台 CCB 实例零配置组网,同机用 UDS、跨机用 LAN自动发现与消息路由。包含 /pipes 命令、心跳机制、消息路由详解。"
keywords: ["群控", "局域网协作", "UDS", "多实例", "消息路由"]
---
# 群控:本机 + 局域网多实例协作
## 概述
Pipes 系统提供 Claude Code CLI 实例之间的通讯能力让你可以在一台机器main上操控其他实例sub发送 prompt、查看执行结果、审批权限请求——全程零配置。
系统分两层使用同一套协议NDJSON和同一套命令`/pipes``/attach``/send` 等),对用户完全透明:
1. **本机 PipesUDS**:同一台机器上的多个 CLI 实例通过 Unix Domain SocketLinux/macOS或 Windows Named Pipe 协作
2. **局域网 PipesLAN**:不同机器上的 CLI 实例通过 TCP + UDP Multicast beacon 协作
> 严格区分:`/peers` 解决"找到其他会话并发消息"(通用消息投递),`/pipes` 解决"把一个 REPL 变成另一个 REPL 的受控 worker"(主从 REPL 协调平面)。两者职责不同,不要混淆。
### 两层职责拆解
| 层 | 面向 | 传输方式 | 对外入口 |
|------|------|----------|----------|
| UDS peer messaging | 任意 CCB 进程 | 本机 Unix socket / Named pipe | `/peers``SendMessageTool``uds:<socket-path>` |
| pipes control plane | 交互式 REPL 会话间的主从协作 | 本机 socket + LAN TCP | `/pipes``/attach``/detach``/send``/pipe-status``/claim-main` |
两层都依赖本机 socket但命名、角色模型、交互语义和 UI 集成都不同peer 层按 socket 路径寻址服务工具调用pipes 层按 `cli-xxxxxxxx` 会话名和 `main/sub/master/slave` 角色工作,直接影响 REPL 提交路径和 PromptInput 页脚。
## 快速上手
### 场景一:本机多实例
```bash
# 终端 1
bun run dev
# 启动后自动注册为 main
# 终端 2
bun run dev
# 自动注册为 sub-1被 main 自动 attach
```
在终端 1 中输入 `/pipes`,可以看到两个实例。选中 sub-1 后,输入的消息会自动转发到 sub-1 执行。
### 场景二:局域网多机器
前置条件:
- 两台或以上机器在同一局域网
- 每台机器安装了 CCB 并能 `bun run dev`
- 防火墙允许 UDP 7101 + TCP 动态端口(见下方配置)
```bash
# 机器 A (192.168.50.22)
bun run dev
# 机器 B (192.168.50.27)
bun run dev
```
两边启动后等 3-5 秒beacon 广播间隔LAN peers 会自动发现并 attach。输入 `/pipes` 可看到标记 `[LAN]` 的远端实例。
## 防火墙配置
**每台机器都需要执行。** 请先确认网络为局域网(非公共 WiFi路由器未开启 AP 隔离,两台机器在同一子网(`ping` 能通)。
### Windows管理员 PowerShell
```powershell
New-NetFirewallRule -DisplayName "Claude Code LAN Beacon (UDP)" -Direction Inbound -Protocol UDP -LocalPort 7101 -Action Allow -Profile Private
New-NetFirewallRule -DisplayName "Claude Code LAN Pipes (TCP)" -Direction Inbound -Protocol TCP -LocalPort 1024-65535 -Program (Get-Command bun).Source -Action Allow -Profile Private
New-NetFirewallRule -DisplayName "Claude Code 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 -
```
### Linuxfirewalld / iptables
```bash
# firewalld
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
# 或 iptables
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
```
## 交互面板与快捷键
### 状态栏
执行 `/pipes` 后,输入框底部出现 pipe 状态栏(单行),始终可见(直到会话结束):
```
pipe: cli-a91bad56 (main) 192.168.50.22 2/3 selected selected pipes only · ←/→ or m switch · Shift+↓ edit
```
显示:当前 pipe 名、角色、IP、已选数/总数、路由模式。
### 展开选择面板
**Shift+↓**Shift + 下箭头)展开选择面板:
```
pipe: cli-a91bad56 (main) 192.168.50.22 ↑↓ move Space select ←/→ or m route Enter/Esc close Shift+↓ toggle
当前普通 prompt 走 已选 sub切换不会清空选择
☑ cli-da029538 (sub-1 XC/192.168.50.22)
☐ cli-04d67950 (main vmwin11/192.168.50.27)
☑ cli-893747d3 [offline] (sub-2 vmwin11/192.168.50.27)
```
### 面板快捷键
| 快捷键 | 场景 | 作用 |
|--------|------|------|
| **Shift+↓** | 状态栏可见时 | 展开/收起选择面板 |
| **↑ / ↓** | 面板展开时 | 上下移动光标 |
| **Space** | 面板展开时 | 切换当前光标所在 pipe 的选中状态(☑ ↔ ☐) |
| **Enter** | 面板展开时 | 确认并关闭面板 |
| **Esc** | 面板展开时 | 取消并关闭面板 |
| **← / → 或 M** | 状态栏可见且有选中 pipe 时 | 切换路由模式(`selected pipes only``local main` |
### 完整操作流程示例
```
1. 输入 /pipes → 状态栏出现,显示发现的实例
2. 按 Shift+↓ → 展开选择面板
3. 按 ↓ 移动到目标 pipe → 光标移到 cli-04d67950
4. 按 Space → 选中 ☑ cli-04d67950
5. 按 Enter → 确认,面板收起
6. 输入 "帮我检查 git status" → prompt 自动发送到 cli-04d67950 执行
7. 按 M → 切换到 local main 模式
8. 输入 "本地做点什么" → 仅在本地执行
9. 按 M → 切回 selected pipes only
10. 输入 "继续远端任务" → 又发送到 cli-04d67950
```
远端执行结果会流式回传到你的消息列表:
```
[main vmwin11/192.168.50.27 / cli-04d67950] 正在检查 git status...
[main vmwin11/192.168.50.27 / cli-04d67950] Completed
```
## 消息路由
### 路由模式
通过 **M 键**(或 ← / →)切换,**无需展开面板**。切换路由模式**不会清空选择**——你可以在 `local main` 模式下保持选择,随时按 M 切回继续向远端发送。
| 模式 | 状态栏显示 | 行为 |
|------|-----------|------|
| `selected pipes only` | 绿色高亮 | 输入的 prompt **仅**发送到选中的 pipe本地不执行 |
| `local main` | 灰色 | 输入的 prompt 在**本地 main** 执行,不转发到任何 pipe |
### 选中 pipe 后的自动路由
1. 通过 `/pipes select` 或 Shift+↓ 面板选中一个或多个 pipe
2. 在输入框中正常输入消息
3. 消息自动发送到所有选中的**已连接** pipe
4. 每个 pipe 独立执行,结果流式回传到 main 的消息列表
> 选中但未连接的 pipe 不会导致本地处理被错误跳过——只有已连接的 pipe 会收到广播。
## 命令参考
### /pipes
显示所有发现的实例,管理选择状态。再次执行 `/pipes` 切换面板展开/收起。
```
/pipes — 显示所有实例 + 切换选择面板
/pipes select <name> — 选中某实例(消息会广播到它)
/pipes deselect <name> — 取消选中
/pipes all — 全选
/pipes none — 全部取消
```
输出示例:
```
Your pipe: cli-a91bad56
Role: main
Machine ID: 205d6c3a...
IP: 192.168.50.22
Host: XC
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]
Selected: cli-da029538
```
### 其他命令
| 命令 | 说明 |
|------|------|
| `/attach <name>` | 手动 attach 到一个实例(自动识别 LAN peer 并通过 TCP 连接),使其成为 slave |
| `/detach <name>` | 断开与某个 slave 的连接 |
| `/send <name> <msg>` | 向指定 pipe 发送消息(不依赖选择状态,直接指定目标) |
| `/send tcp:host:port <msg>` | 直接通过 TCP 地址发送 |
| `/claim-main` | 强制声明当前机器为 main用于 main 意外退出后的恢复) |
| `/pipe-status` | 显示详细状态 |
| `/peers` | 列出所有已发现的 peer |
通常不需要手动 attach——heartbeat 会自动发现并连接。attach 后对方变为 slave你变为 master可以向它发送 prompt。
示例:
```
/attach cli-04d67950
/send cli-04d67950 请帮我检查一下日志
/send tcp:192.168.50.27:58853 hello
```
## 权限转发
当远端 slave 执行需要权限的工具(如 BashTool
1. slave 发送 `permission_request` 到 main
2. main 弹出权限确认对话框,显示来源标记 `[role hostname/ip / pipeName]`
3. 用户确认/拒绝
4. 结果发回 slave继续或中断
> AI 通过 `SendMessageTool` 发送 `tcp:` 消息时需用户显式确认。
## 架构详解
### 通信协议
所有通讯使用 NDJSONNewline-Delimited JSON每行一个消息
```json
{"type":"ping","from":"cli-abc","ts":"2026-04-11T00:00:00.000Z"}
{"type":"prompt","data":"帮我查看 git status","from":"cli-abc","ts":"..."}
{"type":"stream","data":"正在执行...","from":"cli-def","ts":"..."}
{"type":"done","data":"","from":"cli-def","ts":"..."}
```
### 消息类型
| 类型 | 方向 | 说明 |
|------|------|------|
| `ping`/`pong` | 双向 | 健康检查 |
| `attach_request`/`accept`/`reject` | M→S/S→M | 连接控制 |
| `detach` | M→S | 断开连接 |
| `prompt` | M→S | 主向从发送 prompt |
| `prompt_ack` | S→M | 从确认接收 |
| `stream` | S→M | 从流式回传 AI 输出 |
| `tool_start`/`tool_result` | S→M | 工具执行通知 |
| `done` | S→M | 本轮完成 |
| `error` | 双向 | 错误通知 |
| `permission_request`/`response`/`cancel` | 双向 | 权限审批转发 |
### 传输层
```
本机 LAN
┌──────────────┐ ┌──────────────┐
│ PipeServer │ │ PipeServer │
│ UDS sock │ │ UDS sock │
│ TCP :rand │◄───TCP───►│ TCP :rand │
├──────────────┤ ├──────────────┤
│ LanBeacon │◄──UDP────►│ LanBeacon │
│ 224.0.71.67 │ mcast │ 224.0.71.67 │
└──────────────┘ └──────────────┘
```
- **UDS / Named Pipe**:本机实例间通讯,通过文件系统路径寻址(`~/.claude/pipes/cli-xxx.sock`
- **TCP**LAN 实例间通讯,动态端口,通过 beacon 发现
- **UDP Multicast**peer 发现,组地址 `224.0.71.67`,端口 `7101`TTL=1不跨路由器3 秒广播一次 announce 包
### 角色模型
| 角色 | 说明 |
|------|------|
| `main` | 首个启动的实例,管理 registry |
| `sub` | 后续启动的同机实例(或被 attach 的 LAN 实例) |
| `master` | attach 了至少一个 slave 的实例 |
| `slave` | 被 master attach 控制的实例 |
**角色转换规则:**
- 首个启动 → `main`
- 同机后续启动 → `sub`(自动被 main attach → `slave`
- LAN 发现 → 两边都是 `main`heartbeat 自动互相 attach跨机器 attach 时,两边都可以是 main——不要求对方必须是 sub
- 被 attach → 变为 `slave`(可通过 `/detach` 恢复)
### 发现机制
**本机**:通过 `~/.claude/pipes/registry.json` 文件(带文件锁),`machineId` 绑定主机身份。同机 peer 层读取 `~/.claude/sessions/*.json`,按 `messagingSocketPath` 寻址。
**LAN**:通过 UDP multicast beacon
1. 每台机器启动时创建 UDP multicast beacon每 3 秒广播一次 `{ proto, pipeName, machineId, ip, tcpPort, role }`
2. 收到其他实例的 announce → 记入 peers Map
3. 15 秒未收到广播 → 标记 peer lost
4. Heartbeat 合并 local registry + beacon peers → 统一 attach 目标列表
### Heartbeat 循环5 秒间隔)
**main/master 角色:**
1. `cleanupStaleEntries()` — 清理 registry 中死掉的条目
2. `getAliveSubs()` — 获取存活的本地 subs
3. `refreshDiscoveredPipes()` — 刷新 discoveredPipes包含 LAN peers
4. 合并 LAN peers 到 state
5. 构建统一 attach 目标列表 — 本地 subs + LAN peers
6. 遍历未连接的目标 → 自动 attach
7. 清理断开的 slave 连接 — 同时检查 local registry 和 beacon
**sub 角色:**
1. 检测 main 是否存活
2. main 死亡 → 同机则接管 main 角色,跨机则独立
### 当前 REPL 行为
当前线上行为由 `src/screens/REPL.tsx` 的内联实现负责(以该文件、`pipeTransport.ts``pipeRegistry.ts` 为事实来源):
1. 启动时创建当前 REPL 的 pipe server
2. 通过 `pipeRegistry` 判定 `main` / `sub`
3. 处理 `attach_request` / `detach` / `prompt`
4. 主实例心跳探测并维护 `slaves`
5. `/pipes` 打开状态栏并维护选择器
6. 提交普通消息时,仅向**已连接**的 selected pipes 广播
过去的未接线 hook 方案已收敛,选中但未连接的 pipe 不会导致本地处理被错误跳过。
## 关键文件
| 文件 | 职责 |
|------|------|
| `src/utils/pipeTransport.ts` | PipeServer双模 UDS+TCP、PipeClient、类型定义 |
| `src/utils/lanBeacon.ts` | UDP multicast beacon、singleton 管理 |
| `src/utils/pipeRegistry.ts` | Registry CRUD、角色判定、machineId、LAN merge |
| `src/utils/peerAddress.ts` | 地址解析uds:/bridge:/tcp: scheme |
| `src/utils/udsMessaging.ts` | UDS peer messaging 服务端 |
| `src/utils/udsClient.ts` | UDS peer messaging 客户端 |
| `src/screens/REPL.tsx` | Bootstrap、heartbeat、cleanup、prompt 路由 |
| `src/hooks/useMasterMonitor.ts` | Slave client registry、消息订阅 |
| `src/hooks/useSlaveNotifications.ts` | Slave 端通知处理 |
| `src/commands/pipes/pipes.ts` | /pipes 命令 |
| `src/commands/attach/attach.ts` | /attach 命令 |
| `src/commands/send/send.ts` | /send 命令 |
| `packages/builtin-tools/src/tools/SendMessageTool/SendMessageTool.ts` | AI 发消息工具(含 tcp: 支持) |
## 常见问题
### 看不到 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()` 返回值。
## 配置
### Feature Flag
| Flag | 控制范围 | 默认 |
|------|----------|------|
| `UDS_INBOX` | 本机 Pipe IPC 全部功能(含 UDS peer messaging + pipes control plane | dev/build 启用 |
| `LAN_PIPES` | 局域网 TCP + UDP beacon 扩展 | dev/build 启用 |
手动启用:
```bash
FEATURE_UDS_INBOX=1 FEATURE_LAN_PIPES=1 bun run dev
```
### 安全说明
- TCP 连接当前**无认证**——同 LAN 内知道端口号即可连接
- Multicast TTL=1不跨路由器
- 建议仅在信任的局域网中使用
### 后续优化方向
**安全P0**
1. TCP 认证:首次连接时交换 HMAC-SHA256 token基于 machineId + session secret
2. JSON schema 验证:在所有 `JSON.parse` 入口点增加 Zod 校验,防 prototype pollution
3. Beacon 信息脱敏hash machineId 后再广播
**可靠性P1**
4. 多网卡选择:`getLocalIp()` 应优先选择 RFC 1918 地址,排除 VPN/Docker 接口
5. TCP target 验证:`parseTcpTarget()` 应限制目标为已知 beacon peers 或 RFC 1918 范围
6. PipeServer close():改为 `Promise.allSettled` 并行关闭 UDS + TCP`_closing` guard
**功能P2**
7. mDNS/DNS-SD作为 multicast 受限环境下的 beacon 替代方案
8. 固定端口配置:允许用户指定 TCP 端口范围,便于防火墙精确配置
9. TLS 加密TCP 传输加密,防中间人窃听
10. 双向 prompt当前只有 master → slave 方向,可考虑 slave 主动向 master 发送结果/请求