13.2 Plugin 生命周期钩子

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

---

上一节我们概览了 Plugin 接口的类型定义，本节将深入解析每个钩子的调用时机、输入输出结构和典型用法。

13.2.1 tool：注册自定义工具

tool?: { [key: string]: ToolDefinition }

tool 不是一个函数钩子，而是一个工具定义字典。Plugin 返回 Hooks 对象时，其中的 tool 字段会被 ToolRegistry 读取并注册为可用工具。

调用时机：Instance 初始化时，Plugin 加载完成后。 生效范围：注册的工具对所有 Agent 可用（受权限规则控制）。

13.2.2 config：配置注入

config?: (input: Config) => Promise<void>

调用时机：Plugin 加载完成后，在 Plugin.init() 中调用。 用途：Plugin 可以读取和修改全局配置。这主要用于 Plugin 需要根据当前配置动态调整行为的场景。

13.2.3 chat.params：LLM 调用参数拦截

"chat.params"?: (
  input: {
    sessionID: string
    agent: string
    model: Model
    provider: ProviderContext
    message: UserMessage
  },
  output: {
    temperature: number
    topP: number
    topK: number
    options: Record<string, any>
  },
) => Promise<void>

调用时机：每次调用 LLM 之前，在 LLM.stream() 中触发。 用途：修改发送给 LLM 的参数——温度、Top-P、Top-K，以及 Provider 特定的选项。

典型用法：oh-my-opencode 使用这个钩子为 Anthropic 模型注入 effort 参数（控制模型的推理深度）：

"chat.params": async (input, output) => {
  if (input.provider.info.id === "anthropic") {
    output.options["anthropic"] = {
      thinking: { type: "enabled", budget_tokens: 10000 }
    }
  }
}

13.2.4 chat.message：消息拦截与修改

"chat.message"?: (
  input: {
    sessionID: string
    agent?: string
    model?: { providerID: string; modelID: string }
    messageID?: string
    variant?: string
  },
  output: { message: UserMessage; parts: Part[] },
) => Promise<void>

调用时机：用户发送消息后、发送给 LLM 之前。 用途：修改用户消息内容，或在消息中注入额外的 Part（如文件引用、上下文信息）。

典型用法：在用户消息中自动注入项目规范：

"chat.message": async (input, output) => {
  output.parts.push({
    type: "text",
    text: "[CONTEXT] Project uses TypeScript with strict mode enabled."
  })
}

13.2.5 experimental.chat.messages.transform：消息列表变换

"experimental.chat.messages.transform"?: (
  input: {},
  output: {
    messages: {
      info: Message
      parts: Part[]
    }[]
  },
) => Promise<void>

调用时机：构建发送给 LLM 的消息列表时。 用途：对整个消息历史进行变换——可以过滤、重排、合并消息。这是比 chat.message（单条消息）更强大的钩子。

注意：experimental. 前缀表示这是实验性 API，未来可能发生变化。

13.2.6 experimental.chat.system.transform：系统提示词变换

"experimental.chat.system.transform"?: (
  input: { sessionID?: string; model: Model },
  output: { system: string[] },
) => Promise<void>

调用时机：构建 System Prompt 时。 用途：修改发送给 LLM 的系统提示词列表。可以添加、删除或替换系统提示词段落。

这是 oh-my-opencode 用来注入大量行为指令的主要钩子——Sisyphus Agent 的整套行为规范就是通过这个钩子注入的。

13.2.7 event：事件监听

event?: (input: { event: Event }) => Promise<void>

调用时机：任何事件通过 Bus 发布时。 用途：监听系统事件并执行副作用。

在 Plugin.init() 中，OpenCode 通过通配符订阅将所有 Bus 事件转发给 Plugin：

// plugin/index.ts
export async function init() {
  Bus.subscribeAll(async (input) => {
    const hooks = await state().then((x) => x.hooks)
    for (const hook of hooks) {
      hook["event"]?.({ event: input })
    }
  })
}

13.2.8 tool.execute.before / tool.execute.after：工具执行前后钩子

"tool.execute.before"?: (
  input: { tool: string; sessionID: string; callID: string },
  output: { args: any },
) => Promise<void>

"tool.execute.after"?: (
  input: { tool: string; sessionID: string; callID: string },
  output: { title: string; output: string; metadata: any },
) => Promise<void>

调用时机：每个工具执行前/后。 用途：

• before：修改工具的输入参数，或记录日志。

• after：修改工具的输出结果，或做后处理。

典型用法：操作日志记录：

"tool.execute.before": async (input, output) => {
  console.log(`[${input.tool}] called with:`, output.args)
}

13.2.9 experimental.session.compacting：压缩过程钩子

"experimental.session.compacting"?: (
  input: { sessionID: string },
  output: { context: string[]; prompt?: string },
) => Promise<void>

调用时机：Compaction（上下文压缩）执行前。 用途：

• 向压缩的上下文中注入额外信息（通过 context 数组）。

• 或完全替换压缩提示词（通过设置 prompt）。

13.2.10 钩子触发机制

所有钩子的触发通过 Plugin.trigger() 函数统一管理：

// plugin/index.ts
export async function trigger<Name extends keyof Hooks>(
  name: Name,
  input: Input,
  output: Output
): Promise<Output> {
  if (!name) return output
  for (const hook of await state().then((x) => x.hooks)) {
    const fn = hook[name]
    if (!fn) continue
    await fn(input, output)  // 顺序执行，每个 Plugin 可修改 output
  }
  return output
}

关键设计：

1. 链式执行：多个 Plugin 的同名钩子按注册顺序依次执行。

2. 共享 output：所有 Plugin 共享同一个 output 引用，后续 Plugin 看到的是前面 Plugin 修改后的结果。

3. await 串行：钩子函数是 await 串行执行的，确保前一个 Plugin 的修改在下一个 Plugin 执行前已完成。