CMDC.Context (cmdc v0.5.1)

Copy Markdown View Source

工具和插件的执行上下文，typed struct 杜绝 map 黑洞。

在 Agent Loop 执行过程中作为只读上下文传递给 Tool 的 execute/2 和 Plugin 的 handle_event/3。不应在 Plugin 内修改 Context， 而是通过返回 action 元组影响 Agent 行为。

字段分组

  • 身份 — session_id、working_dir、model
  • 运行时配置 — sandbox、tools、subagents、config
  • 会话数据 — todos、memory_contents
  • 业务上下文 — user_data（来自 Options.user_data，SubAgent 自动继承）
  • 统计 — turn、total_tokens、cost_usd

用于 Tool 实现示例

def execute(args, %CMDC.Context{sandbox: sandbox} = ctx) when not is_nil(sandbox) do
  sandbox.read_file(args["path"], working_dir: ctx.working_dir)
end
def execute(args, ctx) do
  CMDC.Sandbox.Local.read_file(args["path"], working_dir: ctx.working_dir)
end

读取业务上下文（user_data）

def execute(args, %CMDC.Context{user_data: %{tenant_id: t}}) do
  {:ok, "fetched for tenant=#{t}"}
end

Summary

Types

t()

Functions

from_options(opts, session_id, config \\ nil)

从 CMDC.Options.t() 和 session_id 构建初始 Context。

from_state(state)

从 Agent.State map 构建 Context 快照，供 Plugin Pipeline 和 Tool 使用。

total_tokens(context)

返回当前已使用的 token 总量。

Types

t()

@type t() :: %CMDC.Context{
  config: CMDC.Config.t() | nil,
  cost_usd: float(),
  last_assistant_reply: String.t() | nil,
  memory_contents: %{required(String.t()) => String.t()},
  model: String.t(),
  prompt_mode: CMDC.Options.prompt_mode(),
  sandbox: module() | nil,
  session_id: String.t(),
  subagents: [map()],
  todos: [map()],
  tools: [module()],
  total_tokens: non_neg_integer(),
  turn: non_neg_integer(),
  user_data: map(),
  working_dir: String.t()
}

Functions

from_options(opts, session_id, config \\ nil)

@spec from_options(CMDC.Options.t(), String.t(), CMDC.Config.t() | nil) :: t()

从 CMDC.Options.t() 和 session_id 构建初始 Context。

用于 Agent 启动时创建第一个 Context 快照。

from_state(state)

@spec from_state(map()) :: t()

从 Agent.State map 构建 Context 快照，供 Plugin Pipeline 和 Tool 使用。

Agent.State 保证包含 session_id、working_dir、model 字段。

total_tokens(context)

@spec total_tokens(t()) :: non_neg_integer()

返回当前已使用的 token 总量。