审计事件标准 struct + 转换 helper（收敛版，v0.6 落地）。

目的：让集成方一行代码把 CMDC Agent 运行事件落到 audit_logs 表， 不必为众多 EventBus 事件 + telemetry 事件各写一段 case 翻译。

字段约定

借鉴 AWS CloudTrail / GitHub Audit Log 等行业稳定 schema:

推荐使用方式

方式 1:订阅 :after_turn Plugin hook(高价值快路径)

defmodule MyApp.Plugins.AuditSink do
  @behaviour CMDC.Plugin

  @impl true
  def init(opts), do: {:ok, opts}
  @impl true
  def priority, do: 900

  @impl true
  def handle_event({:after_turn, payload}, state, ctx) do
    audit = CMDC.AuditEvent.from_turn(payload, ctx)
    MyApp.AuditLogs.insert!(audit)
    {:continue, state}
  end
  def handle_event(_, state, _), do: {:continue, state}
end

一行写一条 audit_log,带本轮 outcome / messages_diff / token_usage_diff / duration。

方式 2:订阅 EventBus 事件(v0.6+ from_event/3)

CMDC.subscribe(session)

receive do
  {:cmdc_event, sid, event} ->
    case CMDC.AuditEvent.from_event(event, %{session_id: sid}) do
      nil -> :ok
      audit -> MyApp.AuditLogs.insert!(audit)
    end
end

v0.6 收敛版覆盖核心 EventBus 事件，并包含推理事件投影:

• 会话生命周期::agent_start / :agent_end / :agent_abort
• 审批::approval_required / :approval_resolved
• 子代理::subagent_start / :subagent_end
• 工具::tool_execution_start / :tool_execution_end / :tool_blocked
• 系统::compact_start / :compact_end / :model_switched
• 推理::reasoning_thought / :reasoning_branch / :reasoning_score / :reasoning_prune / :reasoning_done
• 错误::stream_error / :error

剩余流式 / 业务事件(:message_delta / :thinking_delta / :status_update 等)按集成方反馈在 v0.6.x patch 滚动加;调用方可用 actor_resolver / target_resolver 自扩展。

方式 3:订阅细粒度 telemetry 事件(细粒度审计)

:telemetry.attach_many(
  "audit-sink",
  CMDC.Telemetry.all_events(),
  fn name, meas, meta, _ ->
    case CMDC.AuditEvent.from_telemetry(name, meas, meta) do
      nil -> :ok          # 不在当前覆盖集
      event -> MyApp.AuditLogs.insert!(event)
    end
  end,
  nil
)

v0.6 收敛版覆盖 18 个 telemetry 事件:

• turn:agent.turn.start/stop
• llm:llm.request.start/stop
• tool:tool.exec.start/stop
• plugin:plugin.pipeline.start/stop / plugin.crash
• compactor:compactor.run.start/stop
• checkpoint:checkpoint.save / checkpoint.load
• subagent:subagent.start/stop
• hibernate:agent.hibernate.configured
• provider registry:provider.registry.lookup / provider.registry.register

剩余 telemetry 事件按反馈滚动加。

resolver 注入扩展(v0.6+)

在 from_event/3 / from_telemetry/4 的 opts 传入:

• :actor_resolver :: (ctx, {default_actor_type, default_actor_id}) -> {atom, String.t()} | nil 返回 nil 走默认;返新 tuple 覆盖

• :target_resolver :: (event, ctx, {default_target_type, default_target_id}) -> {String.t(), String.t()} | nil

• :tags_resolver :: (event, ctx) -> [String.t()] | nil — 自定义 tags

resolver 抛异常 fail-safe(自动 rescue 后用默认值)。

audit = CMDC.AuditEvent.from_event(event, ctx,
  actor_resolver: fn ctx, _default -> {:user, ctx.user_data[:account_id]} end,
  tags_resolver: fn _event, ctx -> ["tenant:" <> ctx.user_data[:tenant]] end
)

序列化

@derive Jason.Encoder 直接 Jason.encode!(audit) 落 JSON;反序列化用 Jason.decode!(json, keys: :atoms!)(请配套使用 :atoms! 避免 atom table 泄漏)。

v0.5 → v0.6 兼容性

• schema_version 从 1 升到 2,加 :tags 字段(默认 [])
• 老 v1 消费者读 v2 兼容(忽略 :tags 字段即可)
• from_turn/2 API 完全不变,命名 "agent.turn.finished/aborted" 保留
• from_telemetry/3 老 6 事件 API 完全不变;新增 12 事件 + 4 元 opts 形式