创建第一个自定义插件

在之前的章节中，我们了解到插件就像是 AI Bot 的技能包，它让助手能够具备各种各样的能力。有了天气查询插件，助手就能报天气；有了翻译插件，助手就能当翻译；有了购物插件，助手就能帮你网购……

总的来说，插件的优势主要有以下几点：

扩展功能：插件能让 AI Bot一专多能，满足用户的多样化需求。
提升效率：通过插件，AI Bot 可以自动化完成很多任务，大大节省时间。
个性化定制：不同的用户可以根据自己的喜好，选择安装不同的插件，打造专属的 AI Bot。

那么，作为一个普通用户，我们能不能也参与到插件的开发中来呢？答案是肯定的！你可能会问，开发插件对我有什么好处呢？首先，这是一个很好的学习机会，能让你对人工智能技术有更直观的了解。其次，通过创建插件，你可以让 AI Bot 更好地服务于你的实际需求。比如，你可以开发一个每日笑话插件，让助手每天给你讲笑话；或者开发一个股票行情插件，让助手随时为你报股票价格。

准备工作

在我们正式开始开发插件之前，需要做一些准备工作，主要是了解 Coze IDE，并设置好开发环境。

Coze IDE 是 Coze 平台提供的在线插件开发工具。你可以把它想象成一个智能化的工作台，它集成了编写代码、管理依赖、测试运行、发布上线等一系列功能，让插件开发变得非常便捷。

Coze IDE 支持 Node.js 和 Python 两种运行环境，你可以根据自己的习惯选择。无论你选择哪一种，Coze IDE 都会帮你打理好所有的环境配置问题，你只需要专注于插件的功能实现就行了。（这里我们选择 Python 环境，并开始创建一个有关对接高德地图服务的插件）

在 Coze IDE 的界面上，你会看到代码编辑器、依赖管理器、测试运行区等各种功能模块，就如上图所示。

构思你的插件

在这次的例子中，我会以对接高德地图的 API 天气查询这个功能为例，带你一步步设计出插件的基本结构。当然，你也可以根据自己的实际需求，设计出其他功能的插件。

高德地图天气查询 API 文档

所以，在这个插件中，我们要新增一个天气查询的功能：

定义插件功能

首先，我们要明确插件的功能是什么。根据天气查询插件的介绍，我们可以总结出这个插件的主要功能:

根据输入的城市编码(adcode)，查询该城市的天气情况。
支持查询实况天气和预报天气两种类型。
返回天气的基本信息，包括温度、湿度、风向、风力等。
数据来源是中国气象局，通过高德地图的 API 接口获取。

了解了插件的功能后，我们可以开始设计输入输出参数了。

设计插件的输入输出参数

根据天气查询插件的 API 文档，我们可以设计出如下的输入输出参数:

输入参数:
- city (字符串类型):城市编码，即 adcode，用于指定查询的城市。
- extensions (字符串类型，可选):气象类型，可选值为base(实况天气)或all(预报天气)，默认为base。
- output (字符串类型，可选):返回格式，可选值为JSON或XML，默认为JSON。
输出参数:
- status (字符串类型):返回状态，值为0或1，其中1表示成功，0表示失败。
- count (整数类型):返回结果总数目。
- info (字符串类型):返回的状态信息。
- infocode (字符串类型):返回状态说明，值为10000表示正确。
- lives (数组类型，当 extensions 为base时返回):实况天气数据信息，每个元素包括:
  - province (字符串类型):省份名。
  - city (字符串类型):城市名。
  - adcode (字符串类型):区域编码。
  - weather (字符串类型):天气现象(汉字描述)。
  - temperature (字符串类型):实时气温，单位为摄氏度。
  - winddirection (字符串类型):风向描述。
  - windpower (字符串类型):风力级别，单位为级。
  - humidity (字符串类型):空气湿度。
  - reporttime (字符串类型):数据发布的时间。
- forecasts (数组类型，当 extensions 为all时返回):预报天气数据信息，每个元素包括:
  - city (字符串类型):城市名称。
  - adcode (字符串类型):城市编码。
  - province (字符串类型):省份名称。
  - reporttime (字符串类型):预报发布时间。
  - casts (数组类型):预报数据列表，包含当天、第二天、第三天的预报数据，每个元素包括:
    - date (字符串类型):日期。
    - week (字符串类型):星期几。
    - dayweather (字符串类型):白天天气现象。
    - nightweather (字符串类型):晚上天气现象。
    - daytemp (字符串类型):白天温度。
    - nighttemp (字符串类型):晚上温度。
    - daywind (字符串类型):白天风向。
    - nightwind (字符串类型):晚上风向。
    - daypower (字符串类型):白天风力。
    - nightpower (字符串类型):晚上风力。

可以看到，虽然这个插件的功能看似简单，但实际的输入输出参数还是比较复杂的，特别是输出参数，根据不同的查询类型(实况或预报)，会返回不同的数据结构。这就需要我们在实现插件功能时，要仔细阅读 API 文档，正确处理各种情况。

步步为营：开发你的第一个插件

现在，我们已经有了插件的基本构思，接下来就要在 Coze IDE 中实现它了。首先，我们需要在 Coze IDE 中创建一个新的插件项目。

登录 Coze 平台，进入你的个人空间或团队空间。
点击左侧导航栏的 插件 选项，进入插件管理页面。
点击右上角的 创建插件 按钮，在弹出的对话框中填写插件的基本信息:
- 插件名称：高德地图服务对接
- 插件描述：对接高德地图的第三方服务
- 插件创建方式：选择 在 Coze IDE 中创建
- IDE 运行时：选择 Python3 (当然你也可以选择 Node.js，看你更熟悉哪种语言)
点击 确定 按钮，就创建了一个新的插件项目。

接着，我们基于这个插件，创建一个天气查询的工具，如下图：

配置插件工具的元数据

创建完插件项目后，我们需要配置其对应工具的元数据，主要是定义输入参数和输出参数的结构。

在插件详情页面，点击 元数据 标签，进入元数据编辑界面。
在 输入参数 部分，按照我们之前设计的，添加以下参数:
- city:城市编码，字符串类型，必填。
- extensions:气象类型，字符串类型，可选，默认值为 base。
- output:返回格式，字符串类型，可选，默认值为 JSON。
在 输出参数 部分，按照我们之前设计的，添加以下参数:
- status:返回状态，字符串类型。
- count:返回结果总数目，整数类型。
- info:返回的状态信息，字符串类型。
- infocode:返回状态说明，字符串类型。
- lives:实况天气数据，数组类型，每个元素包含 province、city、adcode、weather、temperature、winddirection、windpower、humidity、reporttime 等字段。
- forecasts:预报天气数据，数组类型，每个元素包含 city、adcode、province、reporttime、casts 等字段，其中 casts 又是一个数组，包含未来三天的天气预报数据。

编写核心代码

有了明确的输入输出接口，我们就可以开始编写插件的核心代码了。

在插件详情页面，点击 代码 标签，进入代码编辑界面。
在代码编辑器中，你会看到一个基本的代码模板，主要包含一个 handler 函数，这个函数就是我们插件的入口。
在 handler 函数中，我们可以通过 args 参数获取到调用插件时传入的参数，其中 args.input 包含了我们定义的输入参数。
根据输入参数，我们可以构造高德地图 API 的请求 URL 和参数，然后使用 Python 的 requests 库发送 GET 请求，获取返回的 JSON 数据。
拿到 JSON 数据后，我们需要按照插件定义的输出参数结构，将数据进行转换和封装，最终返回给调用方。
在处理数据的过程中，我们还需要注意一些特殊情况的处理，比如网络请求失败、返回数据格式不正确等，要给出相应的错误提示。

下面是一个简化版的 handler 函数实现，供参考:

python

from runtime import Args
from typings.get_weather.get_weather import Input， Output
import requests

def handler(args: Args[Input])->Output:
    city = args.input.city
    extensions = args.input.extensions if args.input.extensions else `base`
    output = args.input.output if args.input.output else `JSON`

    if not city:
        raise ValueError('城市编码不能为空')

    url = 'https://restapi.amap.com/v3/weather/weatherInfo'
    params = {
        'city': city，
        'extensions': extensions，
        'output': output，
        'key': '你具体高德地图的 api key'，
    }

    try:
        response = requests.get(url， params=params)
        response.raise_for_status()
        data = response.json()

        if data['status'] != '1':
            raise ValueError(f'天气查询失败: {data[`info`]}')

        return {
            'status': data['status']，
            'count': data['count']，
            'info': data['info']，
            'infocode': data['infocode']，
            'lives': data.get('lives'， [])，
            'forecasts': data.get('forecasts'， [])，
        }
    except requests.exceptions.RequestException as err:
        raise ValueError(f'天气查询失败: {err}')

在这个实现中，我们使用了 Python 的 requests 库来发送 HTTP 请求。如果请求失败，或者返回的数据状态异常，我们会抛出相应的错误。最终，我们按照定义的输出参数结构，返回处理后的数据。

当然，这只是一个简化版的实现，实际开发中，你可能还需要考虑更多的细节和边界情况。

依赖包管理

在上一步编写核心代码时，我们用到了 requests 这个第三方库。在 Coze IDE 中，Python 的依赖管理与 Node.js 略有不同，但基本原理是一样的。

在 Python 中，我们通常使用 pip 命令来安装第三方库。但在 Coze IDE 中，我们可以直接在代码编辑器左下角的 依赖 部分进行操作。
要安装一个新的库，可以在 依赖 部分的搜索框中，输入库的名称，如 requests，然后在搜索结果中选择需要的版本，点击 安装 按钮即可。
安装完成后，我们就可以在代码中使用 import 语句来引用这个库了，就像上述的示例代码中那样。
如果我们不再需要某个库，也可以在 依赖 列表中，找到这个库，点击右侧的删除按钮来卸载它。

调试与测试

编写完核心代码后，我们需要对插件进行调试和测试，确保它能够正常工作。

在插件详情页面，点击 测试 标签，进入测试界面。
在 输入参数 部分，我们可以填写一组测试数据，比如:
- city: 110000(北京市的编码)
填写完参数后，点击 运行 按钮，就可以看到插件的输出结果了。
如果输出结果不正确，或者插件运行出错，我们可以回到 代码 标签，检查和修改代码，然后再次运行测试。
我们可以准备多组测试数据，覆盖不同的输入情况，以确保插件的稳定性和正确性。

发布你的插件

经过前面的开发、测试和优化，我们的天气查询插件工具已经基本完成了。现在，是时候将它发布到 Coze 平台，让更多的用户能够使用和受益了。

在 Coze 平台上发布一个插件，整个流程非常简单和便捷:

在插件详情页面，点击右上角的 发布 按钮。
查看一下插件的发布信息，确认无误后，点击 下一步 按钮，稍等片刻，你的插件就发布成功了。

发布成功后，你的插件就可以在 Coze 平台的插件市场中被其他用户搜索和使用了。

总结

通过上面的学习，相信你已经掌握了在 Coze 平台上开发和发布一个自定义插件的全流程。创新和尝试固然重要，但我们也要重视用户的反馈和意见。一个好的插件，不仅要有出色的功能，还要有良好的用户体验和口碑。所以，