OpenCode 插件系统与数据库架构深度解析

OpenCode 插件系统与数据库架构深度解析

本文以 opencode 源码为参照，详细分析 third/ 目录下两个第三方插件的生效逻辑、插件的 Hook 分发机制，以及运行时数据库的读写模式。

一、插件加载机制

openCode 的插件系统入口位于 packages/opencode/src/plugin/index.ts，加载流程如下：

1. 配置解析与安装

用户在 opencode.json 中声明插件：

{
  "plugin": [
    "@devtheops/opencode-plugin-otel",
    "superpowers@git+https://github.com/obra/superpowers.git"
  ]
}

PluginLoader.loadExternal() 解析每个 specifier，通过 resolvePluginTarget() 安装 npm 包（或从 git URL 拉取），定位入口文件。

2. 入口提取

模块加载后，applyPlugin 按两种模式识别插件：

• V1 模式：readV1Plugin() 检查是否存在 { id, server: Plugin } 结构的默认导出
• Legacy 模式：getLegacyPlugins() 遍历模块的所有导出，将函数值直接当作 Plugin 实例

3. Hook 注册

所有插件的 Plugin(input) 被调用后返回 Hooks 对象，按顺序存入内部数组。分发方式有三种：

Trigger Hook 的核心逻辑是一个简单的遍历（index.ts:302-315）：

const trigger = Effect.fn("Plugin.trigger")(function* (name, input, output) {
  for (const hook of s.hooks) {
    const fn = hook[name]
    if (!fn) continue
    yield* Effect.promise(async () => fn(input, output))
  }
  return output
})

执行顺序：内置插件（CodexAuth、CopilotAuth 等）先 push，外部插件按 opencode.json 声明顺序依次 push，之后所有 Hook 点按此顺序遍历。没有优先级或排序机制。

二、superpowers 插件的生效逻辑

文件：third/superpowers/.opencode/plugins/superpowers.js

这是一个纯 JavaScript 的单文件插件（107 行），通过两个 Hook 注入技能系统：

Hook 1：config（注册 skills 路径）

config: async (config) => {
  config.skills.paths.push(superpowersSkillsDir)
}

初始化时向 opencode 的 config.skills.paths 注入自己的 skills 目录（<installed-dir>/skills/），让 opencode 启动后自动发现所有 14 个技能（brainstorming、systematic-debugging、test-driven-development 等），无需用户手动配置 symlink。

Hook 2：experimental.chat.system.transform（注入系统引导）

'experimental.chat.system.transform': async (_input, output) => {
  output.system.push(getBootstrapContent())
}

每次构造 LLM 的 system prompt 时，读取 using-superpowers 技能的 SKILL.md 内容（去 frontmatter），包裹在 <EXTREMELY_IMPORTANT> 标签中追加到 system prompt 数组。这使 AI agent 在每次对话中都被强制要求在行动前检查并调用相关 skill。

这个 Hook 在两处被触发（agent/agent.ts:381 和 session/llm/request.ts:70），因此不止执行一次。但由于 output.system 每次都是调用方新创建的局部数组，不存在重复追加问题。

三、opencode-plugin-otel 插件的生效逻辑

文件：third/opencode-plugin-otel/src/index.ts

这是一个 TypeScript 插件（349 行），将 session 遥测数据通过 OpenTelemetry 协议（OTLP over gRPC/HTTP）导出。所有遥测由 OPENCODE_ENABLE_TELEMETRY 环境变量控制。

核心架构

插件函数体内惰性初始化 OTel SDK（MeterProvider、LoggerProvider、TracerProvider），然后返回三个 Hook：

config Hook

简单调整日志级别。

chat.message Hook

每次用户发送消息时触发（session/prompt.ts），启动 session span（如果尚未存在），记录 user_prompt 日志事件，并初始化 token/cost 计数器。

event Hook

订阅所有 opencode 事件，按类型分发给不同 hander：

注册 SIGTERM/SIGINT/beforeExit 信号实现优雅 shutdown。

遥测无法跨插件监控

当前架构下，一个插件无法以通用方式监控另一个插件 Hook 的执行。因为 hooks 数组是内部闭包的局部变量，Plugin.trigger() 不产生任何可监听的事件——没有优先级、没有 lifecycle hook。只能通过外部 OTLP 后端间接观察 otel 插件自身的指标，或修改核心代码增加 Hook 生命周期事件。

四、LLM 消息的构造流程

这是理解系统提示词注入和数据库读写模式的关键。每次 LLM 调用时：

构造链路（prompt.ts → llm.ts → request.ts）

1. msgs = 从 session_message 表取出全部消息（从最近 compaction 点起）
2. system = [...env, ...instructions, ...mcpInstructions, ...skills]
           └── 每轮重新构造，包含:
               · 当前模型名称、工作目录、日期（new Date().toDateString()）
               · 项目 references 列表
               · agent 可用的 skills 列表
               · MCP server 的指令
3. modelMsgs = MessageV2.toModelMessagesEffect(msgs, model)
4. → Plugin.trigger("experimental.chat.messages.transform", {}, { messages: msgs })
5. → handle.process({ system, messages: modelMsgs })
6. LLMRequestPrep.prepare() 中:
   · system 数组 join 成 header 字符串
   · Plugin.trigger("experimental.chat.system.transform", ..., { system })
   · messages = [{ role: "system", content: x }, ...] + modelMsgs
   · 最终传给 LLM

experimental.chat.system.transform 是插件修改 system prompt 的唯一入口。system prompt 不在 session 持久化的历史中——它是每轮动态构造的局部变量。

对 LLM 缓存的影响

由于 system prompt 每轮重新构造，include 的内容可能变化（如 Today's date 跨天变化、references 增删、skills 列表变化），LLM 服务端的 prompt caching（如 Anthropic 的 cache control）无法获得稳定的前缀命中。opencode 选择了新鲜度优先的设计原则。

五、数据库架构与运行时操作

引擎与配置

• 引擎：SQLite（WAL 模式）
• 文件位置：~/.local/share/opencode/opencode.db
• PRAGMA：journal_mode=WAL、synchronous=NORMAL、busy_timeout=5000、cache_size=-64000（64MB）、foreign_keys=ON

8 张核心表

session                              event_sequence
├── id (PK)                          ├── aggregate_id (PK, FK → session.id)
├── project_id (FK)                  ├── seq
├── title, slug, directory           └── owner_id
├── cost, tokens_*  (实时累加)
├── permission, model, agent         event
├── time_compacting                  ├── id (PK)
└── time_archived (从未写入)         ├── aggregate_id (FK)
                                     ├── seq
session_message                      ├── type
├── id (PK)                          └── data (JSON)
├── session_id (FK, cascade delete)
├── type (user/assistant/shell/      message (V1 遗留)     part (V1 遗留)
│         system/compaction/         (session 级)          (message 级)
│         synthetic/agent-switched/
│         model-switched)
├── seq (unique per session)         session_input          todo
├── data (JSON)                      ├── id (PK)           ├── session_id+position (PK)
└── time_created                     ├── session_id (FK)   ├── content, status
                                     ├── prompt (JSON)     └── priority
session_context_epoch                ├── delivery
├── session_id (PK, FK)              ├── admitted_seq
├── baseline                         └── promoted_seq
├── snapshot (JSON)
└── baseline_seq

核心读写流程

读操作（每次 LLM 请求前）

-- 1. 找到最新 compaction 点
SELECT seq FROM session_message
WHERE session_id = ? AND type = 'compaction'
ORDER BY seq DESC LIMIT 1

-- 2. 从该点加载全量消息
SELECT * FROM session_message
WHERE session_id = ? AND seq >= ?
ORDER BY seq ASC

-- 3. 加载系统上下文基线
SELECT * FROM session_context_epoch WHERE session_id = ?

写操作（每个事件触发级联写入）

用户输入 → publish(session.next.prompted):
  ├── INSERT event (持久化事件)
  └── SessionProjector:
        ├── INSERT session_message (type="user", seq=N)
        └── UPSERT session_input (delivery="steer", admitted_seq=N)

step started → INSERT session_message (type="assistant")  ← 新建一行
text delta   → 纯内存操作，不写 DB (delta 太多)
text ended   → UPDATE session_message (合并完整文本)
tool called  → UPDATE session_message (更新 tool state)
tool success → UPDATE session_message (写入 result)
step ended   → UPDATE session_message (补 finish, cost, tokens)
  └── 同时 UPDATE session SET cost += ?, tokens_* += ?

compaction   → INSERT session_message (type="compaction", seq=P)
  └── 不删除旧行，后续读取只从 seq >= P 处开始

关键点：同一轮 tool-calling 循环中，一个 assistant 消息只占一行 session_message，后续事件都是 UPDATE 同一行而非 INSERT 新行。

数据库膨胀

当前没有自动清理机制：

• Compaction 只是追加 summary 行 + "跳过"旧消息，不删除任何数据
• time_archived 字段存在于 schema 中，但未被任何代码写入
• 没有 TTL、没有到期清理、没有最大行数限制

唯一删除途径：手动删除 session（DELETE FROM session WHERE id = ?，级联清除所有子表）或执行 revert（删除指定 seq 之后的 session_message 和 session_input 行）。

六、Hook 与 Event 完全参考

Hook 类型定义在 packages/plugin/src/index.ts:222-335，Event 定义分散在 packages/schema/src/ 下的多个文件中。

6.1 全部 Hook（21 个）

生命周期 Hook（非 trigger 模式，6 个）

这些 Hook 不通过 Plugin.trigger() 调用，而是由 opencode 核心在特定时机直接调用。

Trigger Hook（(input, output) → void 模式，15 个）

这些 Hook 在特定执行点通过 Plugin.trigger(name, input, output) 调用，插件通过修改 output 对象来影响后续流程。

消息与 LLM 请求

工具生命周期

命令与 Shell

文本、压缩与其他

6.2 持久事件（32 个，session.next.*）

这些事件关联 aggregateID（= sessionID）和 seq，写入 event 表，支持 replay。每个事件 name 即为 type 字段值。

**Live-only（不持久化）**的 session.next.* 事件：text.delta、reasoning.delta、tool.input.delta、compaction.delta——这些流式增量事件仅实时广播，不写 event 表。

6.3 V1 遗留 Session 事件（9 个）

6.4 Session 状态事件（2 个）

6.5 其他 V2 事件（48 个）

全部为 live-only（不持久化）。

6.6 Hook 与 Event 的汇总

架构特点：

• event Hook 接收全部 90 种事件的推送，是插件感知系统状态的唯一通道
• 只有 32 个 session.next.* 持久事件会同时写入 event 和 session_message 两张表
• 同一轮 agent 循环中，一个 assistant 应答对应一行 session_message；step.started INSERT 该行，后续所有 text/tool step 事件 UPDATE 同一行
• experimental.chat.system.transform 是修改 system prompt 的唯一 trigger Hook
• tool.execute.before / tool.execute.after 覆盖所有类型的工具（内置工具 + MCP 工具 + task 子 agent）

总结