04 一次完整请求的跨层旅程

04 一次完整请求的跨层旅程

本节摘要:前三节分别讲了「有哪些层」「每层干什么」「层间规矩」,这一节把它们串成一条河——用一次具体的请求(「帮我把这个函数重命名」),追踪数据如何从应用层一路向下穿越六层、再带着结果返回。这是第 2 章的收尾,也是对前三节知识的综合检验:读完它,抽象的分层就会变成可见的数据流,后续每一章你都能在这趟旅程里找到自己关注的那一段。

一、场景设定

假设你在终端里输入了一条消息:「帮我把 utils 里的 oldName 函数重命名为 newName」。我们追踪这条消息从输入到回显的完整旅程。为了看清分层,这趟旅程会经过六层里的每一层。

二、旅程全景图

先看全貌,再分步拆:

你输入消息
   │
   ▼
[应用层] 解析输入、选定 Agent
   │
   ▼
[领域核心层] 组装本次回合
   ├─ 取会话历史
   ├─ 组装 System Context(第 8 章)
   ├─ 物化可用工具集(第 5 章)
   └─ 求解工具权限(第 4 章)
   │
   ▼
[LLM 抽象层] 构造 provider 中立请求
   ├─ 套上 Route / Protocol(第 6 章)
   └─ 发起流式调用
   │
   ▼
[模型 API] 真正的推理(远端)
   │
   ▼ 流式返回
[LLM 抽象层] 翻译成统一事件流
   │
   ▼ 工具调用事件
[领域核心层] 执行工具(读/改文件)
   ├─ 权限询问(若需要)
   ├─ 工具执行 + 输出边界控制
   └─ 工具结果回流
   │
   ▼ 续跑判断
[领域核心层] 决定是否再调一次模型
   │
   ▼ 最终响应
[应用层] 渲染到终端
   │
   ◄─ 你看到结果
​

三、分步拆解

第 1 步:应用层接住输入

你在终端敲下消息,应用层(这里是 TUI 形态)接住它。应用层做的事很薄:解析输入、确定用哪个 Agent(默认是 build)、把消息交给领域核心层。它不操心「模型怎么调」「工具怎么执行」,那些都是下面层的事。

💡 记住:应用层永远很薄。它的职责是「把用户的东西翻译成内核能懂的调用」,不是亲自干活。

第 2 步:领域核心层组装本次回合

这是旅程里最厚的一段。领域核心层拿到消息后,要为「调一次模型」准备好一切:

• 取会话历史:这次对话之前说过什么(从持久化存储读,呼应第 1 章的会话记录产物)。
• 组装 System Context:把环境信息(Git 状态、工作目录)、指令、技能指引等组合成给模型的初始事实集合(第 8 章详讲)。
• 物化可用工具集:根据当前 Agent 的权限,从注册表里选出它能用的工具(第 5 章)。
• 求解工具权限:每个工具对当前目标,是允许、询问还是拒绝(第 4 章)。

这一步的产物是一个「准备好的回合」——历史有了、上下文有了、工具有了、权限清楚了。

第 3 步:LLM 抽象层构造请求

领域核心层把「准备好的回合」交给 LLM 抽象层。LLM 抽象层把它翻译成 provider 中立的请求(system / messages / tools / 生成参数),然后套上 Route(用哪家厂商、哪个端点)、Protocol(用哪种协议,如 anthropic-messages 或 openai-chat)、Framing(怎么分帧),发起流式调用。

⚠️ 关键不变量:领域核心层给 LLM 抽象层的是「中立请求」,它不关心是哪家厂商。厂商差异全在 LLM 抽象层内部被吸收。这就是第 6 章要讲的「Schema-first」的威力。

第 4 步:模型 API 推理

请求到达远端模型 API,真正的推理在这里发生。模型决定:是直接回复文本,还是请求调用工具。在我们的场景里,它大概率会请求调用「读文件」工具(先看看 oldName 函数长啥样),然后请求调用「改文件」工具。

第 5 步:LLM 抽象层翻译事件流

模型流式返回 token,LLM 抽象层把它们翻译成统一事件流:文本增量、工具调用请求、(后续的)工具结果等。注意——不管模型是哪家,事件流长得都一样。这是上层简洁的关键。

第 6 步:领域核心层执行工具

事件流里出现「工具调用」时,领域核心层接管:

• 权限询问:如果是写操作(改文件),且规则是「询问」,会暂停等你授权(第 4 章)。
• 工具执行:调对应的工具(第 5 章),比如读文件、改文件。
• 输出边界控制:工具输出太大时,运行时层会把它落盘只回传引用,防止撑爆上下文(第 5、9 章)。
• 工具结果回流:把工具结果作为新的消息,准备再喂给模型。

第 7 步:续跑判断

工具执行完后,领域核心层判断:模型是不是还需要再看一眼结果、继续干活?如果是(「needs continuation」),就带着工具结果再走一遍第 3~6 步——这就是「会话循环」(第 7 章详讲)。一个回合里,模型可能被调多次、工具可能被调多次,直到模型认为任务完成。

第 8 步:应用层渲染

模型最终给出「完成了」的文本响应,应用层把它渲染到终端。你看到结果。

四、这趟旅程揭示了什么

把这趟旅程和前几节对照,你会发现几个关键认知被验证了:

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

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

• 第 4 章(Agent/权限)→ 第 1、2、6 步
• 第 5 章(工具系统)→ 第 2、6 步
• 第 6 章(LLM 抽象)→ 第 3、5 步
• 第 7 章(会话核心)→ 第 2、6、7 步(整个循环)
• 第 8 章(System Context)→ 第 2 步
• 第 9 章(上下文压缩)→ 第 2 步(超窗口时介入)

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

六、第 2 章收尾

读完第 2 章,你已经建好了全书的地图和坐标系:知道 OpenCode 是什么(定位)、怎么分层(六层)、层间规矩(依赖铁律)、一次请求怎么流转(跨层旅程)。从第 3 章开始,我们要钻进每一层细看——先从最顶层应用层的「多形态」开始:这套内核怎么支撑八种入口形态。

本节要点回顾

1. 旅程八步:应用层接输入 → 核心层组装回合 → LLM 层构造请求 → 模型推理 → LLM 层翻译事件 → 核心层执行工具 → 续跑判断 → 应用层渲染。
2. 应用层永远很薄,只负责把用户输入翻译成内核调用。
3. 核心层组装回合是最厚的一段:取历史、组 System Context、物化工具、求权限。
4. LLM 层吸收厂商差异:核心层给中立请求,厂商差异在 LLM 层内部消化。
5. 会话是循环:一次输入可能触发多次模型调用 + 多次工具执行,直到任务完成。
6. 旅程是导航线:后续每章都能在旅程里定位自己——读到后面记得回头看这张图。

第 2 章结束。下一章从应用层切入,讲这套内核如何用八种形态把自己暴露给世界。