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

claude-code-best/docs/features/uds-inbox.md

@@ -1,39 +1,53 @@
+---
+tags: [UDS, IPC, pipes, 多实例, 协作]
+create time: 2026-06-09 22:30
+---
+
 # UDS_INBOX / pipes
 
 ## 概述
 
-`UDS_INBOX` 现在不是一个“空壳 flag”，而是一套已经落地的本机 IPC 能力。但它同时承载了两层不同目标，必须拆开理解：
+`UDS_INBOX` 是一套已经落地的本机 IPC 能力，承载两层不同目标：UDS peer messaging（面向任意 Claude Code 进程）和 pipes control plane（面向交互式 REPL 会话之间的主从协作）。
+
+## 正文
+
+### 两层职责
 
 1. **UDS peer messaging**
    - 面向任意 Claude Code 进程。
    - 使用 `src/utils/udsMessaging.ts` 和 `src/utils/udsClient.ts`。
    - 对外入口是 `/peers` 和 `SendMessageTool` 的 `uds:<socket-path>` 地址。
+
 2. **pipes control plane**
    - 面向交互式 REPL 会话之间的主从协作。
    - 使用 `src/utils/pipeTransport.ts`、`src/utils/pipeRegistry.ts` 和 `src/screens/REPL.tsx` 中的内联 bootstrap。
    - 对外入口是 `/pipes`、`/attach`、`/detach`、`/send`、`/pipe-status`、`/history`、`/claim-main`。
 
-这两层都依赖本机 socket，但职责不同。`/peers` 解决“找到其他会话并发消息”，`/pipes` 解决“把一个 REPL 变成另一个 REPL 的受控 worker”。
+> [!tip]
+> 这两层都依赖本机 socket，但职责不同。`/peers` 解决"找到其他会话并发消息"，`/pipes` 解决"把一个 REPL 变成另一个 REPL 的受控 worker"。
 
-## 为什么要有单独的 `pipes`
+### 为什么要有单独的 `pipes`
 
 单独的 `pipes` 层有三个实际理由：
 
 1. **命名与角色模型不同**
    - UDS peer 层按 `messagingSocketPath` 寻址。
    - pipes 层按 `cli-xxxxxxxx` 会话名、`main/sub/master/slave` 角色和 `machineId` 注册表工作。
+
 2. **交互语义不同**
    - peer 层是通用消息投递。
    - pipes 层需要 attach、detach、历史收集、选择性广播、状态栏和 REPL 快捷键。
+
 3. **UI 集成不同**
    - peer 层主要服务工具调用。
    - pipes 层直接影响 REPL 提交路径和 PromptInput 页脚。
 
-如果把两者硬合并，`SendMessageTool` 的通用寻址和 REPL 的主从控制会互相污染，命令语义也会变得混乱。
+> [!warning]
+> 如果把两者硬合并，`SendMessageTool` 的通用寻址和 REPL 的主从控制会互相污染，命令语义也会变得混乱。
 
-## 当前通信模型
+### 当前通信模型
 
-### 1. UDS peer messaging
+#### 1. UDS peer messaging
 
 - 服务端：`src/utils/udsMessaging.ts`
 - 客户端：`src/utils/udsClient.ts`
@@ -41,9 +55,9 @@
 - 地址方式：`uds:<socket-path>`
 - 传输方式：**本机 Unix socket / Windows named pipe**
 
-这层是真正的“通用收件箱”。
+这层是真正的"通用收件箱"。
 
-### 2. pipes control plane
+#### 2. pipes control plane
 
 - 服务端/客户端：`src/utils/pipeTransport.ts`
 - 注册表：`src/utils/pipeRegistry.ts`
@@ -52,9 +66,9 @@
 - 会话名：`cli-${sessionId.slice(0, 8)}`
 - 传输方式：**本机 Unix socket / Windows named pipe**
 
-这层是真正的“主从 REPL 协调平面”。
+这层是真正的"主从 REPL 协调平面"。
 
-## 关于“局域网通信”的事实
+### 关于"局域网通信"的事实
 
 当前实现**不是**真正的局域网传输。
 
@@ -80,14 +94,10 @@
 - `registry` 带有 **机器身份元数据**
 - 但 **尚未实现跨机器局域网 transport**
 
-如果未来要做真局域网版本，至少还需要：
+> [!question]
+> 如果未来要做真局域网版本，至少还需要：TCP/WebSocket transport、认证与会话授权、发现与地址交换、超时、重连和安全边界。
 
-1. TCP/WebSocket transport
-2. 认证与会话授权
-3. 发现与地址交换
-4. 超时、重连和安全边界
-
-## 当前 REPL 行为
+### 当前 REPL 行为
 
 当前线上行为由 `src/screens/REPL.tsx` 的内联实现负责：
 
@@ -104,11 +114,16 @@
 - 当前已明确以 `REPL.tsx` 内联 bootstrap 为唯一生效实现
 - 选中但未连接的 pipe 不再导致本地处理被错误跳过
 
-## 文档与代码对齐约定
+### 文档与代码对齐约定
 
 后续关于 `UDS_INBOX` / `pipes` 的说明应遵守以下表述：
 
-1. 默认称为“本机 IPC / 本机多实例协作”
+1. 默认称为"本机 IPC / 本机多实例协作"
 2. 不把 `localIp` / `hostname` 元数据表述成已完成的 LAN transport
 3. 明确区分 `/peers` 和 `/pipes` 的两层职责
 4. 以 `src/screens/REPL.tsx`、`src/utils/pipeTransport.ts`、`src/utils/pipeRegistry.ts` 为事实来源
+
+## 关联笔记
+
+- [[claude-code-best/docs/features/lan-pipes]]
+- [[claude-code-best/docs/features/pipes-and-lan]]