wonder/cs-note
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault backup: 2026-06-09 23:15:17

Browse Source
This commit is contained in:
wonder
2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude-code-best/docs/features/lan-pipes-implementation.md
+99 -101
View File
@@ -1,39 +1,50 @@
# LAN Pipes — 技术实现文档
面向开发者的实现细节。用户指南见 [lan-pipes.md](./lan-pipes.md)。
---
tags: [LAN, pipes, 实现, TCP, UDP, beacon, NDJSON]
create time: 2026-06-09 22:30
---
## 架构
# LAN Pipes — 技术实现文档
```
Machine A (192.168.50.22) Machine B (192.168.50.27)
┌───────────────────────────┐ ┌───────────────────────────┐
│ PipeServer │ │ PipeServer │
│ UDS: ~/.claude/pipes/ │ │ UDS: ~/.claude/pipes/ │
│ cli-abc.sock │ │ cli-def.sock │
│ TCP: 0.0.0.0:<random> │◄──TCP───►│ TCP: 0.0.0.0:<random> │
├───────────────────────────┤ ├───────────────────────────┤
│ LanBeacon │ │ LanBeacon │
│ UDP 224.0.71.67:7101 │◄──UDP───►│ UDP 224.0.71.67:7101 │
├───────────────────────────┤ ├───────────────────────────┤
│ usePipeIpc (hook) │ │ usePipeIpc (hook) │
│ initPipeServer │ │ initPipeServer │
│ registerMessageHandlers │ │ registerMessageHandlers │
│ runMainHeartbeat │ │ runSubHeartbeat │
│ cleanupPipeIpc │ │ cleanupPipeIpc │
└───────────────────────────┘ └───────────────────────────┘
## 概述
面向开发者的 LAN Pipes 实现细节，涵盖 TCP 扩展、UDP beacon、Hook 架构、NDJSON 协议和跨机器 attach 流程。用户指南见 [[claude-code-best/docs/features/lan-pipes]]。
## 正文
### 架构
```mermaid
flowchart LR
subgraph MachineA["Machine A (192.168.50.22)"]
A1["PipeServer"]
A2["UDS: ~/.claude/pipes/cli-abc.sock"]
A3["TCP: 0.0.0.0:random"]
A4["LanBeacon"]
A5["UDP 224.0.71.67:7101"]
A6["usePipeIpc hook"]
end
subgraph MachineB["Machine B (192.168.50.27)"]
B1["PipeServer"]
B2["UDS: ~/.claude/pipes/cli-def.sock"]
B3["TCP: 0.0.0.0:random"]
B4["LanBeacon"]
B5["UDP 224.0.71.67:7101"]
B6["usePipeIpc hook"]
end
A3 <-->|"TCP"| B3
A5 <-->|"UDP mcast"| B5
```
## Feature Flag
### Feature Flag
`LAN_PIPES` — 在 `scripts/dev.ts` 和 `build.ts` 的 `DEFAULT_FEATURES` 中启用。
所有 LAN 代码路径通过 `feature('LAN_PIPES')` 编译时门控。`feature()` 只能在 `if` 或三元中使用（Bun 编译时常量约束）。
> [!warning]
> 所有 LAN 代码路径通过 `feature('LAN_PIPES')` 编译时门控。`feature()` 只能在 `if` 或三元中使用（Bun 编译时常量约束）。
---
## 核心文件
### 核心文件
| 文件 | 说明 |
|------|------|
@@ -49,13 +60,11 @@ Machine A (192.168.50.22) Machine B (192.168.50.27)
| `src/hooks/usePipeRouter.ts` | 输入路由 hook |
| `src/hooks/useMasterMonitor.ts` | slave 注册表 + 消息订阅 |
---
## PipeServer TCP 扩展
### PipeServer TCP 扩展
`src/utils/pipeTransport.ts`
### 类型
#### 类型
```typescript
export type PipeTransportMode = 'uds' | 'tcp'
@@ -63,7 +72,7 @@ export type TcpEndpoint = { host: string; port: number }
export type PipeServerOptions = { enableTcp?: boolean; tcpPort?: number }
```
### PipeServer 变更
#### PipeServer 变更
- `setupSocket(socket)` — 从 start() 提取的共享方法，UDS 和 TCP 共用
- `start(options?)` — 可选启用 TCP，port=0 让 OS 分配
@@ -73,19 +82,17 @@ export type PipeServerOptions = { enableTcp?: boolean; tcpPort?: number }
socket 帧解析使用 `attachNdjsonFramer()` from `ndjsonFramer.ts`（替代原先 3 份重复代码）。
### PipeClient 变更
#### PipeClient 变更
- 构造函数新增可选 `TcpEndpoint` 参数
- `connect()` 根据 tcpEndpoint 分派到 `connectTcp()` 或 `connectUds()`
- TCP 不需要文件存在轮询，直接建连
---
## LAN Beacon
### LAN Beacon
`src/utils/lanBeacon.ts`
### 协议参数
#### 协议参数
| 参数 | 值 |
|------|-----|
@@ -95,7 +102,7 @@ socket 帧解析使用 `attachNdjsonFramer()` from `ndjsonFramer.ts`（替代原
| Peer 超时 | `15000ms` |
| TTL | `1` |
### Announce 包
#### Announce 包
```typescript
type LanAnnounce = {
@@ -110,7 +117,7 @@ type LanAnnounce = {
}
```
### API
#### API
```typescript
class LanBeacon extends EventEmitter {
@@ -125,21 +132,19 @@ class LanBeacon extends EventEmitter {
}
```
### 存储
#### 存储
module-level singleton：`getLanBeacon()` / `setLanBeacon()`。不挂在 Zustand state 上（避免 `setState` 展开时丢失引用）。
### 网卡绑定
#### 网卡绑定
`addMembership(group, localIp)` + `setMulticastInterface(localIp)` 指定 LAN 网卡。解决 Windows 上 WSL/Docker 虚拟网卡劫持 multicast 的问题。
---
## Hook 架构
### Hook 架构
从 REPL.tsx 提取的 ~830 行 Pipe IPC 代码：
### usePipeIpc（生命周期）
#### usePipeIpc（生命周期）
`src/hooks/usePipeIpc.ts`（623 行）
@@ -165,7 +170,7 @@ const mm = () => require('./useMasterMonitor.js')
`import type` 用于静态类型（不会触发模块加载）。
### 四个阶段函数
#### 四个阶段函数
| 函数 | 职责 |
|------|------|
@@ -174,34 +179,32 @@ const mm = () => require('./useMasterMonitor.js')
| `runMainHeartbeat` | cleanup + 发现 + auto-attach + 清理死连接 |
| `runSubHeartbeat` | 检测 main 是否存活，死亡则接管或独立 |
### usePipeRelay（消息回传）
#### usePipeRelay（消息回传）
`src/hooks/usePipeRelay.ts`（38 行）
提供 `relayPipeMessage()` 和 `pipeReturnHadErrorRef`。relay 函数通过 `getPipeRelay()` module singleton 读取（替代 `globalThis.__pipeSendToMaster`）。
### usePipePermissionForward（权限转发）
#### usePipePermissionForward（权限转发）
`src/hooks/usePipePermissionForward.ts`（159 行）
订阅 `subscribePipeEntries()`，处理：
- `permission_request` → 解析 payload → 查找 tool → 加入确认队列
- `permission_cancel` → 从队列移除
- `stream/error/done` → 转为系统消息显示（含 role + IP 标签）
- `permission_request` -> 解析 payload -> 查找 tool -> 加入确认队列
- `permission_cancel` -> 从队列移除
- `stream/error/done` -> 转为系统消息显示（含 role + IP 标签）
### usePipeRouter（输入路由）
#### usePipeRouter（输入路由）
`src/hooks/usePipeRouter.ts`（130 行）
提供 `routeToSelectedPipes(input): boolean`。读取 `selectedPipes` + `routeMode`，逐个发送到已连接目标。通知显示 `[role] hostname/ip`（LAN peer）或 `[role]`（本机）。
---
## Registry 并行探测
### Registry 并行探测
`src/utils/pipeRegistry.ts`
### getAliveSubs()
#### getAliveSubs()
```typescript
export async function getAliveSubs(): Promise<PipeRegistrySub[]> {
@@ -215,40 +218,38 @@ export async function getAliveSubs(): Promise<PipeRegistrySub[]> {
}
```
### cleanupStaleEntries()
#### cleanupStaleEntries()
两阶段：
1. **无锁并行探测**：`Promise.all` 探测 main + 所有 subs
2. **短暂持锁写入**：`acquireLock()` → 重新读取 → 应用变更 → 写入 → `releaseLock()`
2. **短暂持锁写入**：`acquireLock()` -> 重新读取 -> 应用变更 -> 写入 -> `releaseLock()`
持锁时间从 N 秒降至 ~10ms。
### getMachineId()
#### getMachineId()
Windows/macOS 使用 `execFile`（异步），不阻塞主线程。结果缓存，仅首次调用执行。
---
### NDJSON 协议
## NDJSON 协议
### 消息类型
#### 消息类型
| 类型 | 方向 | 数据 |
|------|------|------|
| `ping` / `pong` | 双向 | 无 |
| `attach_request` | M→S | `meta: { machineId }` |
| `attach_accept` / `attach_reject` | S→M | `data: reason` |
| `detach` | M→S | 无 |
| `prompt` | M→S | `data: prompt_text` |
| `prompt_ack` | S→M | `data: 'accepted'` |
| `stream` | S→M | `data: partial_text` |
| `done` | S→M | 无 |
| `attach_request` | M->S | `meta: { machineId }` |
| `attach_accept` / `attach_reject` | S->M | `data: reason` |
| `detach` | M->S | 无 |
| `prompt` | M->S | `data: prompt_text` |
| `prompt_ack` | S->M | `data: 'accepted'` |
| `stream` | S->M | `data: partial_text` |
| `done` | S->M | 无 |
| `error` | 双向 | `data: error_message` |
| `permission_request` | S→M | `data: JSON(PipePermissionRequestPayload)` |
| `permission_response` | M→S | `data: JSON(PipePermissionResponsePayload)` |
| `permission_cancel` | M→S | `data: JSON({ requestId, reason })` |
| `permission_request` | S->M | `data: JSON(PipePermissionRequestPayload)` |
| `permission_response` | M->S | `data: JSON(PipePermissionResponsePayload)` |
| `permission_cancel` | M->S | `data: JSON({ requestId, reason })` |
### 帧格式
#### 帧格式
每行一个 JSON 对象，`\n` 分隔：
```
@@ -256,40 +257,33 @@ Windows/macOS 使用 `execFile`（异步），不阻塞主线程。结果缓存
{"type":"prompt","data":"检查 git status","from":"cli-abc"}\n
```
---
### 跨机器 Attach 流程
## 跨机器 Attach 流程
```
CLI-B (192.168.50.27) 心跳循环
→ beacon.getPeers() 发现 CLI-A (192.168.50.22)
→ connectToPipe(pName, myName, 3000, { host: '192.168.50.22', port: 58853 })
→ PipeClient.connectTcp() → net.createConnection({ host, port })
→ client.send({ type: 'attach_request', meta: { machineId } })
→ CLI-A 收到：
isLanPeer = (msg.meta.machineId !== myMachineId) → true
→ 不检查 role，直接 reply({ type: 'attach_accept' })
→ setPipeRelay(socket.write)
→ CLI-B 收到 attach_accept
→ addSlaveClient(pName, client)
→ store.setState: role='master', slaves[pName] = { status: 'idle' }
```mermaid
sequenceDiagram
participant CLI-B as CLI-B (192.168.50.27)
participant CLI-A as CLI-A (192.168.50.22)
CLI-B->>CLI-B: 心跳循环
CLI-B->>CLI-B: beacon.getPeers() 发现 CLI-A
CLI-B->>CLI-A: connectToPipe() -> PipeClient.connectTcp()
CLI-B->>CLI-A: attach_request { machineId }
CLI-A->>CLI-A: isLanPeer = (machineId !== myMachineId) -> true
CLI-A->>CLI-B: attach_accept
CLI-B->>CLI-B: addSlaveClient() -> role='master'
```
关键：跨机器 attach 不要求对方是 sub 角色。通过 `machineId` 区分 LAN peer。
---
## SendMessageTool TCP 支持
### SendMessageTool TCP 支持
`packages/builtin-tools/src/tools/SendMessageTool/SendMessageTool.ts`
- `to` 字段支持 `tcp:host:port` 格式
- `checkPermissions`：`tcp:` scheme 返回 `behavior: 'ask'`，`classifierApprovable: false`
- `call()`：创建临时 `PipeClient` → connect → send → disconnect
- `call()`：创建临时 `PipeClient` -> connect -> send -> disconnect
---
## 测试
### 测试
| 文件 | 测试数 | 覆盖 |
|------|--------|------|
@@ -301,9 +295,7 @@ CLI-B (192.168.50.27) 心跳循环
全量：2190 pass / 0 fail
---
## 已知限制
### 已知限制
1. **TCP 无认证** — 同 LAN 内知道端口号即可连接
2. **Beacon 明文广播** — IP/hostname/machineId 未 hash
@@ -311,7 +303,7 @@ CLI-B (192.168.50.27) 心跳循环
4. **端口随机** — 每次启动不同端口，依赖 beacon 发现
5. **SendMessageTool 每次创建新连接** — 未复用已有 slave client
## 后续改进方向
### 后续改进方向
1. HMAC-SHA256 TCP 握手认证
2. machineId hash 后再广播
@@ -319,3 +311,9 @@ CLI-B (192.168.50.27) 心跳循环
4. 固定端口范围配置
5. TLS 加密传输
6. SendMessageTool 复用已连接的 slave client
## 关联笔记
- [[claude-code-best/docs/features/lan-pipes]]
- [[claude-code-best/docs/features/uds-inbox]]
- [[claude-code-best/docs/features/pipes-and-lan]]