3.2 核心数据流：从用户输入到 AI 响应

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2025-02-17

---

理解 OpenCode 架构的关键是理解数据如何从用户的一次键盘输入，流经整个系统，最终产生 AI 的回复。本节将完整追踪这条数据流。

3.2.1 用户消息 → Session.chat() → SessionPrompt.prompt() → LLM.stream()

当用户在 TUI 中输入一条消息并按下回车，以下调用链会依次触发：

用户按下回车
    │
    ▼
TUI 发送 HTTP POST 请求
POST /project/:id/session/:sid/message
body: { parts: [{ type: "text", text: "帮我实现一个排序函数" }] }
    │
    ▼
Server 路由处理 (routes/session.ts)
    │
    ▼
SessionPrompt.prompt(input)          ← session/prompt.ts
    │
    ├── 1. Session.get(sessionID)     获取会话信息
    ├── 2. SessionRevert.cleanup()    清理未完成的回滚
    ├── 3. createUserMessage(input)   创建用户消息并存储
    ├── 4. Session.touch(sessionID)   更新会话时间戳
    └── 5. loop({ sessionID })        进入 Agentic Loop ←── 核心！

SessionPrompt.prompt() 的源码结构清晰地展示了这个流程：

export const prompt = fn(PromptInput, async (input) => {
  const session = await Session.get(input.sessionID)
  await SessionRevert.cleanup(session)
  const message = await createUserMessage(input)
  await Session.touch(input.sessionID)

  if (input.noReply === true) return message

  return loop({ sessionID: input.sessionID })
})

loop() 函数是整个 Agentic Loop 的入口，它会：

1. 从数据库加载会话的所有消息

2. 解析当前应使用的 Agent 和 Model

3. 组装 System Prompt（包括 AGENTS.md 指令、环境信息等）

4. 注册所有可用的 Tools

5. 创建一个 SessionProcessor

6. 调用 LLM.stream() 发起流式 LLM 调用

7. 处理流式响应（文本、思考链、工具调用）

3.2.2 流式响应处理：SessionProcessor 的 Agentic Loop

SessionProcessor（session/processor.ts）是 OpenCode 中最复杂也最重要的模块之一。它实现了完整的 Agentic Loop：

export function create(input: {
  assistantMessage: MessageV2.Assistant
  sessionID: string
  model: Provider.Model
  abort: AbortSignal
}) {
  let attempt = 0
  let needsCompaction = false

  return {
    async process(streamInput: LLM.StreamInput) {
      while (true) {  // ← Agentic Loop 的外层循环
        const stream = await LLM.stream(streamInput)

        for await (const value of stream.fullStream) {
          switch (value.type) {
            case "reasoning-start":     // 思考链开始
            case "reasoning-delta":     // 思考链增量
            case "reasoning-end":       // 思考链结束
            case "text-delta":          // 文本增量
            case "tool-call-start":     // 工具调用开始
            case "tool-call-delta":     // 工具调用参数增量
            case "tool-call-complete":  // 工具调用完成 → 执行工具
            case "finish":              // 本轮生成完成
          }
        }

        // 检查是否有工具调用需要处理
        // 如果有 → 执行工具 → 将结果追加到消息 → 继续循环
        // 如果没有 → 退出循环，AI 回复完成
      }
    }
  }
}

流式事件的处理顺序：

LLM 开始生成
    │
    ├── reasoning-start    → 创建 ReasoningPart
    ├── reasoning-delta    → 更新 ReasoningPart.text（追加增量）
    ├── reasoning-end      → 完成 ReasoningPart
    │
    ├── text-delta         → 追加到 TextPart.text
    │
    ├── tool-call-start    → 创建 ToolPart（状态：pending）
    ├── tool-call-delta    → 更新 ToolPart 参数
    ├── tool-call-complete → 标记 ToolPart（状态：running）→ 执行工具
    │
    └── finish             → 本轮完成，检查是否需要继续

每个 Part 的变化都会实时通过 Session.updatePart() 写入存储，并通过事件总线推送到前端，实现实时显示。

3.2.3 工具调用循环：Tool Call → Execute → Result → Continue

当 LLM 的响应中包含工具调用时，处理流程如下：

LLM 返回工具调用请求
例如: { tool: "read", args: { filePath: "/src/index.ts" } }
    │
    ▼
1. 权限检查 (PermissionNext.evaluate)
    │
    ├── allow → 继续执行
    ├── ask   → 暂停，等待用户确认
    └── deny  → 拒绝执行，返回错误
    │
    ▼
2. 执行工具 (Tool.execute)
    │
    ├── Snapshot.track()    → 执行前创建文件快照
    ├── tool.execute(args)  → 实际执行
    └── 结果写入 ToolPart   → 状态变为 completed/error
    │
    ▼
3. 结果返回给 LLM
    工具的输出（如文件内容）作为新的 tool_result 消息
    追加到消息列表中
    │
    ▼
4. LLM 继续生成
    带着工具结果，LLM 决定：
    ├── 调用更多工具 → 回到步骤 1
    ├── 生成文本回复 → 结束循环
    └── 触发 Doom Loop 检测

Doom Loop 检测：

OpenCode 内置了 Doom Loop（死循环）检测机制：

const DOOM_LOOP_THRESHOLD = 3

如果 Agent 连续 3 次执行相同的操作模式而没有实质性进展，系统会触发 doom_loop 权限检查。根据配置，这可能会暂停执行并询问用户是否继续。这是防止 AI 陷入无限循环的安全措施。

3.2.4 完整的请求-响应时序图

将上述所有步骤串联起来，一次完整的对话交互的时序如下：

  用户         TUI          Server       SessionPrompt    LLM      Tool
   │            │             │               │            │         │
   │──输入消息──►│             │               │            │         │
   │            │──POST msg──►│               │            │         │
   │            │             │──prompt()────►│            │         │
   │            │             │               │            │         │
   │            │             │               │──stream()─►│         │
   │            │◄─SSE:text───│◄─Bus.publish──│◄─text-δ───│         │
   │            │◄─SSE:text───│◄─Bus.publish──│◄─text-δ───│         │
   │            │             │               │            │         │
   │            │             │               │◄─tool-call─│         │
   │            │◄SSE:tool-st─│◄─Bus.publish──│            │         │
   │            │             │               │──execute()──────────►│
   │            │             │               │            │  读文件  │
   │            │◄SSE:tool-ok─│◄─Bus.publish──│◄─result───────────◄─│
   │            │             │               │            │         │
   │            │             │               │──stream()─►│ 带结果  │
   │            │◄─SSE:text───│◄─Bus.publish──│◄─text-δ───│ 继续    │
   │            │             │               │◄─finish────│         │
   │            │◄─SSE:done───│◄─Bus.publish──│            │         │
   │            │             │               │            │         │
   │◄─显示结果──│             │               │            │         │

这张时序图展示了 OpenCode 的核心特点：

1. 异步流式处理：从 LLM 的第一个 token 开始，用户就能看到响应

2. 事件驱动：所有状态变化通过 Bus 广播，前端通过 SSE 接收

3. 循环架构：工具调用和 LLM 生成交替执行，直到 LLM 决定停止

理解了这条核心数据流，后续章节对各个模块的深入分析就有了坐标系。