mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 12:55:51 +00:00
docs: add complete features guide and rewrite LAN Pipes docs (#246)
- 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>
This commit is contained in:
Dosion
562
docs/features/all-features-guide.md
Normal file
562
docs/features/all-features-guide.md
Normal file
@@ -0,0 +1,562 @@
|
|||||||
|
# Claude Code Best (CCB) — 全功能使用指南
|
||||||
|
|
||||||
|
本文档覆盖我们通过 13 个 PR 为 CCB 恢复/新增的**全部功能**，按类别组织，每个功能包含说明、使用方法和示例。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
1. [Buddy 伴侣系统](#1-buddy-伴侣系统)
|
||||||
|
2. [Remote Control 远程控制](#2-remote-control-远程控制)
|
||||||
|
3. [定时任务 /schedule](#3-定时任务-schedule)
|
||||||
|
4. [Voice Mode 语音模式](#4-voice-mode-语音模式)
|
||||||
|
5. [Chrome 浏览器控制](#5-chrome-浏览器控制)
|
||||||
|
6. [Computer Use 屏幕操控](#6-computer-use-屏幕操控)
|
||||||
|
7. [Feature Flags 与 GrowthBook](#7-feature-flags-与-growthbook)
|
||||||
|
8. [/ultraplan 高级规划](#8-ultraplan-高级规划)
|
||||||
|
9. [Daemon 后台守护](#9-daemon-后台守护)
|
||||||
|
10. [Pipe IPC 多实例协作](#10-pipe-ipc-多实例协作)
|
||||||
|
11. [LAN Pipes 局域网群控](#11-lan-pipes-局域网群控)
|
||||||
|
12. [Monitor 后台监控](#12-monitor-后台监控)
|
||||||
|
13. [Workflow 工作流脚本](#13-workflow-工作流脚本)
|
||||||
|
14. [Coordinator 多Worker协调](#14-coordinator-多worker协调)
|
||||||
|
15. [Proactive 自主模式](#15-proactive-自主模式)
|
||||||
|
16. [History / Snip 历史管理](#16-history--snip-历史管理)
|
||||||
|
17. [Fork 子Agent](#17-fork-子agent)
|
||||||
|
18. [其他恢复的工具](#18-其他恢复的工具)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Buddy 伴侣系统
|
||||||
|
|
||||||
|
**PR**: #82 `refactor(buddy): align companion system with official CLI`
|
||||||
|
**Feature Flag**: `BUDDY`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
Buddy 是一个后台运行的伴侣 AI，在你主对话进行的同时，异步观察会话内容并提供建议。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```bash
|
||||||
|
# 启动时自动加载（feature 默认开启）
|
||||||
|
bun run dev
|
||||||
|
|
||||||
|
# 在对话中，Buddy 会在适当时机自动提供建议
|
||||||
|
# 例如当你在调试时，Buddy 可能提示你检查日志
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Remote Control 远程控制
|
||||||
|
|
||||||
|
**PR**: #60 `feat: enable Remote Control (BRIDGE_MODE)` + #170 `feat: restore daemon supervisor`
|
||||||
|
**Feature Flag**: `BRIDGE_MODE`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
通过 WebSocket 远程控制 Claude Code 会话。支持自托管私有部署。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```bash
|
||||||
|
# 启动远程控制模式
|
||||||
|
bun run dev -- remote-control
|
||||||
|
|
||||||
|
# 使用自托管服务器
|
||||||
|
CLAUDE_BRIDGE_BASE_URL=https://your-server.com CLAUDE_BRIDGE_OAUTH_TOKEN=your-token bun run dev --remote-control
|
||||||
|
|
||||||
|
# 或通过 /remote-control 命令在会话中启动
|
||||||
|
/remote-control
|
||||||
|
```
|
||||||
|
|
||||||
|
### 命令
|
||||||
|
- `claude remote-control` / `claude rc` — 启动远程控制客户端
|
||||||
|
- `claude bridge` — 同上（别名）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 定时任务 /schedule
|
||||||
|
|
||||||
|
**PR**: #88 `feat: enable /schedule by adding AGENT_TRIGGERS_REMOTE`
|
||||||
|
**Feature Flag**: `AGENT_TRIGGERS_REMOTE`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
创建定时执行的远程 agent 任务，支持 cron 表达式。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```
|
||||||
|
/schedule create "每天检查依赖更新" --cron "0 9 * * *" --prompt "检查 package.json 中的过期依赖并创建更新 PR"
|
||||||
|
/schedule list — 列出所有定时任务
|
||||||
|
/schedule delete <id> — 删除指定任务
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Voice Mode 语音模式
|
||||||
|
|
||||||
|
**PR**: #92 `feat: enable /voice mode with native audio binaries`
|
||||||
|
**Feature Flag**: `VOICE_MODE`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
Push-to-Talk 语音输入，音频通过 WebSocket 流式传输到 Anthropic STT（Nova 3）。需要 Anthropic OAuth 认证（非 API key）。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```bash
|
||||||
|
# 确保已通过 OAuth 登录
|
||||||
|
claude auth login
|
||||||
|
|
||||||
|
# 在会话中按住指定键说话
|
||||||
|
# 松开后自动转写为文字输入
|
||||||
|
```
|
||||||
|
|
||||||
|
### 前提条件
|
||||||
|
- Anthropic OAuth 认证（不支持 API key 模式）
|
||||||
|
- 系统麦克风权限
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Chrome 浏览器控制
|
||||||
|
|
||||||
|
**PR**: #93 `feat: enable Claude in Chrome MCP with full browser control`
|
||||||
|
**Feature Flag**: `CHICAGO_MCP`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
通过 Chrome 扩展控制浏览器：导航、点击、填表、截图、执行 JS。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```bash
|
||||||
|
# 启动带 Chrome 控制的模式
|
||||||
|
bun run dev -- --chrome
|
||||||
|
|
||||||
|
# 安装 Chrome 扩展后，AI 可以：
|
||||||
|
# - 打开网页、点击按钮
|
||||||
|
# - 填写表单
|
||||||
|
# - 截取页面内容
|
||||||
|
# - 执行 JavaScript
|
||||||
|
```
|
||||||
|
|
||||||
|
### AI 可用工具
|
||||||
|
- `navigate` — 导航到 URL
|
||||||
|
- `click` / `find` / `form_input` — 页面交互
|
||||||
|
- `get_page_text` / `read_page` — 读取内容
|
||||||
|
- `javascript_tool` — 执行 JS
|
||||||
|
- `gif_creator` — 录制操作 GIF
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Computer Use 屏幕操控
|
||||||
|
|
||||||
|
**PR**: #98 + #137 `feat: Computer Use — 跨平台 Executor + Python Bridge + GUI 无障碍`
|
||||||
|
**Feature Flag**: `CHICAGO_MCP`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
跨平台屏幕操控：截图、键鼠模拟、应用管理。支持 macOS + Windows，Linux 后端待完成。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```bash
|
||||||
|
# 启动后 AI 可自动调用屏幕操控工具
|
||||||
|
bun run dev
|
||||||
|
|
||||||
|
# AI 可以：
|
||||||
|
# - 截取屏幕/窗口截图
|
||||||
|
# - 模拟键盘输入和鼠标操作
|
||||||
|
# - 列出运行的应用
|
||||||
|
# - 使用剪贴板
|
||||||
|
```
|
||||||
|
|
||||||
|
### 平台支持
|
||||||
|
| 平台 | 截图 | 键鼠 | 应用管理 |
|
||||||
|
|------|------|------|----------|
|
||||||
|
| macOS | ✅ | ✅ | ✅ |
|
||||||
|
| Windows | ✅ | ✅ | ✅ |
|
||||||
|
| Linux | ⏳ | ⏳ | ⏳ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Feature Flags 与 GrowthBook
|
||||||
|
|
||||||
|
**PR**: #140 + #153 `feat: enable GrowthBook local gate defaults`
|
||||||
|
**Feature Flags**: `SHOT_STATS`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
本地 GrowthBook gate defaults 机制，绕过远程 feature flag 服务，确保功能在无网络时也可使用。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```bash
|
||||||
|
# 通过环境变量启用任意 feature
|
||||||
|
FEATURE_PROACTIVE=1 bun run dev
|
||||||
|
|
||||||
|
# dev/build 模式有各自的默认启用列表
|
||||||
|
# 查看 scripts/dev.ts 中的 DEFAULT_FEATURES
|
||||||
|
```
|
||||||
|
|
||||||
|
### 关键 feature flags
|
||||||
|
| Flag | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| `SHOT_STATS` | API 调用统计 |
|
||||||
|
| `TOKEN_BUDGET` | Token 预算控制 |
|
||||||
|
| `PROMPT_CACHE_BREAK_DETECTION` | Prompt 缓存命中检测 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. /ultraplan 高级规划
|
||||||
|
|
||||||
|
**PR**: #156 `feat: enable /ultraplan and harden GrowthBook fallback chain`
|
||||||
|
**Feature Flag**: `ULTRAPLAN`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
高级多 agent 规划模式。将复杂任务分解为多个阶段，每阶段可分配给不同 agent 并行执行。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```
|
||||||
|
/ultraplan 实现一个完整的用户认证系统，包括注册、登录、密码重置、OAuth 集成
|
||||||
|
```
|
||||||
|
|
||||||
|
AI 会生成：
|
||||||
|
1. 任务分解（多阶段）
|
||||||
|
2. 每阶段的 agent 分配
|
||||||
|
3. 依赖关系图
|
||||||
|
4. 并行执行计划
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Daemon 后台守护
|
||||||
|
|
||||||
|
**PR**: #170 `feat: restore daemon supervisor and remoteControlServer command`
|
||||||
|
**Feature Flag**: `DAEMON`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
Daemon 模式允许 Claude Code 作为后台长驻进程运行，管理多个 worker。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```bash
|
||||||
|
# 启动 daemon
|
||||||
|
claude daemon start
|
||||||
|
|
||||||
|
# 查看状态
|
||||||
|
claude daemon status
|
||||||
|
|
||||||
|
# 停止
|
||||||
|
claude daemon stop
|
||||||
|
|
||||||
|
# 启动远程控制服务器
|
||||||
|
bun run rcs
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Pipe IPC 多实例协作
|
||||||
|
|
||||||
|
**PR**: #241 `feat: restore pipe IPC, LAN pipes, monitor tool`
|
||||||
|
**Feature Flag**: `UDS_INBOX`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
同一台机器上的多个 Claude Code 实例通过 UDS（Unix Domain Socket / Windows Named Pipe）自动发现并协作。首个启动的实例成为 main，后续自动注册为 sub。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
|
||||||
|
**启动多实例**：
|
||||||
|
```bash
|
||||||
|
# 终端 1
|
||||||
|
bun run dev
|
||||||
|
# → 自动成为 main
|
||||||
|
|
||||||
|
# 终端 2
|
||||||
|
bun run dev
|
||||||
|
# → 自动成为 sub-1，被 main attach
|
||||||
|
```
|
||||||
|
|
||||||
|
**管理实例**：
|
||||||
|
```
|
||||||
|
/pipes — 显示所有实例，Shift+↓ 展开选择面板
|
||||||
|
/pipes select <name> — 选中实例
|
||||||
|
/pipes all — 全选
|
||||||
|
/pipes none — 取消全选
|
||||||
|
/attach <name> — 手动 attach 某实例
|
||||||
|
/detach <name> — 断开连接
|
||||||
|
/send <name> <msg> — 向指定实例发送消息
|
||||||
|
/claim-main — 强制声明为 main
|
||||||
|
/pipe-status — 显示详细状态
|
||||||
|
/peers — 列出所有已发现的 peer
|
||||||
|
```
|
||||||
|
|
||||||
|
**选择面板操作**：
|
||||||
|
1. 按 `Shift+↓` 展开面板
|
||||||
|
2. `↑/↓` 移动光标
|
||||||
|
3. `Space` 选中/取消 pipe
|
||||||
|
4. `Enter` 确认关闭
|
||||||
|
5. `←/→` 切换路由模式（selected pipes ↔ local main）
|
||||||
|
|
||||||
|
**消息广播**：
|
||||||
|
选中 pipe 后，输入的消息自动路由到所有选中的 slave 执行，结果流式回传到 main。
|
||||||
|
|
||||||
|
**权限转发**：
|
||||||
|
slave 执行需要权限的工具时（如 BashTool），权限请求自动转发到 main 的确认队列。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. LAN Pipes 局域网群控
|
||||||
|
|
||||||
|
**PR**: #241（同上）
|
||||||
|
**Feature Flag**: `LAN_PIPES`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
在 Pipe IPC 基础上增加 TCP 传输层和 UDP Multicast 发现，实现跨机器零配置协作。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
|
||||||
|
**局域网多机器**：
|
||||||
|
```bash
|
||||||
|
# 机器 A (192.168.50.22)
|
||||||
|
bun run dev
|
||||||
|
|
||||||
|
# 机器 B (192.168.50.27)
|
||||||
|
bun run dev
|
||||||
|
|
||||||
|
# 两边启动后 3-5 秒自动发现和 attach
|
||||||
|
# /pipes 显示 [LAN] 标记的远端实例
|
||||||
|
```
|
||||||
|
|
||||||
|
**防火墙配置**（每台机器都需要）：
|
||||||
|
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
macOS：
|
||||||
|
```bash
|
||||||
|
# 首次运行时系统弹对话框，点"允许"即可
|
||||||
|
```
|
||||||
|
|
||||||
|
Linux：
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
|
**通知显示格式**：
|
||||||
|
```
|
||||||
|
# 本机 sub
|
||||||
|
Routed to [sub-1]; main can continue other tasks
|
||||||
|
|
||||||
|
# LAN peer
|
||||||
|
Routed to [main] vmwin11/192.168.50.27; main can continue other tasks
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. Monitor 后台监控
|
||||||
|
|
||||||
|
**PR**: #241（同上）
|
||||||
|
**Feature Flag**: `MONITOR_TOOL`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
在后台运行 shell 命令持续监控输出（类似 `watch` 命令）。AI 也可自主调用 MonitorTool。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
|
||||||
|
**用户命令**：
|
||||||
|
```
|
||||||
|
/monitor tail -f /var/log/syslog
|
||||||
|
/monitor watch -n 5 docker ps
|
||||||
|
/monitor "while true; do curl -s localhost:3000/health; sleep 10; done"
|
||||||
|
```
|
||||||
|
|
||||||
|
**查看监控**：
|
||||||
|
- 按 `Shift+Down` 展开后台任务面板
|
||||||
|
- 查看监控输出和状态
|
||||||
|
|
||||||
|
**Windows 兼容**：
|
||||||
|
`watch -n <sec> <cmd>` 自动转为 PowerShell 循环：
|
||||||
|
```powershell
|
||||||
|
while($true){ <cmd>; Start-Sleep -Seconds <sec> }
|
||||||
|
```
|
||||||
|
|
||||||
|
**AI 调用**：
|
||||||
|
AI 可在对话中自动调用 `MonitorTool` 监控日志、构建输出等。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. Workflow 工作流脚本
|
||||||
|
|
||||||
|
**PR**: #241（同上）
|
||||||
|
**Feature Flag**: `WORKFLOW_SCRIPTS`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
执行 `.claude/workflows/` 目录下的用户定义工作流脚本。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
|
||||||
|
**创建工作流**：
|
||||||
|
```bash
|
||||||
|
mkdir -p .claude/workflows
|
||||||
|
cat > .claude/workflows/deploy.sh << 'EOF'
|
||||||
|
#!/bin/bash
|
||||||
|
echo "Running tests..."
|
||||||
|
bun test
|
||||||
|
echo "Building..."
|
||||||
|
bun run build
|
||||||
|
echo "Deploying..."
|
||||||
|
EOF
|
||||||
|
chmod +x .claude/workflows/deploy.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
**列出可用工作流**：
|
||||||
|
```
|
||||||
|
/workflows
|
||||||
|
```
|
||||||
|
|
||||||
|
**AI 调用**：
|
||||||
|
AI 可通过 `WorkflowTool` 自动执行工作流：
|
||||||
|
```
|
||||||
|
请执行 deploy 工作流
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. Coordinator 多Worker协调
|
||||||
|
|
||||||
|
**PR**: #241（同上）
|
||||||
|
**Feature Flag**: `COORDINATOR_MODE`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
启用 coordinator 模式后，AI 可自动将任务分配给多个 worker 并行执行。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```
|
||||||
|
/coordinator — 切换 coordinator 模式开/关
|
||||||
|
```
|
||||||
|
|
||||||
|
启用后，AI 在处理复杂任务时会：
|
||||||
|
1. 分析任务可并行的部分
|
||||||
|
2. 自动创建 worker 分支
|
||||||
|
3. 分配子任务
|
||||||
|
4. 汇总结果
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 15. Proactive 自主模式
|
||||||
|
|
||||||
|
**PR**: #241（同上）
|
||||||
|
**Feature Flag**: `PROACTIVE` / `KAIROS`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
启用后 AI 会主动发起操作（而不仅回应用户输入），例如自动检测文件变更、主动提出优化建议。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```
|
||||||
|
/proactive — 切换 proactive 模式开/关
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 16. History / Snip 历史管理
|
||||||
|
|
||||||
|
**PR**: #241（同上）
|
||||||
|
**Feature Flag**: `HISTORY_SNIP`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
查看和管理对话历史，支持手动截断以释放上下文窗口空间。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```
|
||||||
|
/history — 显示对话历史摘要
|
||||||
|
/force-snip — 强制在当前位置截断历史
|
||||||
|
```
|
||||||
|
|
||||||
|
AI 也可通过 `SnipTool` 自动截断过长的对话：
|
||||||
|
```
|
||||||
|
对话太长了，请帮我截断历史
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 17. Fork 子Agent
|
||||||
|
|
||||||
|
**PR**: #241（同上）
|
||||||
|
**Feature Flag**: `FORK_SUBAGENT`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
在当前对话上下文中 fork 一个独立的子 agent，继承完整会话状态独立执行。
|
||||||
|
|
||||||
|
### 使用
|
||||||
|
```
|
||||||
|
/fork — 基于当前上下文 fork 子 agent
|
||||||
|
```
|
||||||
|
|
||||||
|
子 agent 会：
|
||||||
|
- 继承当前的全部对话历史
|
||||||
|
- 在独立的执行环境中运行
|
||||||
|
- 不影响主会话状态
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 18. 其他恢复的工具
|
||||||
|
|
||||||
|
以下工具从 stub 恢复为完整实现：
|
||||||
|
|
||||||
|
| 工具 | 说明 | 使用 |
|
||||||
|
|------|------|------|
|
||||||
|
| `SleepTool` | 暂停执行指定时间 | AI 在轮询场景自动调用 |
|
||||||
|
| `WebBrowserTool` | 终端内网页交互 | AI 需要查看网页时调用 |
|
||||||
|
| `SubscribePRTool` | 订阅 GitHub PR 变更 | `/subscribe-pr` 或 AI 调用 |
|
||||||
|
| `PushNotificationTool` | 推送桌面通知 | AI 在长任务完成时调用 |
|
||||||
|
| `CtxInspectTool` | 检查上下文窗口使用 | AI 判断上下文剩余空间 |
|
||||||
|
| `TerminalCaptureTool` | 截取终端屏幕 | AI 需要看终端输出时调用 |
|
||||||
|
| `SendUserFileTool` | 向用户发送文件 | AI 导出文件时调用 |
|
||||||
|
| `REPLTool` | 启动子 REPL 会话 | AI 需要独立交互环境时调用 |
|
||||||
|
| `VerifyPlanExecutionTool` | 验证执行计划完成度 | AI 完成计划后自动验证 |
|
||||||
|
| `SuggestBackgroundPRTool` | 建议创建后台 PR | AI 发现可独立的变更时提议 |
|
||||||
|
| `ListPeersTool` | 列出已发现的 peer | AI 查询多实例状态时调用 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 附录：全部 Feature Flags
|
||||||
|
|
||||||
|
| Flag | 默认 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `BUDDY` | ✅ dev/build | 伴侣系统 |
|
||||||
|
| `BRIDGE_MODE` | ✅ dev/build | 远程控制 |
|
||||||
|
| `VOICE_MODE` | ✅ dev/build | 语音模式 |
|
||||||
|
| `CHICAGO_MCP` | ✅ dev/build | Computer Use + Chrome |
|
||||||
|
| `AGENT_TRIGGERS_REMOTE` | ✅ dev/build | 定时任务 |
|
||||||
|
| `SHOT_STATS` | ✅ dev/build | API 统计 |
|
||||||
|
| `TOKEN_BUDGET` | ✅ dev/build | Token 预算 |
|
||||||
|
| `PROMPT_CACHE_BREAK_DETECTION` | ✅ dev/build | 缓存检测 |
|
||||||
|
| `ULTRAPLAN` | ✅ dev/build | 高级规划 |
|
||||||
|
| `DAEMON` | ✅ dev/build | 后台守护 |
|
||||||
|
| `UDS_INBOX` | ✅ dev/build | Pipe IPC |
|
||||||
|
| `LAN_PIPES` | ✅ dev/build | LAN 群控 |
|
||||||
|
| `MONITOR_TOOL` | ✅ dev/build | 后台监控 |
|
||||||
|
| `WORKFLOW_SCRIPTS` | ✅ dev/build | 工作流脚本 |
|
||||||
|
| `FORK_SUBAGENT` | ✅ dev/build | 子 Agent |
|
||||||
|
| `KAIROS` | ✅ dev/build | Kairos 调度 |
|
||||||
|
| `COORDINATOR_MODE` | ✅ dev/build | 多 Worker |
|
||||||
|
| `HISTORY_SNIP` | ✅ dev/build | 历史管理 |
|
||||||
|
| `CONTEXT_COLLAPSE` | ✅ dev/build | 上下文折叠 |
|
||||||
|
|
||||||
|
手动启用任意 flag：
|
||||||
|
```bash
|
||||||
|
FEATURE_FLAG_NAME=1 bun run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 附录：PR 列表
|
||||||
|
|
||||||
|
| PR | 日期 | 标题 |
|
||||||
|
|----|------|------|
|
||||||
|
| #60 | 2026-04-02 | feat: enable Remote Control (BRIDGE_MODE) |
|
||||||
|
| #82 | 2026-04-03 | refactor(buddy): align companion system |
|
||||||
|
| #88 | 2026-04-03 | feat: enable /schedule (AGENT_TRIGGERS_REMOTE) |
|
||||||
|
| #89 | 2026-04-03 | feat: built-in status line |
|
||||||
|
| #92 | 2026-04-03 | feat: enable /voice mode |
|
||||||
|
| #93 | 2026-04-03 | feat: enable Chrome MCP |
|
||||||
|
| #98 | 2026-04-03 | feat: enable Computer Use (macOS + Windows + Linux) |
|
||||||
|
| #137 | 2026-04-05 | feat: Computer Use v2 — 跨平台 Executor |
|
||||||
|
| #140 | 2026-04-05 | feat: enable SHOT_STATS, TOKEN_BUDGET |
|
||||||
|
| #153 | 2026-04-06 | feat: enable GrowthBook local gate defaults |
|
||||||
|
| #156 | 2026-04-06 | feat: enable /ultraplan |
|
||||||
|
| #170 | 2026-04-07 | feat: restore daemon supervisor |
|
||||||
|
| #241 | 2026-04-11 | feat: restore pipe IPC, LAN pipes, monitor tool |
|
||||||
@@ -1,545 +1,321 @@
|
|||||||
# LAN Pipes 实现文档
|
# LAN Pipes — 技术实现文档
|
||||||
|
|
||||||
## 1. 概述
|
面向开发者的实现细节。用户指南见 [lan-pipes.md](./lan-pipes.md)。
|
||||||
|
|
||||||
### 1.1 目标
|
---
|
||||||
|
|
||||||
在现有 UDS (Unix Domain Socket) 本地 Pipe 通讯系统基础上，增加 **TCP 传输层** 和 **UDP Multicast 发现机制**，使同一局域网内不同机器上的 Claude Code CLI 实例可以：
|
## 架构
|
||||||
|
|
||||||
1. **自动发现** — 通过 UDP multicast 零配置发现 LAN 内的其他实例
|
|
||||||
2. **TCP 连接** — 通过 TCP 建立跨机器的双向 NDJSON 管道
|
|
||||||
3. **复用现有协议** — attach/detach/prompt/stream 等消息类型无需修改
|
|
||||||
|
|
||||||
### 1.2 设计原则
|
|
||||||
|
|
||||||
- **向后兼容**：所有 LAN 功能通过 `feature('LAN_PIPES')` 门控，不影响现有 UDS 功能
|
|
||||||
- **双模式共存**：PipeServer 同时监听 UDS 和 TCP，PipeClient 根据参数自动选择连接模式
|
|
||||||
- **本地优先**：本地 registry 条目优先于 LAN beacon 发现的条目
|
|
||||||
- **安全保守**：TCP 连接需用户显式同意，multicast TTL=1 不跨路由器
|
|
||||||
|
|
||||||
### 1.3 架构总览
|
|
||||||
|
|
||||||
```
|
```
|
||||||
Machine A (192.168.1.10) Machine B (192.168.1.20)
|
Machine A (192.168.50.22) Machine B (192.168.50.27)
|
||||||
┌───────────────────────────┐ ┌───────────────────────────┐
|
┌───────────────────────────┐ ┌───────────────────────────┐
|
||||||
│ PipeServer │ │ PipeServer │
|
│ PipeServer │ │ PipeServer │
|
||||||
│ UDS: cli-abc.sock │ │ UDS: cli-def.sock │
|
│ UDS: ~/.claude/pipes/ │ │ UDS: ~/.claude/pipes/ │
|
||||||
│ TCP: 0.0.0.0:<random> │◄──TCP───►│ TCP: 0.0.0.0:<random> │
|
│ cli-abc.sock │ │ cli-def.sock │
|
||||||
|
│ TCP: 0.0.0.0:<random> │◄──TCP───►│ TCP: 0.0.0.0:<random> │
|
||||||
├───────────────────────────┤ ├───────────────────────────┤
|
├───────────────────────────┤ ├───────────────────────────┤
|
||||||
│ LanBeacon │ │ LanBeacon │
|
│ LanBeacon │ │ LanBeacon │
|
||||||
│ UDP multicast │◄──UDP───►│ UDP multicast │
|
│ UDP 224.0.71.67:7101 │◄──UDP───►│ UDP 224.0.71.67:7101 │
|
||||||
│ 224.0.71.67:7101 │ mcast │ 224.0.71.67:7101 │
|
|
||||||
├───────────────────────────┤ ├───────────────────────────┤
|
├───────────────────────────┤ ├───────────────────────────┤
|
||||||
│ PipeRegistry │ │ PipeRegistry │
|
│ usePipeIpc (hook) │ │ usePipeIpc (hook) │
|
||||||
│ registry.json (local) │ │ registry.json (local) │
|
│ initPipeServer │ │ initPipeServer │
|
||||||
│ + mergeWithLanPeers() │ │ + mergeWithLanPeers() │
|
│ registerMessageHandlers │ │ registerMessageHandlers │
|
||||||
|
│ runMainHeartbeat │ │ runSubHeartbeat │
|
||||||
|
│ cleanupPipeIpc │ │ cleanupPipeIpc │
|
||||||
└───────────────────────────┘ └───────────────────────────┘
|
└───────────────────────────┘ └───────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
## Feature Flag
|
||||||
|
|
||||||
## 2. Feature Flag
|
`LAN_PIPES` — 在 `scripts/dev.ts` 和 `build.ts` 的 `DEFAULT_FEATURES` 中启用。
|
||||||
|
|
||||||
### 2.1 注册
|
所有 LAN 代码路径通过 `feature('LAN_PIPES')` 编译时门控。`feature()` 只能在 `if` 或三元中使用（Bun 编译时常量约束）。
|
||||||
|
|
||||||
**文件**: `scripts/dev.ts` (L49), `build.ts` (L43)
|
|
||||||
|
|
||||||
`LAN_PIPES` 添加到 `DEFAULT_FEATURES` / `DEFAULT_BUILD_FEATURES` 数组中，dev 和 build 默认启用。
|
|
||||||
|
|
||||||
也可通过环境变量 `FEATURE_LAN_PIPES=1` 单独启用。
|
|
||||||
|
|
||||||
### 2.2 使用约束
|
|
||||||
|
|
||||||
Bun 的 `feature()` 只能在 `if` 语句或三元条件中直接使用（编译时常量），不能赋值给变量。所有使用点均遵循此约束。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3. 核心变更详情
|
## 核心文件
|
||||||
|
|
||||||
### 3.1 PipeServer TCP 扩展
|
| 文件 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| `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 注册表 + 消息订阅 |
|
||||||
|
|
||||||
**文件**: `src/utils/pipeTransport.ts`
|
---
|
||||||
|
|
||||||
#### 新增类型
|
## PipeServer TCP 扩展
|
||||||
|
|
||||||
|
`src/utils/pipeTransport.ts`
|
||||||
|
|
||||||
|
### 类型
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
export type PipeTransportMode = 'uds' | 'tcp'
|
export type PipeTransportMode = 'uds' | 'tcp'
|
||||||
export type TcpEndpoint = { host: string; port: number }
|
export type TcpEndpoint = { host: string; port: number }
|
||||||
export type PipeServerOptions = {
|
export type PipeServerOptions = { enableTcp?: boolean; tcpPort?: number }
|
||||||
enableTcp?: boolean
|
|
||||||
tcpPort?: number // 0 = 随机端口
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### PipeServer 类变更
|
### PipeServer 变更
|
||||||
|
|
||||||
| 成员 | 变更类型 | 说明 |
|
- `setupSocket(socket)` — 从 start() 提取的共享方法，UDS 和 TCP 共用
|
||||||
|------|----------|------|
|
- `start(options?)` — 可选启用 TCP，port=0 让 OS 分配
|
||||||
| `tcpServer: Server \| null` | 新增字段 | TCP net.Server 实例 |
|
- 内部维护两个 `net.Server`，共享同一组 `clients: Set<Socket>` 和 `handlers`
|
||||||
| `_tcpAddress: TcpEndpoint \| null` | 新增字段 | TCP 监听地址 |
|
- `tcpAddress` getter 暴露 TCP 端口
|
||||||
| `tcpAddress` getter | 新增 | 公开 TCP 端口信息 |
|
- `close()` 同时关闭两个 server
|
||||||
| `setupSocket(socket)` | 重构提取 | 从 `start()` 中提取，UDS 和 TCP 共用 |
|
|
||||||
| `start(options?)` | 修改签名 | 新增可选 `PipeServerOptions` 参数 |
|
|
||||||
| `startTcpServer(port)` | 新增私有方法 | 启动 TCP 监听 |
|
|
||||||
| `close()` | 修改 | 增加 TCP server 关闭逻辑 |
|
|
||||||
|
|
||||||
**关键设计决策**：`setupSocket()` 方法被提取为共享逻辑，使 UDS 和 TCP 的 socket 处理完全一致。两种传输模式共享同一组 `clients: Set<Socket>` 和 `handlers`，对上层代码完全透明。
|
socket 帧解析使用 `attachNdjsonFramer()` from `ndjsonFramer.ts`（替代原先 3 份重复代码）。
|
||||||
|
|
||||||
#### 代码路径
|
### PipeClient 变更
|
||||||
|
|
||||||
```
|
- 构造函数新增可选 `TcpEndpoint` 参数
|
||||||
start(options?)
|
- `connect()` 根据 tcpEndpoint 分派到 `connectTcp()` 或 `connectUds()`
|
||||||
├── ensurePipesDir()
|
- TCP 不需要文件存在轮询，直接建连
|
||||||
├── 清理 stale socket (Unix)
|
|
||||||
├── createServer() → UDS 监听 (现有逻辑)
|
|
||||||
│ └── setupSocket() ← 提取的共享逻辑
|
|
||||||
└── if options.enableTcp
|
|
||||||
└── startTcpServer(port)
|
|
||||||
├── createServer() → TCP 监听 0.0.0.0
|
|
||||||
│ └── setupSocket() ← 同一个方法
|
|
||||||
└── 记录 _tcpAddress
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.2 PipeClient TCP 扩展
|
|
||||||
|
|
||||||
**文件**: `src/utils/pipeTransport.ts`
|
|
||||||
|
|
||||||
#### PipeClient 类变更
|
|
||||||
|
|
||||||
| 成员 | 变更类型 | 说明 |
|
|
||||||
|------|----------|------|
|
|
||||||
| `tcpEndpoint: TcpEndpoint \| null` | 新增字段 | TCP 连接目标 |
|
|
||||||
| `constructor(target, sender?, tcpEndpoint?)` | 修改签名 | 新增可选 TCP endpoint |
|
|
||||||
| `connect(timeout)` | 修改 | 根据 tcpEndpoint 分派 |
|
|
||||||
| `connectTcp(timeout)` | 新增私有方法 | TCP 连接实现 |
|
|
||||||
| `connectUds(timeout)` | 重构提取 | 原 `connect()` 的 UDS 逻辑 |
|
|
||||||
|
|
||||||
**关键设计决策**：TCP 连接不需要等待文件存在（UDS 的 `access()` 轮询），直接建立 TCP 连接。超时机制相同。
|
|
||||||
|
|
||||||
### 3.3 工厂函数更新
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// 新签名
|
|
||||||
export async function createPipeServer(
|
|
||||||
name: string,
|
|
||||||
options?: PipeServerOptions, // 新增
|
|
||||||
): Promise<PipeServer>
|
|
||||||
|
|
||||||
export async function connectToPipe(
|
|
||||||
targetName: string,
|
|
||||||
senderName?: string,
|
|
||||||
timeoutMs?: number,
|
|
||||||
tcpEndpoint?: TcpEndpoint, // 新增
|
|
||||||
): Promise<PipeClient>
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 3.4 LAN Beacon — UDP Multicast 发现
|
## LAN Beacon
|
||||||
|
|
||||||
**文件**: `src/utils/lanBeacon.ts` (新文件，~170 行)
|
`src/utils/lanBeacon.ts`
|
||||||
|
|
||||||
#### 协议参数
|
### 协议参数
|
||||||
|
|
||||||
| 参数 | 值 | 说明 |
|
| 参数 | 值 |
|
||||||
|------|-----|------|
|
|------|-----|
|
||||||
| Multicast 组 | `224.0.71.67` | "CC" = Claude Code 的 ASCII 对应 |
|
| Multicast 组 | `224.0.71.67` |
|
||||||
| 端口 | `7101` | 固定 UDP 端口 |
|
| 端口 | `7101` |
|
||||||
| 广播间隔 | `3000ms` | 3 秒一次 announce |
|
| 广播间隔 | `3000ms` |
|
||||||
| Peer 超时 | `15000ms` | 15 秒无 announce 视为 lost |
|
| Peer 超时 | `15000ms` |
|
||||||
| TTL | `1` | 仅链路本地，不跨路由器 |
|
| TTL | `1` |
|
||||||
|
|
||||||
#### Announce 包格式
|
### Announce 包
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
type LanAnnounce = {
|
type LanAnnounce = {
|
||||||
proto: 'claude-pipe-v1' // 协议标识符（用于过滤非本协议 UDP 包）
|
proto: 'claude-pipe-v1'
|
||||||
pipeName: string // e.g. "cli-abc12345"
|
pipeName: string
|
||||||
machineId: string // OS-level 稳定指纹
|
machineId: string
|
||||||
hostname: string // 主机名
|
hostname: string
|
||||||
ip: string // 发送端本地 IPv4
|
ip: string
|
||||||
tcpPort: number // TCP PipeServer 端口
|
tcpPort: number
|
||||||
role: 'main' | 'sub' // 当前角色
|
role: 'main' | 'sub'
|
||||||
ts: number // unix ms 时间戳
|
ts: number
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
#### LanBeacon 类 API
|
### API
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
class LanBeacon extends EventEmitter {
|
class LanBeacon extends EventEmitter {
|
||||||
constructor(announce: Omit<LanAnnounce, 'proto' | 'ts'>)
|
constructor(announce: Omit<LanAnnounce, 'proto' | 'ts'>)
|
||||||
start(): void // 开始广播 + 监听
|
start(): void
|
||||||
stop(): void // 停止并释放资源
|
stop(): void
|
||||||
getPeers(): Map<string, LanAnnounce> // 当前已知 peers
|
getPeers(): Map<string, LanAnnounce> // 防御性拷贝
|
||||||
updateAnnounce(partial): void // 更新自身 announce 数据
|
updateAnnounce(partial): void // 使用 spread（不可变更新）
|
||||||
|
|
||||||
// Events
|
|
||||||
on('peer-discovered', (peer: LanAnnounce) => void)
|
on('peer-discovered', (peer: LanAnnounce) => void)
|
||||||
on('peer-lost', (pipeName: string) => void)
|
on('peer-lost', (pipeName: string) => void)
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 内部行为
|
### 存储
|
||||||
|
|
||||||
1. **启动**：`createSocket({ type: 'udp4', reuseAddr: true })` → `bind(7101)` → `addMembership('224.0.71.67')` → `setMulticastTTL(1)`
|
module-level singleton：`getLanBeacon()` / `setLanBeacon()`。不挂在 Zustand state 上（避免 `setState` 展开时丢失引用）。
|
||||||
2. **广播**：`setInterval(sendAnnounce, 3000)` + 启动时立即发一次
|
|
||||||
3. **接收**：`socket.on('message')` → JSON.parse → 过滤 `proto !== 'claude-pipe-v1'` 和自身 → 更新 peers Map → 触发 `peer-discovered` 事件
|
|
||||||
4. **清理**：`setInterval(cleanupStalePeers, 7500)` — 超过 15 秒未收到 announce 的 peer 从 Map 移除，触发 `peer-lost` 事件
|
|
||||||
5. **停止**：清除所有 timer → `dropMembership` → `socket.close()` → 清空 peers
|
|
||||||
|
|
||||||
#### 错误处理
|
### 网卡绑定
|
||||||
|
|
||||||
所有 socket/网络错误均为 **non-fatal**（logError 但不 throw）。multicast 在某些网络环境可能不支持，这不应阻止 CLI 正常运行。
|
`addMembership(group, localIp)` + `setMulticastInterface(localIp)` 指定 LAN 网卡。解决 Windows 上 WSL/Docker 虚拟网卡劫持 multicast 的问题。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 3.5 Registry 扩展
|
## Hook 架构
|
||||||
|
|
||||||
**文件**: `src/utils/pipeRegistry.ts`
|
从 REPL.tsx 提取的 ~830 行 Pipe IPC 代码：
|
||||||
|
|
||||||
#### 类型变更
|
### usePipeIpc（生命周期）
|
||||||
|
|
||||||
|
`src/hooks/usePipeIpc.ts`（623 行）
|
||||||
|
|
||||||
|
在 REPL.tsx 顶层通过 feature-gated require 加载：
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
export interface PipeRegistryEntry {
|
const usePipeIpc = feature('UDS_INBOX')
|
||||||
// ... 现有字段 ...
|
? require('../hooks/usePipeIpc.js').usePipeIpc
|
||||||
tcpPort?: number // 新增：TCP 监听端口
|
: () => undefined;
|
||||||
lanVisible?: boolean // 新增：是否参与 LAN 广播
|
|
||||||
}
|
// 组件内
|
||||||
|
usePipeIpc({ store, handleIncomingPrompt });
|
||||||
```
|
```
|
||||||
|
|
||||||
#### 新增函数
|
内部使用 **lazy getter** 函数加载依赖（避免循环依赖导致 Bun 运行时崩溃）：
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
export type MergedPipeEntry = {
|
const pt = () => require('../utils/pipeTransport.js')
|
||||||
id: string
|
const pr = () => require('../utils/pipeRegistry.js')
|
||||||
pipeName: string
|
const mm = () => require('./useMasterMonitor.js')
|
||||||
role: string
|
// ...
|
||||||
machineId: string
|
|
||||||
ip: string
|
|
||||||
hostname: string
|
|
||||||
alive: boolean
|
|
||||||
source: 'local' | 'lan' // 来源标识
|
|
||||||
tcpEndpoint?: TcpEndpoint // LAN peer 的 TCP 端点
|
|
||||||
}
|
|
||||||
|
|
||||||
export function mergeWithLanPeers(
|
|
||||||
registry: PipeRegistry,
|
|
||||||
lanPeers: Map<string, LanAnnounce>,
|
|
||||||
): MergedPipeEntry[]
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**合并逻辑**：
|
`import type` 用于静态类型（不会触发模块加载）。
|
||||||
1. 先添加本地 registry 的 main 和所有 subs（`source: 'local'`）
|
|
||||||
2. 遍历 LAN peers，跳过已在本地 registry 中存在的 pipeName
|
### 四个阶段函数
|
||||||
3. 剩余的 LAN peers 作为 `source: 'lan'` 条目添加
|
|
||||||
|
| 函数 | 职责 |
|
||||||
|
|------|------|
|
||||||
|
| `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]`（本机）。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 3.6 Peer Address 扩展
|
## Registry 并行探测
|
||||||
|
|
||||||
**文件**: `src/utils/peerAddress.ts`
|
`src/utils/pipeRegistry.ts`
|
||||||
|
|
||||||
#### parseAddress 变更
|
### getAliveSubs()
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
// 之前
|
export async function getAliveSubs(): Promise<PipeRegistrySub[]> {
|
||||||
export function parseAddress(to: string): {
|
const registry = await readRegistry()
|
||||||
scheme: 'uds' | 'bridge' | 'other'
|
const results = await Promise.all(
|
||||||
target: string
|
registry.subs.map(sub =>
|
||||||
}
|
isPipeAlive(sub.pipeName, 1000).then(alive => alive ? sub : null)
|
||||||
|
)
|
||||||
// 之后
|
)
|
||||||
export function parseAddress(to: string): {
|
return results.filter(Boolean)
|
||||||
scheme: 'uds' | 'bridge' | 'tcp' | 'other' // 新增 'tcp'
|
|
||||||
target: string
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
新增 `tcp:` 前缀解析：`tcp:192.168.1.20:7100` → `{ scheme: 'tcp', target: '192.168.1.20:7100' }`
|
### cleanupStaleEntries()
|
||||||
|
|
||||||
#### 新增 parseTcpTarget
|
两阶段：
|
||||||
|
1. **无锁并行探测**：`Promise.all` 探测 main + 所有 subs
|
||||||
|
2. **短暂持锁写入**：`acquireLock()` → 重新读取 → 应用变更 → 写入 → `releaseLock()`
|
||||||
|
|
||||||
```typescript
|
持锁时间从 N 秒降至 ~10ms。
|
||||||
export function parseTcpTarget(
|
|
||||||
target: string,
|
|
||||||
): { host: string; port: number } | null
|
|
||||||
```
|
|
||||||
|
|
||||||
解析 `host:port` 字符串，正则 `^([^:]+):(\d+)$`。
|
### getMachineId()
|
||||||
|
|
||||||
|
Windows/macOS 使用 `execFile`（异步），不阻塞主线程。结果缓存，仅首次调用执行。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 3.7 REPL Bootstrap 集成
|
## NDJSON 协议
|
||||||
|
|
||||||
**文件**: `src/screens/REPL.tsx`
|
### 消息类型
|
||||||
|
|
||||||
#### 启动阶段 (L5165-5200)
|
| 类型 | 方向 | 数据 |
|
||||||
|
|------|------|------|
|
||||||
|
| `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 })` |
|
||||||
|
|
||||||
在现有 `createPipeServer(pipeName)` 调用处：
|
### 帧格式
|
||||||
|
|
||||||
```typescript
|
每行一个 JSON 对象，`\n` 分隔：
|
||||||
// 根据 LAN_PIPES flag 决定是否启用 TCP
|
|
||||||
const server = await createPipeServer(
|
|
||||||
pipeName,
|
|
||||||
feature('LAN_PIPES') ? { enableTcp: true, tcpPort: 0 } : undefined
|
|
||||||
);
|
|
||||||
|
|
||||||
// 启动 LAN beacon
|
|
||||||
if (feature('LAN_PIPES') && server.tcpAddress) {
|
|
||||||
const { LanBeacon } = require('../utils/lanBeacon.js');
|
|
||||||
lanBeaconInstance = new LanBeacon({
|
|
||||||
pipeName, machineId, hostname, ip, tcpPort: server.tcpAddress.port, role
|
|
||||||
});
|
|
||||||
lanBeaconInstance.start();
|
|
||||||
|
|
||||||
// Store beacon in module-level singleton (not on Zustand state)
|
|
||||||
const { setLanBeacon } = require('../utils/lanBeacon.js');
|
|
||||||
setLanBeacon(lanBeaconInstance);
|
|
||||||
|
|
||||||
// 注册 entry 时附带 tcpPort
|
|
||||||
await registerAsMain({ ...entry, tcpPort: server.tcpAddress.port, lanVisible: true });
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
{"type":"ping","from":"cli-abc","ts":"2026-04-11T00:00:00.000Z"}\n
|
||||||
#### Heartbeat <20><>段
|
{"type":"prompt","data":"检查 git status","from":"cli-abc"}\n
|
||||||
|
|
||||||
在 main heartbeat 循环中：
|
|
||||||
|
|
||||||
1. `refreshDiscoveredPipes(aliveSubs)` 同时包含本地 subs 和 LAN beacon peers
|
|
||||||
2. auto-attach 循环同时遍历本地 subs 和 LAN peers（LAN peers 通过 TCP endpoint 连接）
|
|
||||||
3. cleanup 时检查 LAN beacon peers 列表，避免误删 LAN 连接
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// auto-attach 统一目标列表：本地 subs + LAN peers
|
|
||||||
const attachTargets = [...aliveSubs.map(s => ({ pipeName: s.pipeName }))];
|
|
||||||
if (feature('LAN_PIPES')) {
|
|
||||||
const beacon = getLanBeacon();
|
|
||||||
for (const [name, peer] of beacon.getPeers()) {
|
|
||||||
attachTargets.push({ pipeName: name, tcpEndpoint: { host: peer.ip, port: peer.tcpPort } });
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Cleanup 阶段
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// 停止 LAN beacon
|
|
||||||
const { getLanBeacon, setLanBeacon } = require('../utils/lanBeacon.js');
|
|
||||||
const beacon = getLanBeacon();
|
|
||||||
if (beacon) {
|
|
||||||
try { beacon.stop(); } catch {}
|
|
||||||
setLanBeacon(null);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Beacon 存储方案**：使用 `lanBeacon.ts` 中的 module-level singleton（`getLanBeacon()`/`setLanBeacon()`），不挂在 Zustand store state 上，避免 `setState` 展开时丢失引用。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3.8 /pipes 命令 LAN 显示
|
|
||||||
|
|
||||||
**文件**: `src/commands/pipes/pipes.ts`
|
|
||||||
|
|
||||||
在现有 registry 显示之后，如果 `feature('LAN_PIPES')` 启用：
|
|
||||||
|
|
||||||
1. 通过 `getLanBeacon()` 获取 LAN peers
|
|
||||||
2. 调用 `mergeWithLanPeers()` 合并
|
|
||||||
3. 过滤 `source === 'lan'` 的条目
|
|
||||||
4. 显示格式：`☐ [role] pipeName hostname/ip tcp:host:port [LAN]`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3.9 /attach 命令 TCP 支持
|
|
||||||
|
|
||||||
**文件**: `src/commands/attach/attach.ts`
|
|
||||||
|
|
||||||
在连接之前，如果 `feature('LAN_PIPES')` 启用：
|
|
||||||
|
|
||||||
1. 在 `discoveredPipes` 中查找目标 pipe
|
|
||||||
2. 通过 `_lanBeacon.getPeers()` 检查是否为 LAN peer
|
|
||||||
3. 如果是，构造 `TcpEndpoint` 传给 `connectToPipe()`
|
|
||||||
4. 错误消息中包含 TCP 端点信息便于诊断
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3.10 SendMessageTool TCP 支持
|
|
||||||
|
|
||||||
**文件**: `src/tools/SendMessageTool/SendMessageTool.ts`
|
|
||||||
|
|
||||||
#### inputSchema 描述更新
|
|
||||||
|
|
||||||
当 `LAN_PIPES` 启用时，`to` 字段描述追加 `, or "tcp:<host>:<port>" for a LAN peer`。
|
|
||||||
|
|
||||||
#### checkPermissions
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
if (feature('LAN_PIPES') && parseAddress(input.to).scheme === 'tcp') {
|
|
||||||
return {
|
|
||||||
behavior: 'ask',
|
|
||||||
message: `Send a message to LAN peer ${input.to}?...`,
|
|
||||||
decisionReason: {
|
|
||||||
type: 'safetyCheck',
|
|
||||||
reason: 'Cross-machine LAN message requires explicit user consent',
|
|
||||||
classifierApprovable: false,
|
|
||||||
},
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**安全设计**：`classifierApprovable: false` 确保自动模式不会跳过用户确认。
|
|
||||||
|
|
||||||
#### validateInput
|
|
||||||
|
|
||||||
新增 `tcp:` scheme 验证分支（与 `uds:` 类似，仅允许 plain text 消息）。
|
|
||||||
|
|
||||||
#### call()
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
if (addr.scheme === 'tcp' && feature('LAN_PIPES')) {
|
|
||||||
const ep = parseTcpTarget(addr.target);
|
|
||||||
const client = new PipeClient(input.to, `send-${process.pid}`, ep);
|
|
||||||
await client.connect(5000);
|
|
||||||
client.send({ type: 'chat', data: input.message });
|
|
||||||
client.disconnect();
|
|
||||||
return { data: { success: true, message: `... → TCP ${ep.host}:${ep.port}` } };
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 4. 数据流
|
## 跨机器 Attach 流程
|
||||||
|
|
||||||
### 4.1 LAN 发现流程
|
|
||||||
|
|
||||||
```
|
```
|
||||||
CLI-A 启动
|
CLI-B (192.168.50.27) 心跳循环
|
||||||
→ PipeServer.start({ enableTcp: true, tcpPort: 0 })
|
→ beacon.getPeers() 发现 CLI-A (192.168.50.22)
|
||||||
→ TCP server 监听 0.0.0.0:随机端口
|
→ connectToPipe(pName, myName, 3000, { host: '192.168.50.22', port: 58853 })
|
||||||
→ LanBeacon.start()
|
|
||||||
→ 每 3s 广播 UDP announce (pipeName, ip, tcpPort, role, machineId)
|
|
||||||
|
|
||||||
CLI-B 启动 (另一台机器)
|
|
||||||
→ 同上
|
|
||||||
→ LanBeacon 收到 CLI-A 的 announce
|
|
||||||
→ peer-discovered 事件
|
|
||||||
→ Heartbeat 循环合并 LAN peers 到 discoveredPipes
|
|
||||||
|
|
||||||
用户在 CLI-B 执行 /pipes
|
|
||||||
→ 显示 CLI-A 条目，标记 [LAN]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4.2 跨机器 Attach 流程
|
|
||||||
|
|
||||||
```
|
|
||||||
CLI-B 执行 /attach cli-abc12345
|
|
||||||
→ feature('LAN_PIPES') → 查找 discoveredPipes → 找到 LAN peer
|
|
||||||
→ _lanBeacon.getPeers() → 获取 { ip: '192.168.1.10', tcpPort: 7100 }
|
|
||||||
→ connectToPipe(name, myName, undefined, { host: '192.168.1.10', port: 7100 })
|
|
||||||
→ PipeClient.connectTcp() → net.createConnection({ host, port })
|
→ PipeClient.connectTcp() → net.createConnection({ host, port })
|
||||||
→ client.send({ type: 'attach_request' })
|
→ client.send({ type: 'attach_request', meta: { machineId } })
|
||||||
→ 等待 attach_accept / attach_reject
|
→ CLI-A 收到：
|
||||||
→ 成功：注册 slave client，切换 master 角色
|
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' }
|
||||||
```
|
```
|
||||||
|
|
||||||
### 4.3 跨机器消息发送
|
关键：跨机器 attach 不要求对方是 sub 角色。通过 `machineId` 区分 LAN peer。
|
||||||
|
|
||||||
```
|
|
||||||
用户或 AI 使用 SendMessageTool
|
|
||||||
→ to: "tcp:192.168.1.20:7102"
|
|
||||||
→ checkPermissions → behavior: 'ask' → 用户确认
|
|
||||||
→ parseTcpTarget('192.168.1.20:7102') → { host, port }
|
|
||||||
→ new PipeClient(to, sender, { host, port })
|
|
||||||
→ client.connect(5000)
|
|
||||||
→ client.send({ type: 'chat', data: message })
|
|
||||||
→ client.disconnect()
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 5. 测试
|
## SendMessageTool TCP 支持
|
||||||
|
|
||||||
### 5.1 新增测试文件
|
`src/tools/SendMessageTool/SendMessageTool.ts`
|
||||||
|
|
||||||
| 文件 | 测试数 | 覆盖内容 |
|
- `to` 字段支持 `tcp:host:port` 格式
|
||||||
|------|--------|----------|
|
- `checkPermissions`：`tcp:` scheme 返回 `behavior: 'ask'`，`classifierApprovable: false`
|
||||||
| `src/utils/__tests__/lanBeacon.test.ts` | 7 | socket 初始化、announce 发送、peer 发现、自身过滤、协议过滤、role 更新 |
|
- `call()`：创建临时 `PipeClient` → connect → send → disconnect
|
||||||
| `src/utils/__tests__/peerAddress.test.ts` | 8 | uds/bridge/tcp/other scheme 解析、parseTcpTarget 正确/异常 |
|
|
||||||
|
|
||||||
### 5.2 测试策略
|
|
||||||
|
|
||||||
- **lanBeacon.test.ts**：mock dgram 模块，验证 beacon 的发送/接收/清理逻辑
|
|
||||||
- **peerAddress.test.ts**：纯函数测试，无外部依赖
|
|
||||||
- **现有 pipeTransport.test.ts**：2 个现有测试继续通过（TCP 扩展不改变 UDS 行为）
|
|
||||||
|
|
||||||
### 5.3 测试结果
|
|
||||||
|
|
||||||
```
|
|
||||||
全量测试：2190 pass / 0 fail / 130 files / 4.27s
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 6. 变更文件清单
|
## 测试
|
||||||
|
|
||||||
| 文件 | 操作 | 变更行数(约) |
|
| 文件 | 测试数 | 覆盖 |
|
||||||
|------|------|-------------|
|
|------|--------|------|
|
||||||
| `scripts/dev.ts` | 修改 | +1 (feature flag) |
|
| `lanBeacon.test.ts` | 7 | socket 初始化、announce、peer 发现/过滤/清理 |
|
||||||
| `build.ts` | 修改 | +1 (feature flag) |
|
| `peerAddress.test.ts` | 8 | scheme 解析、parseTcpTarget、端口范围验证 |
|
||||||
| `src/utils/pipeTransport.ts` | 修改 | +120 (TCP 扩展) |
|
| `pipePermissionRelay.test.ts` | 2 | setPipeRelay singleton、权限请求/响应 |
|
||||||
| `src/utils/lanBeacon.ts` | **新增** | ~170 (UDP beacon) |
|
| `pipeTransport.test.ts` | 2 | UDS 基础行为 |
|
||||||
| `src/utils/pipeRegistry.ts` | 修改 | +80 (类型 + merge 函数) |
|
| `useMasterMonitor.test.ts` | 5 | slave 注册/移除、事件发射 |
|
||||||
| `src/utils/peerAddress.ts` | 修改 | +12 (tcp scheme + parseTcpTarget) |
|
|
||||||
| `src/screens/REPL.tsx` | 修改 | +45 (bootstrap + heartbeat + cleanup) |
|
全量：2190 pass / 0 fail
|
||||||
| `src/commands/pipes/pipes.ts` | 修改 | +25 (LAN peers 显示) |
|
|
||||||
| `src/commands/attach/attach.ts` | 修改 | +25 (TCP endpoint 解析) |
|
|
||||||
| `src/tools/SendMessageTool/SendMessageTool.ts` | 修改 | +45 (tcp scheme 全链路) |
|
|
||||||
| `src/utils/__tests__/lanBeacon.test.ts` | **新增** | ~140 (7 tests) |
|
|
||||||
| `src/utils/__tests__/peerAddress.test.ts` | **新增** | ~60 (8 tests) |
|
|
||||||
| `docs/features/lan-pipes.md` | **新增** | ~90 (用户文档) |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 7. 已知限制和后续改进
|
## 已知限制
|
||||||
|
|
||||||
### 7.1 当前限制
|
1. **TCP 无认证** — 同 LAN 内知道端口号即可连接
|
||||||
|
2. **Beacon 明文广播** — IP/hostname/machineId 未 hash
|
||||||
|
3. **单网卡选择** — `getLocalIp()` 返回首个非内部 IPv4，可能选到 VPN
|
||||||
|
4. **端口随机** — 每次启动不同端口，依赖 beacon 发现
|
||||||
|
5. **SendMessageTool 每次创建新连接** — 未复用已有 slave client
|
||||||
|
|
||||||
1. **无 TCP 认证**：TCP 连接无握手认证，同一局域网内任何知道端口号的进程都能连接
|
## 后续改进方向
|
||||||
2. **beacon ref 通过 `(state as any)._lanBeacon` 传递**：这是一个 pragmatic hack，因为 AppState 类型由 decompiled 代码定义，修改类型的成本过高
|
|
||||||
3. **multicast 依赖网络环境**：部分企业网络、AP 隔离的 WiFi 可能不支持 multicast
|
|
||||||
4. **TCP 端口随机**：每次启动分配不同端口，需依赖 beacon 发现
|
|
||||||
|
|
||||||
### 7.2 后续改进方向
|
1. HMAC-SHA256 TCP 握手认证
|
||||||
|
2. machineId hash 后再广播
|
||||||
1. **HMAC-SHA256 认证**：首次 TCP 握手交换 machineId + challenge token
|
3. 多网卡选择（优先 RFC 1918 地址）
|
||||||
2. **heartbeat 中 TCP auto-attach LAN peers**：目前 heartbeat 只 auto-attach 本地 registry 的 subs，LAN peers 需手动 /attach
|
4. 固定端口范围配置
|
||||||
3. **固定端口范围配置**：允许用户配置 TCP 端口范围，便于防火墙规则
|
5. TLS 加密传输
|
||||||
4. **mDNS/DNS-SD 作为 beacon 替代**：在 multicast 受限的环境提供更可靠的发现
|
6. SendMessageTool 复用已连接的 slave client
|
||||||
5. **加密传输**：TLS over TCP，确保消息不被中间人窃听
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 防火墙要求
|
|
||||||
|
|
||||||
| 协议 | 端口 | 方向 | 用途 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| UDP | 7101 | IN + OUT | Multicast beacon 发现 |
|
|
||||||
| TCP | 动态 (0) | IN | PipeServer TCP 监听 |
|
|
||||||
|
|
||||||
### Windows
|
|
||||||
|
|
||||||
```powershell
|
|
||||||
netsh advfirewall firewall add rule name="Claude LAN Beacon" dir=in action=allow protocol=UDP localport=7101
|
|
||||||
netsh advfirewall firewall add rule name="Claude LAN Pipes" dir=in action=allow program="<bun路径>" enable=yes
|
|
||||||
```
|
|
||||||
|
|
||||||
### macOS
|
|
||||||
|
|
||||||
首次运行时系统弹窗允许即可。
|
|
||||||
|
|
||||||
### Linux
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo firewall-cmd --add-port=7101/udp
|
|
||||||
# TCP 端口随机，建议放行 bun 进程
|
|
||||||
```
|
|
||||||
|
|||||||
@@ -1,86 +1,193 @@
|
|||||||
# LAN Pipes — 局域网跨机器通讯
|
# LAN Pipes — 局域网多机器群控指南
|
||||||
|
|
||||||
## 概述
|
## 什么是 LAN Pipes
|
||||||
|
|
||||||
在现有 UDS (Unix Domain Socket) 本地 Pipe 通讯基础上，增加 TCP 传输层和 UDP Multicast 发现机制，使同一局域网内不同机器上的 Claude Code 实例可以互相发现、连接和双向通讯。
|
LAN Pipes 让多台机器上的 Claude Code 实例通过局域网自动发现并协作。你可以在一台机器（main）上操控其他机器（sub）上的 Claude Code，发送 prompt、查看执行结果、审批权限请求——全程零配置。
|
||||||
|
|
||||||
## Feature Flag
|
基于本机 Pipe IPC（`UDS_INBOX`）扩展，新增 TCP 传输层 + UDP Multicast 发现。
|
||||||
|
|
||||||
`LAN_PIPES` — dev/build 默认启用。也可通过 `FEATURE_LAN_PIPES=1` 环境变量启用。
|
## 前置条件
|
||||||
|
|
||||||
## 架构
|
- 两台或以上机器在同一局域网
|
||||||
|
- 每台机器安装了 CCB 并能 `bun run dev`
|
||||||
|
- Feature flag `LAN_PIPES`（dev/build 默认开启）
|
||||||
|
- 防火墙允许 UDP 7101 + TCP 动态端口（见下方配置）
|
||||||
|
|
||||||
```
|
## 快速开始
|
||||||
Machine A (192.168.1.10) Machine B (192.168.1.20)
|
|
||||||
┌─────────────────────────┐ ┌─────────────────────────┐
|
### 第一步：配置防火墙
|
||||||
│ PipeServer │ │ PipeServer │
|
|
||||||
│ UDS: cli-abc.sock │ │ UDS: cli-def.sock │
|
**每台机器都需要执行。**
|
||||||
│ TCP: 0.0.0.0:7100 │◄─TCP────►│ TCP: 0.0.0.0:7102 │
|
|
||||||
├─────────────────────────┤ ├─────────────────────────┤
|
**Windows**（管理员 PowerShell）：
|
||||||
│ LanBeacon │◄─UDP─────│ LanBeacon │
|
```powershell
|
||||||
│ multicast 224.0.71.67 │ mcast ►│ multicast 224.0.71.67 │
|
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`
|
||||||
|
|
||||||
### 1. PipeServer TCP 扩展 (`pipeTransport.ts`)
|
**macOS**：
|
||||||
|
首次运行时系统弹出"允许接受传入连接"对话框，点击"允许"。
|
||||||
|
|
||||||
- `PipeServer.start()` 接受 `PipeServerOptions`，可选启用 TCP 监听
|
如果使用 pf 防火墙：
|
||||||
- 内部维护两个 `net.Server` — UDS + TCP，共享同一组 clients 和 handlers
|
```bash
|
||||||
- `PipeServer.tcpAddress` getter 返回 TCP 端口信息
|
echo "pass in proto udp from any to any port 7101" | sudo pfctl -ef -
|
||||||
|
```
|
||||||
|
|
||||||
### 2. PipeClient TCP 扩展 (`pipeTransport.ts`)
|
**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
|
||||||
|
```
|
||||||
|
|
||||||
- 构造函数新增可选 `TcpEndpoint` 参数
|
**Linux**（iptables）：
|
||||||
- `connect()` 根据是否有 TCP endpoint 选择连接模式
|
```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
|
||||||
|
```
|
||||||
|
|
||||||
### 3. LAN Beacon (`lanBeacon.ts`)
|
### 第二步：启动
|
||||||
|
|
||||||
- UDP multicast 组: `224.0.71.67:7101`
|
```bash
|
||||||
- 每 3 秒广播 announce 包，包含 pipeName、machineId、hostname、ip、tcpPort、role
|
# 机器 A（例如 192.168.50.22）
|
||||||
- 15 秒无 announce 视为 peer lost
|
bun run dev
|
||||||
- TTL=1，仅 link-local，不跨路由器
|
|
||||||
|
|
||||||
### 4. Registry 扩展 (`pipeRegistry.ts`)
|
# 机器 B（例如 192.168.50.27）
|
||||||
|
bun run dev
|
||||||
|
```
|
||||||
|
|
||||||
- `PipeRegistryEntry` 新增 `tcpPort?` 和 `lanVisible?` 字段
|
启动后等待 3-5 秒（beacon 广播间隔），两边自动发现并连接。
|
||||||
- `mergeWithLanPeers()` 合并本地 registry 和 LAN beacon 发现的远端 peers
|
|
||||||
|
|
||||||
### 5. Peer Address (`peerAddress.ts`)
|
### 第三步：查看和操作
|
||||||
|
|
||||||
- `parseAddress()` 新增 `tcp` scheme: `tcp:192.168.1.20:7100`
|
|
||||||
- `parseTcpTarget()` 解析 `host:port` 字符串
|
|
||||||
|
|
||||||
## 使用方式
|
|
||||||
|
|
||||||
### 查看 LAN Peers
|
|
||||||
|
|
||||||
|
在任一台机器上：
|
||||||
```
|
```
|
||||||
/pipes
|
/pipes
|
||||||
```
|
```
|
||||||
|
|
||||||
输出中会显示 `[LAN]` 标记的远端实例。
|
输出示例：
|
||||||
|
|
||||||
### 连接远端实例
|
|
||||||
|
|
||||||
```
|
```
|
||||||
/attach <pipe-name>
|
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]
|
||||||
```
|
```
|
||||||
|
|
||||||
自动检测 LAN peer 并通过 TCP 连接。
|
### 第四步：选中目标并发送任务
|
||||||
|
|
||||||
### 发送消息到 LAN Peer
|
1. 按 `Shift+↓` 展开选择面板
|
||||||
|
2. `↑↓` 移动到 LAN peer
|
||||||
|
3. `Space` 选中
|
||||||
|
4. `Enter` 确认
|
||||||
|
5. 输入 prompt，自动路由到远端执行
|
||||||
|
|
||||||
|
远端执行结果会流式回传到你的消息列表：
|
||||||
```
|
```
|
||||||
/send tcp:192.168.1.20:7100 <message>
|
[main vmwin11/192.168.50.27 / cli-04d67950] 正在检查 git status...
|
||||||
|
[main vmwin11/192.168.50.27 / cli-04d67950] Completed
|
||||||
```
|
```
|
||||||
|
|
||||||
或通过 SendMessage tool 使用 `tcp:` scheme。
|
## 完整命令参考
|
||||||
|
|
||||||
## 安全
|
| 命令 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| `/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 |
|
||||||
|
|
||||||
- TCP 连接需用户显式同意（checkPermissions 返回 `ask`）
|
## 快捷键
|
||||||
- Multicast TTL=1，仅限链路本地
|
|
||||||
- 后续可增加 HMAC-SHA256 challenge 认证
|
| 快捷键 | 场景 | 作用 |
|
||||||
|
|--------|------|------|
|
||||||
|
| `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:` 消息时需**用户显式确认**
|
||||||
|
- 建议仅在信任的局域网中使用
|
||||||
|
|||||||
Reference in New Issue
Block a user