OpenCode 实现原理

[Pines-Cheng]

Claude Code 多 Agent 架构和上下文工程的特点：

1. 多 Agent 架构的关键词：主从两层架构，子 Agent 按需动态创建，Agent 生命周期管理，Agent 事件通信机制，无状态隔离架构，静态工具过滤机制、子 Agent 可并发执行，用户可自定义子 Agent。
2. 上下文工程关键词：上下文隔离机制，最小必要信息，单向最终报告机制，三层存储架构，上下文窗口分层，Token 预算管理，自动压缩机制，8 段式结构化压缩 Prompt，智能文件（上下文）恢复机制，Token 缓存机制。

开源项目 OpenCode：https://github.com/sst/opencode ，简直就是 Claude Code 的开源实现版。
上面的那些关键词，比如：子 Agent 按需动态创建、无状态隔离架构、子 Agent 并发执行、用户自定义子 Agent、上下文隔离机制、单向最终报告机制等等等，它全部都实现且开源了。

多 Agent 架构核心设计

1. Agent 类型定义

系统定义了三种不同模式的 agent：

• primary: 主要 agent（如 build、plan）
• subagent: 子 agent（如 general）
• all: 可以在任何模式下使用的 agent

2. 内置 Agent 类型

系统预定义了几个核心 agent：

• general: 通用 agent，用于复杂问题研究、代码搜索和多步骤任务执行
• build: 构建相关的主要 agent
• plan: 规划相关的主要 agent，权限相对受限（编辑和 bash 权限为 "ask"）

3. Task Tool 实现机制

核心流程：

1. Agent 发现: 通过 Agent.list() 获取所有非主要模式的 agent
2. 动态描述生成: 将可用的 agent 列表动态插入到工具描述中
3. 会话创建: 为每个子任务创建独立的会话（Session）
4. 消息传递: 通过 Bus 系统进行实时消息传递和状态更新
5. 工具配置: 每个 agent 都有自己的工具权限配置

关键实现细节：

// 获取指定类型的 agent
const agent = await Agent.get(params.subagent_type)

// 创建独立会话
const session = await Session.create(ctx.sessionID, params.description + ` (@${agent.name} subagent)`)

// 配置 agent 特定的工具权限
tools: {
  todowrite: false,
  todoread: false, 
  task: false,  // 防止递归调用
  ...agent.tools,  // agent 特定工具
}

4. 权限管理系统

每个 agent 都有细粒度的权限控制：

• edit: 文件编辑权限
• bash: 命令执行权限（可按命令模式配置）
• webfetch: 网络请求权限

5. 消息和状态管理

• 使用 Bus 系统 进行 agent 间的消息传递
• 通过 MessageV2.Event.PartUpdated 事件实时更新任务状态
• 支持任务中止机制

6. 配置化扩展

系统支持通过配置文件动态添加自定义 agent，包括：

• 自定义模型配置
• 专用系统提示词
• 特定工具权限
• 温度和 top_p 参数调整

架构优势

1. 模块化: 每个 agent 专注于特定领域的任务
2. 隔离性: 独立的会话确保任务间不互相干扰
3. 可扩展性: 支持配置化添加新的 agent 类型
4. 权限控制: 细粒度的权限管理确保安全性
5. 实时通信: Bus 系统支持 agent 间的实时状态同步

这种架构实现了一个灵活、安全且可扩展的多 agent 系统，能够根据不同任务类型自动选择和调度合适的专业化 agent。

[Pines-Cheng]

根据代码分析，系统中的 agent 列表包括以下几种：

内置 Agent

1. general (通用 agent)

• 模式: subagent
• 描述: 通用目的 agent，用于研究复杂问题、搜索代码和执行多步骤任务
• 适用场景: 当你搜索关键词或文件但不确定能在前几次尝试中找到正确匹配时使用
• 工具权限: 继承默认工具配置，但禁用了 todoread 和 todowrite

2. build (构建 agent)

• 模式: primary
• 描述: 用于构建相关任务的主要 agent
• 工具权限: 拥有完整的默认工具权限

3. plan (规划 agent)

• 模式: primary
• 描述: 用于规划相关任务的主要 agent
• 权限特点: 相对受限，编辑和 bash 权限设置为 "ask"（需要询问）

自定义 Agent

系统还支持通过配置文件 (cfg.agent) 动态添加自定义 agent，这些 agent 可以配置：

• 自定义名称和描述
• 专用模型配置 (modelID, providerID)
• 自定义系统提示词 (prompt)
• 特定工具权限组合 (tools)
• 运行参数 (temperature, top_p)
• 运行模式 (subagent/primary/all)
• 权限控制 (edit/bash/webfetch)

Agent 生成功能

系统还提供了 Agent.generate() 功能，可以基于描述自动生成新的 agent 配置，包括：

• 唯一标识符
• 使用场景描述
• 系统提示词

这种设计使得系统既有稳定的内置 agent 来处理常见任务，又具备高度的可扩展性来适应特定需求。

[Pines-Cheng]

subagent 无状态隔离架构

基于代码分析，subagent 的无状态和自主性是通过以下几个关键机制实现的：

1. 无状态实现

独立会话隔离

// 每次调用都创建全新的独立会话
const session = await Session.create(ctx.sessionID, params.description + ` (@${agent.name} subagent)`)

每个 subagent 任务都在完全独立的会话中运行，不会保留任何历史状态或上下文。

一次性执行模式

const result = await Session.prompt({
  messageID,
  sessionID: session.id,
  // ... 配置参数
  parts: [
    {
      id: Identifier.ascending("part"),
      type: "text",
      text: params.prompt, // 完整的任务描述
    },
  ],
})

subagent 接收一个完整的任务描述，执行后返回结果，整个过程是原子性的。

2. 自主性实现

完整工具权限配置

tools: {
  todowrite: false,
  todoread: false,
  task: false,  // 防止递归调用
  ...agent.tools,  // agent 特定的工具集
}

每个 subagent 都配备了执行任务所需的完整工具集，能够自主完成复杂任务而无需外部干预。

权限自治

permission: {
  edit: "allow",     // 文件编辑权限
  bash: { "*": "allow" },  // 命令执行权限
  webfetch: "allow", // 网络请求权限
}

subagent 拥有执行任务所需的各种权限，可以自主进行文件操作、命令执行等。

模型和参数独立配置

const model = agent.model ?? {
  modelID: msg.info.modelID,
  providerID: msg.info.providerID,
}

每个 subagent 可以使用专门配置的模型和参数（temperature、top_p），优化其特定领域的表现。

3. 通信机制

实时状态反馈

const unsub = Bus.subscribe(MessageV2.Event.PartUpdated, async (evt) => {
  // 实时更新任务进度
  ctx.metadata({
    title: params.description,
    metadata: {
      summary: Object.values(parts).sort((a, b) => a.id?.localeCompare(b.id)),
    },
  })
})

通过 Bus 系统实现实时状态更新，但不影响 subagent 的无状态特性。

中止机制

ctx.abort.addEventListener("abort", () => {
  Session.abort(session.id)
})

支持任务中止，确保资源管理的自主性。

4. 设计原则

根据 task.txt 中的说明：

"Each agent invocation is stateless. You will not be able to send additional messages to the agent, nor will the agent be able to communicate with you outside of its final report."

这确保了：

• 单次交互: 一次调用，一次响应
• 完整任务描述: 必须在初始提示中包含所有必要信息
• 自包含执行: subagent 必须能够独立完成整个任务

这种设计使得 subagent 既能够处理复杂任务，又保持了系统的简洁性和可预测性。

[Pines-Cheng]

subagent 并发执行

subagent 可以并发执行。从代码和设计文档中可以看出几个支持并发的关键特性：

1. 架构支持并发

独立会话设计

const session = await Session.create(ctx.sessionID, params.description + ` (@${agent.name} subagent)`)

每个 subagent 都运行在完全独立的会话中，彼此之间没有状态依赖，天然支持并发执行。

无状态特性

由于每个 subagent 调用都是无状态的，多个 subagent 可以同时运行而不会产生竞态条件或状态冲突。

2. 明确的并发建议

在 task.txt 文档中明确提到：

"Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses"

这表明系统设计时就考虑了并发执行，并且鼓励这种使用方式。

3. 实时状态管理

Bus 系统支持多任务

const unsub = Bus.subscribe(MessageV2.Event.PartUpdated, async (evt) => {
  if (evt.properties.part.sessionID !== session.id) return
  // 每个会话独立处理自己的事件
})

Bus 事件系统通过 sessionID 区分不同的 subagent 任务，支持多个任务同时进行状态更新。

独立的消息 ID

const messageID = Identifier.ascending("message")

每个 subagent 都有独立的消息标识符，避免了并发时的 ID 冲突。

4. 并发执行的优势

• 性能提升: 多个任务可以并行处理，显著提高整体执行效率
• 资源利用: 充分利用系统资源，避免串行等待
• 任务隔离: 一个 subagent 的失败不会影响其他并发执行的 subagent

5. 使用示例

根据文档建议，可以在单个消息中启动多个 subagent：

// 伪代码示例
Task(description="Search code", prompt="Find all API endpoints", subagent_type="general")
Task(description="Check tests", prompt="Analyze test coverage", subagent_type="general") 
Task(description="Review docs", prompt="Check documentation completeness", subagent_type="general")

这种设计使得系统能够高效处理复杂的多步骤任务，通过并发执行多个专业化的 subagent 来完成不同方面的工作。

[Pines-Cheng]

subagent 按需动态创建

subagent 支持按需动态创建。从代码中可以看到几个关键的动态创建机制：

1. 运行时动态生成

Agent.generate() 方法

export async function generate(input: { description: string }) {
  const defaultModel = await Provider.defaultModel()
  const model = await Provider.getModel(defaultModel.providerID, defaultModel.modelID)
  const system = SystemPrompt.header(defaultModel.providerID)
  system.push(PROMPT_GENERATE)
  const existing = await list()
  const result = await generateObject({
    // ...
    content: `Create an agent configuration based on this request: \"${input.description}\".\n\nIMPORTANT: The following identifiers already exist and must NOT be used: ${existing.map((i) => i.name).join(", ")}\n  Return ONLY the JSON object, no other text, do not wrap in backticks`,
    // ...
    schema: z.object({
      identifier: z.string(),
      whenToUse: z.string(), 
      systemPrompt: z.string(),
    }),
  })
  return result.object
}

这个方法可以基于描述自动生成新的 agent 配置，包括：

• 唯一标识符: 自动避免与现有 agent 冲突
• 使用场景: 描述何时使用该 agent
• 系统提示词: 为 agent 定制专门的行为指令

2. 配置驱动的动态加载

配置文件支持

for (const [key, value] of Object.entries(cfg.agent ?? {})) {
  if (value.disable) {
    delete result[key]
    continue
  }
  let item = result[key]
  if (!item)
    item = result[key] = {
      name: key,
      mode: "all",
      permission: agentPermission,
      options: {},
      tools: {},
      builtIn: false,  // 标记为非内置
    }
  // 动态配置各种属性...
}

系统可以通过配置文件动态添加新的 agent 类型，无需重启或重新部署。

3. 实例状态管理

Instance.state() 机制

const state = Instance.state(async () => {
  const cfg = await Config.get()
  // 每次都重新计算可用的 agent 列表
  const result: Record<string, Info> = { /* ... */ }
  return result
})

使用 Instance.state() 确保 agent 列表是动态计算的，可以实时反映配置变化。

4. 动态创建的优势

• 灵活性: 可以根据具体需求临时创建专门的 agent
• 扩展性: 无需修改核心代码就能添加新功能
• 智能化: 通过 AI 自动生成合适的 agent 配置
• 避免冲突: 自动检查现有 agent 名称，确保唯一性

5. 使用场景

动态创建特别适用于：

• 处理特定领域的专业任务
• 临时性的复杂工作流
• 需要特殊权限配置的任务
• 实验性功能的快速原型

这种设计使得系统既有稳定的内置 agent 处理常见任务，又能够灵活地按需创建专门的 agent 来处理特殊需求。

[Pines-Cheng]

无状态隔离架构

这个系统采用了完整的无状态隔离架构。从代码分析可以看出以下几个关键的架构特征：

1. 会话级隔离

独立会话创建

const session = await Session.create(ctx.sessionID, params.description + ` (@${agent.name} subagent)`)

每个 agent 执行都在完全独立的会话中运行，确保状态完全隔离。

唯一消息标识

const messageID = Identifier.ascending("message")

每次调用都生成独立的消息 ID，避免状态混淆。

2. 状态管理架构

Instance.state() 模式

const state = Instance.state(async () => {
  const cfg = await Config.get()
  // 每次都重新计算状态
  return result
})

使用函数式状态管理，每次访问都重新计算，确保无状态特性。

配置驱动

Agent 的所有行为都由配置驱动，而不是内部状态：

export async function get(agent: string) {
  return state().then((x) => x[agent])
}

3. 进程隔离机制

事件总线隔离

const unsub = Bus.subscribe(MessageV2.Event.PartUpdated, async (evt) => {
  if (evt.properties.part.sessionID !== session.id) return
  // 只处理自己会话的事件
})

通过 sessionID 确保事件处理的隔离性。

工具权限隔离

tools: {
  todowrite: false,
  todoread: false,
  task: false,  // 防止递归调用
  ...agent.tools,
}

每个 agent 都有独立的工具权限配置，防止相互干扰。

4. 权限隔离

细粒度权限控制

function mergeAgentPermissions(basePermission: any, overridePermission: any): Agent.Info["permission"] {
  // 每个 agent 独立的权限配置
  const result: Agent.Info["permission"] = {
    edit: merged.edit ?? "allow",
    webfetch: merged.webfetch ?? "allow", 
    bash: mergedBash ?? { "*": "allow" },
  }
  return result
}

5. 架构优势

• 故障隔离: 一个 agent 的失败不会影响其他 agent
• 并发安全: 多个 agent 可以安全并发执行
• 资源隔离: 每个 agent 有独立的资源配额和权限
• 状态一致性: 无状态设计避免了状态同步问题
• 可扩展性: 新增 agent 不会影响现有系统

6. 无状态验证

从 task.txt 的描述也证实了这一点：

"Each agent invocation is stateless. You will not be able to send additional messages to the agent"

这种架构确保了系统的高可靠性、可扩展性和维护性，是典型的微服务无状态架构模式在 AI Agent 系统中的应用。

[Pines-Cheng]

自定义子 Agent

用户完全可以自定义子 Agent。从代码分析可以看到系统提供了多种自定义方式：

1. 配置文件自定义

通过配置添加自定义 Agent

for (const [key, value] of Object.entries(cfg.agent ?? {})) {
  if (value.disable) {
    delete result[key]
    continue
  }
  let item = result[key]
  if (!item)
    item = result[key] = {
      name: key,
      mode: "all",
      permission: agentPermission,
      options: {},
      tools: {},
      builtIn: false,  // 标记为非内置
    }
  // 支持自定义各种属性...
}

用户可以在配置文件中定义新的 agent，包括：

可自定义的属性

• name: Agent 名称
• description: Agent 描述和用途说明
• model: 专用模型配置 (modelID, providerID)
• prompt: 自定义系统提示词
• tools: 工具权限配置
• temperature: 创造性参数
• top_p: 采样参数
• mode: 运行模式 (subagent/primary/all)
• permission: 权限控制 (edit/bash/webfetch)

2. 动态生成自定义 Agent

Agent.generate() 功能

export async function generate(input: { description: string }) {
  // ...
  const result = await generateObject({
    // ...
    schema: z.object({
      identifier: z.string(),
      whenToUse: z.string(),
      systemPrompt: z.string(),
    }),
  })
  return result.object
}

系统可以基于用户描述自动生成新的 agent 配置，包括：

• 唯一标识符
• 使用场景描述
• 专门的系统提示词

3. 权限细粒度控制

自定义权限配置

function mergeAgentPermissions(basePermission: any, overridePermission: any): Agent.Info["permission"] {
  // 支持细粒度权限配置
  const result: Agent.Info["permission"] = {
    edit: merged.edit ?? "allow",
    webfetch: merged.webfetch ?? "allow",
    bash: mergedBash ?? { "*": "allow" },
  }
  return result
}

用户可以为自定义 agent 配置不同的权限级别：

• edit: "allow" | "ask" | "deny"
• bash: 按命令模式配置
• webfetch: 网络访问权限

4. 工具集自定义

灵活的工具配置

item.tools = {
  ...defaultTools,
  ...item.tools,
}

用户可以为自定义 agent 配置专门的工具集，启用或禁用特定工具。

5. 配置示例

用户可以在配置文件中这样定义自定义 agent：

{
  "agent": {
    "code-reviewer": {
      "description": "专门用于代码审查的 agent",
      "prompt": "你是一个专业的代码审查员...",
      "model": "anthropic/claude-3-5-sonnet-20241022",
      "temperature": 0.1,
      "mode": "subagent",
      "tools": {
        "read": true,
        "edit": false,
        "bash": false
      },
      "permission": {
        "edit": "ask",
        "bash": "deny",
        "webfetch": "allow"
      }
    }
  }
}

6. 动态加载和热更新

由于使用了 Instance.state() 机制，自定义 agent 配置可以动态加载，无需重启系统。

这种设计使得用户可以根据具体需求创建专门的 agent，实现高度的定制化和扩展性。

[Pines-Cheng]

DeepWiki Q&A with Code Context for Repository: sst/opencode

Q1

上下文压缩是怎么做的？

Answer

您询问的是上下文压缩(context compaction)的实现方式。 opencode:1-16

压缩触发机制

上下文压缩在token使用量超过模型上下文窗口限制时自动触发。 opencode:29-37 isOverflow函数检查当前消息的token总数(输入+缓存读取+输出)是否超过可用上下文空间。

压缩流程

压缩过程分为两个主要步骤:

1. Prune(修剪)

首先执行prune函数来清理旧的工具调用输出。 opencode:45-83 该函数:

• 从最新消息向后遍历,保护最近40,000个token的工具调用 opencode:40-40
• 标记更早的工具调用输出为已压缩,但不删除它们 opencode:76-78
• 只有当可修剪的token数超过20,000时才执行修剪 opencode:39-39

2. Summarize(摘要生成)

然后执行run函数生成对话摘要。 opencode:85-173 该函数:

• 过滤出需要摘要的消息 opencode:94-94
• 使用AI模型生成摘要,提示词要求"提供详细但简洁的对话摘要,重点关注有助于继续对话的信息,包括我们做了什么、正在做什么、正在处理哪些文件以及接下来要做什么" opencode:138-144
• 创建一个新的assistant消息来存储摘要 opencode:102-124
• 发布压缩完成事件 opencode:165-167

用户界面集成

在TUI中,用户可以通过/compact命令手动触发压缩。 opencode:72-80 压缩完成后会显示成功提示。 opencode:660-663

Notes

压缩功能可以通过OPENCODE_DISABLE_AUTOCOMPACT和OPENCODE_DISABLE_PRUNE标志禁用。 opencode:30-30 opencode:46-46 这种两阶段设计(先修剪工具输出,再生成摘要)确保了在保持对话连贯性的同时有效管理token使用量。

Wiki pages you might want to explore:

• Tools and Permissions (sst/opencode)
• User Interfaces (sst/opencode)

Citations

File: packages/opencode/src/session/compaction.ts (L1-16)

import { generateText, type ModelMessage } from "ai"
import { Session } from "."
import { Identifier } from "../id/id"
import { Instance } from "../project/instance"
import { Provider } from "../provider/provider"
import { defer } from "../util/defer"
import { MessageV2 } from "./message-v2"
import { SystemPrompt } from "./system"
import { Bus } from "../bus"
import z from "zod/v4"
import type { ModelsDev } from "../provider/models"
import { SessionPrompt } from "./prompt"
import { Flag } from "../flag/flag"
import { Token } from "../util/token"
import { Log } from "../util/log"

File: packages/opencode/src/session/compaction.ts (L29-37)

  export function isOverflow(input: { tokens: MessageV2.Assistant["tokens"]; model: ModelsDev.Model }) {
    if (Flag.OPENCODE_DISABLE_AUTOCOMPACT) return false
    const context = input.model.limit.context
    if (context === 0) return false
    const count = input.tokens.input + input.tokens.cache.read + input.tokens.output
    const output = Math.min(input.model.limit.output, SessionPrompt.OUTPUT_TOKEN_MAX) || SessionPrompt.OUTPUT_TOKEN_MAX
    const usable = context - output
    return count > usable
  }

File: packages/opencode/src/session/compaction.ts (L39-39)

  export const PRUNE_MINIMUM = 20_000

File: packages/opencode/src/session/compaction.ts (L40-40)

  export const PRUNE_PROTECT = 40_000

File: packages/opencode/src/session/compaction.ts (L45-83)

  export async function prune(input: { sessionID: string }) {
    if (Flag.OPENCODE_DISABLE_PRUNE) return
    log.info("pruning")
    const msgs = await Session.messages(input.sessionID)
    let total = 0
    let pruned = 0
    const toPrune = []
    let turns = 0

    loop: for (let msgIndex = msgs.length - 1; msgIndex >= 0; msgIndex--) {
      const msg = msgs[msgIndex]
      if (msg.info.role === "user") turns++
      if (turns < 2) continue
      if (msg.info.role === "assistant" && msg.info.summary) break loop
      for (let partIndex = msg.parts.length - 1; partIndex >= 0; partIndex--) {
        const part = msg.parts[partIndex]
        if (part.type === "tool")
          if (part.state.status === "completed") {
            if (part.state.time.compacted) break loop
            const estimate = Token.estimate(part.state.output)
            total += estimate
            if (total > PRUNE_PROTECT) {
              pruned += estimate
              toPrune.push(part)
            }
          }
      }
    }
    log.info("found", { pruned, total })
    if (pruned > PRUNE_MINIMUM) {
      for (const part of toPrune) {
        if (part.state.status === "completed") {
          part.state.time.compacted = Date.now()
          await Session.updatePart(part)
        }
      }
      log.info("pruned", { count: toPrune.length })
    }
  }

File: packages/opencode/src/session/compaction.ts (L85-173)

  export async function run(input: { sessionID: string; providerID: string; modelID: string }) {
    await Session.update(input.sessionID, (draft) => {
      draft.time.compacting = Date.now()
    })
    await using _ = defer(async () => {
      await Session.update(input.sessionID, (draft) => {
        draft.time.compacting = undefined
      })
    })
    const toSummarize = await Session.messages(input.sessionID).then(MessageV2.filterSummarized)
    const model = await Provider.getModel(input.providerID, input.modelID)
    const system = [
      ...SystemPrompt.summarize(model.providerID),
      ...(await SystemPrompt.environment()),
      ...(await SystemPrompt.custom()),
    ]

    const msg = (await Session.updateMessage({
      id: Identifier.ascending("message"),
      role: "assistant",
      sessionID: input.sessionID,
      system,
      mode: "build",
      path: {
        cwd: Instance.directory,
        root: Instance.worktree,
      },
      cost: 0,
      tokens: {
        output: 0,
        input: 0,
        reasoning: 0,
        cache: { read: 0, write: 0 },
      },
      modelID: input.modelID,
      providerID: model.providerID,
      time: {
        created: Date.now(),
      },
    })) as MessageV2.Assistant
    const generated = await generateText({
      maxRetries: 10,
      model: model.language,
      messages: [
        ...system.map(
          (x): ModelMessage => ({
            role: "system",
            content: x,
          }),
        ),
        ...MessageV2.toModelMessage(toSummarize),
        {
          role: "user",
          content: [
            {
              type: "text",
              text: "Provide a detailed but concise summary of our conversation above. Focus on information that would be helpful for continuing the conversation, including what we did, what we're doing, which files we're working on, and what we're going to do next.",
            },
          ],
        },
      ],
    })
    const usage = Session.getUsage(model.info, generated.usage, generated.providerMetadata)
    msg.cost += usage.cost
    msg.tokens = usage.tokens
    msg.summary = true
    msg.time.completed = Date.now()
    await Session.updateMessage(msg)
    const part = await Session.updatePart({
      type: "text",
      sessionID: input.sessionID,
      messageID: msg.id,
      id: Identifier.ascending("part"),
      text: generated.text,
      time: {
        start: Date.now(),
        end: Date.now(),
      },
    })

    Bus.publish(Event.Compacted, {
      sessionID: input.sessionID,
    })

    return {
      info: msg,
      parts: [part],
    }
  }

File: packages/web/src/content/docs/tui.mdx (L72-80)

### compact

Compact the current session. _Alias_: `/summarize`

```bash frame="none"
/compact

Keybind: ctrl+x c

**File:** packages/tui/internal/tui/tui.go (L660-663)

```go
	case opencode.EventListResponseEventSessionCompacted:
		if msg.Properties.SessionID == a.app.Session.ID {
			return a, toast.NewSuccessToast("Session compacted successfully")
		}

Q2

压缩后的消息保存在哪里？

Answer

压缩后的消息通过 Session.updateMessage() 和 Session.updatePart() 保存到存储系统中。 opencode:152-163

存储位置

压缩生成的摘要消息作为一个新的 assistant 消息保存,包含以下信息: opencode:102-124

消息的具体存储路径遵循 Storage 命名空间的规则:

• 消息信息保存在: storage/message/{sessionID}/{messageID}.json opencode:263-299
• 消息部分(parts)保存在: storage/part/{messageID}/{partID}.json opencode:246-261

摘要消息的特殊标记

压缩生成的消息会被标记 summary: true,这样系统可以识别哪些消息是摘要。 opencode:150-150 opencode:285-285

后续使用

当需要获取会话消息时,MessageV2.filterSummarized() 函数会找到最后一个摘要消息,并只返回从该摘要开始的消息,从而实现上下文压缩的效果。 opencode:576-580 opencode:341-341

Notes

所有消息数据都通过 Storage 命名空间持久化到文件系统,存储在 Global.Path.data + "/storage" 目录下。压缩后的消息与普通消息使用相同的存储机制,只是通过 summary 字段进行区分。

Wiki pages you might want to explore:

• Core Architecture (sst/opencode)

Citations

File: packages/opencode/src/session/compaction.ts (L102-124)

    const msg = (await Session.updateMessage({
      id: Identifier.ascending("message"),
      role: "assistant",
      sessionID: input.sessionID,
      system,
      mode: "build",
      path: {
        cwd: Instance.directory,
        root: Instance.worktree,
      },
      cost: 0,
      tokens: {
        output: 0,
        input: 0,
        reasoning: 0,
        cache: { read: 0, write: 0 },
      },
      modelID: input.modelID,
      providerID: model.providerID,
      time: {
        created: Date.now(),
      },
    })) as MessageV2.Assistant

File: packages/opencode/src/session/compaction.ts (L150-150)

    msg.summary = true

File: packages/opencode/src/session/compaction.ts (L152-163)

    await Session.updateMessage(msg)
    const part = await Session.updatePart({
      type: "text",
      sessionID: input.sessionID,
      messageID: msg.id,
      id: Identifier.ascending("part"),
      text: generated.text,
      time: {
        start: Date.now(),
        end: Date.now(),
      },
    })

File: packages/opencode/src/session/message-v2.ts (L246-261)

  export const Part = z
    .discriminatedUnion("type", [
      TextPart,
      ReasoningPart,
      FilePart,
      ToolPart,
      StepStartPart,
      StepFinishPart,
      SnapshotPart,
      PatchPart,
      AgentPart,
    ])
    .meta({
      ref: "Part",
    })
  export type Part = z.infer<typeof Part>

File: packages/opencode/src/session/message-v2.ts (L263-299)

  export const Assistant = Base.extend({
    role: z.literal("assistant"),
    time: z.object({
      created: z.number(),
      completed: z.number().optional(),
    }),
    error: z
      .discriminatedUnion("name", [
        AuthError.Schema,
        NamedError.Unknown.Schema,
        OutputLengthError.Schema,
        AbortedError.Schema,
      ])
      .optional(),
    system: z.string().array(),
    modelID: z.string(),
    providerID: z.string(),
    mode: z.string(),
    path: z.object({
      cwd: z.string(),
      root: z.string(),
    }),
    summary: z.boolean().optional(),
    cost: z.number(),
    tokens: z.object({
      input: z.number(),
      output: z.number(),
      reasoning: z.number(),
      cache: z.object({
        read: z.number(),
        write: z.number(),
      }),
    }),
  }).meta({
    ref: "AssistantMessage",
  })
  export type Assistant = z.infer<typeof Assistant>

File: packages/opencode/src/session/message-v2.ts (L576-580)

  export function filterSummarized(msgs: { info: MessageV2.Info; parts: MessageV2.Part[] }[]) {
    const i = msgs.findLastIndex((m) => m.info.role === "assistant" && !!m.info.summary)
    if (i === -1) return msgs.slice()
    return msgs.slice(i)
  }

File: packages/opencode/src/session/prompt.ts (L341-341)

    let msgs = await Session.messages(input.sessionID).then(MessageV2.filterSummarized)

Q3

消息信息 和 消息部分(parts)分别是什么？

Answer

在OpenCode中,**消息信息(Message Info)和消息部分(Parts)**是两个独立但相关的数据结构,用于存储会话中的消息内容。 opencode:236-299

消息信息(Message Info)

消息信息是消息的元数据容器,包含消息的基本属性和状态信息。 opencode:263-299 根据角色不同,分为两种类型:

User消息

• id: 消息唯一标识符
• sessionID: 所属会话ID
• role: "user"
• time: 创建时间 opencode:236-244

Assistant消息

除了基本字段外,还包含:

• system: 系统提示词数组
• mode: 代理模式(如"build"、"plan")
• modelID/providerID: 使用的模型信息
• cost: 消费成本
• tokens: token使用统计(输入、输出、推理、缓存)
• path: 工作目录信息
• summary: 是否为摘要消息
• error: 错误信息(如果有) opencode:263-299

消息部分(Parts)

Parts是消息的实际内容载体,一个消息可以包含多个parts。 opencode:246-261 每个part都有:

• id: part唯一标识符
• messageID: 所属消息ID
• sessionID: 所属会话ID
• type: 类型标识

支持的part类型包括:

• TextPart: 文本内容 opencode:623-637
• ReasoningPart: 推理过程 opencode:639-652
• ToolPart: 工具调用及其状态
• FilePart: 文件附件
• AgentPart: 代理引用
• StepStartPart/StepFinishPart: 步骤标记 opencode:246-261

存储和使用

在存储层面,它们分别保存:

• Message Info: storage/message/{sessionID}/{messageID}.json
• Parts: storage/part/{messageID}/{partID}.json opencode:270-293

当获取消息时,系统会组合这两部分返回MessageV2.WithParts对象,包含info和parts数组。 opencode:336-340 opencode:197-208

Notes

这种分离设计允许:

1. 独立更新消息元数据和内容部分
2. 流式传输时逐步添加parts而不修改整个消息
3. 更细粒度的事件通知(message.updated和message.part.updated) opencode:1013-1033

Wiki pages you might want to explore:

• Core Architecture (sst/opencode)

Citations

File: packages/opencode/src/session/message-v2.ts (L236-299)

  export const User = Base.extend({
    role: z.literal("user"),
    time: z.object({
      created: z.number(),
    }),
  }).meta({
    ref: "UserMessage",
  })
  export type User = z.infer<typeof User>

  export const Part = z
    .discriminatedUnion("type", [
      TextPart,
      ReasoningPart,
      FilePart,
      ToolPart,
      StepStartPart,
      StepFinishPart,
      SnapshotPart,
      PatchPart,
      AgentPart,
    ])
    .meta({
      ref: "Part",
    })
  export type Part = z.infer<typeof Part>

  export const Assistant = Base.extend({
    role: z.literal("assistant"),
    time: z.object({
      created: z.number(),
      completed: z.number().optional(),
    }),
    error: z
      .discriminatedUnion("name", [
        AuthError.Schema,
        NamedError.Unknown.Schema,
        OutputLengthError.Schema,
        AbortedError.Schema,
      ])
      .optional(),
    system: z.string().array(),
    modelID: z.string(),
    providerID: z.string(),
    mode: z.string(),
    path: z.object({
      cwd: z.string(),
      root: z.string(),
    }),
    summary: z.boolean().optional(),
    cost: z.number(),
    tokens: z.object({
      input: z.number(),
      output: z.number(),
      reasoning: z.number(),
      cache: z.object({
        read: z.number(),
        write: z.number(),
      }),
    }),
  }).meta({
    ref: "AssistantMessage",
  })
  export type Assistant = z.infer<typeof Assistant>

File: packages/opencode/src/session/message-v2.ts (L336-340)

  export const WithParts = z.object({
    info: Info,
    parts: z.array(Part),
  })
  export type WithParts = z.infer<typeof WithParts>

File: packages/sdk/js/src/gen/types.gen.ts (L623-637)

export type TextPart = {
  id: string
  sessionID: string
  messageID: string
  type: "text"
  text: string
  synthetic?: boolean
  time?: {
    start: number
    end?: number
  }
  metadata?: {
    [key: string]: unknown
  }
}

File: packages/sdk/js/src/gen/types.gen.ts (L639-652)

export type ReasoningPart = {
  id: string
  sessionID: string
  messageID: string
  type: "reasoning"
  text: string
  metadata?: {
    [key: string]: unknown
  }
  time: {
    start: number
    end?: number
  }
}

File: packages/sdk/js/src/gen/types.gen.ts (L1013-1033)

export type EventMessageUpdated = {
  type: "message.updated"
  properties: {
    info: Message
  }
}

export type EventMessageRemoved = {
  type: "message.removed"
  properties: {
    sessionID: string
    messageID: string
  }
}

export type EventMessagePartUpdated = {
  type: "message.part.updated"
  properties: {
    part: Part
  }
}

File: packages/opencode/src/session/index.ts (L197-208)

  export async function messages(sessionID: string) {
    const result = [] as MessageV2.WithParts[]
    for (const p of await Storage.list(["message", sessionID])) {
      const read = await Storage.read<MessageV2.Info>(p)
      result.push({
        info: read,
        parts: await getParts(read.id),
      })
    }
    result.sort((a, b) => (a.info.id > b.info.id ? 1 : -1))
    return result
  }

File: packages/opencode/src/session/index.ts (L270-293)

  export async function updateMessage(msg: MessageV2.Info) {
    await Storage.write(["message", msg.sessionID, msg.id], msg)
    Bus.publish(MessageV2.Event.Updated, {
      info: msg,
    })
    return msg
  }

  export async function removeMessage(sessionID: string, messageID: string) {
    await Storage.remove(["message", sessionID, messageID])
    Bus.publish(MessageV2.Event.Removed, {
      sessionID,
      messageID,
    })
    return messageID
  }

  export async function updatePart(part: MessageV2.Part) {
    await Storage.write(["part", part.messageID, part.id], part)
    Bus.publish(MessageV2.Event.PartUpdated, {
      part,
    })
    return part
  }