CMDC.Checkpoint.Snapshot (cmdc v0.4.0)

Copy Markdown View Source

会话快照标准 payload。

统一 CMDC.Checkpoint.save/3 的输出与 load/2 的输入。 含 @schema_version 便于未来 schema 演进时向前兼容。

不可序列化字段策略

Agent.State 中以下字段在 save/2 时会被自动剥离， 并在 resume_session!/2 时由 plugin :session_start hook 重建：

  • pid() 字段（如 :agent_pid / :owner_pid）
  • Stream / Task 引用
  • :reference 字段（如 :monitor_ref）

这一策略避免序列化死引用、同时保证 plugin 状态可以靠 :session_start 重新初始化。Snapshot 会保留这些字段名加 :_stripped 标记 以便恢复时知道哪些 plugin 需要重置。

Examples

iex> snap = Snapshot.new(session_id: "sess-1", state: %{messages: []})
iex> snap.schema_version
1

Summary

Types

serializable()

可被序列化为 snapshot 的负载（通常是 Agent.State 或 map）。

t()

Functions

new(opts)

构建新的 Snapshot，自动生成 checkpoint_id + saved_at， 并剥离不可序列化字段。

schema_version()

返回 schema 版本号常量。

Types

serializable()

@type serializable() :: map() | struct()

可被序列化为 snapshot 的负载（通常是 Agent.State 或 map）。

t()

@type t() :: %CMDC.Checkpoint.Snapshot{
  checkpoint_id: String.t(),
  label: String.t() | nil,
  metadata: map(),
  saved_at: DateTime.t(),
  schema_version: pos_integer(),
  session_id: String.t(),
  state: serializable(),
  stripped_fields: [atom()]
}

Functions

new(opts)

@spec new(keyword()) :: t()

构建新的 Snapshot，自动生成 checkpoint_id + saved_at， 并剥离不可序列化字段。

选项

  • :session_id — 必填
  • :state — 必填（Agent.State 或任意 map）
  • :label — 可选标签
  • :metadata — 用户附加 map（默认 %{}）

schema_version()

@spec schema_version() :: pos_integer()

返回 schema 版本号常量。