Thunderbolt CLI ACP桥接实战如何用 iroh/WSS 把 stdio 代理快速接入桌面应用【免费下载链接】thunderboltAI You Control: Choose your models. Own your data. Eliminate vendor lock-in.项目地址: https://gitcode.com/GitHub_Trending/thund/thunderboltThunderbolt CLI 内置了一个ACP 桥接器Bridge可以把任何基于 stdio 的 Agent Client ProtocolACP代理通过WSSWebSocket本机回环或irohP2P 端到端加密两种传输安全地接入 Thunderbolt 桌面应用。无需写任何胶水代码一条命令即可完成本地 stdio 进程 ↔ 网络字节流 ↔ 桌面 UI全部自动搞定 ⚡。一、为什么需要 ACP 桥接Thunderbolt 桌面应用支持接入能说话 ACP 协议的远程代理。但市面上大量成熟代理以及thunderbolt acp serve自身都以stdio 模式运行——它们只认 stdin/stdout 上的 JSON-RPC不监听任何端口。这就需要一个翻译官桥接器Bridgethunderbolt acp --transport wss|iroh -- agent命令负责监听网络连接并为每个连接拉起一个 stdio 代理子进程把两者的字节流双向泵送。桌面应用客户端按代理类型选择 WebSocket 或 iroh 传输打开一条双向流用同样的 ndjson 帧格式承载 ACP 消息。核心设计是连接与进程 1:1 绑定一条网络连接对应一个acp serve进程连接断开进程即被杀掉进程退出会话自然结束生命周期清晰可预期。二、桥接架构速览┌──────────────────┐ ┌─────────────────────────────┐ │ 桌面应用 (客户端) │◄────────►│ CLI 桥接器 (服务端) │ │ │ WSS 或 │ │ │ ACP 客户端流 │ iroh │ 每个连接 spawn 一个 │ │ (ndjson 帧) │ │ stdio 代理子进程 (ndjson 帧) │ └──────────────────┘ └─────────────────────────────┘两种传输的差异维度WSS默认irohP2P网络范围仅本机回环loopback-only经 n0 中继的全互联网 P2P加密依赖本机隔离QUIC 端到端加密到桥授权回环地址天然隔离NodeId 白名单典型场景局域网开发机、Docker 内联调试跨设备远程接入、家庭服务器关键实现位置桥接服务端irohcli/src/iroh/bridge.tsstdio 代理进程管理cli/src/commands/bridge.tsacp serve入口把内置编码代理暴露为 stdio ACP 服务cli/src/acp/serve.ts桌面端传输工厂按代理类型路由到 WebSocket 或 irohsrc/acp/transports/index.ts桌面端 iroh 拨号Rust→wasm 客户端首次使用才懒加载 wasm 分块src/acp/iroh/iroh-transport.ts三、一键启动步骤3.1 WSS 桥接本机最快路径想在本机把任意 stdio ACP 代理挂给桌面应用一条命令thunderbolt acp --transport wss -- 你的代理命令例如桥接第三方 ACP 代理或让 MCP 服务器走同一套管道thunderbolt acp --transport wss -- npx zed-industries/claude-code-acp thunderbolt mcp --transport wss --port 9001 -- uvx mcp-server-fetch--之后是任意 stdio 命令--port可指定监听端口仅 wss 生效。命令行帮助见 cli/src/cli.ts。3.2 iroh P2P 桥接跨设备 端到端加密想把自己这台机器上的代理分享给任意设备# 分享 Thunderbolt 内置代理 thunderbolt acp --transport iroh -- thunderbolt acp serve # 分享任意第三方 stdio ACP 代理 thunderbolt acp --transport iroh -- npx zed-industries/claude-code-acp启动后会打印一个iroh ticket节点票据。它承载了桥的 NodeIded25519 公钥身份任何拿到 ticket 的客户端经中继即可拨入且整条 QUIC 通道端到端加密。iroh 路径的安全细节值得留意见 cli/src/iroh/bridge.tsNodeId 白名单QUIC 握手免费验证了对端身份白名单之上才是授权门限流防护每个远端 10 秒最多 10 次连接且全局并发握手有硬上限防止身份轮换式攻击自托管中继可选默认走 n0 公共中继也可设环境变量指向自托管 iroh-relay 的 wss 地址参考 deploy/iroh-relay/。3.3 桌面应用侧三步完成接入打开Agents → Add Agent填写名称URL 栏粘贴wss://...端点本机桥或 iroh ticket跨设备桥点击Add Agent应用会自动选择对应传输并建立双向流。应用侧对托管型代理managed-acp与用户自定义外部代理remote-acp采用不同的路由策略——前者带 bearer 凭据直连云端后端后者按代理开关决定走原生 WebSocket 还是经通用代理隧道路由逻辑统一收口在 src/acp/transports/index.ts。四、幕后机制stdio 如何过网桥接器把子进程的 stdin/stdout 接到一条网络双向流上使用与 WebSocket 路径完全一致的ndjson按行分隔 JSON帧格式src/acp/iroh/ndjson.ts所以 ACP SDK 两端看到的都是同一个{ readable, writable }消息流协议层零改动。内置代理的转换层Pi harness 事件 → ACPsession/update通知消息增量、思考增量、工具调用开始/结束一一对应见 cli/src/acp/harness-to-acp.ts。桌面端则用镜像的 ACP→AI SDK 翻译器把流还给聊天界面src/acp/translators/acp-to-ai-sdk.ts。 一个易错点iroh 靠ALPN区分协议thunderbolt/acp/0与thunderbolt/mcp/0必须逐字节匹配否则 QUIC 握手直接拒连——ACP 客户端无法驱动 MCP 桥反之亦然。五、常见问题Qwss 和 iroh 该选哪个本机/同机容器开发选 wss零配置、默认回环要跨设备、跨网络、要求端到端加密就选 iroh。Q桥的进程会一直占用我的代理吗不会。每个连接独立 spawn 一个子进程连接断开即被回收cli/src/iroh/lifecycle.ts同一桥可并发服务多个客户端。Qticket 泄漏了怎么办在桥的白名单allowlist中移除对应 NodeId 即可吊销acp serve的会话存储独立持久化见 cli/src/acp/session-store.ts。六、小结Thunderbolt CLI 的 ACP 桥接器把stdio 代理上网这件麻烦事压缩成了一条命令 一次粘贴 ticket✅WSS本机回环开发调试最快路径✅irohP2P 端到端加密NodeId 白名单授权可自托管中继✅桌面应用Add Agent 弹窗里粘贴端点即完成接入传输层自动路由。更多协议细节可查阅 docs/architecture/ 下的架构文档以及 CLI 自带的--help输出cli/src/cli.ts。上手体验从这里开始 。【免费下载链接】thunderboltAI You Control: Choose your models. Own your data. Eliminate vendor lock-in.项目地址: https://gitcode.com/GitHub_Trending/thund/thunderbolt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Thunderbolt CLI ACP桥接实战：如何用 iroh/WSS 把 stdio 代理快速接入桌面应用
Thunderbolt CLI ACP桥接实战如何用 iroh/WSS 把 stdio 代理快速接入桌面应用【免费下载链接】thunderboltAI You Control: Choose your models. Own your data. Eliminate vendor lock-in.项目地址: https://gitcode.com/GitHub_Trending/thund/thunderboltThunderbolt CLI 内置了一个ACP 桥接器Bridge可以把任何基于 stdio 的 Agent Client ProtocolACP代理通过WSSWebSocket本机回环或irohP2P 端到端加密两种传输安全地接入 Thunderbolt 桌面应用。无需写任何胶水代码一条命令即可完成本地 stdio 进程 ↔ 网络字节流 ↔ 桌面 UI全部自动搞定 ⚡。一、为什么需要 ACP 桥接Thunderbolt 桌面应用支持接入能说话 ACP 协议的远程代理。但市面上大量成熟代理以及thunderbolt acp serve自身都以stdio 模式运行——它们只认 stdin/stdout 上的 JSON-RPC不监听任何端口。这就需要一个翻译官桥接器Bridgethunderbolt acp --transport wss|iroh -- agent命令负责监听网络连接并为每个连接拉起一个 stdio 代理子进程把两者的字节流双向泵送。桌面应用客户端按代理类型选择 WebSocket 或 iroh 传输打开一条双向流用同样的 ndjson 帧格式承载 ACP 消息。核心设计是连接与进程 1:1 绑定一条网络连接对应一个acp serve进程连接断开进程即被杀掉进程退出会话自然结束生命周期清晰可预期。二、桥接架构速览┌──────────────────┐ ┌─────────────────────────────┐ │ 桌面应用 (客户端) │◄────────►│ CLI 桥接器 (服务端) │ │ │ WSS 或 │ │ │ ACP 客户端流 │ iroh │ 每个连接 spawn 一个 │ │ (ndjson 帧) │ │ stdio 代理子进程 (ndjson 帧) │ └──────────────────┘ └─────────────────────────────┘两种传输的差异维度WSS默认irohP2P网络范围仅本机回环loopback-only经 n0 中继的全互联网 P2P加密依赖本机隔离QUIC 端到端加密到桥授权回环地址天然隔离NodeId 白名单典型场景局域网开发机、Docker 内联调试跨设备远程接入、家庭服务器关键实现位置桥接服务端irohcli/src/iroh/bridge.tsstdio 代理进程管理cli/src/commands/bridge.tsacp serve入口把内置编码代理暴露为 stdio ACP 服务cli/src/acp/serve.ts桌面端传输工厂按代理类型路由到 WebSocket 或 irohsrc/acp/transports/index.ts桌面端 iroh 拨号Rust→wasm 客户端首次使用才懒加载 wasm 分块src/acp/iroh/iroh-transport.ts三、一键启动步骤3.1 WSS 桥接本机最快路径想在本机把任意 stdio ACP 代理挂给桌面应用一条命令thunderbolt acp --transport wss -- 你的代理命令例如桥接第三方 ACP 代理或让 MCP 服务器走同一套管道thunderbolt acp --transport wss -- npx zed-industries/claude-code-acp thunderbolt mcp --transport wss --port 9001 -- uvx mcp-server-fetch--之后是任意 stdio 命令--port可指定监听端口仅 wss 生效。命令行帮助见 cli/src/cli.ts。3.2 iroh P2P 桥接跨设备 端到端加密想把自己这台机器上的代理分享给任意设备# 分享 Thunderbolt 内置代理 thunderbolt acp --transport iroh -- thunderbolt acp serve # 分享任意第三方 stdio ACP 代理 thunderbolt acp --transport iroh -- npx zed-industries/claude-code-acp启动后会打印一个iroh ticket节点票据。它承载了桥的 NodeIded25519 公钥身份任何拿到 ticket 的客户端经中继即可拨入且整条 QUIC 通道端到端加密。iroh 路径的安全细节值得留意见 cli/src/iroh/bridge.tsNodeId 白名单QUIC 握手免费验证了对端身份白名单之上才是授权门限流防护每个远端 10 秒最多 10 次连接且全局并发握手有硬上限防止身份轮换式攻击自托管中继可选默认走 n0 公共中继也可设环境变量指向自托管 iroh-relay 的 wss 地址参考 deploy/iroh-relay/。3.3 桌面应用侧三步完成接入打开Agents → Add Agent填写名称URL 栏粘贴wss://...端点本机桥或 iroh ticket跨设备桥点击Add Agent应用会自动选择对应传输并建立双向流。应用侧对托管型代理managed-acp与用户自定义外部代理remote-acp采用不同的路由策略——前者带 bearer 凭据直连云端后端后者按代理开关决定走原生 WebSocket 还是经通用代理隧道路由逻辑统一收口在 src/acp/transports/index.ts。四、幕后机制stdio 如何过网桥接器把子进程的 stdin/stdout 接到一条网络双向流上使用与 WebSocket 路径完全一致的ndjson按行分隔 JSON帧格式src/acp/iroh/ndjson.ts所以 ACP SDK 两端看到的都是同一个{ readable, writable }消息流协议层零改动。内置代理的转换层Pi harness 事件 → ACPsession/update通知消息增量、思考增量、工具调用开始/结束一一对应见 cli/src/acp/harness-to-acp.ts。桌面端则用镜像的 ACP→AI SDK 翻译器把流还给聊天界面src/acp/translators/acp-to-ai-sdk.ts。 一个易错点iroh 靠ALPN区分协议thunderbolt/acp/0与thunderbolt/mcp/0必须逐字节匹配否则 QUIC 握手直接拒连——ACP 客户端无法驱动 MCP 桥反之亦然。五、常见问题Qwss 和 iroh 该选哪个本机/同机容器开发选 wss零配置、默认回环要跨设备、跨网络、要求端到端加密就选 iroh。Q桥的进程会一直占用我的代理吗不会。每个连接独立 spawn 一个子进程连接断开即被回收cli/src/iroh/lifecycle.ts同一桥可并发服务多个客户端。Qticket 泄漏了怎么办在桥的白名单allowlist中移除对应 NodeId 即可吊销acp serve的会话存储独立持久化见 cli/src/acp/session-store.ts。六、小结Thunderbolt CLI 的 ACP 桥接器把stdio 代理上网这件麻烦事压缩成了一条命令 一次粘贴 ticket✅WSS本机回环开发调试最快路径✅irohP2P 端到端加密NodeId 白名单授权可自托管中继✅桌面应用Add Agent 弹窗里粘贴端点即完成接入传输层自动路由。更多协议细节可查阅 docs/architecture/ 下的架构文档以及 CLI 自带的--help输出cli/src/cli.ts。上手体验从这里开始 。【免费下载链接】thunderboltAI You Control: Choose your models. Own your data. Eliminate vendor lock-in.项目地址: https://gitcode.com/GitHub_Trending/thund/thunderbolt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考