Capabilities 总览

什么是 Capability

Capability（能力） 是 ESP-Claw 中一切可被调用功能的统一抽象单元。每个 cap_* 组件向 claw_cap 注册一个或多个带有元数据的 描述符（claw_cap_descriptor_t），系统在运行时通过统一入口路由调用。

一个 Capability 可以扮演三种角色：

角色	`kind` 值	说明
可调用工具	`CLAW_CAP_KIND_CALLABLE`	接收 JSON 输入，返回字符串结果；可被 LLM、Console、事件规则调用
事件源	`CLAW_CAP_KIND_EVENT_SOURCE`	持续运行，产生事件推入 `claw_event_router`
混合	`CLAW_CAP_KIND_HYBRID`	同时具备调用与事件源能力

所有描述符通过 Capability Group（claw_cap_group_t）组织，Group 是 Capability 的最小管理单元，支持统一注册、启停与 LLM 可见性控制。

系统内置 Capability 分类

分类	组件	说明
IM 接入	`cap_im_*`	即时通讯平台接入，同时作为事件源产生用户消息事件
文件系统	`cap_files`	受管 FATFS 目录的读写、编辑、列举与删除
Lua 脚本	`cap_lua`	Lua 脚本的写入、同步/异步执行与任务管理
Skill 管理	`cap_skill`	Skill 的注册/注销与激活/停用（暴露 core 功能为工具）
LLM 检视	`cap_llm_inspect`	将本地图像文件发送给 LLM 分析（与 LLM 产生嵌套交互）
网络搜索	`cap_web_search`	调用外部搜索 API
时间	`cap_time`	查询设备当前时间
系统信息	`cap_system`	查询设备系统/内存/CPU/Wi-Fi/IP 信息，并支持触发重启等运维操作
调度器	`cap_scheduler`	定时任务的注册与管理
Router 管理	`cap_router_mgr`	动态维护 Event Router 规则
MCP	`cap_mcp_*`	Model Context Protocol 客户端/服务端
CLI	`cap_cli`	将 Capability 调用暴露为终端命令
会话管理	`cap_session_mgr`	会话状态读写

Group 注册机制

每个 cap_* 组件在应用层通过 cap_xxx_register_group() 将自身注册到 claw_cap：

// 以 cap_files 为例
esp_err_t cap_files_register_group(void)
{
    if (claw_cap_group_exists(s_files_group.group_id)) {
        return ESP_OK;
    }
    return claw_cap_register_group(&s_files_group);
}

claw_cap_register_group 内部会验证 Group ID 唯一性，并将所有描述符的 init 钩子执行完成后即完成注册。调用 claw_cap_start_group 后，生命周期钩子 start 被调用（如 TG 轮询任务启动）。

LLM 可见性控制

并非所有已注册的 Group 都对 LLM 可见。claw_cap_set_llm_visible_groups 通过白名单决定哪些 Group 的工具会注入 LLM 上下文：

// 典型设置：只对 LLM 初始暴露基础工具
static const char *VISIBLE_GROUPS[] = { "cap_files", "cap_skill", "cap_system" };
claw_cap_set_llm_visible_groups(VISIBLE_GROUPS, 3);

其余 Group 仍然存在，Console 与自动化规则可直接调用；通过激活 Skill 可以动态扩展 LLM 可见的工具集。

调用路径

Capability 可通过以下三条路径被调用：

LLM 工具调用：claw_core → claw_cap_call_from_core（携带 session/channel 上下文）
Console 命令：cap call <name> <json> 直接执行
Event Router 规则：规则动作 call_cap（见数据流与自动化）

claw_cap_call_context_t.caller 字段标识调用来源（SYSTEM / AGENT / CONSOLE），Capability 实现可据此区分行为。

详细文档

如何实现 Capability 从零实现一个 cap_* 组件的完整步骤与最佳实践

cap_im_tg IM 接入代表：事件源 + 可调用工具的双重角色

cap_skill core 功能暴露代表：将 claw_skill 能力封装为工具

cap_llm_inspect LLM 交互代表：在工具执行中嵌套发起 LLM 推理

cap_files 文件系统代表：受管目录的完整 CRUD 能力

cap_system 系统信息代表：读取设备运行状态并支持安全重启

cap_scheduler 定时调度代表：基于时间触发事件，管理周期性任务

cap_lua 与 Lua 综述 Lua 脚本能力与 Lua 在 ESP-Claw 中的整体定位

Lua 扩展模块 lua_module_* 的注册机制、实现方式与 display 模块分析