企业官网建设流程全解析

PI-Desktop 远程 Agent 控制架构：SSH 隧道与 Headless Host 完整路线图

【免费下载链接】PI-DesktopLocal-first AI coding agent desktop: Electron + Rust host core + pi Agent Harness + user-installable plugins项目地址: https://gitcode.com/GitHub_Trending/pid/PI-Desktop

PI-Desktop 是一款本地优先的 AI 编程 Agent 桌面应用。它的远程 Agent 控制目标架构正在推进中：通过SSH 隧道把本地的 PI-Desktop 变成"远程客户端"，让 Headless 版 Agent Host（pi-host）在远程 Linux/WSL 机器上替你跑任务、读写代码、执行命令。本文带你看懂这套架构的 5 个核心设计和 R0–R3 四阶段路线图。

为什么远程控制不能简单"开个端口"？

你可能会想：Agent 跑在远程机器上，把它的接口暴露到网络上不就行了？PI-Desktop 团队明确拒绝了这条捷径，原因有三：

• 信任边界：现有的本地 IPC、host.proxy和 Rust host-core 的 JSON-RPC 接口都是为"进程内可信通信"设计的，直接暴露等于绕过所有权限边界，把 Electron 进程变成一台公网后端服务。
• 生命周期问题：远程 UI 必须能随时断开、重连后不丢事件、能远程回答审批请求，还能与其他客户端共享同一个会话——本地接口根本不支持这些。
• 安全底线：Rust host-core（负责 SQLite、工具、权限、密钥）必须永远绑定回环地址，在任何机器上都不可被网络直接访问。

因此 ADR 0205 决定：定义一条专门的远程 Agent 控制协议（RACP），让"语义契约"与"传输方式"解耦。完整决策记录见 0205-remote-agent-control-boundary.md。

目标架构：5 个核心设计决策

1️⃣ Agent Host 是唯一的"事实来源"

会话、回合、事件序列、审批、附件、工作区策略、崩溃恢复，全部由Agent Host拥有。客户端只是一个"可断开"的观察者与控制器——你关掉窗口，正在跑的回合照常继续。

2️⃣ RACP 协议：一套语义，多种传输

RACP（PI Remote Agent Control Protocol）v1 是传输中立的语义契约，由 typebox schema 在 packages/shared/src/racp.ts 中定义（唯一契约源，其余格式全部生成）：

关键机制：每个事件都带{ epoch, sequence }游标，断线重连时用游标精确续播，游标失效则返回完整快照同步；所有变更操作幂等，丢失响应重试也不会产生第二个回合。协议规范见 19-remote-agent-control-protocol.md。

3️⃣ SSH 隧道：第一种（也是首个落地的）远程拓扑

这是用户呼声最高的场景（issue #176、#140）：在本机桌面上操作远程 Linux/WSL 机器上的项目。设计借鉴了 VS Code Remote-SSH 的成熟模型：

PI-Desktop (本地, 远程客户端) 远程机器 ├── Renderer ── lib/api.ts ─┐ ├── pi-host (Headless Agent Host) ├── Electron Main │ │ ├── agent-host 模块 │ └── RACP 客户端适配器 ────┼─SSH 端口转发─▶│ ├── Node pi sidecar └── 本地会话（保持不变） │ │ └── Rust host-core (仅回环)

引导流程全部走你自己的 SSH 会话，绝不走 RACP：

1. 用你现有的 SSH 配置和密钥连上远程机器；
2. 桌面端上传一个小的引导脚本，从 GitHub Releases 下载与桌面端同版本的pi-host包，校验已发布的 SHA-256 后安装；
3. pi-host启动并仅绑定回环，通过 SSH 通道下发一次性配对令牌；
4. 建立本地端口转发，以头部认证方式连接RACP-WS，用配对令牌换取设备令牌存入桌面端安全存储；
5. Host 将该桌面设备记为owner。

模型供应商的配置同样通过 SSH 引导通道写入，永远不经过 RACP——密钥边界由此保持不变。

4️⃣ Headless Agent Host：无 Electron 依赖的独立模块

pi-host包之所以能搬到任何机器上跑，前提是核心逻辑与桌面壳彻底分离。packages/agent-host 是一个零 Electron 依赖的模块（核心实现见 agent-host.ts），它拥有：

• 会话/回合准入与每会话回合队列（由 Rust host-core 持久化，重启后按序恢复）
• 审批代理（approval broker）
• 带 epoch 的内存事件日志与快照构建器

桌面 IPC、本地 MCP 控制面、RACP 都是这一个模块的调用方。这意味着"独立 Host 抽取"是搬模块，而不是重新拆 Electron Main。

5️⃣ 构造上"用户本地"（User-local by Construction）

D385 修正定下铁律：项目不运营任何身份、账号或中继服务。客户端持有的唯一凭证是你自己的 Host 在配对时签发的设备令牌；PI 官方不运行 Gateway，如未来需要 Gateway，只能由用户在自有基础设施上自托管。所有出站连接只去你自己的 SSH 主机、你配置的模型供应商和消息渠道。

远程会话的所有权如何划分？

一个容易混淆的点：远程会话的"身体"住在哪台机器上？

• 在远程 Host 上：对话记录与 SQLite、回合与队列、内置工具目录与工作区边界、权限、供应商密钥、~/.agents中的技能/子代理定义、MCP 服务器、定时任务
• 在桌面上：窗口与外壳、本地会话、设置界面、插件面板、浏览器预览
• 从桌面中继：桌面端通过tools/advertise广播自己配置的 MCP 服务器和无需工作区的插件工具，它们在远程会话目录中显示为"中继工具"，实际在桌面上执行（遵循桌面自己的插件权限）；需要工作区/文件系统访问的工具则被排除

工作面板的文件浏览、读取、diff 直接作用于远程会话根目录；终端（terminal/*操作）运行在远程机器上，输出带有限重放环，SSH 断线后可续传。

路线图：R0–R3 里程碑与当前进展

R2 的验收标准相当硬核（E2E-231）：从桌面发起的回合只能在远程机器上读写和执行；审批出现在桌面卡片上；SSH 会话中断后按游标恢复且不产生重复回合；被篡改的pi-host包下载必须被拒。完整的交付规格见 07-remote-control-rollout.md。

安全与故障恢复要点

• 远程权限上限：远程发起的回合运行在"会话模式"与 Host 配置的权限上限（默认ask）两者之中较低者；SSH 配对的owner桌面默认豁免（因为 SSH 访问本身已超出上限所限制的能力），Host 策略可重新启用上限。
• 审批时效：本地默认 120 秒超时即拒绝；当有远程订阅者在线时默认放宽到30 分钟（可配置），因为远程审批人很少守在键盘前。
• 故障模型：客户端断开 → 回合继续；SSH 隧道掉线 → 适配器重建转发并按游标续播；Host 重启 → 新 epoch，客户端从快照重同步，持久化队列恢复后挂起等待控制端接入，绝不在无人值守时自动开跑。
• 安全规格全文见 02-remote-control-security.md。

想深入了解？推荐阅读顺序

1. 0205-remote-agent-control-boundary.md — 架构决策与三次修正（D374/D375/D385）的完整背景
2. 05-remote-agent-control.md — 目标架构、拓扑图与所有权划分
3. 19-remote-agent-control-protocol.md — RACP 协议规范
4. 07-remote-control-rollout.md — 里程碑、验收标准与灰度发布计划
5. agent-host.ts — 已落地的 Headless Agent Host 模块源码

一句话总结：PI-Desktop 的远程 Agent 控制不是一夜之间"上云"，而是一次有纪律的模块化迁移——先抽 Headless 模块（R1 已完成），再走 SSH 隧道落地远程 Host（R2），最后才是消息集成与可选的 Gateway。整个过程不改变你熟悉的本地体验，也让"在咖啡馆里盯着家里服务器跑 Agent"这件事，既可行又安全。

【免费下载链接】PI-DesktopLocal-first AI coding agent desktop: Electron + Rust host core + pi Agent Harness + user-installable plugins项目地址: https://gitcode.com/GitHub_Trending/pid/PI-Desktop