# cmdc v0.5.1 - Table of Contents

Elixir Agent Kernel — OTP gen_statem 驱动的 AI Agent 开发库

## Pages

- 入门
  - [概览](readme.md)
  - [5 分钟上手](quickstart.md)
  - [核心概念](concepts.md)

- 指南
  - [Agent 状态机与事件](agent-loop.md)
  - [写一个 Plugin](plugins.md)
  - [写一个 Tool](tools.md)
  - [常见配方](cookbook.md)
  - [升级指南](upgrading.md)

- 发布
  - [Changelog](changelog-public.md)
  - [License](license.md)

## Modules

- [CMDC.Application](CMDC.Application.md): CMDC OTP 应用入口。
- [CMDC.Backend.Results.EditResult](CMDC.Backend.Results.EditResult.md): `backend.edit/4` 返回。
- [CMDC.Backend.Results.FileData](CMDC.Backend.Results.FileData.md): 文件数据 typed map。
- [CMDC.Backend.Results.FileDownloadResponse](CMDC.Backend.Results.FileDownloadResponse.md): `backend.download_files/1` 单文件结果。
- [CMDC.Backend.Results.FileInfo](CMDC.Backend.Results.FileInfo.md): 目录条目元信息。
- [CMDC.Backend.Results.FileUploadResponse](CMDC.Backend.Results.FileUploadResponse.md): `backend.upload_files/1` 单文件结果。
- [CMDC.Backend.Results.GlobResult](CMDC.Backend.Results.GlobResult.md): `backend.glob/2` 返回。
- [CMDC.Backend.Results.GrepMatch](CMDC.Backend.Results.GrepMatch.md): grep 单条匹配。
- [CMDC.Backend.Results.GrepResult](CMDC.Backend.Results.GrepResult.md): `backend.grep/3` 返回。
- [CMDC.Backend.Results.LsResult](CMDC.Backend.Results.LsResult.md): `backend.ls/1` 返回。
- [CMDC.Backend.Results.ReadResult](CMDC.Backend.Results.ReadResult.md): `backend.read/3` 返回。
- [CMDC.Backend.Results.WriteResult](CMDC.Backend.Results.WriteResult.md): `backend.write/2` 返回。
- [CMDC.Checkpoint.Backend.DETS](CMDC.Checkpoint.Backend.DETS.md): 轻持久化 DETS 后端 — 单节点磁盘持久化。
- [CMDC.Checkpoint.Backend.ETS](CMDC.Checkpoint.Backend.ETS.md): 默认 ETS 后端 — 进程内、零依赖、最快。
- [CMDC.Plan.Step](CMDC.Plan.Step.md): Plan 里的单个步骤。
- [CMDC.Plugin.Builtin.AutoCheckpoint](CMDC.Plugin.Builtin.AutoCheckpoint.md): 按以下任一条件**OR 触发** `CMDC.checkpoint!/2`，自动持久化会话快照。
- [CMDC.Provider.Registry](CMDC.Provider.Registry.md): 命名 Provider Profile 注册表 — 多租户场景下的运行时 provider/opts 寻址中心。
- [CMDC.Provider.Registry.Broadcaster](CMDC.Provider.Registry.Broadcaster.md): Provider Profile 变更跨节点广播 behaviour。
- [CMDC.Provider.Registry.Broadcaster.Noop](CMDC.Provider.Registry.Broadcaster.Noop.md): 零依赖 No-op Broadcaster —— 单机部署 / 单元测试默认实现。
- [CMDC.Provider.Registry.Broadcaster.PG](CMDC.Provider.Registry.Broadcaster.PG.md): 基于 OTP `:pg` 模块的零依赖 best-effort broadcaster — cmdc 默认实现。

- 入门
  - [CMDC](CMDC.md): CMDC — Elixir Agent Kernel 公共 API 入口。
  - [CMDC.Config](CMDC.Config.md): CMDC 会话的类型化配置 struct。
  - [CMDC.Context](CMDC.Context.md): 工具和插件的执行上下文，typed struct 杜绝 map 黑洞。
  - [CMDC.Message](CMDC.Message.md): Agent 会话中的消息结构体。
  - [CMDC.Options](CMDC.Options.md): 创建 CMDC Agent 的类型化选项 struct。

- 事件与状态
  - [CMDC.Event](CMDC.Event.md): Agent 运行时结构化事件。
  - [CMDC.EventBus](CMDC.EventBus.md): 基于 Registry 的会话事件发布/订阅系统，附带可选的 ring buffer 用于断线重连补帧。
  - [CMDC.Plan](CMDC.Plan.md): 结构化执行计划 — Agent Planning Pattern 的运行时实体。
  - [CMDC.TokenUsage](CMDC.TokenUsage.md): 公开的 token 用量 struct。

- 工具（Tools）
  - [CMDC.Tool](CMDC.Tool.md): Agent 工具 behaviour 接口定义。
  - [CMDC.Tool.AskUser](CMDC.Tool.AskUser.md): 向用户提问，等待用户回答后继续。
  - [CMDC.Tool.CompactConversation](CMDC.Tool.CompactConversation.md): 手动触发上下文压缩。
  - [CMDC.Tool.EditFile](CMDC.Tool.EditFile.md): 通过精确字符串替换编辑文件（str_replace 模式）。
  - [CMDC.Tool.Glob](CMDC.Tool.Glob.md): 文件名模式匹配。
  - [CMDC.Tool.Grep](CMDC.Tool.Grep.md): 跨文件 regex 内容搜索，支持 glob 过滤。
  - [CMDC.Tool.ListDir](CMDC.Tool.ListDir.md): 列出目录内容。
  - [CMDC.Tool.ReadFile](CMDC.Tool.ReadFile.md): 读取文件内容，支持 offset/limit 分页。
  - [CMDC.Tool.Shell](CMDC.Tool.Shell.md): 在 shell 中执行命令，支持超时和大输出自动存文件。
  - [CMDC.Tool.Task](CMDC.Tool.Task.md): 子代理工具 — 在独立进程中启动子 Agent 执行委托任务。
  - [CMDC.Tool.WriteFile](CMDC.Tool.WriteFile.md): 将内容写入文件，必要时自动创建父目录。
  - [CMDC.Tool.WriteTodos](CMDC.Tool.WriteTodos.md): 更新 Agent 的 Todo 任务列表。

- Plugins（安全与控制）
  - [CMDC.Plugin](CMDC.Plugin.md): Plugin behaviour 定义。所有插件实现此 behaviour。
  - [CMDC.Plugin.Builtin.ContentPolicy](CMDC.Plugin.Builtin.ContentPolicy.md): LLM-as-Judge 内容安全拦截 Plugin。
  - [CMDC.Plugin.Builtin.EventLogger](CMDC.Plugin.Builtin.EventLogger.md): P0 事件日志插件 — 将 Agent Pipeline 事件以 JSON Lines 格式追加写入日志文件。
  - [CMDC.Plugin.Builtin.HumanApproval](CMDC.Plugin.Builtin.HumanApproval.md): P0 人类审批插件 — 高风险工具执行前等待人类确认（HITL）。
  - [CMDC.Plugin.Builtin.OutputFilter](CMDC.Plugin.Builtin.OutputFilter.md): P1 输出过滤插件 — 对 LLM 回复进行 PII/敏感词过滤。
  - [CMDC.Plugin.Builtin.PatchToolCalls](CMDC.Plugin.Builtin.PatchToolCalls.md): P1 悬空工具调用修复插件。
  - [CMDC.Plugin.Builtin.SecurityGuard](CMDC.Plugin.Builtin.SecurityGuard.md): P0 安全防护插件 — 路径黑名单 + 命令黑名单 + 审计日志。

- Plugins（优化与记忆）
  - [CMDC.Plugin.Builtin.CostGuard](CMDC.Plugin.Builtin.CostGuard.md): P1 成本硬限制插件 — Token 和成本预算控制。
  - [CMDC.Plugin.Builtin.EpisodicMemory](CMDC.Plugin.Builtin.EpisodicMemory.md): 情景记忆 few-shot Plugin。
  - [CMDC.Plugin.Builtin.LargeResultOffload](CMDC.Plugin.Builtin.LargeResultOffload.md): 大工具结果自动 offload 到 backend。
  - [CMDC.Plugin.Builtin.MemoryFlush](CMDC.Plugin.Builtin.MemoryFlush.md): 压缩前持久化关键事实插件。
  - [CMDC.Plugin.Builtin.MemoryLoader](CMDC.Plugin.Builtin.MemoryLoader.md): P1 持久记忆插件 — 加载 AGENTS.md 并注入系统提示词。
  - [CMDC.Plugin.Builtin.ModelRouter](CMDC.Plugin.Builtin.ModelRouter.md): P2 模型路由插件 — 按规则在 `before_request` 自动切换 LLM 模型。
  - [CMDC.Plugin.Builtin.Planning](CMDC.Plugin.Builtin.Planning.md): P2 规划插件 — 在用户 prompt 提交前强制 LLM 先生成结构化 Plan。
  - [CMDC.Plugin.Builtin.PromptCache](CMDC.Plugin.Builtin.PromptCache.md): P1 Anthropic Prompt Caching 插件。
  - [CMDC.Plugin.Builtin.Recovery](CMDC.Plugin.Builtin.Recovery.md): P1 异常恢复策略链插件 — 工具失败时按策略链逐级恢复。
  - [CMDC.Plugin.Builtin.Reflection](CMDC.Plugin.Builtin.Reflection.md): P2 反思循环插件 —「生产者-评审者」模型。

- 存储与沙箱
  - [CMDC.Backend](CMDC.Backend.md): CMDC.Backend behaviour — 文件 / 状态 / 远程存储的统一访问层。
  - [CMDC.Backend.Composite](CMDC.Backend.Composite.md): 路由后端 — 按路径前缀转发到不同子 backend。
  - [CMDC.Backend.Filesystem](CMDC.Backend.Filesystem.md): 本地文件系统 backend。
  - [CMDC.Backend.State](CMDC.Backend.State.md): 内存 backend — 文件存于 ETS。
  - [CMDC.Checkpoint](CMDC.Checkpoint.md): 会话快照（checkpoint）一等公民 API。
  - [CMDC.Checkpoint.Backend](CMDC.Checkpoint.Backend.md): Checkpoint 存储后端 behaviour。
  - [CMDC.Checkpoint.Snapshot](CMDC.Checkpoint.Snapshot.md): 会话快照标准 payload。
  - [CMDC.Memory](CMDC.Memory.md): Memory behaviour 接口 — 可插拔的语义记忆存储。
  - [CMDC.Memory.ETS](CMDC.Memory.ETS.md): 基于 ETS 的内存 Memory 实现。
  - [CMDC.Sandbox](CMDC.Sandbox.md): 文件操作和命令执行的抽象层。
  - [CMDC.Sandbox.Local](CMDC.Sandbox.Local.md): Sandbox 的本地 OS 默认实现，直接调用本地文件系统和 shell。

- 扩展点
  - [CMDC.Blueprint](CMDC.Blueprint.md): Agent 蓝图声明式定义，可复用的 Agent 配置模板。
  - [CMDC.Blueprint.Base](CMDC.Blueprint.Base.md): 内置 Plugin 基座蓝图。
  - [CMDC.Gateway](CMDC.Gateway.md): 出站事件推送契约。
  - [CMDC.Gateway.Local](CMDC.Gateway.Local.md): 本地内存 Gateway 实现（嵌入式部署模式）。
  - [CMDC.Provider](CMDC.Provider.md): req_llm 的薄封装层，负责发起流式 LLM 请求。
  - [CMDC.Provider.StreamBridge](CMDC.Provider.StreamBridge.md): 将 req_llm 的 `StreamResponse` 转为 gen_statem 消息的桥接进程。
  - [CMDC.Skill](CMDC.Skill.md): Skill（技能）元数据 struct + 发现与加载系统。
  - [CMDC.Skill.Selector](CMDC.Skill.Selector.md): Skill 选择器 behaviour — 为智能 Skill 筛选预留扩展点。
  - [CMDC.SubAgent](CMDC.SubAgent.md): 子代理声明式规格 struct。
  - [CMDC.Telemetry](CMDC.Telemetry.md): CMDC 标准 `:telemetry` 事件契约。

- 集成
  - [CMDC.MCP.Bridge](CMDC.MCP.Bridge.md): MCP 工具桥接器 — 将 MCP server 工具包装为 `CMDC.Tool` behaviour 模块。
  - [CMDC.MCP.Client](CMDC.MCP.Client.md): Anubis MCP 客户端封装。
  - [CMDC.MCP.Config](CMDC.MCP.Config.md): MCP server 配置发现与解析。
  - [CMDC.MCP.Supervisor](CMDC.MCP.Supervisor.md): MCP 客户端进程树监督者。

- 内核（高级）
  - [CMDC.Agent](CMDC.Agent.md): Agent 状态机 — 使用 `:gen_statem` 编排四状态循环。
  - [CMDC.Agent.BasePrompt](CMDC.Agent.BasePrompt.md): 默认基座提示词。
  - [CMDC.Plugin.Registry](CMDC.Plugin.Registry.md): Plugin 注册表。
  - [CMDC.SessionServer](CMDC.SessionServer.md): 每个会话的进程树监督者。
  - [CMDC.SubAgent.Supervisor](CMDC.SubAgent.Supervisor.md): 子代理进程树动态监督者。

