多实例群控

这是什么

Pipes 系统提供 qsdashi CLI 实例之间的通讯能力，分两层，但共用同一套 NDJSON 协议与同一套命令：

• Pipe IPC（本机）：同一台机器上的多个实例通过 UDS（Unix Domain Socket / Windows Named Pipe）协作。首个启动的实例注册为 main，后续实例成为 sub 并被 main 自动 attach。
• LAN Pipes（局域网）：在 Pipe IPC 基础上扩展 TCP 传输层 + UDP Multicast 发现。 不同机器上的实例自动发现并互相 attach，跨机器时两边都可以是 main。

角色模型：

选中目标实例后，在输入框正常输入普通 prompt 即可自动路由到远端执行；每个目标独立执行， 结果以 stream / done 流式回传到你的消息列表。当远端实例执行需要权限的 工具（如 BashTool）时，权限请求会转发回 master 弹出确认对话框。

前置条件

安装启用

1. 启用特性 flag

   dev 模式在启动命令前注入两个 FEATURE_ 变量：

   Terminal 复制

   # 本机 + 局域网管道
   FEATURE_UDS_INBOX=1 FEATURE_LAN_PIPES=1 bun run dev
   
   # build 产物：特性在编译期决定，需要带上变量重新构建
   FEATURE_UDS_INBOX=1 FEATURE_LAN_PIPES=1 bun run build

2. （LAN）配置防火墙

   每台机器都需要放行组播 beacon 与动态 TCP。Windows 管理员 PowerShell：

   Windows PowerShell（管理员） 复制

   New-NetFirewallRule -DisplayName "QSM LAN Beacon (UDP)" -Direction Inbound -Protocol UDP -LocalPort 7101 -Action Allow -Profile Private
   New-NetFirewallRule -DisplayName "QSM LAN Pipes (TCP)" -Direction Inbound -Protocol TCP -LocalPort 1024-65535 -Program (Get-Command bun).Source -Action Allow -Profile Private
   New-NetFirewallRule -DisplayName "QSM LAN Beacon Out (UDP)" -Direction Outbound -Protocol UDP -RemotePort 7101 -Action Allow -Profile Private
   # 确认网络为「专用」
   Get-NetConnectionProfile

   Linux / macOS 等价配置：

   Linux / macOS 复制

   # Linux（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
   
   # macOS：首次运行弹出「允许接受传入连接」对话框，点允许即可

3. 启动多个实例

   本机场景：终端 1 启动即为 main，终端 2 启动即自动成为 sub-1 并被 main attach。LAN 场景：两台机器各自启动，等待 3-5 秒（beacon 广播间隔） 后自动发现并互相 attach。

4. 查看并选择目标

   在任一台机器执行 /pipes 打开状态栏与选择面板，选中目标后输入 prompt 即自动路由。 详见「常用命令与参数」。

配置

特性与环境变量：

LAN beacon 协议参数（源码常量，不可配置）：

存储位置：

常用命令与参数

斜杠命令：

选择面板快捷键：

两种路由模式（切换不会清空选择）：

实战示例

本机多实例：把任务甩给 sub 执行

# 终端 1：启动，自动成为 main；终端 2：启动，自动成为 sub-1 并被 attach
/pipes
# → 状态栏出现，列出 main 与 sub-1

# 展开面板并选中 sub-1
# Shift+↓ 展开 → ↓ 移动 → Space 选中 → Enter 确认

# 直接输入普通 prompt，自动路由到 sub-1 执行
帮我检查一下 git status

# 状态栏 ←/→ 或展开后 M 切到 local main，输入只在本地执行
# 再切回 selected pipes only 继续向远端发送

LAN 跨机器：零配置发现

# 机器 A（192.168.50.22）与机器 B（192.168.50.27）分别启动
FEATURE_UDS_INBOX=1 FEATURE_LAN_PIPES=1 bun run dev

# 等待 3-5 秒 beacon 广播后，在任一台执行
/pipes
# → LAN Peers: ☐ [main] cli-04d67950  vmwin11/192.168.50.27
#             tcp:192.168.50.27:58853  [LAN]

# 手动 attach（可选，heartbeat 通常已自动完成）
/attach cli-04d67950

# 选中后输入 prompt，远端执行结果流式回传：
# [main vmwin11/192.168.50.27 / cli-04d67950] 正在检查 git status...
# [main vmwin11/192.168.50.27 / cli-04d67950] Completed

main 角色每 5 秒跑一次 heartbeat：清理死条目、刷新发现的实例（含 LAN peer）、构建统一的 attach 目标列表并自动连接未连接者。跨机器 attach 时通过 machineId 区分 LAN peer， 不要求对方是 sub 角色。

常见问题排错