Hermes Desktop 架构：Electron 如何连接本地 Python Agent
内容提要
本文介绍Hermes Agent桌面端架构，核心是Electron连接本地Python后端。桌面端分为Electron主进程、Preload桥、React渲染器和Python后端四个权威边界，通过WebSocket JSON-RPC通信。Electron启动hermes serve子进程，Renderer直接连接Python Gateway处理会话与模型调用，桌面UI工具通过desktop_ui Toolset交互。文章还详述消息从输入框到AIAgent的完整流程，以及execute_code实现程序化工具调用的四种连接方式。
延伸解读
两条通道分离：桌面能力与Agent通信不混用
文章强调桌面端存在两条独立通道：Renderer与Electron主进程之间通过Preload IPC处理窗口、文件、剪贴板等本机能力；而与Python后端的通信则绕过主进程，直接通过WebSocket JSON-RPC进行。这种设计避免了将所有调用都经由Electron中转的误解，也保证了Agent逻辑与UI状态解耦。理解这一分离有助于排查桌面端问题：UI卡顿未必影响Agent运行，反之亦然。
desktop_ui工具集：反向调用的实现机制
Python Agent需要读取终端或预览面板状态时，并非直接访问Renderer内存，而是通过注册为仅桌面会话可见的desktop_ui Toolset，借助Gateway事件进行请求-应答。工具是否可用取决于会话的SessionSource，而非环境变量。这意味着即使后端运行在远程，UI工具仍会回到发起会话的桌面Renderer，而终端、文件等操作则留在远端执行。
execute_code的四种连接方式：不止是本地
文章指出“连接本地Python”有四种不同含义，其中execute_code是Agent工具路径之一，用于程序化工具调用。其RPC通道根据环境选择：本地POSIX用Unix Socket，Windows用回环TCP，远程环境用文件RPC。这种设计让多步工具编排移到代码层，但工具权限仍受会话允许集与沙箱白名单约束，父Agent保持执行权威。
Q&A
Hermes Desktop 的架构中，Electron 和 Python 后端是如何连接的？
Electron 主进程启动 hermes serve 子进程，React 渲染进程通过 WebSocket 与 Python 后端建立 JSON-RPC 连接，实现通信。
Hermes Desktop 中，React 渲染进程如何与 Python 后端通信？
React 渲染进程通过 WebSocket 直接连接 Python 后端的 TUI 网关，使用 JSON-RPC 协议进行通信，绕过 Electron 主进程。
Hermes Desktop 中，桌面 UI 工具（如终端、预览）是如何被 Agent 调用的？
桌面 UI 工具通过 desktop_ui Toolset 注册，Agent 调用时通过 TUI 网关发送请求到 React 渲染进程，渲染进程操作对应的 Pane 并返回结果。
Hermes Desktop 中，Electron 如何启动本地 Python 后端？
Electron 主进程通过 backend-command.ts 解析后端候选路径，探测 CLI 和 serve 能力，然后启动 hermes serve --host 127.0.0.1 --port 0 子进程，并通过 ready 文件获取实际端口，完成 HTTP 和 WebSocket 探测后连接。
Hermes Desktop 中，一条消息从输入框到 AIAgent 的完整流程是怎样的？
用户输入消息后，React 渲染进程通过 JsonRpcGatewayClient 发送 prompt.submit 请求，经 WebSocket 到达 TUI 网关，网关调用 AIAgent 的 run_conversation，AIAgent 执行模型调用和工具调用，最后通过事件流将结果返回给渲染进程。
Hermes Desktop 中，execute_code 实现程序化工具调用的四种连接方式是什么？
四种连接方式包括：本机 POSIX 使用 Unix 套接字，Windows 使用回环 TCP，远程环境（如 Docker、SSH）使用文件 RPC，以及通过生成的 hermes_tools.py 进行 RPC 回调。
Hermes Desktop 中，如何判断桌面工具是否可用？
判断依据是会话的 SessionSource，而不是环境变量。即使后端在远程，只要会话来自桌面，UI 工具仍会回到发起会话的桌面 Renderer。
