企业官网建设流程全解析

Electric Agents Desktop 桌面端能力演进全解析：从 Electron 壳到本地 Agent 运行时

【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric

导读

本文以开源仓库GitHub_Trending/el/electric中 packages/agents-desktop/CHANGELOG.md 为主线，系统梳理@electric-ax/agents-desktop从 0.1.0 到 0.6.1 的全部能力演进：包括 Electron 桌面壳、本地 Horton 运行时、MCP 服务器管理、模型推理流式展示、沙箱隔离、Codex 认证、自动更新等核心模块。读完本文，你将掌握该桌面应用的架构分层、各版本关键特性的实现原理，以及如何基于 packages/agents-desktop/README.md 启动开发环境、配置环境变量与settings.json。

一、包定位：基于 Electron 的本地 Agent 运行时桌面壳

@electric-ax/agents-desktop（产品名Electric Agents）是 Electric Agents 生态的桌面应用，使用 Electron 构建，将本地 Horton 运行时、agents-server 连接、MCP 工具注册、系统托盘、自动更新等能力封装进一个原生桌面壳中。从 package.json 可以看到它的关键依赖：

• electron/electron-builder/vite-plugin-electron：桌面壳与打包、HMR 开发链路；
• @electric-sql/client：与 Electric Postgres shape 流同步；
• better-sqlite3/sqlite-vec：本地 SQLite 缓存与向量存储；
• electron-updater：应用自动更新；
• dockerode/e2b：可选沙箱提供方（Docker 容器与 E2B 远程沙箱）；
• undici：HTTP 缓存调度器。

源码结构上，src 按职责拆分为app（应用生命周期/控制器/更新器）、cli、cloud（Cloud 认证与服务匹配）、credentials（API Key / Codex / 模型选择）、discovery（本地 agents-server 发现）、ipc（进程通信）、runtime（本地运行时生命周期与 MCP 注册）、services（密钥存储）、settings（settings.json读写与 MCP 默认值）、ui（托盘与菜单）、windows（多窗口管理）。这与 CHANGELOG 0.1.10 "Refactor the desktop main process into focused modules" 的演进方向一致。

二、从 0.1.0 到 0.1.2：桌面壳与多服务器/多窗口地基

2.1 0.1.0：首版 Electron 桌面壳

0.1.0 是包的起点，确立了桌面应用的核心形态：

• Electron 应用，打包一个本地 Horton 运行时，提供系统托盘状态、多窗口支持、无边框窗口 + 应用内标题栏、原生菜单、About 对话框；
• 启动时 API Key 提示（Anthropic / OpenAI / Brave）；
• localhost agents-server 自动发现（对应 src/discovery/local-discovery.ts，其探测端口列表定义在 src/shared/constants.ts：4437, 4438, 4439, 3000, 4000, 8080，每 30 秒轮询一次，单次超时 1500ms）；
• 通过vite-plugin-electron支持 HMR 开发。

同一版本还引入了MCP 支持：Agent 可以调用外部 MCP 服务器的工具、读取资源、使用提示词（stdio + Streamable HTTP），OAuth 由运行时处理。桌面端暴露 Settings → MCP Servers 页面，以及settings.json中的mcp.servers块，与工作区级mcp.json叠加。内置horton与workerAgent 通过mcp.tools()透明地看到已注册的 MCP 工具。

关联包：MCP 注册表 API 位于 packages/agents-mcp，含RegistryAPI、传输层、OAuth 桥，以及可选的keychainPersistence/filePersistence持久化助手。

2.2 0.1.1：tenant 路由重构与 runner 注册对齐

0.1.1 是一次重要的架构对齐版本：

• pull-wake runner 注册与请求实际身份对齐，并将 runner 迁移到 tenant 感知的 agents-server 路由之上。agents-server 从此支持 runner 注册、runner 持有的 pull-wake 订阅、dispatch 策略解析、订阅流链接、紧凑 Durable Streams wake 认领、回调转发的认领生命周期处理，以及认领作用域的写令牌；
• agents-server HTTP 路由重构为单一globalRouter入口（src 中的 agents-server 导出），ElectricAgentsServer只负责生命周期装配，请求统一经由 OSS 包装路由器转发；
• 破坏性变更：实体 RPC URL 从/:type/:instanceId/...迁移到/_electric/entities/:type/:instanceId/...，涉及 entity spawn/get/head/delete、send、fork、tag、schedule 端点；
• 破坏性变更：@electric-ax/agents-server根导出收敛为库模式路由装配面（DB 设置助手、AgentsHost、StreamClient、globalRouter、TenantContext、GlobalRoutes、EntityBridgeCoordinator等）。

2.3 0.1.2：打包与 Principals 支持

0.1.2 引入桌面打包资源/配置、多服务器桌面设置、聊天与工作区 UI 改进，以及队列收件箱消息模式。同时，agents 系统全面引入Principal概念：每个 API 请求携带Principal（user / agent / service / system），贯穿请求生命周期；runner dispatch 通过 dispatch 策略授权限定到认证所有者；运行时在 handler 上下文中暴露ctx.principal，使 Agent 代码可以实现 principal 感知逻辑。桌面端默认在本地开发时使用system:dev-localprincipal（详见后文 0.1.3 与 0.1.4）。

三、0.1.3–0.1.5：Cloud 登录、环境变量与打包体验

3.1 0.1.3：Electric Cloud 登录与开发 principal

0.1.3 为桌面端带来Electric Cloud 登录：

• 新增 Settings → Account 面板，通过 GitHub 或 Google 走dashboard.electric-sql.cloud的loopback OAuth流程（与 CLI 同一套流程），用 ElectronsafeStorage加密 JWT，再通过auth.whoami刷新姓名与工作区；
• 新增首次启动引导（onboarding），覆盖 Cloud 登录与 LLM API Key 两项；
• 新增Cloud Agent Servers设置区：同步用户 Cloud agent servers，在主进程按租户铸币 agents 令牌，并把桌面运行时/UI 连接到 tenant 作用域的 Cloud agents URL——令牌不暴露给渲染进程，也不写进settings.json；
• 新增ELECTRIC_DESKTOP_PRINCIPAL环境变量：本地开发免认证，桌面端对所有发往 agents-server 的请求注入electric-principal头。

3.2 0.1.4：请求路由、health 端点与 owner_principal 重命名

0.1.4 的要点：

• Cloud 请求使用 Electric Cloud 的service查询参数定位 tenant 专用 agents URL；
• 本地可变 agents-server 请求全部改走 Electron 主进程，避免 CORS 预检被渲染进程连接数限制卡住（对应 src/ipc/server-fetch.ts 链路）；
• 未认证的本地会话默认使用system:dev-localprincipal，并在变更时解析乐观发送 principal，避免挂起消息显示为unknown；
• 新增 pull-wake runner 健康检查端点GET /_electric/runners/:id/health，返回 runner 状态、客户端上报的 stream/heartbeat/claim 指标、活跃认领与 dispatch 统计，并推导 health（healthy/degraded/unhealthy）。PullWakeRunner在心跳中上报内部诊断，存于独立的runner_runtime_diagnostics表，保持主runnersshape 稳定；
• 破坏性变更：owner_user_id重命名为owner_principal，存储规范化的 principal URL（而非 key），在路由边界做严格校验与规范化，所有调用方必须发送 principal URL。

3.3 0.1.5：CI、PATH 恢复与 UI 端口

0.1.5 添加桌面构建产物与 canary 发布的 CI 工作流；打包应用恢复用户 shell PATH（对应依赖fix-path），使 Finder/GUI 启动时也能找到gh等 CLI 工具；新增ELECTRIC_DESKTOP_UI_PORT环境变量，支持并行桌面开发，并在构建产物文件名中带上版本号。

四、0.1.6–0.1.9：运行时选择、DeepSeek、tenant URL 与 Codex 显式登录

4.1 0.1.6：runner 选择器

0.1.6 在新建会话视图加入runner 选择器，让用户决定由哪个 pull-wake runner 负责 spawn 出的实体。默认优先选择 Electron 壳自身的 runner（保持原有的单运行时行为），否则回退到第一个启用的 runner；仅在至少注册了一个 runner 时才渲染选择器，使用 webhook dispatch 的服务器不受影响。

4.2 0.1.7：DeepSeek 支持

0.1.7 将 DeepSeek 加入支持的 LLM 提供方，是全栈联动的一次典型改动：

• agents-runtime：detectAvailableProviders()现在检测DEEPSEEK_API_KEY，deepseek加入AvailableProvider类型、PREFERRED_IDS_BY_PROVIDER与envCatalog()；
• agents：模型目录探测https://api.deepseek.com/v1/models，默认回退模型为deepseek-v4-flash；
• agents-desktop：ApiKeys新增deepseek字段，持久化在系统密钥链中，并镜像为运行时环境的DEEPSEEK_API_KEY（见 src/credentials/api-keys.ts，EMPTY_API_KEYS已含 anthropic/openai/deepseek/moonshot/brave/e2b 六项）；
• agents-server-ui：ApiKeysForm、OnboardingModal、CredentialsPage均新增 DeepSeek API Key 输入并透传。

4.3 0.1.8–0.1.9：onboarding 打磨与 tenant URL 规范化

0.1.8 打磨桌面 onboarding 与设置中的服务器管理。0.1.9 则是一次较大的协议层变更：

• agents-server URL 被视为opaque tenant 作用域 base URL，根于/t/<tenant-id>/v1，桌面与移动端 Cloud 客户端统一迁移到该形态；
• observation 流的 ensure 端点移到/_electric/observations/*/ensure-stream；
• 预 alpha 的 entity/cron/schema/tag/docs API 更名为 Electric Agents 命名；
• 新增非交互式electric agents viewtranscript 命令；
• Codex 显式登录：原生 PKCE OAuth（在用户默认浏览器打开以规避 Cloudflare 机器人检测）、对检测到的 Codex CLI / OpenCode 登录逐来源授权、"Use this login?" 内联提示、凭据变化触发的 "Restart local runtime" 横幅。运行时不再隐式读取~/.codex/auth.json，改用ELECTRIC_CODEX_ACCESS_TOKEN，并以ELECTRIC_CODEX_REQUIRE_OPT_IN=1强制显式选择。

相关实现可参见 src/credentials/codex-auth.ts：它支持desktop-oauth（桌面 OAuth）、codex-cli（解析~/.codex/auth.json，要求auth_mode === 'chatgpt'）、opencode（解析平台路径下的 auth.json）三种来源，并通过syncCodexEnvironment把可用的 access token 注入运行时环境。

五、0.1.10–0.1.13：主进程拆分、保活、CLI 内置与沙箱隔离

5.1 0.1.10–0.1.12：主进程模块化、保活与内置 CLI

• 0.1.10：将桌面主进程拆分为聚焦模块（Electron bootstrap、应用状态、凭据、运行时生命周期、IPC、Cloud 认证、UI shell），对应 src 的目录组织；
• 0.1.11：随应用内置 Electric CLI并提供托管安装/状态 UI；允许用户选择 Horton 模型选择器中展示哪些已配置的 provider 模型，并按 provider 分组；新增Kimi / Moonshot API支持（模型目录条目、运行时 provider 解析、桌面凭据持久化、UI 凭据输入）；新增登录时自启偏好（含后台启动处理，见 src/shared/constants.ts 的BACKGROUND_LAUNCH_ARG）；
• 0.1.12：本地运行时活跃期间保持应用唤醒（Settings、onboarding、托盘菜单三处入口）。托盘菜单的 "Keep Awake While Local Runtime Is Active" 复选项由 src/ui/tray.ts 构建。

5.2 0.1.13：Sandbox 原语

0.1.13 引入Sandbox 原语（@electric-ax/agents-runtime/sandbox），用于隔离 LLM 驱动的工具调用，三种提供方：

• unrestrictedSandbox()：显式直通；
• remoteSandbox({provider: 'e2b'})：E2B 作为可选 peer 依赖；
• dockerSandbox()：经dockerode做容器隔离（多实体托管的推荐路径）。

内置实体（Horton、Worker）默认经chooseDefaultSandbox(workingDirectory)使用unrestrictedSandbox，更强隔离需要显式构造 docker/remote。相关行为变化：bash 不再向子进程转发process.env（堵住$ANTHROPIC_API_KEY之类的环境变量泄漏——直通型沙箱仍无法完全隔离 secrets，例如/proc/<ppid>/environ，不可信或多租户实体应使用 docker/remote）；read/write/edit 拒绝工作区外的符号链接逃逸。

运行时向 agents-server 通告命名沙箱 profile（如local、docker），spawn 请求按名选择，服务器会校验选择是否在该 runner 通告的集合内，新建会话 UI 显示选择器。内部实现上，内置工具工厂（createBashTool、createFetchUrlTool等）的文件系统与网络访问全部经由当前活跃的Sandbox路由。

六、0.1.14：MCP 管理、自动更新与消息共享

0.1.14 是桌面端功能密度最高的一版，值得拆开细讲。

6.1 内置 Playwright MCP 默认值

首次启动时，桌面端向settings.json的mcp.servers块植入@playwright/mcp默认项，让新安装即可开箱使用浏览器自动化。默认值定义为 src/settings/mcp-defaults.ts 中的DEFAULT_MCP_SERVERS：

export const DEFAULT_MCP_SERVERS: ReadonlyArray<McpServerConfig> = [ { name: `playwright`, transport: `stdio`, command: `npx`, args: [`-y`, `@playwright/mcp`], }, ]

植入是可退出的默认值：种子化后该条目与其它settings.jsonMCP 服务器行为一致（可 Edit / Remove / Disable），删除后靠seededDefaultMcpServerNames标记保证不会在重启后重新植入，尊重用户意图。未来内置默认值只需追加到DEFAULT_MCP_SERVERS，已安装用户只要名字未被记录为已植入，下次启动即会自动补上。

6.2 MCP 服务器的表单化管理与来源感知

0.1.14 之前，注册 MCP 服务器只能手改settings.json或工作区mcp.json。本版本新增Add / Edit / Remove 表单流程（Settings → MCP Servers），对话框支持http与stdio两种传输、全部四种认证模式，写入全局settings.json mcp.servers块。校验规则在 src/settings/store.ts 的validateMcpServerConfig：名称需匹配^[a-zA-Z0-9_-]{1,128}$（因为服务器名会被前缀为mcp__<server>__<tool>）；http 传输要求http(s)://URL 与 auth；stdio 传输要求 command。

MCP 页面同时获得来源（provenance）+ 遮蔽（shadowing）感知：

• 来自工作区mcp.json的条目渲染 "from mcp.json" 徽标且只读（无 Edit/Remove），生命周期动词仍可用；
• 当settings.json中的名字与工作区mcp.json冲突时，工作区仍然优先（既有规则），被遮蔽的 settings 条目以灰色渲染在运行中的工作区孪生条目旁，让用户看清被覆盖的情况。

磁盘上mcp按名键控（镜像mcp.json形态），内存中重写为数组形式交给BuiltinAgentsServer.extraMcpServers（见normalizeMcp/serializeSettings）。BuiltinAgentsServer新增公开的setExtraMcpServers(extras)，桌面端可以不重启就把 add/edit/remove 变更推送到活跃的 MCP 注册表。

6.3 自动更新：electron-updater 接入

本版本接上electron-updater的第一阶段：

• Check for Updates… 菜单项（macOS 在 Electric Agents 菜单，Windows/Linux 在 Help 菜单，另有窗口内应用图标菜单）+ 启动后约 10 秒的静默后台检查；
• Windows/Linux：签名平台流程端到端打通——后台下载并显示 dock/taskbar 进度条，然后提示 "Restart now" 通过quitAndInstall()应用；
• macOS：在 Developer ID 签名落地前以notify-only运行——Squirrel.Mac 无法替换未签名 bundle，因此完全跳过下载，提示打开 releases 页面；
• publish provider 从github切换到generic，指向移动的agents-desktop-latesttag（因为仓库整体 "latest" release 被多包共享，GitHub provider 会选错）；canary 构建发布到beta通道（agents-desktop-canaryURL），稳定用户不会自动升级到 canary。

实现细节见 src/app/updater.ts：autoDownload = false（下载前征询用户）、macOS 上autoInstallOnAppQuit关闭、下载进度写入每个存活窗口的setProgressBar、并做了防重复下载/防重复弹窗（downloadStartedVersion/promptedDownloadedVersion）以及并发检查合并。

6.4 用时显示、Codex 认证修复与共享

• 响应期间 meta 行显示Thinking · 12s（开始出 token 后只显示12s），回合落定后显示✓ done in 1m 5s；历史回合（页面加载时已完成）保持裸标签，因为客户端没有可靠的完成时间戳；
• 修复低开销工具调用的 Codex 认证：向 URL 提取与 worker 工具传递新鲜的 access token；
• 为内置 agents 本地 Node runner 安装Undici HTTP 缓存调度器，让 Durable Streams 追读可以利用服务器缓存头；桌面端用磁盘 SQLite 缓存，运行时重启可复用缓存的追读响应；
• 把 tenant 作用域的用户暴露为Electric shape，并新增聊天共享对话框：可按用户 principal 或全部工作区用户授予 view / chat / manage 权限；view/chat 共享包含 fork 权限，fork 出的聊天归创建它的 principal 所有；Cloud 请求注入当前登录用户为 Electric principal。

6.5 0.1.15：未登录时的清晰提示

0.1.15 修了一个体验问题：在未登录状态下连接 Electric Cloud 服务器时，不再把 pull-wake runner 注册错误直接抛给用户，而是显示清晰的登录提示。

七、0.1.16–0.1.18：Token 用量、pg-sync 观测与流式推理

7.1 0.1.16：每响应 Token 用量

Agent meta 行现在显示每次响应的 token 用量，例如1.2k ↑ 412 ↓，随每一步落定更新。技术细节：

• StepValue新增可选的input_tokens/output_tokens列（Zod + TS），严格加法式——旧事件因两字段可选而保持有效，无需迁移；
• outbound-bridge.ts:onStepEnd现在持久化pi-adapter.ts传来的tokenInput/tokenOutput（此前这两个值被接收后丢弃）；
• EntityTimelineStepItem/IncludesStep暴露新字段，物化步骤的三个.select()块都包含它们；
• 缓存的agent_response区块获得tokens?: { input?, output? }（在区块构建时对 run 的步骤求和），区块缓存指纹纳入步骤 token 增量，迟到的onStepEnd会使过期区块失效。

7.2 0.1.17：pg-sync 观测源

0.1.17 加入pg-sync 观测源：Agent 可以观测 Electric Postgres shape 流，并在匹配的行变更（insert/update/delete）时被唤醒。包含服务端桥接管理（游标持久化、durable 流转发），并为 Horton Agent 提供observe_pg_sync工具。同时升级@electric-sql/client@1.5.21。实现对应 packages/agents-runtime/src/observation-sources.ts。

7.3 0.1.18：流式展示模型推理 / 扩展思考内容

0.1.18 把模型的 "thinking" 内容流式渲染进 UI。支持的推理来源包括 Anthropic extended thinking、DeepSeek-R1 reasoning、Moonshot K2、OpenAI Responses summaries。交互形态：

• 推理进行中：在答案上方以淡色显示实时推理文本，沿用Thinkingshimmer 标题，带已耗时间 ticker；
• 推理落定后：折叠为▸ Thought for 12s，点击展开；
• 一次运行中的多条推理行独立按序渲染，工具调用回合能看到每一步各自的推理。

实现层面的四处改动：

• Schema：reasoning行新增run_id、encrypted（Anthropic redacted-thinking 不透明负载，必须原样回传模型）、summary_title（写入时从 provider 加粗标题提取）；新增reasoningDeltas集合，镜像textDeltas用于流式内容；
• Bridge：OutboundBridge新增onReasoningStart/onReasoningDelta/onReasoningEnd，与文本路径平行；
• Adapter：pi-adapter.ts把 pi-ai 的thinking_start/thinking_delta/thinking_end事件路由到 bridge，并在thinking_end时一次性解析**Title**\n\n<body>标题（仅 OpenAI Responses），避免 UI 每次渲染重复解析；
• Timeline / UI：EntityTimelineRunRow增加实时reasoning集合（delta-join 构建内容）；新组件<ReasoningSection>在AgentResponseLive的答案上方渲染，settled 后折叠为Thought for Ns；redacted Anthropic 块渲染单行灰字（内容不透明，但加密负载仍持久化在服务端，模型下一轮能拿回来）。

不产生推理的 provider 什么都不发 → 不渲染 reasoning 区；本 PR 之前记录的历史响应没有闭合提示。

同时，Anthropic extended thinking 对支持推理的模型改为常开：reasoningEffort: auto映射到最小预算（1024 tokens），与 OpenAI 分支auto默认minimal对齐；显式low/medium/high仍按原样缩放预算。

八、0.6.x：桌面可配置技能目录与 pull-wake runner 标签

8.1 0.6.0：runner 标签可辨识

0.6.0 随全部 Electric Agents 包以 0.6 版本发布。patch 部分给桌面 pull-wake runner 一个可辨识标签，取代硬编码的Electric Agents Desktop，方便在移动/桌面 runner 选择器中区分多个 runner。标签默认形如<identity> · <hostname>，其中 identity 取已登录的 Cloud 名称（回退到 email，再回退Electric Desktop），可通过settings.json的pullWakeRunnerLabel或环境变量ELECTRIC_DESKTOP_PULL_WAKE_RUNNER_LABEL覆盖。已存在的 runner 会在下次启动自动采用新标签（注册基于稳定的 runner id 做 upsert）。

8.2 0.6.1：桌面可配置技能目录

0.6.1 为桌面端加入可配置技能目录：用户可指定额外目录，并把常见的 Claude/Codex 技能位置纳入，使Markdown 命令文件以斜杠命令技能（slash-command skills）方式递归加载，而无需 LLM 元数据提取。这与 src/settings/store.ts 中DesktopSettings.skillDirectories字段（normalizeSkillDirectories去重、剔除空串）直接对应，也是 packages/agents 技能系统在桌面端的一等公民化。

九、开发环境与配置实操

9.1 启动开发环境

按 packages/agents-desktop/README.md：

1. 前置条件：本地运行一个 agents-server（例如http://localhost:4437）；
2. 执行pnpm dev，同时启动 UI 开发服务器（带 HMR）与 Electron 主进程；
3. 对本地未认证的 agents-server，桌面默认把 pull-wake runner 的 owner 设为 agents-server 在 dev 回退模式下使用的同一system:dev-localprincipal。

9.2 环境变量速查

9.3 settings.json 位置与内容

桌面设置存储在：

• macOS：~/Library/Application Support/Electric Agents/settings.json
• Linux：~/.config/Electric Agents/settings.json

可配置服务器、每服务器请求头、工作目录；多数本地开发场景用上文环境变量即可。写入时带version字段（当前SETTINGS_VERSION = 2），读取时会做迁移（旧activeServer会归一化进servers；旧内联apiKeys会迁入系统密钥链；缺失pullWakeRunnerId会自动生成 UUID）。API Key 本身不落盘于settings.json，而是存于系统密钥存储（SecretStore），并在保存时镜像进运行时环境变量（applyApiKeysToEnv，见 src/credentials/api-keys.ts）。Cloud 服务器令牌则按cloud-agents-token:<tenantId>键存于 SecretStore，仅主进程可取用（见 src/shared/types.ts 的ServerConfig.tenantId注释）。

十、从变更记录看架构演进主线

纵观 0.1.0 → 0.6.1，agents-desktop的演进有三条清晰主线：

1. 从壳到平台：0.1.0 的 Electron 壳（托盘/多窗口/本地发现）逐步长出 Cloud 登录（0.1.3）、runner 体系（0.1.1/0.1.4/0.1.6/0.6.0）、自动更新（0.1.14）、保活与自启（0.1.11/0.1.12）等平台能力；
2. 从封闭到开放：MCP 从 0.1.0 的注册表支持，演进到 0.1.14 的表单化管理、来源/遮蔽感知与热更新，再到 0.6.1 把技能目录也做成可配置；沙箱原语（0.1.13）则为多租户/不可信实体托管提供隔离路径；
3. 从静默到可视化：0.1.16 的 token 用量、0.1.18 的流式推理、0.1.14 的用时显示，共同把本地 Agent 运行时的内部状态变成用户可感知、可调试的实时 UI。

对想深入源码的读者，推荐按此顺序阅读：先看 src/main.ts 与 src/app/controller.ts 了解进程生命周期，再通过 src/runtime/controller.ts 与 src/runtime/lifecycle.ts 追踪本地运行时启停，最后用 src/settings/store.ts + src/settings/mcp-defaults.ts 验证 MCP 配置链路。

【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric