Capability 系统

什么是 Capability

Capability 是注册在 C 层的可调用工具，LLM 通过 tool-use API 以 function-call 方式直接调用。每个 Capability 具有唯一的字符串 id、JSON 输入 Schema 和执行函数。除 LLM 调用外，还支持以下方式触发：

AT 命令：AT+CLAW=cap,<id>[,<json_args>]
Lua 脚本：通过 cap Lua 模块使用 cap.call("id", json_string)
内部 C 代码：claw_cap_call() C API

Capability 组与门控

所有 Capability 按功能划分到对应的 cap_group。大多数组始终对 LLM 可见；部分组默认隐藏，需激活对应 Skill 后才解锁。这一机制确保 LLM 在调用硬件相关或资源密集型工具前获得必要的上下文。

组名	门控 Skill	包含的 Capability
`files`	(始终可见)	`file_read`, `file_write`, `file_delete`, `file_list`, `file_move`, `file_copy`, `file_stat`
`skill_mgr`	(始终可见)	`skill_list`, `skill_activate`, `skill_save`, `skill_delete`, `skill_deactivate`
`lua`	(始终可见)	`lua_run`, `lua_run_async`, `lua_job_get`, `lua_job_list`, `lua_job_stop`
`scheduler`	(始终可见)	`scheduler_add_job`, `scheduler_list_jobs`, `scheduler_remove_job`, `scheduler_enable_job`, `scheduler_disable_job`
`system`	(始终可见)	`get_heap_info`, `get_task_list`, `get_info`, `get_wifi`, `get_ip`, `restart`
`time`	(始终可见)	`get_current_time`, `sync_time`
`http_request`	(始终可见)	`http_request`
`net_discover`	(始终可见)	`net_discover_start`, `net_discover_stop`, `net_discover_peer`
`vision`	(始终可见)	`vision_describe`
`web_search`	(始终可见)	`web_search`
`im_local` / `im_telegram` / 等	(始终可见)	`local_send_text`, `telegram_send_text`, `feishu_send_message`, `wechat_send_text`, `qq_send_message`, `im_send_media`
`board`	board_hardware_info （需先激活）	`board_list_devices`, `board_get_device`, `board_query_peripheral`, `board_schema`, `board_reload`
`audio_stream`	camera_capture （需先激活）	`audio_stream_start`, `audio_stream_tx_start`, `audio_stream_rx_start`, `audio_stream_stop`, `audio_stream_pause`, `audio_stream_status`

Capability 速查表

文件管理

Capability	说明
`file_read`	从 `vfs:/` 或 `rolfs:/` 读取文件内容
`file_write`	写入或追加文件内容
`file_delete`	删除文件（会先停止使用该路径的 Lua 任务）
`file_list`	列出指定路径下的文件和子目录
`file_move`	移动或重命名文件
`file_copy`	将文件复制到新路径
`file_stat`	获取文件元数据（大小、类型、修改时间）

Skill 管理

Capability	说明
`skill_list`	列出所有可用 Skill（内置 + 用户）
`skill_activate`	在当前会话中激活 Skill；注入其 SKILL.md 上下文并解锁对应 cap_groups
`skill_save`	保存新的用户 Skill（SKILL.md + 可选 scripts/main.lua）
`skill_delete`	删除用户创建的 Skill 目录
`skill_deactivate`	从会话激活列表中停用 Skill

Lua 执行

Capability	说明
`lua_run`	同步执行 Lua 脚本；返回 `run()` 返回值及 `print()` 输出
`lua_run_async`	以后台任务方式启动 Lua 脚本；立即返回 `job_id`
`lua_job_get`	获取后台任务状态及增量日志输出（通过 since_seq 参数）
`lua_job_list`	列出所有后台 Lua 任务及其状态
`lua_job_stop`	协作式停止正在运行的后台任务

调度器

Capability	说明
`scheduler_add_job`	添加或更新调度任务（支持 event_type、delay_sec、interval_sec、cron）
`scheduler_list_jobs`	列出所有已注册的调度任务
`scheduler_remove_job`	按 ID 删除调度任务
`scheduler_enable_job`	启用之前已禁用的任务
`scheduler_disable_job`	禁用任务而不删除

板级硬件 (需先激活 board_hardware_info )

Capability	说明
`board_list_devices`	列出板上所有已注册的硬件设备（传感器、显示屏等）
`board_get_device`	获取设备完整信息：芯片、接口引脚分配、驱动参数
`board_query_peripheral`	查询某类外设是否可用及哪些引脚/实例空闲
`board_schema`	获取板级硬件描述 Schema（芯片定义、约束条件）
`board_reload`	从 VFS 重新加载 board.json 配置

系统信息

Capability	说明
`get_heap_info`	获取空闲堆内存及历史最小值
`get_task_list`	列出所有 FreeRTOS 任务的状态、优先级和栈水位
`get_info`	获取芯片型号、固件版本、运行时间
`get_wifi`	获取 Wi-Fi SSID、信道、RSSI 及 IP 地址
`get_ip`	获取当前 IP 地址
`restart`	短暂延迟后软复位设备

时间

Capability	说明
`get_current_time`	获取当前挂钟时间（UTC+8）及 Unix 时间戳
`sync_time`	触发 SNTP 时间同步并将结果写入系统时钟和 RTC

网络

Capability	说明
`http_request`	发起 HTTP/HTTPS 请求（GET/POST/PUT/PATCH/DELETE/HEAD）；返回状态码和响应体
`net_discover_start`	启动持续的 UDP 广播/监听对端发现；在对端出现/消失时触发回调
`net_discover_stop`	停止对端发现后台服务
`net_discover_peer`	一次性对端发现（阻塞直至找到或超时）

音频流 (需先激活 camera_capture )

Capability	说明
`audio_stream_start`	一次性同时启动 RX（UDP→扬声器）和 TX（DMIC→UDP）流
`audio_stream_tx_start`	启动 DMIC 到 UDP 的发送流（C 层控制推送开关）
`audio_stream_rx_start`	启动 UDP 到扬声器的接收流；应在 TX 之前调用
`audio_stream_stop`	停止 TX 和 RX 流任务
`audio_stream_pause`	暂停音频流
`audio_stream_status`	获取 TX/RX 运行状态及 UDP 包计数

视觉

Capability	说明
`vision_describe`	对摄像头图像进行视觉描述

网络搜索

Capability	说明
`web_search`	执行网络搜索并返回摘要结果

即时通讯

Capability	说明
`local_send_text`	向本地 WebUI 发送文本消息
`telegram_send_text`	通过 Telegram Bot 发送文本消息
`feishu_send_message`	通过飞书发送消息
`wechat_send_text`	通过微信发送文本消息
`qq_send_message`	通过 QQ 发送消息
`im_send_media`	向 IM 平台发送媒体文件

AT 命令接口

列出所有已注册的 Capability：

AT+CLAW=cap

列出所有已安装的 Skill（调用 skill_list Capability）：

AT+CLAW=cap,skill_list

调用 Capability 并传入 JSON 参数：

AT+CLAW=cap,<capability_id>,<json_args>

示例：

AT+CLAW=cap,get_info
AT+CLAW=cap,file_list,{"path":"vfs:/skills/"}
AT+CLAW=cap,lua_run,{"path":"vfs:/tmp/test.lua","args":{}}
AT+CLAW=cap,skill_activate,{"name":"board_hardware_info"}

指定会话 ID（用于控制每会话 cap_groups 可见性）：

AT+CLAW=cap,<capability_id>,<json_args>,sid,<session_id>

在 Lua 脚本中调用 Capability

在 Skill 脚本中使用 cap Lua 模块。cap.call 始终返回两个值：

local cap   = require("cap")
local cjson = require("cjson")

-- 正确：同时接收 ok（布尔值）和 result_json（字符串）
local ok, result_json = cap.call("get_current_time", "{}")
if not ok then
    return '{"error":' .. (result_json or '"cap call failed"') .. '}'
end
local t = cjson.decode(result_json)
-- 使用 t.timestamp、t.datetime 等字段

-- 错误：只接收一个返回值时，变量得到的是布尔值 ok，JSON payload 被丢弃
-- local result = cap.call("get_current_time", "{}")  -- 请勿这样写