CMDC.Backend behaviour — 文件 / 状态 / 远程存储的统一访问层。

对标 deepagents BackendProtocol 1:1 对齐。让工具层（read_file / write_file / edit_file / ls / glob / grep / execute 等）与底层执行环境完全解耦，支持任意 backend 实现（ETS / 本地文件 / Docker / Modal / E2B / Postgres ...）。

设计

• 10 个核心 callback：
  • 文件操作：ls/1 read/3 write/2 edit/4 grep/3 glob/2
  • 二进制传输：upload_files/1 download_files/1
  • 沙盒扩展（可选）：execute/2 id/0（由 CMDC.Sandbox 子 behaviour 引入）
• 统一 Result struct：见 CMDC.Backend.Results，所有 callback 返回 struct， 不再用 {:ok, val} | {:error, reason} 双形态，便于 pattern match 与 序列化（Postgres / JSON）。
• 标准错误码 atom：:file_not_found / :permission_denied / :is_directory / :invalid_path（4 基础 + 允许 backend 扩展 string）。
• 可路由 (Composite)：CMDC.Backend.Composite 支持按路径前缀路由到不同子 backend，让一个会话同时挂载 sandbox + PG memory + ETS history。

与 CMDC.Sandbox 关系

历史 CMDC.Sandbox 已经定义了类似但更简单的 8 callback（read_file/write_file/...）。 Phase 12C.0 将 CMDC.Sandbox 重构为 extends CMDC.Backend，只新增 execute/2 与 id/0，消除两套接口重叠。

与 CMDC.Memory 关系

现有 CMDC.Memory 是「语义记忆存储」behaviour（store/search/similarity_search）， 与本模块用途完全不同，命名上独立，不冲突。

Quick Start

backend = CMDC.Backend.State.new(:my_table)
%CMDC.Backend.Results.WriteResult{path: "/hello.txt"} =
  CMDC.Backend.write(backend, "/hello.txt", "world")
%CMDC.Backend.Results.ReadResult{file_data: %{content: "world"}} =
  CMDC.Backend.read(backend, "/hello.txt")

实现指南

实现 backend 时只需 use CMDC.Backend（引入默认 read/3 等 dispatcher）+ 实现 callback。最少要实现 ls / read / write 三件套，其他可逐步补齐。

defmodule MyBackend do
  use CMDC.Backend

  @impl true
  def read(backend, path, opts), do: ...

  # 其他 callback ...
end

Backend Factory

支持运行期注入：传递工厂 {module, opts} 或 lambda runtime -> backend.t()。