OpenCode Agent 架构深度解析

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

用户输入
  │
  ▼
SessionPrompt.prompt()                    ← session/prompt.ts:1371
  │
  ├── createUserMessage()                  ← 解析文本、文件、agent 附件
  │     ├── resolvePart()                  ← 每个附件类型分别处理
  │     ├── 保存 User 消息到数据库
  │     └── 保存各 Part（text/file/agent/subtask）
  │
  └── loop()                               ← session/prompt.ts:1630
        │
        └── runLoop()                      ← while(true) 核心循环
              │
              ├── 加载消息历史
              ├── 拼装 system prompt
              ├── 拼装 messages
              ├── 注册 tools
              │
              ├── processor.process()      ← 发送给 LLM，处理流式响应
              │     └── llm.stream()
              │           └── streamText() ← AI SDK
              │
              ├── 模型返回了 tool-call？
              │     ├── Yes → 执行 tool → 继续循环
              │     └── No  → break，结束
              │
              └── 最终返回 assistant 消息

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

第 1 步：从数据库加载消息历史（过滤掉已压缩的）
         │
第 2 步：判断是否需要退出循环
         │   最后一条 assistant 消息已经 finish 且不是 "tool-calls" → 退出
         │
第 3 步：step++
         │
第 4 步：如果是第 1 步，异步生成 session 标题（不阻塞主循环）
         │
第 5 步：获取 model（resolve provider + model ID）
         │
第 6 步：处理 subtask（子 agent）或 compaction（上下文压缩）如果有的话
         │
第 7 步：创建一条新的 Assistant 消息（空壳，等待 LLM 填充）
         │
第 8 步：创建 Processor（处理 LLM 流式响应的处理器）
         │
第 9 步：resolveTools() — 收集所有可用工具
         │
第 10 步：拼装 system prompt（env + instructions + skills）
         │
第 11 步：handle.process() — 发给 LLM，流式处理响应
         │
第 12 步：根据结果决定 continue / break

1
2
3
4
5
6
7
8

if (
  lastAssistant?.finish &&
  !["tool-calls"].includes(lastAssistant.finish) &&
  !hasToolCalls &&
  lastUser.id < lastAssistant.id
) {
  break  // 退出循环
}

1
2
3
4
5
6
7

const [skills, env, instructions, modelMsgs] = yield* Effect.all([
  sys.skills(agent),           // → string | undefined
  sys.environment(model),      // → string[]
  instruction.system(),        // → string[]
  MessageV2.toModelMessagesEffect(msgs, model),
])
const system = [...env, ...instructions, ...(skills ? [skills] : [])]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

You are powered by the model named claude-sonnet-4-20250514.
The exact model ID is anthropic/claude-sonnet-4-20250514
Here is some useful information about the environment you are running in:
<env>
  Working directory: /root/codes/myproject
  Workspace root folder: /root/codes/myproject
  Is directory a git repo: yes
  Platform: linux
  Today's date: Thu May 07 2026
</env>

1
2

Instructions from: /root/codes/myproject/AGENTS.md
[文件内容]

1
2
3
4
5
6
7

Skills provide specialized instructions and workflows for specific tasks.
Use the skill tool to load a skill when a task matches its description.

Available skills:
- answers: USE FOR AI-grounded answers via OpenAI-compatible /chat/completions...
- bx: USE FOR web search, research, RAG...
- frontend-design: Create distinctive, production-grade frontend interfaces...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const system: string[] = []
system.push(
  [
    ...(input.agent.prompt ? [input.agent.prompt] : SystemPrompt.provider(input.model)),
    ...input.system,       // ← 上面收集的 env + instructions + skills
    ...(input.user.system ? [input.user.system] : []),
  ]
    .filter((x) => x)
    .join("\n"),           // 用 \n 拼成一个完整字符串，作为 system[0]
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

export function provider(model: Provider.Model) {
  if (model.api.id.includes("gpt-4") || model.api.id.includes("o1") || model.api.id.includes("o3"))
    return [PROMPT_BEAST]       // beast.txt
  if (model.api.id.includes("gpt")) {
    if (model.api.id.includes("codex")) return [PROMPT_CODEX]  // codex.txt
    return [PROMPT_GPT]         // gpt.txt
  }
  if (model.api.id.includes("gemini-")) return [PROMPT_GEMINI]  // gemini.txt
  if (model.api.id.includes("claude")) return [PROMPT_ANTHROPIC] // anthropic.txt
  // ... 其他模型
  return [PROMPT_DEFAULT]       // default.txt
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

[
  {
    role: "system",
    content: "                              // ← system[0]，一个大字符串
      [anthropic.txt 全文]                   ← provider prompt
      \n
      You are powered by...                  ← env
      <env>...</env>
      \n
      Instructions from: /path/AGENTS.md     ← instructions
      [AGENTS.md 内容]
      \n
      Skills provide specialized...          ← skills
      - answers: USE FOR...
      - frontend-design: Create...
    "
  },
  { role: "user", parts: [...] },           // ← 用户历史消息
  { role: "assistant", parts: [...] },      // ← 助手历史消息
  ...
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

streamText({
  temperature,        // agent.temperature ?? 根据模型自动计算
  topP,              // agent.topP ?? 根据模型自动计算
  topK,              // 根据模型自动计算
  maxOutputTokens,   // 根据模型限制计算
  tools,             // 内置工具 + MCP 工具（几十个）
  toolChoice,        // 通常 undefined（auto），结构化输出时 "required"
  messages,          // [system 消息, ...历史对话]
  model,             // 包装后的 language model，带 middleware
  headers,           // session affinity、user-agent 等
  providerOptions,   // provider 特有参数（如 Anthropic 的 extended thinking）
  abortSignal,       // 取消控制
  maxRetries: 0,     // 默认不重试（processor 层面有 retry 逻辑）
  experimental_repairToolCall,  // 工具调用修复（大小写问题）
})

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

llm.stream({
  agent: titleAgent,           // 专用 title agent，temperature: 0.5
  small: true,                 // 标记为小请求（用 getSmallModel）
  tools: {},                   // 无工具！
  system: [],                  // 无额外 system
  model: smallModel,           // 用小/便宜模型
  messages: [
    { role: "user", content: "Generate a title for this conversation:\n" },
    ...历史消息（只取第一条真实用户消息之前的上下文）
  ],
})

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

processor.process({
  user: userMessage,
  agent: compactionAgent,    // 专用 compaction agent，权限全部 deny
  tools: {},                 // 无工具！
  system: [],                // 无额外 system（agent 自带 prompt）
  messages: [
    ...历史消息（截断版，stripMedia=true，工具输出截断到 2000 字符）,
    { role: "user", content: "Create/Update summary..." }
  ],
})

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

## Goal
## Constraints & Preferences
## Progress
### Done
### In Progress
### Blocked
## Key Decisions
## Next Steps
## Critical Context
## Relevant Files

1
2
3
4
5
6
7
8
9

generateObject({   // 注意：不是 streamText！用 generateObject
  temperature: 0.3,
  messages: [
    { role: "system", content: generate.txt },
    { role: "user", content: `Create an agent configuration based on: "${description}"` },
  ],
  model,
  schema: z.object({ identifier, whenToUse, systemPrompt }),
})

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// 流控制
{ type: "start" }
{ type: "finish" }

// 文本输出
{ type: "text-start" }
{ type: "text-delta", text: string }
{ type: "text-end" }

// 思考链（部分模型如 Claude、o1）
{ type: "reasoning-start", id: string }
{ type: "reasoning-delta", id: string, text: string, providerMetadata?: any }
{ type: "reasoning-end", id: string }

// 工具调用
{ type: "tool-input-start", id: string, toolName: string }
{ type: "tool-input-delta", id: string, text: string }
{ type: "tool-input-end", id: string }
{ type: "tool-call", toolCallId: string, toolName: string, input: any }
{ type: "tool-result", toolCallId: string, output: any }
{ type: "tool-error", toolCallId: string, error: any }

// 步骤控制（多步调用时）
{ type: "start-step" }
{ type: "finish-step", finishReason: string, usage: LanguageModelUsage, providerMetadata?: any }

// 错误
{ type: "error", error: any }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

const recentParts = parts.slice(-DOOM_LOOP_THRESHOLD)  // 3

if (
  recentParts.length === DOOM_LOOP_THRESHOLD &&
  recentParts.every(part =>
    part.type === "tool" &&
    part.tool === value.toolName &&
    JSON.stringify(part.state.input) === JSON.stringify(value.input)
  )
) {
  yield* permission.ask({ permission: "doom_loop", ... })
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

interface AgentInfo {
  name: string
  description?: string
  mode: "subagent" | "primary" | "all"
  native?: boolean
  hidden?: boolean
  topP?: number
  temperature?: number
  color?: string
  permission: PermissionRuleset
  model?: { modelID: string; providerID: string }
  variant?: string
  prompt?: string        // 自定义 system prompt（如 explore agent 有专用 prompt）
  options: Record<string, unknown>
  steps?: number         // 最大循环步数
}

1
2
3
4

for (const [key, value] of Object.entries(cfg.agent ?? {})) {
  if (value.disable) { delete agents[key]; continue }
  // 合并/覆盖配置...
}

1
2
3
4
5
6
7
8

// llm.ts:449-454
function resolveTools(input) {
  const disabled = Permission.disabled(
    Object.keys(input.tools),
    Permission.merge(input.agent.permission, input.permission ?? []),
  )
  return Record.filter(input.tools, (_, k) => input.user.tools?.[k] !== false && !disabled.has(k))
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

type ToolContext = {
  sessionID: string
  abort: AbortSignal
  messageID: string
  callID: string
  agent: string
  messages: MessageV2.WithParts[]
  metadata: (val) => Effect  // 更新工具调用元数据
  ask: (req) => Effect       // 权限询问
  extra: {
    model: Provider.Model
    bypassAgentCheck: boolean
    promptOps: TaskPromptOps
  }
}