03 一次用户操作的控制流旅程

03 一次用户操作的控制流旅程

本节摘要:前两节讲了拓扑和哲学,这一节把它们串成一条河——用一次具体的用户操作(「在界面发起一次会话」),追踪控制流如何从渲染进程穿越主进程、服务端、引擎,再带着结果返回。这是第 2 章的收尾,也是对前两节知识的综合检验:读完它,抽象的拓扑和哲学就会变成可见的数据流,后续每一章你都能在这趟旅程里找到自己关注的那一段。

一、场景设定

假设你在桌面界面里,针对当前工作区发起一条会话消息:「这个项目大概做什么?」。我们追踪这条消息从输入到回显的完整控制流。

二、旅程全景图

先看全貌,再分步拆:

你在界面输入消息
   │
   ▼ [渲染进程] 接住输入,准备调服务端 API
   │
   ▼ [渲染进程→主进程] 通过 IPC 桥接
   │
   ▼ [主进程] 转发到服务端(或直接由渲染进程调服务端 HTTP)
   │
   ▼ [服务端] 接收请求,路由匹配
   │
   ▼ [服务端] 鉴权(第 4 章)
   │
   ▼ [服务端] 代理到引擎 / 执行能力(第 3、7 章)
   │
   ▼ [引擎] 真正干活(读文件、调模型、调工具)
   │
   ▼ 结果原路返回
   │
   ◄─ 你在界面看到结果
​

三、分步拆解

第 1 步:渲染进程接住输入

你在界面敲下消息,渲染进程(React 单页应用)接住它。渲染进程做的事很薄:把消息封装成一个对服务端的 API 调用。它不自己处理「会话逻辑」——那是服务端的事(服务端消费优先,第 02 节)。

💡 记住:渲染进程永远很薄。它的职责是「把用户操作翻译成服务端 API 调用 + 把服务端返回渲染出来」,不亲自干业务逻辑。

第 2 步:渲染进程与主进程的 IPC 桥接

桌面形态下,渲染进程有些操作需要通过 IPC(进程间通信)走主进程——尤其是涉及桌面专属能力的(窗口、文件对话框、运行时管理)。不过对服务端的常规 API 调用,渲染进程通常直接走 HTTP(服务端就是个 HTTP 服务)。

这里有个细节:渲染进程通过一个「桌面桥接代理」(desktopBridge,第 10 章)访问桌面专属能力,通过 HTTP 访问服务端。两条路各管一摊。

第 3 步:服务端接收并路由匹配

请求到达服务端,服务端用它的自研路由引擎(第 3 章)匹配路径。匹配到「会话」相关路由后,进入对应的处理器。

⚠️ 这里有个第 3 章的伏笔:服务端不用任何 Web 框架,路由是正则编译式的。怎么做到的、为什么这么做,第 3 章详讲。

第 4 步:鉴权

服务端在执行业务前,先做鉴权(第 4 章)——这个请求是哪个令牌来的?它是什么 scope(所有者/协作者/查看者)?它有权做这件事吗?鉴权不通过,直接拒绝。

在我们的场景里(工作区所有者本人发起会话),鉴权通过,继续。

第 5 步:代理到引擎 / 执行能力

这是旅程里最关键的分叉。服务端拿到一个合法的会话请求后,要么:

• 代理到引擎:如果是引擎相关的(如发起对话、跑工具),服务端把请求透明地代理到底层引擎(第 3 章的反向代理)。
• 执行能力:如果是能力相关的(如调一个技能、执行 meta-MCP 能力),服务端自己执行或协调(第 7 章)。

在我们的场景里(发起会话),走的是「代理到引擎」。

第 6 步:引擎干活

请求到达引擎(OpenCode),真正的 Agent 运行时启动:

• 组装系统上下文(OpenCode 教程第 8 章)
• 物化工具集(OpenCode 教程第 5 章)
• 调用模型,流式返回(OpenCode 教程第 6、7 章)
• 必要时调工具(读文件等)

引擎干完活,把结果(通常是流式的事件)经服务端原路返回。

第 7 步:结果返回与渲染

结果从引擎 → 服务端 →(HTTP/IPC)→ 渲染进程。渲染进程把流式结果实时渲染到界面,你看到模型一段段吐出回答。

四、这趟旅程揭示了什么

把这趟旅程和前两节对照,几个关键认知被验证:

五、后续章节在旅程里的位置

这趟旅程是全书的「导航线」。后续每一章都能在旅程里找到对应:

• 第 3 章(服务端路由)→ 第 3 步
• 第 4 章(鉴权)→ 第 4 步
• 第 5 章(引擎托管)→ 第 5~6 步
• 第 7 章(meta-MCP)→ 第 5 步(执行能力分支)
• 第 8 章(Reload 事件)→ 贯穿(实时性)
• 第 9 章(桌面主进程)→ 第 2 步(IPC、运行时管理)
• 第 10 章(前端)→ 第 1、7 步

💡 建议:把这张旅程图记住,读到后面章节时回头看一眼,你会一直清楚「我现在在旅程的哪一段」。

本节要点回顾

1. 旅程七步:渲染进程接输入 → IPC/HTTP 到主进程/服务端 → 服务端路由匹配 → 鉴权 → 代理引擎或执行能力 → 引擎干活 → 结果返回渲染。
2. 渲染进程永远很薄,只调 API + 渲染结果。
3. 服务端是中枢:第 3~6 步都在它或经它。
4. 关键分叉:引擎相关走「代理到引擎」,能力相关走「执行能力」(第 7 章)。
5. 权限贯穿:服务端鉴权 + 引擎内工具级权限,两层把关。
6. 旅程是导航线:后续每章都能在旅程里定位——读到后面记得回头看。

拓扑、哲学、旅程都清楚了,最后一节点出全书最精巧的设计——能力四源与 meta-MCP,作为第 2 章的高光收尾,也为第 7 章埋伏笔。