内置工具 API 参考

CeeCore 为 Agent 技能提供了一套内置工具。这些工具无需在 tools.json 中声明即可使用，覆盖了最常见的技能需求。

工具概览

工具	用途	权限要求
http_request	发送 HTTP 请求	http
schedule_task	创建定时任务	cron
send_notification	推送通知	notification
read_file	读取文件	file
write_file	写入文件	file
search_memory	搜索设备记忆	无
get_device_info	获取设备信息	无

最低版本要求：CeeCore 固件 ≥ 1.0.0。部分工具在更高版本中新增参数。

http_request — HTTP 请求

发送 HTTP 请求到外部 API。

参数

参数	类型	必填	说明
url	string	✅	请求 URL
method	string	❌	HTTP 方法，默认 "GET"
headers	object	❌	请求头
body	string/object	❌	请求体（POST/PUT 时使用）
timeout	integer	❌	超时时间（秒），默认 30

示例

{
  "name": "http_request",
  "parameters": {
    "url": "https://api.openweathermap.org/data/2.5/weather",
    "method": "GET",
    "headers": {
      "Accept": "application/json"
    },
    "timeout": 10
  }
}

返回值

{
  "status": 200,
  "headers": {},
  "body": {}
}

注意事项

• 所有外部 HTTP 请求需要 http 权限
• 请求超时默认 30 秒，最大 60 秒
• 响应体自动解析 JSON，非 JSON 返回文本
• 不支持重定向跟随（3xx 状态码直接返回）

schedule_task — 定时任务

创建定时执行的任务。

参数

参数	类型	必填	说明
name	string	✅	任务名称
schedule	string	✅	Cron 表达式或时间描述
action	string	✅	触发时执行的操作描述
enabled	boolean	❌	是否启用，默认 true

Cron 表达式支持

分钟 小时 日期 月份 星期
*    *    *    *    *

示例：
"0 8 * * *"     → 每天早上 8:00
"0 */6 * * *"   → 每 6 小时
"30 9 * * 1-5"  → 工作日早上 9:30

时间描述支持

也可以用自然语言描述时间：

"every morning at 8:00"
"every 6 hours"
"every weekday at 9:30"

示例

{
  "name": "schedule_task",
  "parameters": {
    "name": "morning-weather",
    "schedule": "0 8 * * *",
    "action": "获取天气数据并推送给用户",
    "enabled": true
  }
}

注意事项

• 需要 cron 权限
• 任务名称全局唯一
• 设备重启后定时任务自动恢复
• 最多同时运行 20 个定时任务

send_notification — 推送通知

向用户发送推送通知。

参数

参数	类型	必填	说明
title	string	✅	通知标题
message	string	✅	通知内容
priority	string	❌	优先级："low"/"normal"/"high"
sound	boolean	❌	是否播放声音，默认 true
badge	integer	❌	应用角标数字

示例

{
  "name": "send_notification",
  "parameters": {
    "title": "今日天气",
    "message": "北京今天晴，15℃~25℃，适合出行",
    "priority": "normal",
    "sound": true
  }
}

优先级说明

优先级	行为
low	静默推送，仅在通知中心显示
normal	标准推送，有声音和横幅
high	强提醒，忽略勿扰模式

注意事项

• 需要 notification 权限
• 单条通知内容 ≤ 500 字符
• 每小时最多推送 10 条（防止骚扰）
• high 优先级仅用于紧急情况

read_file — 读取文件

从设备文件系统读取文件内容。

参数

参数	类型	必填	说明
path	string	✅	文件路径（相对于技能工作目录）
encoding	string	❌	编码，默认 "utf-8"
max_bytes	integer	❌	最大读取字节数，默认 1048576（1MB）

示例

{
  "name": "read_file",
  "parameters": {
    "path": "data/config.json",
    "encoding": "utf-8"
  }
}

返回值

{
  "path": "data/config.json",
  "content": "...",
  "size": 1024,
  "encoding": "utf-8"
}

注意事项

• 需要 file 权限
• 只能读取技能工作目录下的文件
• 最大读取 10MB
• 不支持二进制文件

write_file — 写入文件

向设备文件系统写入文件。

参数

参数	类型	必填	说明
path	string	✅	文件路径（相对于技能工作目录）
content	string	✅	文件内容
encoding	string	❌	编码，默认 "utf-8"
append	boolean	❌	是否追加，默认 false（覆盖）

示例

{
  "name": "write_file",
  "parameters": {
    "path": "reports/daily-2026-08-27.md",
    "content": "# 工作日报\n\n...",
    "encoding": "utf-8"
  }
}

注意事项

• 需要 file 权限
• 只能写入技能工作目录下
• 自动创建不存在的父目录
• 单文件最大 10MB

search_memory — 搜索记忆

在设备的记忆系统中搜索信息。

参数

参数	类型	必填	说明
query	string	✅	搜索关键词
limit	integer	❌	返回数量，默认 10，最大 50
category	string	❌	记忆分类过滤

示例

{
  "name": "search_memory",
  "parameters": {
    "query": "用户偏好",
    "limit": 5
  }
}

返回值

{
  "results": [
    {
      "content": "用户喜欢简洁的回复风格",
      "category": "preference",
      "timestamp": "2026-08-27T08:00:00Z"
    }
  ],
  "total": 15
}

注意事项

• 无需权限声明
• 只能搜索当前用户授权范围内的记忆
• 搜索结果按相关度排序

get_device_info — 获取设备信息

获取 CeeCore 设备的系统信息。

参数

无必填参数。

参数	类型	必填	说明
fields	string[]	❌	要获取的信息字段，默认全部

可选字段："version"、"uptime"、"storage"、"memory"、"network"、"skills"

示例

{
  "name": "get_device_info",
  "parameters": {
    "fields": ["version", "uptime", "storage"]
  }
}

返回值

{
  "version": "1.2.0",
  "uptime": 86400,
  "storage": {
    "total": 34359738368,
    "used": 8589934592,
    "available": 25769803776
  },
  "memory": {
    "total": 8589934592,
    "used": 4294967296
  },
  "network": {
    "type": "wifi",
    "ip": "192.168.1.100"
  },
  "skills": {
    "installed": 8,
    "active": 5
  }
}

注意事项

• 无需权限声明
• 返回的设备信息不包含用户隐私数据

完整使用示例

以下是一个技能 prompt.md 中综合使用多个内置工具的示例：

# 日报生成器

## 任务

每天下午 5:00，自动生成工作日报：

1. 使用 `search_memory` 搜索今天的对话记录
2. 使用 `http_request` 查询今日日历事件
3. 使用 `read_file` 读取日报模板
4. 根据以上信息生成日报
5. 使用 `write_file` 保存日报到 `reports/` 目录
6. 使用 `send_notification` 推送日报摘要

## 工具使用规则

- `http_request`：调用日历 API 时超时设置 10 秒
- `search_memory`：搜索关键词为日期 + "工作"
- `send_notification`：优先级 normal，不需要声音
- 所有文件操作都在技能工作目录下

权限速查

你想用的工具	需要的权限
http_request	http
schedule_task	cron
send_notification	notification
read_file / write_file	file
search_memory	无
get_device_info	无

在 manifest.json 中声明权限：

"permissions": ["http", "cron", "notification", "file"]

← manifest.json Schema 参考 | 返回开发者入门概览