自定义插件

配置

修改配置文件

根据以下说明，修改项目根目录的setting.yaml文件（或使用默认路径）：

custom:
  # 自定义唤醒热词存放路径，建议不要使用太多的热词模型，防止误唤醒
  hotwords: '~/.kim/hotwords'
  # 自动以插件存放路径
  plugins: '~/.kim/plugins'  # 该目录下的插件支持热重载，修改后无需重新运行脚本

编写插件

编写规范

• 插件依赖的方法及参数说明

  is_all_word_segment_in_text()方法：判断输入text与插件的WORDS予以匹配

  plugin_output()方法：插件信息输出，输出方式取决于当前的Mic运行模式（text/voice）

  WORDS：list数据类型，以数组的形式设置唤醒插件的关键字

  PRIORITY：定义插件优先级，因为插件响应时以优先级搞的为准

  logger：初始化日志对象，方便插件运行调试

以下为示例代码：

# -*- coding: utf-8-*-
import logging

WORDS = ["echo", "传话", "重复一下"]
PRIORITY = 0
logger = logging.getLogger()
from src.plugins import is_all_word_segment_in_text,plugin_output

• 必要方法

  包含is_valid()和handle()两个方法，is_valid()用于判断输入text与插件定义的WORDS是否语义匹配

  ​

  以下"Echo"插件为例：

  def handle(text, mic, profile, iot_client=None, chatbot=None):
      """
      插件处理入口
      :param text: 插件传入文本
      :param mic:
      :param profile:
      :param iot_client: 传入物联网对象，自定插件照写即可
      :param chatbot: 传入chatbot对象
      :return:
      """
      text_str = ''.join(text)
      robot_says = text_str.replace('echo', '').replace('传话', '').replace('重复一下', '')
      plugin_output(text, mic, robot_says)  # 输出响应
  
  def is_valid(text):
      """
      判断输入text与插件定义的WORDS是否语义匹配
      :param text:
      :return:
      """
      return is_all_word_segment_in_text(WORDS, text)

  ​

• 返回消息通过机器人输出到钉钉群

  插件响应信息输出到钉钉有两种方式：

  1. 用户输入信息语义包含“发送到钉钉”

  2. 有些插件，在输出结果时，可能不利于通过单行文本或语音的方式展示。在对应情况下，我们可以设置强制发送到钉钉

    plugin_output(text, mic, robot_says,force_ding=True)  # 输出插件响应

扩展思路

我们编写插件，可能希望控制智能家居设备，也可能希望查询信息；Kim分别提供了“阿里云API市场”和“HomeAssistant”接入方案，以下为抛砖引玉：

• 阿里云API市场（https://market.aliyun.com/data）

  阿里云的API市场提供了丰富的API输出能力，为开发者提供了驾照查分、物流查询、股票行情、油价、交通、翻译等众多API接口。缺点是，目前API的计费方式不够友好，在接入API较多时维护会比较麻烦。 以Python为例，插件handle()函数的写法：

  def handle(text, mic, profile, iot_client=None,chatbot=None):
      text = ''.join(text)
      host = 'http://jisuzxfy.market.alicloudapi.com'
      path = '/translate/translate'
      method = 'GET'
      appcode = load_yaml_settings()['aliyun']['api_market']['appcode']
      querys = 'from=zh-CN&text=' + text + '&to=en&type=google'
      bodys = {}
      url = host + path + '?' + querys
      headers = {
          'Authorization': 'APPCODE ' + appcode,
          'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8'
      }
      r = requests.request(method=method, url=url, data=bodys, headers=headers)
      data = json.loads(r.content.decode('utf8'))
      if int(data['status']) == 0:
          mic.say(data['result']['result'])
      else:
          mic.say('阿里云接口调用出错，检查一下插件吧')

  其中涉及到的配置文件：

  aliyun:
    api_market:  # 云市场
      appcode: "<你的Appcode>"

  ※ 阿里云API市场配置和接入方法

• 基于“HomeAssistant”的智能家居（https://home-assistant.io/）

  围绕HomeAssistant的智能家居方案已经相对比较成熟，目前已经支持国内的小米、博联等国内的智能家居品牌，Kim项目会基于小米给出对应的方案。

  HA目前已支持接入“小米智能网关”和“小米万能遥控器”，更多资料，请移步HA官网。

  Kim插件接入参考：https://home-assistant.io/developers/python_api/

阿里云API市场和HomeAssistant赋予了Kim丰富的扩展空间，等你一起来挖掘更多更有意思的玩法，欢迎在issue中或加入钉钉群讨论。

※ 插件贡献请看此文