# 核心概念

CMDC 的设计就是 7 个互不重叠的抽象搭积木。读完本章你能在脑里画出整个调用图。

---

## 一、Agent — gen_statem 状态机

每个会话对应一个 OTP 进程，跑 `:gen_statem` 状态机，4 个状态：

```
idle ─prompt──▶ running ─stream chunk──▶ streaming ─tool calls──▶ executing_tools
  ▲                                                                    │
  └────────── 工具批次完成 / abort / agent_end ───────────────────────┘
```

外部代码不直接持 Agent struct，**只通过 pid 或 session_id 字符串交互**：

```elixir
{:ok, session} = CMDC.create_agent(model: "anthropic:claude-sonnet-4-5")

CMDC.prompt(session, "...")       # 异步 cast，立即返回
CMDC.steer(session, ref, "...")   # 中段干预
CMDC.abort(session)               # 中止
CMDC.status(session)              # 状态快照
CMDC.stop(session)                # 终止 Supervisor 树
```

完整 API 矩阵见 [`CMDC`](CMDC.html)，状态机详细行为见
[Agent 状态机与事件](agent-loop.html)。

---

## 二、Session — Supervisor Tree

`create_agent/1` 实际启动了一棵 Supervisor 树：

```
SessionServer (Supervisor :rest_for_one)
├── Agent (gen_statem)
└── SubAgent.Supervisor (DynamicSupervisor)
    ├── 子 Agent #1 (gen_statem)
    └── 子 Agent #2 (gen_statem)
        └── ...（孙 Agent 同样隔离）
```

子 Agent crash 不影响父 Agent；父 Agent crash 由 SessionServer 决定是否
重启全树。Stop 一个 session = 停整棵树。

---

## 三、EventBus — 唯一的对外合约

Agent 内部所有"事情发生了"都通过 `CMDC.Emitter` 广播到
[`CMDC.EventBus`](CMDC.EventBus.html)，订阅者收到统一格式：

```
{:cmdc_event, session_id, event}
```

事件类型分七大类（`session` / `stream` / `tool` / `approval` / `subagent` /
`plugin_event` / `error`），完整清单见 [`CMDC.Event`](CMDC.Event.html)。

**消费方式**：

| 场景 | API |
|---|---|
| 当前进程订阅 | `CMDC.subscribe/2` |
| 重连补帧 | `CMDC.subscribe(session, since: last_index)`（需 `event_buffer_size > 0`）|
| Agent 崩溃监控 | `CMDC.monitor/1` → `{:cmdc_down, ref, sid, reason}` |

---

## 四、Plugin — 切面拦截器

Plugin 实现 [`CMDC.Plugin`](CMDC.Plugin.html) behaviour，在 13 个 hook 中
返回 8 种 action 之一：

| 关键 hook | 用途 | 常用 action |
|---|---|---|
| `:session_start / :session_end` | 资源初始化/清理 | `:emit` |
| `{:before_prompt, text}` | 用户 prompt 进 Agent 前 | `:intervene` 改写、`:abort` 拦截 |
| `{:before_request, messages}` | LLM 请求前 | `:switch_model` 路由模型 |
| `{:after_response, msg}` | LLM 回复后 | `:abort` / `:intervene` |
| `{:before_tool, name, args}` | 工具执行前 | `:block_tool` 拦截、`:replace_tool_args` 改参 |
| `{:on_tool_error, ...}` | 工具失败 | `:continue` 重试、`:abort` 放弃 |
| `{:after_tool, name, call_id, result}` | 单工具后 | `:replace_tool_result` 改 result |
| `{:before_compact, messages}` | 压缩前 | 持久化关键事实 |

完整矩阵 + 5 个范例见 [写一个 Plugin](plugins.html)。

---

## 五、Tool — Agent 可调用的能力

Tool 是 LLM 视角的"函数"，实现 [`CMDC.Tool`](CMDC.Tool.html) behaviour：

```elixir
@callback name() :: String.t()
@callback description() :: String.t()
@callback parameters() :: map()                          # JSON Schema
@callback execute(args :: map(), ctx :: CMDC.Context.t()) ::
            {:ok, String.t()} | {:error, String.t()} | {:effect, term()}
```

CMDC 内置 11 个：`ReadFile / WriteFile / EditFile / Shell / Grep / ListDir /
Glob / Task（子代理）/ WriteTodos / AskUser / CompactConversation`。

文件类工具默认走 [`CMDC.Sandbox`](CMDC.Sandbox.html) 代理，所有路径在
`working_dir` 内做边界校验。详见 [写一个 Tool](tools.html)。

---

## 六、Backend / Sandbox — 文件与执行的抽象

[`CMDC.Backend`](CMDC.Backend.html) 是文件 / 状态 / 远程存储的统一访问层
（10 callback：ls / read / write / edit / grep / glob / upload / download +
扩展的 execute / id），3 个内置实现：

| Backend | 用途 | 持久性 |
|---|---|---|
| `Backend.State` | 内存 ETS，单测 / 短会话 | 进程级 |
| `Backend.Filesystem` | 本地文件，CLI / 开发 | 跨进程 |
| `Backend.Composite` | prefix 路由组合，生产推荐 | — |

[`CMDC.Sandbox`](CMDC.Sandbox.html) 是 Backend 的子集 + 加 `execute`
（shell 命令）。`Sandbox.Local` 是默认实现。

**典型生产配置**（一个会话挂多套存储）：

```elixir
backend = CMDC.Backend.Composite.new(
  default: CMDC.Backend.Filesystem.new(root_dir: "/tmp/work", virtual_mode: true),
  routes: %{
    "/memories/" => MyApp.PgBackend.new(),                # 长期记忆
    "/conversation_history/" => CMDC.Backend.State.new()  # 短期 ETS
  }
)

{:ok, session} = CMDC.create_agent(model: "...", backend: backend)
```

---

## 七、Skill / Memory / Checkpoint — 三类持久化

CMDC 把"持久化"按时间尺度拆成三层，命名独立、互不重叠：

| 模块 | 时间尺度 | 用途 | 数据形态 |
|---|---|---|---|
| [`CMDC.Skill`](CMDC.Skill.html) | 永久 | 加载 SKILL.md 注入 system prompt | `.md` 文件 + frontmatter |
| [`CMDC.Memory`](CMDC.Memory.html) behaviour | 跨会话 | 语义记忆存储（store / search / similarity） | 由 backend 决定（ETS / Postgres + pgvector） |
| [`CMDC.Checkpoint`](CMDC.Checkpoint.html) | 单会话快照 | BEAM 重启 / 跨设备恢复 | `Snapshot` struct 序列化 |

**易混淆**：

- `Backend` 是「文件接口」（read_file 之类）
- `Memory` 是「语义记忆接口」（向量检索之类）
- `Checkpoint` 是「会话快照」（save / load / list）

详见 [`CMDC.Backend`](CMDC.Backend.html) / [`CMDC.Memory`](CMDC.Memory.html) /
[`CMDC.Checkpoint`](CMDC.Checkpoint.html) 三个模块文档。

### v0.5 新增 facade API

- **[`CMDC.checkpoint!/2`](CMDC.html#checkpoint!/2)** — 从运行中 session 抓快照
  （内部走 `Agent.get_state` + `Checkpoint.save`，序列化策略自动剥离运行期字段）
- **[`CMDC.resume_session!/2`](CMDC.html#resume_session!/2)** — 从 snapshot 重建 session,
  续 prompt 时 LLM 看到完整历史，无需自己拼装
- **[`CMDC.Checkpoint.Snapshot.redact/2`](CMDC.Checkpoint.Snapshot.html#redact/2)** —
  backend 写前预处理 hook（接 Cloak / KMS / 任意脱敏函数）
- **[`CMDC.Plugin.Builtin.AutoCheckpoint`](CMDC.Plugin.Builtin.AutoCheckpoint.html)** —
  内置 Plugin，按 turn / on_tools / on_events OR 触发自动存档 + max_checkpoints / ttl_seconds GC,
  走 `CMDC.AsyncTaskSupervisor` 异步执行不阻塞 gen_statem

### v0.5 新增 Hibernate 配置

[`CMDC.Options.hibernate_after_ms`](CMDC.Options.html) —
Agent 进程空闲 N 毫秒后走 OTP 原生 `:hibernate_after` 自动 hibernate，
单进程 heap 8KB → 1.5KB（节省 ~80% 内存）。长会话多租户场景必备。

---

## 依赖关系一览

```
                    ┌─────────────────┐
                    │   CMDC (facade) │
                    └────────┬────────┘
                             │
        ┌────────────┬───────┴────────┬────────────┐
        ▼            ▼                ▼            ▼
   SessionServer  EventBus       Checkpoint    Telemetry
        │
   ┌────┴────┐
   ▼         ▼
  Agent  SubAgent.Supervisor
   │
   ├── State / Stream / ToolRunner / Compactor   ← @moduledoc false 私有
   ├── Plugin Pipeline
   │     └── 16 内置 Plugin
   ├── Tool（11 内置）
   │     └── Sandbox / Backend
   ├── Provider（req_llm 封装）
   ├── Skill / Memory / Blueprint
   └── MCP（Bridge / Client / Supervisor）
```

层级规则：**只允许向下依赖，同层不互相依赖**。

---

## 下一步

- 想看 Agent 状态机怎么转：[Agent 状态机与事件](agent-loop.html)
- 想写第一个切面：[写一个 Plugin](plugins.html)
- 想加个外部能力：[写一个 Tool](tools.html)
- 想看常见组合：[常见配方](cookbook.html)