01 三进程拓扑与职责边界

01 三进程拓扑与职责边界

本节摘要:理解 OpenWork 最大的障碍,是搞不清「到底有几个东西在跑」。答案是一个三进程模型(加上被托管的引擎,实际是四个角色):用户看到的界面是渲染进程(React 单页应用);它跑在 Electron 主进程(桌面外壳)里;主进程生成并管理本地服务端(自研 HTTP 中枢);服务端反向托管底层引擎(OpenCode)。本节用一张拓扑图把这四个角色讲清,重点是各自的职责边界——谁干什么、谁不干什么。把这个拓扑钉在脑子里,后续每一章你都能定位「我在哪个角色」。

一、为什么会有这么多进程

先回答一个自然疑问:为什么不能把所有东西塞进一个进程?三个工程理由:

1. 前端要在两个环境跑:同一个 React 单页应用,既跑在浏览器也跑在 Electron,所以它必须与「桌面专属逻辑」解耦。
2. 服务端要多客户端复用:服务端要同时被桌面、CLI 接入的 Agent、企业云共用,所以它必须独立成进程,不能塞进 Electron。
3. 引擎是第三方内核:底层引擎(OpenCode)是被托管的,它有自己的进程边界,主进程通过子进程方式管理它。

这些约束合起来,自然推出「多进程」结构。

二、四角色拓扑

┌─────────────────────────────────────┐
│  渲染进程(React 单页应用)            │  用户看到的界面
├─────────────────────────────────────┤
│  Electron 主进程(桌面外壳)           │  窗口管理、运行时管理、IPC
│     │ 生成管理                        │
│     ▼                                │
│     本地服务端(自研 HTTP 中枢)        │  路由、鉴权、能力管理、引擎反代
│       │ 反向托管                      │
│       ▼                              │
│       底层引擎 OpenCode(Agent 运行时) │  会话循环、工具调用、上下文管理
└─────────────────────────────────────┘
​

注意:严格说渲染进程和主进程都在 Electron 这个「应用」里,但它们是两个隔离的进程(Electron 的多进程模型);服务端是主进程生成的子进程;引擎是服务端反向托管的子进程。所以「三进程」是渲染、主、服务端,引擎算第四个角色(被服务端托管的子进程)。

三、逐角色拆解

渲染进程:用户看到的界面

渲染进程是用户直接交互的界面——一个 React 单页应用。它的职责:

• 渲染界面(会话、工作区、设置)
• 把用户操作翻译成对服务端的 API 调用
• 通过 IPC 桥接与主进程通信(桌面专属操作)

它不直接调引擎、不直接管文件系统——这些都是通过服务端。这个边界很重要:渲染进程永远只是「服务端的客户端」(第 02 节的主题)。

Electron 主进程:桌面大管家

主进程是桌面形态的「大管家」,职责偏系统层:

• 窗口管理(创建、关闭、托盘)
• 生成并管理服务端子进程(运行时管理器,第 9 章)
• IPC 通信(渲染进程与主进程之间的桥)
• 自动更新、品牌图标、CDP 端口探测(第 9 章)

它不直接处理业务逻辑——业务逻辑在服务端。主进程更像「基础设施层」,负责让服务端能跑起来、让渲染进程能显示。

本地服务端:唯一中枢

服务端是整个产品的「中枢」,几乎所有的业务逻辑都在这里:

• HTTP 路由与分发(第 3 章)
• 鉴权与权限(第 4 章)
• 引擎托管与配置注入(第 5 章)
• 能力管理(第 6 章)
• meta-MCP(第 7 章)
• Reload 事件(第 8 章)

它是所有客户端(桌面、CLI Agent、企业云)的共同后端。这是为什么第 3~8 章都围着它转——它是 OpenWork 的心脏。

底层引擎 OpenCode:Agent 运行时

引擎是被服务端反向托管的子进程,职责是真正的 Agent 运行时:

• 会话循环(OpenCode 教程第 7 章)
• 工具调用(OpenCode 教程第 5 章)
• 上下文管理(OpenCode 教程第 8、9 章)

它不直接被渲染进程调——所有对引擎的访问都经服务端代理(第 3 章)。服务端是引擎的「门卫」。

💡 记住边界:渲染进程只认服务端;主进程只管基础设施;服务端是中枢也代理引擎;引擎只管 Agent 运行时。这四条边界一旦清楚,你就能解释任何一次操作「该由谁处理」。

四、为什么服务端要独立成进程

这是拓扑里最关键的设计决策,值得单独强调。服务端独立成进程(而不是塞进主进程),换来三样东西:

1. 多客户端复用:服务端可以被桌面渲染进程、CLI 接入的 Agent、企业云 Web 同时调用。如果塞进主进程,只有桌面能用。
2. 隔离与稳定:服务端崩了不会拖垮桌面外壳,桌面外壳崩了不会丢业务状态。
3. 可独立部署:服务端可以单独跑在服务器上(纯服务端形态),支撑远程客户端。

这就是为什么 OpenWork 的工程文档反复强调「服务端消费优先」——把中枢独立出来,让一切客户端共用它。这是下一节的主题。

五、这张拓扑怎么用

从现在起,每读到一个新概念,先问自己:它在哪个角色里? 举几个例子预热:

• 「会话怎么发起」→ 渲染进程发起,服务端处理,引擎干活
• 「能力存在哪」→ 服务端管理
• 「窗口怎么创建」→ 主进程
• 「工具怎么调用」→ 引擎内部(经服务端代理)

本节要点回顾

1. 四角色:渲染进程(界面)、Electron 主进程(桌面大管家)、本地服务端(中枢)、底层引擎(Agent 运行时)。
2. 渲染进程只认服务端,不直接调引擎;主进程只管基础设施;服务端是中枢也代理引擎。
3. 服务端独立成进程换来多客户端复用、隔离稳定、可独立部署——这是拓扑的关键决策。
4. 引擎被反向托管,所有对它的访问都经服务端代理。
5. 边界清楚后,任何操作都能定位「该由谁处理」。
6. 用法:读新概念先问「它在哪个角色里」——这是全书的定位框架。

拓扑清楚了,但有一个贯穿它的核心哲学没讲——为什么渲染进程只认服务端?这就是下一节「服务端消费优先」。