mycroft-core 开发指南:Skills API 与 Plugin API 全解析
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/source/mycroft.rst:Skills API 主索引(类、装饰器、子模块目录);
- doc/source/plugins.rst:Plugin API(TTS / STT / HotWordEngine / AudioBackend);
- doc/source/mycroft.audio.rst、doc/source/mycroft.filesystem.rst、doc/source/mycroft.util.rst、doc/source/mycroft.util.log.rst、doc/source/mycroft.util.parse.rst、doc/source/mycroft.util.format.rst、doc/source/mycroft.util.time.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 快速上手自己的第一个技能或插件。