coze基础用法

# 导入 Coze 运行时所需的 Args 类，用于获取输入参数和日志记录器
from runtime import Args
# 导入 requests 库，用于发送 HTTP 请求（调用天气 API）
import requests # 需要安装对应的库

# 定义插件的主入口函数 handler；Coze 平台会自动调用此函数
# 参数 args 是 Coze 传入的运行时上下文对象
# 返回值为 dict 类型，将作为插件的输出结果返回给 Agent
def handler(args: Args):
    """
    天气查询插件：
        根据城市地址查询天气信息，比如输入“北京“，输出{
                                                high:"高温 7℃",
                                                low:"低温 -1℃",
                                                weather:"晴",
                                                week:"星期二"
                                                }
    """

    # === 1. 解析输入 ===
    try:
        # 从 args.input 中获取 location 字段，并去除首尾空格（如用户输入 " 北京 "）
        # 注意：此处假设输入为对象属性访问（如 args.input.location），适用于 manifest 中声明了 location 字段的情况
        location = args.input.location.strip()
    except Exception:
        # 若获取 location 失败（如字段不存在、输入非对象等），设为空字符串
        location = ""

    # === 2. 城市编码映射（仅北京、天津，内置）===
    # 构建城市名称 → 天气 API 编码的映射字典（仅保留北京和天津两个城市，轻量且教学友好）
    city_code_map = {
        "北京": "101010100",   # 北京市的天气 API 编码
        "天津": "101030100"    # 天津市的天气 API 编码
    }
    # 根据用户输入的城市名，查找对应的编码；若找不到则返回 None
    city_code = city_code_map.get(location)

    # 不支持的城市（如输入“上海”或空字符串）→ 返回空值结构
    if not city_code:
        # 记录警告日志：提示该城市暂不支持（可在 Coze 后台查看）
        args.logger.warning(f"Unsupported location: '{location}'")
        # 返回标准化的空结果（所有字段为 None），保证输出结构一致
        return {
            "high": None,       # 最高温度
            "low": None,        # 最低温度
            "weather": None,    # 天气类型（如“晴”）
            "week": None        # 星期（如“星期二”）
        }

    # === 3. 调用天气 API ===
    # 拼接完整 API 请求 URL，替换 {city_code} 为实际城市编码
    url = f"http://t.weather.itboy.net/api/weather/city/{city_code}"
    
    try:
        # 发起 GET 请求，设置超时 5 秒（防止插件卡死）
        response = requests.get(url, timeout=5)
        # 若 HTTP 状态码非 2xx，主动抛出异常（如 404、500 等）
        response.raise_for_status()
        # 将响应体解析为 JSON 字典（安全方式，避免使用危险的 eval()）
        data = response.json()

        # 检查 API 业务层返回状态码（该 API 约定 status=200 表示成功）
        if data.get("status") != 200:
            # 若业务状态异常（如城市编码错误），抛出自定义异常
            raise ValueError("Weather API returned non-200 status")

        # 从返回数据中提取「今日」天气预报（forecast 列表第 0 项即为当天）
        # 路径：data → forecast 数组 → 第 0 个元素
        forecast = data["data"]["forecast"][0]
        
        # 构造并返回天气基本信息字典
        return {
            "high": forecast["high"],     # 字符串，如 "高温 7℃"
            "low": forecast["low"],       # 字符串，如 "低温 -1℃"
            "weather": forecast["type"],  # 字符串，如 "晴"、"小雨"
            "week": forecast["week"]      # 字符串，如 "星期二"
        }

    # 捕获所有可能的异常（网络错误、JSON 解析失败、字段缺失等）
    except Exception as e:
        # 记录错误日志，包含具体异常信息和请求城市，便于调试
        args.logger.error(f"Weather query failed for '{location}': {e}")
        # 统一返回空值结构，确保插件健壮性（不会因异常导致 Agent 崩溃）
        return {
            "high": None,
            "low": None,
            "weather": None,
            "week": None
        }