Cherry Studio Agent Skill 入门指南：从零构建你的第一个智能体技能

共计 2224 个字符，预计需要花费 6 分钟才能阅读完成。

核心概念：Agent Skill 是什么？

可以把 Agent Skill 想象成手机里的各种小程序：每个技能专注解决一个特定问题（比如查天气、订餐厅），而 Cherry Studio 就是运行这些技能的智能手机平台。当用户说 ” 明天会下雨吗 ” 时，系统会自动匹配天气查询技能，你的代码负责处理这个请求并返回答案。

关键组件：

• 意图（Intent）：用户想要做什么（如 ” 查询天气 ”）
• 实体（Entity）：关键参数（如 ” 北京 ”、” 明天 ”）
• 对话流（Dialog Flow）：多轮交互逻辑

环境准备

1. 注册 Cherry Studio 开发者账号
2. 安装必备工具：
3. Python 3.8+ 或 Node.js 16+
4. VS Code 或其他 IDE
5. 安装 SDK（以 Python 为例）：

   pip install cherry-sdk

6. 获取 API 密钥：在开发者控制台创建新项目后获取

开发实战：天气查询技能

1. 创建技能骨架

# weather_skill.py
from cherry import AgentSkill, Request, Response

class WeatherSkill(AgentSkill):
    def __init__(self):
        super().__init__(
            name="weather",
            description="查询城市天气情况"
        )

    async def execute(self, request: Request) -> Response:
        """处理天气查询请求"""
        city = request.entities.get("city")  # 获取城市参数
        # 这里会继续补充...

2. 处理地理参数

# 在 execute 方法中添加：if not city:
    return Response(
        text="请问您想查询哪个城市的天气？",
        requires_slot="city"  # 要求用户补充信息
    )

3. 调用天气 API（示例用 OpenWeatherMap）

import os
import requests

# 在类中添加方法
async def _get_weather(self, city: str) -> dict:
    api_key = os.getenv("WEATHER_API_KEY")
    url = f"https://api.openweathermap.org/data/2.5/weather?q={city}&appid={api_key}"
    try:
        response = requests.get(url)
        data = response.json()
        return {"temp": round(data["main"]["temp"] - 273.15, 1),  # 转摄氏度
            "desc": data["weather"][0]["description"]
        }
    except Exception as e:
        print(f"API 调用失败: {e}")
        return None

4. 返回结构化响应

# 完善 execute 方法
weather_data = await self._get_weather(city)
if not weather_data:
    return Response(text="暂时无法获取天气信息，请稍后再试")

return Response(text=f"{city}当前天气：{weather_data['desc']}，气温{weather_data['temp']}℃",
    entities={"city": city}  # 记住上下文
)

调试与测试

本地测试方法

1. 模拟请求对象：

   test_request = Request(
       intent="query_weather",
       entities={"city": "北京"}
   )
   print(await WeatherSkill().execute(test_request))

2. 使用 SDK 测试工具：

   cherry-cli test --skill weather_skill.py

云端调试技巧

• 在开发者控制台查看请求日志
• 使用 ” 对话回放 ” 功能重现问题场景
• 设置断点调试（需配置远程调试）

生产部署

1. 打包技能：

   cherry-cli pack --skill weather_skill.py --output weather.zip

2. 发布流程：

3. 控制台上传 zip 包
4. 填写版本说明

5. 选择发布环境（测试 / 生产）

6. 性能优化：

7. 添加缓存（示例）：

   from datetime import timedelta
   from cachetools import TTLCache
   
   # 在__init__中添加：self.cache = TTLCache(maxsize=100, ttl=timedelta(minutes=30))

8. 安全注意事项：

9. 永远不要硬编码 API 密钥
10. 验证用户输入（防止 SQL 注入等）
11. 设置合理的 API 调用频率限制

避坑指南

1. 报错：Missing required slot
   → 检查是否所有必填参数都设置了 requires_slot 提示

2. API 响应慢
   → 添加超时设置和重试机制

   response = requests.get(url, timeout=3)

3. 中文乱码
   → 确保响应头包含Content-Type: application/json; charset=utf-8

4. 技能不触发
   → 检查控制台中的意图匹配配置是否正确

5. 变量未定义
   → 使用类型提示和 mypy 静态检查

下一步学习建议

掌握基础技能后，可以尝试：

• 添加多轮对话（如询问具体日期）
• 集成数据库存储用户偏好
• 开发包含 UI 组件的富交互技能
• 学习技能组合（Chain Skill）实现复杂流程

官方文档中还有更多高级功能等待探索，祝你开发愉快！