wonder/cs-note
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
cs-note/claude-code-best/docs/features/lan-pipes-implementation.md
T

9.7 KiB
Raw Permalink Blame History

tags, create time
tags create time
LAN
pipes
实现
TCP
UDP
beacon
NDJSON
2026-06-09 22:30

LAN Pipes — 技术实现文档

概述

面向开发者的 LAN Pipes 实现细节，涵盖 TCP 扩展、UDP beacon、Hook 架构、NDJSON 协议和跨机器 attach 流程。用户指南见 claude-code-best/docs/features/lan-pipes。

正文

架构

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

LAN_PIPES — 在 scripts/dev.ts 和 build.ts 的 DEFAULT_FEATURES 中启用。

Warning

所有 LAN 代码路径通过 feature('LAN_PIPES') 编译时门控。feature() 只能在 if 或三元中使用（Bun 编译时常量约束）。

核心文件

文件 说明
src/utils/pipeTransport.ts PipeServer/PipeClient（UDS + TCP 双模式）
src/utils/lanBeacon.ts UDP multicast beacon + module singleton
src/utils/ndjsonFramer.ts 共享 NDJSON socket 帧解析
src/utils/pipeRegistry.ts 文件注册表 + mergeWithLanPeers()
src/utils/peerAddress.ts 地址解析（uds/bridge/tcp scheme）
src/utils/pipePermissionRelay.ts 权限转发 + setPipeRelay/getPipeRelay singleton
src/hooks/usePipeIpc.ts 生命周期 hook（从 REPL.tsx 提取）
src/hooks/usePipeRelay.ts 消息回传 hook
src/hooks/usePipePermissionForward.ts 权限转发 hook
src/hooks/usePipeRouter.ts 输入路由 hook
src/hooks/useMasterMonitor.ts slave 注册表 + 消息订阅

PipeServer TCP 扩展

src/utils/pipeTransport.ts

类型

export type PipeTransportMode = 'uds' | 'tcp'
export type TcpEndpoint = { host: string; port: number }
export type PipeServerOptions = { enableTcp?: boolean; tcpPort?: number }

PipeServer 变更

  • setupSocket(socket) — 从 start() 提取的共享方法，UDS 和 TCP 共用
  • start(options?) — 可选启用 TCP，port=0 让 OS 分配
  • 内部维护两个 net.Server，共享同一组 clients: Set<Socket> 和 handlers
  • tcpAddress getter 暴露 TCP 端口
  • close() 同时关闭两个 server

socket 帧解析使用 attachNdjsonFramer() from ndjsonFramer.ts（替代原先 3 份重复代码）。

PipeClient 变更

  • 构造函数新增可选 TcpEndpoint 参数
  • connect() 根据 tcpEndpoint 分派到 connectTcp() 或 connectUds()
  • TCP 不需要文件存在轮询，直接建连

LAN Beacon

src/utils/lanBeacon.ts

协议参数

参数 值
Multicast 组 224.0.71.67
端口 7101
广播间隔 3000ms
Peer 超时 15000ms
TTL 1

Announce 包

type LanAnnounce = {
  proto: 'claude-pipe-v1'
  pipeName: string
  machineId: string
  hostname: string
  ip: string
  tcpPort: number
  role: 'main' | 'sub'
  ts: number
}

API

class LanBeacon extends EventEmitter {
  constructor(announce: Omit<LanAnnounce, 'proto' | 'ts'>)
  start(): void
  stop(): void
  getPeers(): Map<string, LanAnnounce>  // 防御性拷贝
  updateAnnounce(partial): void         // 使用 spread（不可变更新）

  on('peer-discovered', (peer: LanAnnounce) => void)
  on('peer-lost', (pipeName: string) => void)
}

存储

module-level singleton：getLanBeacon() / setLanBeacon()。不挂在 Zustand state 上（避免 setState 展开时丢失引用）。

网卡绑定

addMembership(group, localIp) + setMulticastInterface(localIp) 指定 LAN 网卡。解决 Windows 上 WSL/Docker 虚拟网卡劫持 multicast 的问题。

Hook 架构

从 REPL.tsx 提取的 ~830 行 Pipe IPC 代码：

usePipeIpc（生命周期）

src/hooks/usePipeIpc.ts（623 行）

在 REPL.tsx 顶层通过 feature-gated require 加载：

const usePipeIpc = feature('UDS_INBOX')
  ? require('../hooks/usePipeIpc.js').usePipeIpc
  : () => undefined;

// 组件内
usePipeIpc({ store, handleIncomingPrompt });

内部使用 lazy getter 函数加载依赖（避免循环依赖导致 Bun 运行时崩溃）：

const pt = () => require('../utils/pipeTransport.js')
const pr = () => require('../utils/pipeRegistry.js')
const mm = () => require('./useMasterMonitor.js')
// ...

import type 用于静态类型（不会触发模块加载）。

四个阶段函数

函数 职责
initPipeServer 角色判定 + server 创建 + beacon 启动
registerMessageHandlers ping、attach、prompt、permission、detach 五个 handler
runMainHeartbeat cleanup + 发现 + auto-attach + 清理死连接
runSubHeartbeat 检测 main 是否存活，死亡则接管或独立

usePipeRelay（消息回传）

src/hooks/usePipeRelay.ts（38 行）

提供 relayPipeMessage() 和 pipeReturnHadErrorRef。relay 函数通过 getPipeRelay() module singleton 读取（替代 globalThis.__pipeSendToMaster）。

usePipePermissionForward（权限转发）

src/hooks/usePipePermissionForward.ts（159 行）

订阅 subscribePipeEntries()，处理：

  • permission_request -> 解析 payload -> 查找 tool -> 加入确认队列
  • permission_cancel -> 从队列移除
  • stream/error/done -> 转为系统消息显示（含 role + IP 标签）

usePipeRouter（输入路由）

src/hooks/usePipeRouter.ts（130 行）

提供 routeToSelectedPipes(input): boolean。读取 selectedPipes + routeMode，逐个发送到已连接目标。通知显示 [role] hostname/ip（LAN peer）或 [role]（本机）。

Registry 并行探测

src/utils/pipeRegistry.ts

getAliveSubs()

export async function getAliveSubs(): Promise<PipeRegistrySub[]> {
  const registry = await readRegistry()
  const results = await Promise.all(
    registry.subs.map(sub =>
      isPipeAlive(sub.pipeName, 1000).then(alive => alive ? sub : null)
    )
  )
  return results.filter(Boolean)
}

cleanupStaleEntries()

两阶段：

  1. 无锁并行探测：Promise.all 探测 main + 所有 subs
  2. 短暂持锁写入：acquireLock() -> 重新读取 -> 应用变更 -> 写入 -> releaseLock()

持锁时间从 N 秒降至 ~10ms。

getMachineId()

Windows/macOS 使用 execFile（异步），不阻塞主线程。结果缓存，仅首次调用执行。

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 无
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 })

帧格式

每行一个 JSON 对象，\n 分隔：

{"type":"ping","from":"cli-abc","ts":"2026-04-11T00:00:00.000Z"}\n
{"type":"prompt","data":"检查 git status","from":"cli-abc"}\n

跨机器 Attach 流程

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 支持

packages/builtin-tools/src/tools/SendMessageTool/SendMessageTool.ts

  • to 字段支持 tcp:host:port 格式
  • checkPermissions：tcp: scheme 返回 behavior: 'ask'，classifierApprovable: false
  • call()：创建临时 PipeClient -> connect -> send -> disconnect

测试

文件 测试数 覆盖
lanBeacon.test.ts 7 socket 初始化、announce、peer 发现/过滤/清理
peerAddress.test.ts 8 scheme 解析、parseTcpTarget、端口范围验证
pipePermissionRelay.test.ts 2 setPipeRelay singleton、权限请求/响应
pipeTransport.test.ts 2 UDS 基础行为
useMasterMonitor.test.ts 5 slave 注册/移除、事件发射

全量：2190 pass / 0 fail

已知限制

  1. TCP 无认证 — 同 LAN 内知道端口号即可连接
  2. Beacon 明文广播 — IP/hostname/machineId 未 hash
  3. 单网卡选择 — getLocalIp() 返回首个非内部 IPv4，可能选到 VPN
  4. 端口随机 — 每次启动不同端口，依赖 beacon 发现
  5. SendMessageTool 每次创建新连接 — 未复用已有 slave client

后续改进方向

  1. HMAC-SHA256 TCP 握手认证
  2. machineId hash 后再广播
  3. 多网卡选择（优先 RFC 1918 地址）
  4. 固定端口范围配置
  5. TLS 加密传输
  6. SendMessageTool 复用已连接的 slave client

关联笔记

Reference in New Issue View Git Blame Copy Permalink