Plugin behaviour 定义。所有插件实现此 behaviour。

Plugin 系统是拦截 Agent 生命周期的核心切面：14 个事件 × 8 种 action。 本 moduledoc 给出速查表与最小实现示例。完整范例见 guides/cookbook.md。

14 种事件（event）— 速查表

:after_turn payload 字段

Plugin 通过 handle_event({:after_turn, payload}, state, ctx) 接收。 payload :: map() 含：

• :outcome — :finished | :aborted

• :abort_reason — term() | nil（仅在 :aborted 时非 nil）

• :messages_diff — [CMDC.Message.t()] 本次 prompt cycle 新增的消息（按时间顺序）
• :token_usage_diff — %CMDC.TokenUsage{} 本次增量
• :started_at_ms / :ended_at_ms / :duration_ms

与 :session_end 的区别：

• :session_end 无 payload，保持现状（不破坏 EventLogger 等老 Plugin）
• :after_turn 带结构化 payload，新 Plugin 推荐使用；典型场景： 把本轮对话写入审计 / 长期记忆 / 计费系统

8 种 Action

Hook × Action 完整矩阵

下表标 ✓ 表示该 hook 接受该 action；- 表示该 hook 不支持该 action（Pipeline 内部 忽略并继续处理后续 plugin，不抛错）。每个 hook 都隐含支持 :continue 和 :emit。

*:on_tool_error 在 Task retry 内部 Pipeline 触发，无完整 Agent state 上下文，:switch_model action 被收集但不应用（避免脏写 state.model）。 若需基于工具失败切 model，请在 :after_tool 钩子中匹配 {:error, _} result。

Action 失败/嵌套语义补充

• :abort 短路：Pipeline 立即停止，后续 plugin 不再执行；Agent 直接回 idle
  • 广播 {:agent_abort, reason} + 触发 :after_turn (outcome=:aborted)
• :block_tool 短路（仅 :before_tool）：当前工具不执行，注入 synthetic error tool_result；后续 plugin 也不再执行；其他工具继续按 batch 调度
• :skip 短路：跳过所有后续 plugin，但不影响 Agent 主流程（Agent 按"无 action" 继续推进）
• :intervene 累积式：多个 plugin 同时 intervene 时，prompt 按 priority 顺序 拼接（ 分隔），最终一次性注入；不短路
• :replace_tool_args 覆盖式：多个 plugin 同时返回时取最后执行（priority 最大） 的值；不短路
• :emit 累积式：所有 plugin 的 emit 事件按时序追加到 emitted_events, Pipeline 结束后 Agent 统一 broadcast；不短路；支持 4 种形态：
  • {:emit, {name, payload}, state} — 单事件
  • {:emit, [{name, payload}, ...], state} — 多事件
  • {:emit, name, payload, state} — 4 元简写
  • {:emit, {name, a, b}, state} — 3 元 tuple payload（如 :update_system_context）
• :switch_model 覆盖式：多个 plugin 同时返回时取最后执行（priority 最大）的值; 支持 3 元和 4 元两种形态；4 元 {:switch_model, model, state, provider_opts: [...]} 同步切 provider 参数

Plugin emit 自动注入 user_data

emit 出来的 {:plugin_event, name, payload} 事件，当 payload 是 map 时， Agent 会自动 merge state.user_data 到 :user_data 字段（仅当 payload 不含 :user_data 时）。Plugin 可在 payload 中加 :_no_user_data 键 opt-out （broadcast 前自动 pop）。订阅方可以直接从 payload.user_data 反查业务账号。

优先级范围

• P0 安全类：0-99（最先执行）
• P1 核心类：100-299
• P2 质量类：300-599
• P3 智能类：600-899
• 自定义：900+（最后执行）

运行期热更 Plugin opts（v0.6+）

集成方可通过 CMDC.update_plugin_opts/3 在长会话中调整已注册 Plugin 的运行时 参数，无需停 Agent 重启。改动语义如下：

• 入队即返：update_plugin_opts/3 是 cast，立即返回 :ok，新 opts 进 state.pending_plugin_opts 队列（同一 plugin 多次更新 LWW 覆盖）
• 仅 idle 生效：Agent 进入 idle 状态时统一 flush，期间状态机不动； running / streaming / executing_tools 期间排队等待，避免热路径状态错乱
• :before_plugin_opts_update hook：flush 时先走一次 Plugin Pipeline，其它 Plugin 可 :abort / :skip 拒绝（典型场景：SecurityGuard 校验新 opts 合法性）
• 可选 on_config_update/2 callback：未实现的 Plugin 走默认替换语义 （新 plugin_state = new_opts 当 map，否则直接取 new_opts）
• 结果广播：每条 flush 完成后 emit {:plugin_opts_updated, %{plugin, success?, error}}

何时实现 on_config_update/2

仅当 Plugin 内部 state 是结构化的复合数据（含计数器 / 缓存 / 子结构）、并且热更 时希望"保留运行时累积值、只覆盖配置部分"时需要实现。简单"opts == state"的 Plugin 让默认实现兜底即可。

最小实现示例

defmodule MyApp.AuditPlugin do
  @moduledoc "记录所有工具调用。"
  @behaviour CMDC.Plugin

  @impl true
  def init(_opts), do: {:ok, %{calls: []}}

  @impl true
  def priority, do: 500

  @impl true
  def handle_event({:before_tool, name, args}, state, _ctx) do
    {:continue, %{state | calls: [{name, args} | state.calls]}}
  end

  def handle_event(_event, state, _ctx), do: {:continue, state}
end

5 个完整 Cookbook（DangerousCommandGuard / PromptAuditLog / BudgetGuard / ToolFallbackGuard / SteeringContentGuard）见 guides/cookbook.md。