Crate crabmate

Expand description

CrabMate 库：OpenAI 兼容多供应商 LLM、Agent 主循环、HTTP 服务、工具与工作流。二进制入口见 src/main.rs 的 run 包装。

§公开 API（semver）

白名单见仓库 docs/design/crates_io_single_package.md §2.4。

承诺 protocol（Client / WASM）：六个模块 cm_types、cm_display_rules、 cm_api_contract、cm_chat_export、cm_turn_layout、cm_sse_protocol。没有 types / sse / config 别名。
承诺 server（默认，含 protocol）：组合面模块名 agent / config / llm / sse / types 的存在；以及 run、run_agent_turn、build_tools*、ProcessHandles、 tool_sandbox 等根上显式 pub use。
不承诺：#[doc(hidden)] 的 cm_agent / cm_llm / cm_config / cm_workflow / cm_internal、e2e_scenario、test_serve；agent::agent_turn 等组合面内部路径。 cm_tools / cmd_mate 等为实现模块，pub(crate)。

本 crate 默认 feature 是带库的 serve 服务器，不是通用嵌入式 Agent SDK。 HTTP 线契约以 docs/SSE协议.md、cm_api_contract 与 GET /openapi.json 为准。

日志由 tracing 处理；observability::init_tracing_subscriber（cm_internal）安装 tracing-subscriber 并用 tracing-log 桥接既有 log:: 调用。RUST_LOG 优先。未设置时：--serve 默认 info；其它 CLI 模式默认 warn（不输出 info）；--log <FILE> 在未设置 RUST_LOG 时默认 info。时间戳默认本机本地时区（RFC3339）。设 CM_LOG_JSON=1 时输出 JSON 行（便于 jq / 日志平台）。

Re-exports§

pub use crate::cm_sse_protocol::sse;
pub use crate::cm_types as types;
pub use config::LlmHttpAuthMode;
pub use llm::ChatCompletionsBackend;
pub use llm::CompleteChatRetryingParams;
pub use llm::E2eMode;
pub use llm::OPENAI_COMPAT_BACKEND;
pub use llm::OpenAiCompatBackend;
pub use llm::StreamChatParams;
pub use llm::TraceEvent;
pub use llm::TraceSink;
pub use llm::default_chat_completions_backend;
pub use llm::shared_static_chat_backend;
pub use types::ChatRequest;
pub use types::FunctionCall;
pub use types::LlmSeedOverride;
pub use types::Message;
pub use types::ToolCall;
pub use types::message_content_as_str;

Modules§

agent: Agent 回合、上下文裁剪/摘要、PER、工作流与终答规划解析（与 lib 中 HTTP 路由、tools 实现解耦）。
cm_api_contract: CrabMate HTTP JSON 契约（纯 serde；无 axum / Leptos）。
cm_chat_export: 会话导出契约：JSON 信封常量 / ChatSessionFile / DisplayChatSessionFile，以及 Markdown 分段（无 I/O）。
cm_display_rules: 聊天区展示层共用的字符串规则（无 UI / 无 I/O）。
cm_sse_protocol: CrabMate POST /chat/stream 控制面 JSON 的协议版本常量、SSE 帧层工具函数与运行时。
cm_turn_layout: Canonical Turn layout + reducer + projector（对齐 OpenAI assistant→tool→assistant 与 AG-UI 段边界）。
cm_types: API 与对话相关类型
dev_tag: Development 工具子域标签：按语言栈 / 职责过滤，与 [super::ToolCategory::Development] 配合使用。
http_client: 对外部模型 API（及同类 HTTPS 端点）的 reqwest::Client 单例构造。
llm: 与大模型（OpenAI 兼容 /chat/completions）交互的封装层。
text_sanitize: 面向用户可见正文的轻量清洗（规划摘要等）。面向用户可见正文的轻量清洗（聊天、规划摘要等）。
tool_sandbox: Docker 沙盒内 tool-runner-internal 入口；二进制与 main 经此路径调用。 Docker 沙盒（sync_default_tool_sandbox_mode = docker）：在隔离容器中执行多类工具（见 ToolInvocationLine.kind）。

Structs§

AgentConfig: Agent 运行配置（组合式；各子域字段含义见对应 *Config 结构体文档）。
AgentTurnLlmOverrides: 本回合对 chat/completions 的采样与模型路由覆盖（相对 config::AgentConfig）。
AgentTurnTransport: 回合传输与端点表现（SSE、取消、审批上下文等），与模型采样/路由覆盖解耦。
CliExitError
E2eCliArgs: e2e 解析结果（供 cli_run 执行）。
LongTermMemoryRuntime: 进程内共享：SQLite 连接 + 可选 fastembed（首次 embed 时初始化；未编译 fastembed feature 时无嵌入器）。
ParsedCliArgs: parse_args 的返回值：具名字段替代长元组，便于增删选项与调用方阅读。
PerTurnFlight: 单条 /chat / /chat/stream 任务在跑 run_agent_turn 时，PER 相关状态的只读镜像（进程内、按 job_id 区分）。
ProcessHandles: Web serve 与 CLI chat/repl 共用的进程级句柄（显式 Arc 传递，替代模块级 static）。
ReadFileTurnCache: 一轮对话内的 read_file 缓存（Arc<Mutex<…>> 由 run_agent_turn 创建并共享给各工具调用）。
RunAgentTurnAttach: 记忆 / 工具策略附件（入口袋；进环后映射到 RunLoopAttach 相关字段）。
RunAgentTurnObs: 可观测与进程句柄（入口袋；与环内 RunLoopObs 对应，勿与之混淆）。
RunAgentTurnParams: Web/CLI/基准测试共用的 run_agent_turn 入参（避免长参数列表）。
RunAgentTurnSession: 会话消息与工作区（入口袋；与环内 RunLoopCore 工作区字段对应）。
RunAgentTurnSharedInputs: Web/CLI/bench 共用的 LLM 接入侧不变输入（HTTP 客户端、密钥、配置快照、工具表）。
ToolDispatchMeta
ToolsBuildOptions: 构建工具列表时的分类与开发子域标签过滤。
TracingChatTurn: Web /chat* 单任务：job_id / conversation_id 根 span + 可递增的外层轮次；工具日志前更新 tool_call_seq / tool_call_id（展示标签，协议层仍以原始 id 为准）。
TurnProcessHandles: run_agent_turn / 工具执行所需的进程句柄面（不含侧栏任务表与 CLI LTM）。
WebChatJsonBuildArgs: 构造 RunAgentTurnParams::web_chat_json 所需的参数包。
WebChatStreamBuildArgs: 构造 RunAgentTurnParams::web_chat_stream 所需的参数包（避免长形参列表）。
WebRequestAudit: 单次 HTTP 对话任务携带的审计上下文（队列 → run_agent_turn）。
WebToolRuntime

Enums§

ExtraCliCommand: parse_args 扩展槽：非默认 CLI 流程（doctor / models / probe）。
PlannerExecutorMode: 规划器与执行器的运行模式。
SaveSessionFormat: save-session --format 取值
ToolExecutionClass: 工具在运行时的执行类别。
ToolReplayCli: tool-replay 子命令解析结果（供 runtime::cli 执行）
WebBearerCli: web-bearer 解析结果（供 runtime 执行；不要求 API_KEY）

Constants§

EXIT_GENERAL: 一般失败（配置、I/O、未分类错误）
EXIT_MODEL_ERROR: 模型接口或解析失败
EXIT_QUOTA_OR_RATE_LIMIT: 配额 / 限流
EXIT_TOOLS_ALL_RUN_COMMAND_DENIED: Historical：同进程 chat 下本回合内所有 run_command 均被用户拒绝（码 4）。 D2.2 后生产路径不再发出该码（无同进程 CLI 工具审批）；契约测试仍断言常量值 == 4 作占位。
EXIT_TOOL_REPLAY_MISMATCH: tool-replay 下存在不一致的工具输出
EXIT_USAGE: 参数/用法错误

Traits§

ExposeSecret: 敏感字符串（Debug / 结构化日志默认脱敏）；取值请用 ExposeSecret::expose_secret。 Expose a reference to an inner secret

Functions§

all_dispatch_metadata: 注册表中显式声明的工具；其余名称运行时走 SyncDefault（同步 run_tool）。
build_tools: 构建传给 API 的工具列表（表驱动注册）。
build_tools_filtered: 构建传给 API 的工具列表：可按顶层分类过滤（[ToolCategory::Basic] / [ToolCategory::Development]）。
build_tools_with_options: 同时支持顶层分类与 Development 子域标签过滤（见 ToolsBuildOptions）。
classify_model_error_message: 根据 run_agent_turn / LLM 层常见错误文案归类退出码（启发式，与 llm::api 用户可见串对齐）。
execution_class_for_tool: 合并「注册表元数据 + 默认同步」的执行类别，便于文档或将来生成 OpenAPI。
is_readonly_tool: 判断工具是否为只读（不修改工作区文件系统），供并行执行决策使用。
load_config: 加载配置：嵌入的 config/default_config.toml、config/session.toml、config/context_inject.toml、config/tools.toml、config/sandbox.toml、config/planning.toml、config/memory.toml 为底，再被配置文件覆盖，最后被环境变量覆盖。若指定 config_path，则只从该文件读取覆盖；否则优先 cwd 的 config.toml / .agent_demo.toml，再尝试 $XDG_CONFIG_HOME/crabmate/config.toml（可从 /etc/crabmate 首次种子；源码树内默认跳过，除非设 CM_CRABMATE_CONFIG_DIR）。若最终 api_base、model 或任一运行参数仍未设置则返回错误。默认 system_prompt_file 在 [super::finalize::finalize] 中按 cwd、各已加载配置文件目录（逆序）、run_command_working_dir 解析相对路径。
load_config_for_cli: CLI 子命令入口：加载失败时打印错误并映射为 InvalidData，与历史 lib::run 行为一致。
new_turn_cache_handle: 供 run_agent_turn 在启用缓存时构造句柄。
normalize_legacy_argv: 若 argv 在 未写子命令名 时使用历史平铺 flag（--serve、--benchmark 等），改写为 serve / bench / … 形式再交给 clap。
parse_args: 解析命令行：须显式子命令（serve / bench / config / doctor / …）；同进程 chat|repl|tui 入口已移除。
parse_args_from_argv: 使用给定 argv（首元素为程序名）解析 CLI，供契约/集成测试；生产请用 parse_args。
root_clap_command_for_man_page: 与当前构建一致的根级 clap::Command，供 crabmate-gen-man 生成 man/crabmate.1（troff）。
run: CLI 入口逻辑（与历史二进制 main 等价）：解析参数、加载配置、启动 Web / REPL 等。
run_agent_turn: 执行一轮 Agent：发请求、若遇 tool_calls 则执行工具并继续，直到模型返回最终回复。 cfg 建议使用 Arc 共享（与进程内 Web 服务状态一致），以便工具在 spawn_blocking 路径中复用同一份配置而不反复深拷贝。若提供 transport.out，则流式 content 会通过 out 发送（供 SSE 等使用）；transport.no_stream 为 true 时 API 使用 stream: false，有正文则通过 out 一次性下发整段。 effective_working_dir 为当前生效的工作目录（可与前端设置的工作区一致）。 transport.cancel 为 Some 时，各轮请求会在流式读与重试间隔中轮询其标志；置位后尽快结束并返回 Ok（或 Err：[agent::agent_turn::RunAgentTurnError] 中含取消 / 限流 / SSE 早停等，用户可见串与常量 crate::types::LLM_CANCELLED_ERROR 对齐），供协作取消等场景使用。分阶段规划下若规划轮未解析出合法 agent_reply_plan v1：不再整轮失败退出：保留规划轮助手正文并降级为与门控拒绝时相同的常规 run_agent_outer_loop（含工具）。规划轮会先丢弃 API 返回的原生 tool_calls，再视情况执行工具，避免网关误报 tool_calls 时静默无动作。 transport.per_flight 仅 Web 队列任务传入，用于 GET /status 的 per_active_jobs 镜像；运维 CLI 传 None。自定义 ChatCompletionsBackend 见 AgentTurnTransport::llm_backend。
run_cli_from_parsed: 已解析 CLI 参数后的入口；main 在 block_on 时优先调用本函数以减小 future 嵌套深度。
try_dispatch_meta: 若在 all_dispatch_metadata 中登记则返回其元数据，否则 None（运行时走同步 run_tool）。

Type Aliases§

ReadFileTurnCacheHandle
SharedAgentConfig: 进程内共享的 AgentConfig（serve / repl / chat / bench）；热重载时 write 更新，回合开始时 read+clone 得快照传入 run_agent_turn。

Crate crabmate

Crate crabmate Copy item path

§公开 API（semver）

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate crabmate