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

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

13 种事件（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+（最后执行）

最小实现示例

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。