CMDC.Options (cmdc v0.4.1)

Copy Markdown View Source

创建 CMDC Agent 的类型化选项 struct。

替代裸 keyword list，通过 NimbleOptions 在运行时校验所有字段， 提供清晰的错误信息和文档，实现 AI-Friendly 类型系统的第一层防护。

快速开始

opts = CMDC.Options.new!(
  model: "anthropic:claude-sonnet-4-5",
  tools: [CMDC.Tool.ReadFile, CMDC.Tool.Shell],
  system_prompt: "你是一个专业的代码助手。",
  max_turns: 50
)

字段说明

  • :model — 必填，模型标识符，格式 "provider:model_id"，如 "anthropic:claude-sonnet-4-5"
  • :tools — Tool behaviour 模块列表，空则不加载任何工具
  • :system_prompt — 自定义系统提示词，拼接在 BasePrompt 之前；nil 则只用 BasePrompt
  • :plugins — Plugin 列表，支持 Module 或 {Module, keyword()} 两种形式
  • :subagents — SubAgent 声明式规格列表（CMDC.SubAgent.t() 的列表）
  • :skills_dirs — Skills 目录列表，Agent 自动发现 SKILL.md 文件
  • :memory — Memory 文件路径列表，如 ["AGENTS.md", "~/.cmdc/AGENTS.md"]
  • :sandbox — Sandbox behaviour 实现模块，nil 则直接 OS 执行
  • :response_format — 结构化输出 JSON Schema，nil 则自由文本
  • :provider_opts — 传递给 req_llm 的选项，如 [api_key: "sk-..."]
  • :max_turns — 最大对话轮数，默认 100
  • :max_tokens — 模型最大输出 token，nil 则由 Provider 决定
  • :working_dir — 工作目录，工具的文件操作相对此路径，默认 "."
  • :max_steering_queue — Steering queue 最大长度，默认 3（详见 guides/cookbook.md 中段干预配方）
  • :interrupt_immune_tools — Steering 触发时不会被强杀的工具白名单
  • :user_data — 业务上下文透传 map，原样写入 ctx.user_data，SubAgent 自动继承
  • :messages — 历史消息列表（[CMDC.Message.t()]），创建 Agent 时直接写入 state.messages， 用于 idle 休眠唤醒 / 跨进程恢复，跳过把历史灌成 prompt 让 LLM 重读的开销
  • :event_buffer_size — EventBus per-session ring buffer 大小，默认 0（关闭）。 设置 > 0 后该 session 的事件会按 FIFO 缓存，订阅者可用 subscribe(sid, since: idx) 实现断线重连补帧。典型值 50 ~ 200。

  • :prompt_mode — 系统提示词模式，:full | :task | :minimal | :none，默认 :full。 控制 Agent.SystemPrompt.build/1 注入的段落密度，用于 SubAgent / 长会话降本。

Summary

Types

plugin_spec()
prompt_mode()
t()

Functions

merge(base, overrides)

从已有 Options struct 合并覆盖字段，返回新 struct。

new(opts)

从 keyword list 构建 Options struct，返回 {:ok, t()} 或 {:error, NimbleOptions.ValidationError.t()}。

new!(opts)

从 keyword list 构建 Options struct，校验失败时抛出异常。

schema()

返回 NimbleOptions schema（用于文档生成和运行时检查）。

Types

plugin_spec()

@type plugin_spec() :: module() | {module(), keyword()}

prompt_mode()

@type prompt_mode() :: :full | :task | :minimal | :none

t()

@type t() :: %CMDC.Options{
  event_buffer_size: non_neg_integer(),
  interrupt_immune_tools: [String.t()],
  max_steering_queue: pos_integer(),
  max_tokens: pos_integer() | nil,
  max_turns: pos_integer(),
  memory: [String.t()],
  messages: [CMDC.Message.t()],
  model: String.t(),
  plugins: [plugin_spec()],
  prompt_mode: prompt_mode(),
  provider_opts: keyword(),
  response_format: map() | nil,
  sandbox: module() | nil,
  skill_selector: module() | nil,
  skills_dirs: [String.t()],
  subagents: [map()],
  system_prompt: String.t() | nil,
  tools: [module()],
  user_data: map(),
  working_dir: String.t()
}

Functions

merge(base, overrides)

@spec merge(
  t(),
  keyword()
) :: t()

从已有 Options struct 合并覆盖字段，返回新 struct。

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, NimbleOptions.ValidationError.t()}

从 keyword list 构建 Options struct，返回 {:ok, t()} 或 {:error, NimbleOptions.ValidationError.t()}。

new!(opts)

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

从 keyword list 构建 Options struct，校验失败时抛出异常。

示例

iex> CMDC.Options.new!(model: "anthropic:claude-sonnet-4-5")
%CMDC.Options{model: "anthropic:claude-sonnet-4-5", tools: [], ...}

iex> CMDC.Options.new!([])
** (NimbleOptions.ValidationError) required option :model not found

schema()

@spec schema() :: NimbleOptions.t()

返回 NimbleOptions schema（用于文档生成和运行时检查）。