Agent 核心循环

0. 本章学习目标

• 解释用户输入如何进入 SessionPrompt.prompt。
• 解释 OpenCode 为什么需要 runLoop，而不是只调用一次模型。
• 说明 runLoop 如何选择 agent、model、tools 和 system prompt。
• 说明 SessionProcessor 如何把 LLM 流式事件转成 message parts。
• 说明 tool result 如何回到 message history，并触发下一轮推理。

2. 它在 OpenCode agent 中的位置

CLI/API
  -> SessionPrompt.prompt
  -> SessionPrompt.runLoop
  -> SessionTools.resolve
  -> SessionProcessor.process
  -> LLM.stream
  -> SessionProcessor.handleEvent
  -> message parts
  -> runLoop next round

3. 生活类比

把 agent loop 想成项目经理处理任务：用户给需求，项目经理看项目记录，决定找哪个专家和哪些工具； 专家可能要求查文件或跑命令，项目经理把结果贴回记录，再让专家继续判断，直到完成。

这个过程对应源码里的 while (true)。来源：packages/opencode/src/session/prompt.ts:1248-1477。

5. 最小源码路径

1. packages/opencode/src/cli/cmd/run.ts:791-798：CLI 调用 client.session.prompt。
2. packages/opencode/src/server/routes/instance/httpapi/handlers/session.ts:279-290：API handler 调用 promptSvc.prompt。
3. packages/opencode/src/session/prompt.ts:1211-1229：创建 user message 并调用 loop。
4. packages/opencode/src/session/prompt.ts:1240-1481：执行核心 runLoop。
5. packages/opencode/src/session/processor.ts:779-847：消费 LLM stream。
6. packages/opencode/src/session/llm.ts:402-493：调用 AI SDK/native runtime。
7. packages/opencode/src/session/processor.ts:376-500：处理 tool-call/tool-result。

6. 用户输入到 agent 行动的整体链路

6.1 用户输入

const result = await client.session.prompt({
  sessionID,
  agent,
  model,
  variant: args.variant,
  parts: [...files, { type: "text", text: message }],
})

路径：packages/opencode/src/cli/cmd/run.ts:791-798

6.2 session / message

const message = yield* createUserMessage(input)
yield* sessions.touch(input.sessionID)
if (input.noReply === true) return message
return yield* loop({ sessionID: input.sessionID })

路径：packages/opencode/src/session/prompt.ts:1211-1229

6.3 agent 决策

let msgs = yield* MessageV2.filterCompactedEffect(sessionID)
const { user: lastUser, assistant: lastAssistant, finished: lastFinished, tasks } = MessageV2.latest(msgs)
const model = yield* getModel(lastUser.model.providerID, lastUser.model.modelID, sessionID)
const agent = yield* agents.get(lastUser.agent)

路径：packages/opencode/src/session/prompt.ts:1252-1317

6.4 LLM 调用

const result = yield* handle.process({
  user: lastUser,
  agent,
  sessionID,
  system,
  messages: [...modelMsgs],
  tools,
  model,
})

路径：packages/opencode/src/session/prompt.ts:1429-1440

6.5 tool call

case "tool-call": {
  const toolCall = yield* ensureToolCall(value)
  const input = toolInput(value.input)
  yield* updateToolCall(value.id, (match) => ({
    ...match,
    tool: value.name,
    state: { status: "running", input, time: { start: Date.now() } },
  }))
}

路径：packages/opencode/src/session/processor.ts:376-421

6.6 tool result

yield* session.updatePart({
  ...match.part,
  state: {
    status: "completed",
    input: match.part.state.input,
    output: output.output,
    metadata: output.metadata,
    title: output.title,
    time: { start: match.part.state.time.start, end: Date.now() },
  },
})

路径：packages/opencode/src/session/processor.ts:169-193

6.7 再次推理

if (result === "stop") return "break" as const
if (result === "compact") {
  yield* compaction.create({ sessionID, agent: lastUser.agent, model: lastUser.model, auto: true })
}
return "continue" as const

路径：packages/opencode/src/session/prompt.ts:1461-1471

7. 核心源码逐段讲解

7.1 prompt：入口不直接问模型

prompt 先写 user message，再进入 loop。这保证 CLI、API、TUI 都能复用同一个状态入口。 来源：packages/opencode/src/session/prompt.ts:1211-1229。

7.2 loop：同一 session 不能随便并发跑

return yield* state.ensureRunning(input.sessionID, lastAssistant(input.sessionID), runLoop(input.sessionID))

来源：packages/opencode/src/session/prompt.ts:1485-1489、packages/opencode/src/session/run-state.ts:87-93。

7.3 runLoop：真正的状态机

runLoop 每轮设置 busy，读取 compacted messages，找到最新 user/assistant/tasks， 然后选择 agent、model、tools 并调用 processor。来源：packages/opencode/src/session/prompt.ts:1248-1440。

7.4 退出条件：不是所有 stop 都能停

OpenCode 明确处理 provider 返回 stop 但 assistant message 仍含 tool calls 的情况，这时要继续 loop。 来源：packages/opencode/src/session/prompt.ts:1261-1276。

7.5 Processor：事件处理器

Processor 调用 llm.stream，用 Stream.tap 逐个处理事件。 来源：packages/opencode/src/session/processor.ts:779-795。

8. 关键 TypeScript 语法复习

• Effect.gen(function* () { ... })：把 Effect 异步流程写成同步风格。来源：packages/opencode/src/session/prompt.ts:1240-1243。
• const { user: lastUser, ... } = MessageV2.latest(msgs)：对象解构并重命名。来源：packages/opencode/src/session/prompt.ts:1254。
• export type Result = "compact" | "stop" | "continue"：字符串 literal union。来源：packages/opencode/src/session/processor.ts:36。
• Record<string, AITool>：对象 map 类型。来源：packages/opencode/src/session/tools.ts:34。
• { ...result, attachments: ... }：对象 spread 浅拷贝并补字段。来源：packages/opencode/src/session/tools.ts:93-102。
• ToolState 的 discriminator status：判别联合类型。来源：packages/opencode/src/session/message-v2.ts:299-320。

9. 涉及的设计模式和架构思想

• State Machine：runLoop 根据 stop/continue/compact/subtask 切换状态。
• Application Service：SessionPrompt 协调 session、agent、provider、processor、tools。
• Strategy / Registry：工具由 registry 解析，具体实现由 item.execute 执行。
• Gateway / Adapter：LLM.stream 隐藏 AI SDK/native runtime 差异。
• Event Processor：SessionProcessor 消费 LLMEvent 并更新消息 parts。
• Policy / Interceptor：ctx.ask 把权限检查插入工具执行上下文。

10. 它如何和 Tool、Provider、Session、文件系统协作

11. 如果自己实现 mini agent，这一章对应什么代码

type ToolState = "pending" | "running" | "completed" | "error"

async function runLoop(sessionID: string) {
  while (true) {
    const messages = await sessionStore.loadMessages(sessionID)
    const latestUser = findLatestUser(messages)
    const tools = toolRegistry.resolve()
    const result = await llm.stream({ messages, tools })

    await processor.apply(sessionID, result)

    if (result.finish === "stop" && !hasUnresolvedToolCalls(sessionID)) break
    if (result.finish === "tool-calls") continue
  }
}

先不要实现 LSP、compaction、subtask、plugin。先把 user -> llm -> tool -> result -> next loop 跑通。

14. 源码追踪任务

1. 从 packages/opencode/src/cli/cmd/run.ts:791-798 追到 SessionPrompt.prompt。
2. 从 packages/opencode/src/session/prompt.ts:1429-1440 追到 SessionProcessor.process。
3. 从 packages/opencode/src/session/processor.ts:789-795 追到 LLM.stream。
4. 从 packages/opencode/src/session/llm/ai-sdk.ts:191-218 追到 processor 的 tool-call/tool-result case。
5. 从 SessionTools.resolve 追一个具体工具，例如 read 或 edit。

15. 面试式自测

1. OpenCode 的 agent loop 和普通 chat completion 最大区别是什么？
2. 为什么 agent loop 需要持久化 message parts？
3. SessionProcessor 为什么不直接返回字符串？
4. OpenCode 如何处理模型返回了 tool call 的情况？
5. 什么情况下 loop 会返回 compact？
6. 为什么 tool 执行上下文里要有 ask？
7. 如果要避免同一 session 并发跑两个 loop，你会怎么设计？