mycroft-core 开发指南:Skills API 与 Plugin API 全解析

原创2026-10-14 19:41:201,981 阅读
文章标签:人工智能语音交互助手智能硬件

mycroft-core 开发指南:Skills API 与 Plugin API 全解析

本文以 mycroft-core 仓库中的技术文档(doc/index.rst 及其下属文档树)为骨架,系统梳理 Mycroft 人工智能平台的技能(Skill)开发接口与插件(Plugin)开发接口。读者将掌握 MycroftSkill 基类、四大常用 Skill 子类(CommonIoTSkill、CommonPlaySkill、CommonQuerySkill、FallbackSkill)、意图注册与上下文管理机制,以及 TTS、STT、唤醒词、音频后端四类插件的基类契约与配置接入方式,同时了解 util 工具库在自然语言解析、文本格式化与资源处理上的实战用法。

文档结构总览:一份面向开发者的 API 参考

doc/index.rst 是 Mycroft 技术文档的入口主文件,它把整套参考手册划分为两个面向不同开发者的部分:

  • Mycroft Skills API(doc/index.rst 第 6-15 行):供技能作者(Skill author)在开发技能时查阅的类与方法参考,正文入口指向 doc/source/mycroft.rst。
  • Mycroft plugin API(doc/index.rst 第 17-25 行):供插件作者(Plugin author)在扩展平台能力时查阅的基类参考,正文入口指向 doc/source/plugins.rst。

两部分均以 Sphinx autoclass / autofunction 指令直接从源码生成 API 文档,因此本文的每一个类、方法、装饰器都与仓库中的真实实现一一对应,可作为技能与插件开发的权威索引。

Mycroft Skills API:技能开发的核心类与装饰器

技能是 Mycroft 中承载业务能力的基本单元。doc/source/mycroft.rst 依次列出了技能开发需要用到的核心类、装饰器与工具模块,下面结合源码逐一展开。

MycroftSkill:所有技能的基类

MycroftSkill(源码位于 mycroft/skills/mycroft_skill/mycroft_skill.py)是所有技能都必须继承的基类,构造参数包括:

  • name:技能名称,缺省时使用类名;
  • bus:可选的 MycroftWebsocketClient 消息总线连接;
  • use_settings:设为 False 可完全不使用技能设置(默认 True)。

基类在构造时自动完成大量初始化工作(见 __init__,第 119-167 行),技能作者在派生类中可直接使用以下成员:

成员 类型 说明
self.name str 技能名称
self.root_dir str 技能根目录的绝对路径,如 /opt/mycroft/skills/my-skill.me/
self.config_core dict Mycroft 全局配置
self.settings dict 技能设置,修改后会在事件处理结束时自动保存
self.settings_change_callback callable 设置更新时的回调
self.file_system FileSystemAccess 技能专属的文件系统沙箱(详见后文)
self.log Logger 以技能名创建的日志实例
self.gui SkillGUI GUI 交互接口
self.event_scheduler / self.intent_service 接口对象 事件调度与意图服务代理
self.location / self.location_pretty / self.location_timezone / self.lang property 位置、时区与语言配置的便捷访问

值得注意的是:bus 与 enclosure 在 __init__ 阶段尚未初始化完毕,源码(第 200-218 行)会在此时访问它们抛出明确异常并提示"Move code from __init__() to initialize()"。因此依赖总线、外壳等运行时能力的初始化逻辑应放在 initialize() 中(第 373-379 行),该方法在技能完整构造并注册到系统后被调用。

基类提供的主要方法与用途:

  • 语音输出:speak()(第 1216-1241 行)直接说出文本,支持 expect_response(说完后立即监听)、wait(阻塞直到说完)与 meta 元信息;speak_dialog()(第 1243-1266 行)从 locale/<lang>/*.dialog 文件随机渲染一句话;acknowledge()(第 1268-1284 行)播放确认音效。
  • 对话交互:get_response()(第 446-508 行)说出提示语并等待用户回答,支持 validator(校验函数)、on_fail(失败提示)、num_retries(重试次数,-1 表示无限);ask_yesno()(第 547-567 行)处理"yes/no"回答并自动兼容 yeah、sure 等变体;ask_selection()(第 569-623 行)让用户从选项列表中挑选,自动支持模糊匹配与"first/second/option number four"等数字化选择。
  • 意图注册:register_intent()(第 989-1016 行)接受 Intent、IntentBuilder 或 .intent 文件;register_intent_file()(第 1018-1052 行)注册 Padatious 意图文件;register_entity_file()(第 1054-1079 行)注册实体示例文件;disable_intent() / enable_intent()(第 1093-1138 行)用于动态开关意图。
  • 词汇与正则:register_vocabulary()(第 1194-1203 行)、register_regex()(第 1205-1214 行)。
  • 上下文管理:set_context() / remove_context()(第 1140-1192 行)管理 Adapt 上下文;set_cross_skill_context() / remove_cross_skill_context()(第 1169-1185 行)通过消息总线广播给所有技能。
  • 资源查找:find_resource()(第 775-811 行)按 资源目录/<lang>/、资源目录/、locale/<lang>/ 的顺序查找资源,未命中时回退到 en-us;translate()、translate_namedvalues()、translate_template()、translate_list()(第 757-898 行)加载对应扩展名的本地化文件。
  • 事件:add_event() / remove_event()(第 905-958 行)注册与移除消息总线事件,支持 once 只触发一次。
  • 会话控制:converse()(第 395-413 行)让技能在激活后先"看一眼"后续话语,返回 True 表示已处理;make_active()(第 693-700 行)将技能推入活跃列表以启用 converse;stop() 由子类重写以响应 mycroft.stop。
  • 其他:report_metric()(第 674-681 行)上报技能指标;send_email()(第 683-691 行)通过 DeviceApi 向注册用户发邮件;get_intro_message()(第 385-393 行)返回首次加载时的欢迎语。

系统事件处理在 _register_system_event_handlers()(第 314-344 行)中自动完成:只有子类真正实现了 stop() 时才注册 mycroft.stop 处理器;mycroft.skill.enable_intent / disable_intent / set_cross_context / remove_cross_context 与 mycroft.skills.settings.changed 均有默认处理。

四大常用 Skill 子类

doc/source/mycroft.rst 还专门列出了四个面向特定场景的基类,它们让技能作者无需从零实现通用协议。

CommonIoTSkill:物联网设备控制

源码位于 mycroft/skills/common_iot_skill.py,注意文件头部标注"CLASSES IN THIS FILE ARE STILL EXPERIMENTAL"。它围绕 IoTRequest 协议定义了四组枚举:

  • Thing(第 68-83 行):可被控制的设备,如 LIGHT、THERMOSTAT、DOOR、LOCK、PLUG、SWITCH、TEMPERATURE、HEAT、AIR_CONDITIONING;
  • Attribute(第 86-94 行):设备属性,如 BRIGHTNESS、COLOR、COLOR_TEMPERATURE、TEMPERATURE;
  • State(第 97-118 行):设备状态,如 STATE、POWERED、LOCKED、OCCUPIED 等;
  • Action(第 121-141 行):可执行动作,如 ON、OFF、TOGGLE、ADJUST、SET、INCREASE、DECREASE、BINARY_QUERY、INFORMATION_QUERY、LOCATE 等。

消息总线交互使用 _BusKeys(第 47-60 行)定义的约定:iot:trigger 触发请求、iot:run.<skill_id> 执行、iot:speak 播报等。技能作者通过组合这些枚举构造标准化的 IoT 请求,即可接入统一的智能家居控制流程。

CommonPlaySkill:统一播放能力

源码位于 mycroft/skills/common_play_skill.py。任何媒体类技能(音乐、播客等)继承它并实现两个抽象方法即可接入"播放控制"体系,无需额外词汇:

  • CPS_match_query_phrase(phrase):判断技能能否播放该查询,返回 (match, level, callback_data) 三元组;
  • CPS_start(phrase, data):启动媒体播放。

匹配级别由 CPSMatchLevel 枚举定义(第 23-29 行):EXACT(精确)、MULTI_KEY、TITLE、ARTIST、CATEGORY、GENERIC。置信度由 __calc_confidence(第 115 行起)根据"被消费掉的词占原句的比例"折算为 0-1 值,例如 play pandora 比 play pandora is my girlfriend 匹配更纯粹、置信度更高。CPSTrackStatus(第 32-45 行)描述了播放状态机(播放/排队/暂停/缓冲/结束等)。基类在 bind()(第 71-84 行)中自动注册 play:query 与 play:start 事件,并持有 AudioService 实例用于把播放转交给音频子系统。

CommonQuerySkill:通用问答能力

源码位于 mycroft/skills/common_query_skill.py。问答类技能继承它后实现 CQS_match_query_phrase 返回答案,可选的 CQS_action 在答案被选中时执行附加动作。匹配级别 CQSMatchLevel(第 21-24 行)为 EXACT / CATEGORY / GENERAL,对应的基础置信度在 level_confidence(第 79-83 行)中预设为 0.9 / 0.6 / 0.5。基类在 bind() 中注册 question:query 与 question:action 事件(第 85-94 行),并加载 res/text/<lang>/noise_words.list 停用词表参与置信度计算(第 64-77 行)。

FallbackSkill:兜底意图处理

源码位于 mycroft/skills/fallback_skill.py。当 Adapt 与 Padatious 都无法匹配用户话语时,所有 Fallback 技能按注册时指定的优先级依次被询问。优先级空间约定如下(源码 docstring):

优先级 归属 用途
1-4 保留 暂未使用,为 Pre-Padatious 预留
5 MYCROFT Padatious 近似匹配(conf > 0.8)
6-88 USER 一般用途
89 MYCROFT Padatious 宽松匹配(conf > 0.5)
90-99 USER 未被捕获的意图
100+ MYCROFT 未知话语或其他未来用途

数值越小的优先级越先执行;同一优先级可有多个 handler,但顺序不保证。Fallback handler 可以"观察"也可以"消费"(consume)话语——一旦消费,后续 handler 不再看到它。核心注册方法为 register_fallback(handler, priority)(第 131 行起),入口处理由 make_intent_failure_handler(第 60-108 行)按优先级排序后逐个尝试,直到某个 handler 返回 True;处理耗时通过 report_timing 上报。

意图注册装饰器

mycroft/skills/mycroft_skill/decorators.py 定义了文档中列出的三个装饰器:

  • @intent_handler(intent_parser)(第 18-29 行):把方法标记为意图处理器,intent_parser 可以是 Intent、IntentBuilder 或 .intent 文件名,注册时由 _register_decorated(mycroft_skill.py 第 739-755 行)统一收集并调用 register_intent;
  • @intent_file_handler(intent_file)(第 32-46 行):等价于注册 .intent 文件处理器,源码注明已弃用,推荐改用 @intent_handler;
  • @adds_context / @removes_context:分别给意图处理前后的会话添加/移除 Adapt 上下文(在 doc/source/mycroft.rst 中被列为核心装饰器)。

此外装饰器模块还提供 @resting_screen_handler(name)(第 49-62 行)注册待机界面、@skill_api_method(第 65-74 行)把方法暴露为技能公共 API。

技能文件系统沙箱:FileSystemAccess

doc/source/mycroft.filesystem.rst 指向 mycroft/filesystem/init.py 中的 FileSystemAccess。每个技能在构造时都获得一个以 skills/<skill_name> 命名的专属命名空间(mycroft_skill.py 第 153 行),物理位置按 XDG 规范位于配置目录下的 mycroft/skills/<name>,旧式 ~/.mycroft/... 路径会自动迁移。其方法包括:

  • open(filename, mode):在命名空间内打开文件,路径相对命名空间(暂不支持子目录);
  • exists(filename):检查文件是否存在;
  • 另有 read / write / delete 等便捷操作(见文件其余部分)。

音频服务交互:AudioService

AudioService(源码 mycroft/skills/audioservice.py)是技能与音频子系统的消息总线客户端,方法一一对应控制命令:

  • queue(tracks):把曲目加入播放列表,支持单个 URI 或列表,每个曲目可为 (uri, mime) 元组提供 mime 提示,内部用 ensure_uri(第 20-40 行)把本地路径转换为 file:// URI;
  • play(tracks, utterance, repeat):开始播放,repeat 控制循环;
  • stop() / next() / prev() / pause() / resume() / seek(seconds):播放控制与跳转(seek 负数表示倒带)。

同时 mycroft.audio 模块(mycroft/audio/init.py)导出三个供技能使用的函数——is_speaking()、stop_speaking()、wait_while_speaking()(实现见 mycroft/audio/utils.py),MycroftSkill.speak(wait=True) 内部正是调用 wait_while_speaking() 实现阻塞(mycroft_skill.py 第 1240-1241 行)。

mycroft.util:技能开发的工具箱

doc/source/mycroft.util.rst 指出该包涵盖音频播放、自然语言解析与生成、缓存目录查找、路径解析等常用操作,并强调"下面仅列出技能开发者感兴趣的一部分函数"。

音频播放与资源工具

  • LOG(实现见 mycroft/util/log.py):全局日志伪函数,日志器名自动取调用方模块名,支持 LOG.debug('msg %s', x) 与 LOG('custom').info(...) 两种风格;默认日志级别只能在系统/用户配置文件中设置(源码 docstring 注明)。
  • play_wav / play_mp3 / play_ogg(实现于 mycroft/util/audio_utils.py,由 mycroft/util/init.py 导出):分别播放对应格式音频,命令模板可在配置中覆盖。
  • resolve_resource_file:解析资源文件路径(实现于 mycroft/util/file_utils.py),MycroftSkill.voc_match 等内部大量使用。
  • get_cache_directory:获取缓存目录路径,供技能存放临时/缓存数据。

自然语言解析:mycroft.util.parse

doc/source/mycroft.util.parse.rst 列出 8 个解析函数。从 mycroft/util/parse.py 可以看到,解析逻辑委托给 lingua-franca 库,mycroft.util.parse 在其上做 Mycroft 适配,从而实现多语言本地化。核心函数:

  • extract_datetime(text, anchorDate, lang, default_time)(第 65-122 行):从句子提取日期时间,支持"5 days from today""tomorrow""Tuesday"等相对表达;含糊词被赋予固定值(morning=8 AM、afternoon=3 PM、evening=7 PM),未指定时间默认 12 AM;返回 [datetime, leftover_string] 二元组,找不到返回 None。示例:"What is the weather like the day after tomorrow?" → [2017-07-02 00:00, 'what is weather like']。
  • extract_duration / extract_number / extract_numbers / get_gender / normalize / fuzzy_match / match_one:分别处理时长、数字(支持序数)、性别、文本归一化与模糊匹配(match_one 用于选项匹配,ask_selection 中即用它打分)。

自然语言格式化:mycroft.util.format

doc/source/mycroft.util.format.rst 列出 9 个格式化函数,用途是"从数字、日期、时间等常见数据类型生成自然语言"。源码位于 mycroft/util/format.py:

  • nice_number / pronounce_number:把数字转成自然读法;
  • nice_date / nice_date_time / nice_year / nice_time:日期时间的自然语言格式化;
  • nice_duration(duration, lang, speech, use_years, clock, resolution) / nice_duration_dt(date1, date2, ...)(第 302 行、345 行):时长转自然语言,内部共用 _duration_handler(第 62-107 行),接受秒数、timedelta 或两个 datetime;resolution 参数使用 TimeResolution 枚举(YEARS...MILLISECONDS,第 53-59 行)控制输出精度,clock 参数产生数字时钟式输出;
  • join_list(list, connector, lang):用连接词拼接列表,ask_selection 用它生成 "A, B or C?" 的询问(mycroft_skill.py 第 606 行)。

时间处理:mycroft.util.time

doc/source/mycroft.util.time.rst 对应 mycroft/util/time.py,提供本地/系统/全局三种时间域的转换函数:now_utc()、now_local(tz)、to_utc(dt)、to_local(dt)、to_system(dt) 与 default_timezone()。技能在涉及"用户本地时间"的场合(如 extract_datetime 的默认锚点,parse.py 第 118 行)应通过这套 API 统一处理时区。

Mycroft Plugin API:四类可扩展插件

doc/source/plugins.rst 明确说明:"Mycroft 通过插件扩展,可新增 Speech To Text 引擎、Text To Speech 引擎、唤醒词引擎和新的音频播放后端。"插件通过 load_plugin(mycroft/util/plugins.py,TTS 侧用法见 mycroft/tts/tts.py)按入口点动态加载,因此插件作者只需按基类契约实现并注册即可被平台识别。

TTS 插件基类:TTS

TTS 是所有 TTS 引擎的抽象基类(ABCMeta),构造参数包括 lang、config(该引擎的配置块)、validator(TTSValidator 实例)、audio_ext(默认 wav)、phonetic_spelling、ssml_tags(引擎支持的 SSML 标签列表)。关键机制:

  • 全局共享的 PlaybackThread(第 69 行起)与 queue:首个 TTS 实例创建时启动播放线程(第 264-267 行),负责音频实际播放并发送 viseme 数据到外壳;
  • execute(sentence, ident, listen)(第 431-446 行):入口方法,先 validate_ssml 过滤不支持的标签,再通过 create_signal("isSpeaking") 置位播报信号,随后调用子类实现的 get_tts(sentence, wav_file)(第 340-351 行);
  • begin_audio() / end_audio(listen)(第 303-326 行):分别发出 recognizer_loop:audio_output_start 与 audio_output_end 消息,listen=True 时追加 mycroft.mic.listen 触发聆听,并清理音频缓存;
  • validate_ssml(第 374-400 行):引擎不支持 SSML 时移除全部标签,支持时仅保留 ssml_tags 中的标签并可经 modify_tag 改写;
  • preprocess_utterance / _preprocess_sentence(第 402-429 行):先按句号/分号/问号切句,再允许引擎做二次分块;
  • available_languages 属性(第 276-286 行)由子类覆盖以声明支持的语言集合;
  • TTSValidator(第 585-633 行):模板校验方法依次检查依赖、实例类型、.wav 文件名、语言与连接;TTSFactory(第 647 行起)内置了 mimic、mimic2、google、marytts、espeak、festival、bing、ibm、yandex、dummy 等引擎(见 mycroft/tts/ 目录下的各实现文件)。

插件作者实现 TTS 时,应覆盖 get_tts(),并在构造时传入配套的 TTSValidator 子类(至少实现 validate_lang、validate_connection、get_tts_class)。

STT 插件基类:STT 与 StreamingSTT

STT 是所有语音识别后端的抽象基类。构造时读取 lang(从 config_core 规范化为 BCP-47 格式,如 en-US,见 init_language 第 52-59 行)与 stt 配置块下当前 module 对应的配置;credential 从配置的 credential 键读取。核心抽象方法:

  • execute(audio, language=None):接收 AudioData(mycroft 录制的音频)与可选语言码,返回文本字符串。

基类之上提供多种凭证模板(第 80-105 行):TokenSTT(credential.token)、GoogleJsonSTT(credential.json)、BasicSTT(username/password)、KeySTT(client_id/client_key),插件可按对接引擎的鉴权方式选用。available_languages 属性声明支持的语言。StreamingSTT 与 StreamThread 类(文档中同样列出)用于实现流式识别,StreamThread 负责在后台线程持续把音频喂给引擎。

内置引擎包括 GoogleSTT、MycroftSTT 等(同一文件后续部分),配置示例见 mycroft/configuration/mycroft.conf:"stt": { "module": "mycroft" },可切换到 google、wit、ibm、kaldi、bing、houndify、deepspeech_server、govivace、yandex,并可为各引擎提供 uri、credential 等子配置块。

唤醒词插件基类:HotWordEngine

HotWordEngine 是唤醒词(wake word)插件的基类,构造参数为 key_phrase(默认 "hey mycroft")、config、lang。构造时从 hotwords 配置块取对应唤醒词的配置,并根据 phoneme_duration(默认 120ms,配置见 mycroft.conf 第 198 行)与音素数量估算期望唤醒词时长。子类必须实现:

  • found_wake_word(frame_data):检查给定的音频帧中是否包含唤醒词,返回布尔值;
  • 可选的 stop() 做资源清理。

内置实现包括 PreciseHotword(对应 precise 模块,支持 sensitivity、trigger_level 等参数,见 mycroft/configuration/mycroft.conf)与 PocketSphinxHotword。配置方式:在 "hotwords" 下按唤醒词短语定义 module、phonemes、threshold、lang 等(默认配置含 "hey mycroft" 与 "wake up" 两项)。

音频后端插件基类:AudioBackend 与 RemoteAudioBackend

AudioBackend 是所有音频播放后端的抽象基类,构造参数为 config 与 bus。必须实现四个抽象方法:

  • supported_uris():返回支持的 URI 类型列表;
  • clear_list():清空播放列表;
  • add_list(tracks):向播放列表添加曲目;
  • play(repeat=False):开始播放,repeat 控制循环;
  • stop():停止播放并返回是否成功。

可选覆盖的方法(第 78-149 行)包括:set_track_start_callback(注册曲目开始回调,用于上报 mycroft.audio.service.track_start)、pause / resume / next / previous、lower_volume / restore_volume(实现音频 ducking,即 Mycroft 聆听/说话时压低媒体音量)、seek_forward / seek_backward、track_info(返回含 artist/album 的字典)、shutdown。

RemoteAudioBackend(第 152 行起)是远程后端的基类(如 Chromecast、Mopidy 服务器),文档注明这类后端总会排在普通后端之后被尝试,以确保默认优先本地播放。默认配置在 mycroft.conf 的 "Audio" 块(第 340-353 行):内置 local(type simple,默认后端)与 vlc(带 duck: true)两个后端,"default-backend" 指定默认项;仓库中的现成实现可参考 mycroft/audio/services/simple/、mycroft/audio/services/vlc/ 与 mycroft/audio/services/mopidy/。

从文档到实战:一个技能的最小骨架

综合 Skills API 各要素,一个典型技能大致如下(代码基于仓库中真实 API 归纳,方法签名与行为均可对照前文源码):

from mycroft import MycroftSkill, intent_handler


class HelloSkill(MycroftSkill):
    def initialize(self):
        # 依赖 bus 等运行时能力的初始化放这里
        self.log.info("Hello skill ready")

    @intent_handler("hello.intent")   # 或传入 IntentBuilder 构造的 Intent
    def handle_hello(self, message):
        self.speak_dialog("hello", data={"name": self.location_pretty or "friend"})

    @intent_handler("color.intent")
    def handle_color(self, message):
        color = self.ask_selection(["red", "green", "blue"],
                                   dialog="ask.color")
        if color:
            self.speak("You picked " + color)

    def stop(self):
        # 响应 mycroft.stop,返回 True 表示已处理
        return True


def create_skill():
    return HelloSkill()

配套资源目录约定(源码 load_data_files 与 find_resource 逻辑,mycroft_skill.py 第 775-834 行、1298-1307 行):

hello-skill/
├── __init__.py          # 含 create_skill()
├── locale/
│   └── en-us/
│       ├── hello.dialog # 问候语模板(支持 mustache 占位符)
│       ├── ask.color.dialog
│       ├── hello.intent # Padatious 示例句:例如 "say hello"
│       └── color.intent
└── settings.json        # 可选:技能设置

locale/<lang>/ 是统一的本地化资源目录,dialog/vocab/regex 等旧式目录仍被兼容(第 816-825 行),非 en-us 语言缺失资源时自动回退英文(第 804-811 行)。

阅读与构建文档

本文对应的 Sphinx 文档源位于 doc/index.rst,完整的 RST 文档树还包括:

文档构建配置见 doc/conf.py 与 doc/Makefile,在仓库 doc/ 目录执行 make html 即可生成 HTML 版 API 手册(依赖见 doc/requirements.txt)。由于大部分内容由 autoclass / autofunction 从源码自动生成,文档与代码永远同步,技能与插件作者应以本文梳理的源码路径为最终事实依据。

小结

以 doc/index.rst 为入口的这套参考手册,实际勾勒出了 mycroft-core 的两条扩展主线:技能层(MycroftSkill 及其四个场景子类 + 意图装饰器 + util 工具库)让开发者以最少代码接入意图识别、多轮对话、媒体播放、问答与 IoT 控制;插件层(TTS / STT / HotWordEngine / AudioBackend 四个抽象基类)让平台能力可以按统一契约无限扩展。理解这些基类的构造参数、抽象方法与事件约定,即可对照仓库源码 mycroft/skills/、mycroft/tts/、mycroft/stt/、mycroft/audio/services/ 与默认配置 mycroft/configuration/mycroft.conf 快速上手自己的第一个技能或插件。

登录后查看全文
mycroft-core