人工智能语音交互助手智能硬件【免费下载链接】mycroft-coreMycroft Core, the Mycroft Artificial Intelligence platform.项目地址https://gitcode.com/gh_mirrors/my/mycroft-core点击查看免费下载本篇技术指南以 Mycroft Core 官方 API 文档 doc/source/mycroft.rst 为骨架系统梳理开发 Mycroft 技能Skill所需的全部核心 Python API技能基类MycroftSkill与四类通用技能抽象CommonIoT / CommonPlay / CommonQuery / Fallback、意图注册与上下文装饰器、音频控制、文件系统沙箱以及util下的日志、播放、解析、格式化与时间工具。读完本文你将能够对照源码定位每个 API 的真实实现并直接用它编写、调试与本地化自己的 Mycroft 技能。一、文档定位一份面向技能开发者的公开 API 索引doc/source/mycroft.rst是 Mycroft Core 使用 Sphinx 自动生成 API 参考的入口页面它按功能域将整个mycroft包拆成两大板块mycroft.skills技能开发的最核心命名空间涵盖技能基类、通用技能抽象类、音频服务与意图/上下文装饰器mycroft.audio/mycroft.filesystem/mycroft.util含 log、parse、format、time支撑技能运行的基础设施模块。该文档大量使用.. autoclass::与.. autofunction::指令即 API 文档内容直接取自源码 docstring。因此本文在解读 API 的同时会逐一给出对应的源码文件位置让你可以「从文档跳转到实现」。二、mycroft.skills技能系统的六大核心类文档开篇列出六个通过autoclass导出的类它们全部可以从顶层mycroft包或mycroft.skills子包导入。顶层包 mycroft/init.py 的__all__中导出了MycroftSkill、FallbackSkill、intent_handler、intent_file_handler、adds_context、removes_context、AdaptIntent等确认了文档与导出的一致性。1. MycroftSkill所有技能的共同基类MycroftSkill定义于 mycroft/skills/mycroft_skill/mycroft_skill.py构造签名与核心成员如下class MycroftSkill: def __init__(self, nameNone, busNone, use_settingsTrue):name技能名缺省取类名self.__class__.__name__bus可选的 messagebus WebSocket 客户端连接use_settings设为False可完全关闭技能设置settings机制。实例化后自动建立的成员包括成员含义self.root_dir技能根目录绝对路径由模块文件位置推断如/opt/mycroft/skills/my-skill.me/self.guiSkillGUI对象用于驱动 Mark 1 / Mark 2 等设备的 GUI 显示self.config_core全局配置Configuration.get()的字典快照self.settings/self.settings_write_path技能私有设置及写回路径self.settings_change_callback设置变更回调技能可赋值以响应远端设置更新self.dialog_renderer对话渲染器由init_dialog()装载dialog/lang或locale/lang目录技能开发中最高频的方法集中在同一文件内speak(utterance, expect_responseFalse, waitFalse, metaNone)L1216通过bus.emit(Message(speak, ...))发出 TTS 请求expect_responseTrue会让 Mycroft 说完立即进入聆听状态waitTrue则阻塞直到播报结束内部调用wait_while_speaking()。源码同时会通过enclosure.register(self.name)把技能注册为活跃技能。speak_dialog(key, dataNone, ...)L1243从locale/lang/key.dialog对话文件中随机取一句渲染后说出若 dialog 目录缺失会回退为直接speak(key)并打出警告。register_intent(intent_parser, handler)L989注册 Adapt 意图。IntentBuilder会被自动build()若传入的是以.intent结尾的字符串则转交register_intent_file其余类型必须是adapt.intent.Intent实例。register_intent_file(intent_file, handler)L1018注册 Padatious 意图文件。docstring 中给出了标准写法例如food.order.intentOrder some {food}. Order some {food} from {place}. Im hungry. Grab some {food} from {place}.也支持用括号表达可选/变体如(Order | Grab) some {food} (from {place} | )并可配合register_entity_file()补充{food}、{place}的候选值。get_response(dialog, dataNone, validatorNone, on_failNone, num_retries-1)L446向用户提问并等待回答。validator是def validator(utterance) - bool形式的校验函数on_fail可以是对话 key 或返回提示语的函数num_retries-1表示无限重试用户可随时说 cancel 或超时中止。配套的ask_yesno(prompt, dataNone)会自动处理 yeah / sure 等肯定变体返回yes/no/ 其他原话或NoneL547-L565。schedule_event/schedule_repeating_event/cancel_scheduled_event等基于EventSchedulerInterface的定时任务接口。set_context(context, word, origin)/remove_context(context)直接操纵 Adapt 上下文管理器。2. FallbackSkill兜底技能FallbackSkill同样由顶层包导出实现在 mycroft/skills/fallback_skill.py核心 API 为register_fallback(handler, priority)注册兜底处理器。当常规意图全部匹配失败时按优先级从高到低依次尝试兜底技能适合实现「帮我查一下」「随机播放」这类无固定意图的请求remove_fallback(handler_to_del)/remove_instance_handlers()注销处理器常用于技能shutdown()阶段。3. CommonIoTSkill物联网统一接入抽象实现在 mycroft/skills/common_iot_skill.py文档以:show-inheritance:标注其继承关系。它把「动作Action 事物Thing 属性Attribute」抽象为IoTRequest技能开发者需要实现supported_request_version() - IoTRequestVersion声明支持的协议版本get_entities() - [str]/get_scenes() - [str]向系统注册可用的实体与场景can_handle(request) - bool判断本技能是否能处理某请求run_request(request, callback_data) - None真正执行设备控制逻辑。请求会通过消息总线分发内部_handle_trigger/_run_request并自动为请求附加跟踪上下文。4. CommonPlaySkill通用媒体播放抽象实现在 mycroft/skills/common_play_skill.py用于让不同音频技能如 Mopidy、VLC 后端响应「播放某首歌/某个电台」这类跨技能请求。核心回调CPS_match_query_phrase(phrase)返回(media_type, confidence, callback_data)三元组confidence是 0~1 的匹配置信度系统会取所有技能中置信度最高者CPS_start(phrase, data)开始播放CPS_play(*args, **kwargs)继续播放如从暂停恢复CPS_send_status(...)/CPS_send_tracklist(tracklist)向 GUI 推送播放状态与播放列表stop()停止并清理播放状态。其底层通过mycroft.audio.service.play/queue/stop等总线消息与音频子系统协作__calc_confidence负责按匹配层级计算置信度。5. CommonQuerySkill通用问答抽象实现在 mycroft/skills/common_query_skill.py用于「谁唱了这首歌」「现在几点了」这类问答型请求的聚合。开发者实现CQS_match_query_phrase(phrase)返回(confidence, answer_data)CQS_action(phrase, data)执行后续动作如朗读答案、打开页面。系统通过__handle_question_query汇总各技能的置信度后择优选答remove_noise()会先剥离疑问句中的无意义词汇如 please tell me。6. AudioService技能侧音频控制实现在 mycroft/skills/audioservice.py是技能向音频子系统发指令的客户端门面。它接收一个bus连接所有方法都通过消息总线与mycroft.audio服务通信方法总线消息说明queue(tracks)mycroft.audio.service.queue将曲目加入播放队列tracks可为 uri 字符串或(uri, mime)元组play(tracks, utterance, repeat)mycroft.audio.service.play开始播放repeatTrue循环stop()/next()/prev()mycroft.audio.service.stop/next/prev停止、切歌、回退pause()/resume()mycroft.audio.service.pause/resume暂停 / 恢复seek(seconds)seek_forward/seek_backward快进/快退负数自动转为回退track_info()track_infotrack_info_reply同步等待当前曲目信息超时 1 秒返回{}available_backends()list_backends查询可用音频后端is_playing属性基于track_info()播放中返回True注意ensure_uri()的路径处理普通路径会被自动补全为file://绝对 URI已含://的字符串原样保留(uri, mime)元组同样被处理非法类型抛ValueError。三、四个装饰器意图与上下文的关键入口文档列出的四个autofunction装饰器中意图相关两个实现在 mycroft/skills/mycroft_skill/decorators.py上下文相关两个实现在 mycroft/skills/context.py全部由顶层mycroft包再导出。1.intent_handler(intent_parser)intent_handler(IntentBuilder(WeatherIntent) .require(WeatherKeyword) .optionally(Location)) def handle_weather(self, message): ...实现要点decorators.py L18-L29装饰器并不立即注册意图而是把intent_parser追加到函数的func.intents列表中技能加载时MycroftSkill._register_decorated()会遍历这些列表统一调用register_intent完成注册。因此一个处理函数可以叠加多个intent_handler。2.intent_file_handler(intent_file)intent_file_handler(food.order.intent) def handle_order(self, message): ...与intent_handler机制相同只是把文件路径存入func.intent_files最终由register_intent_file注册。需要说明的是源码 docstring 明确标注该装饰器deprecated现在直接用intent_handler(food.order.intent)传入.intent文件路径即可获得同等效果register_intent内部会自动识别.intent后缀并转交文件注册。3.adds_context(context, words)adds_context(OrderingFood) def handle_order(self, message): ...来自 mycroft/skills/context.py方法执行成功后自动调用args[0].set_context(context, words)把上下文关键词注入 Adapt 上下文管理器让后续省略了主语/宾语的追问如「要加辣吗」仍能命中同一技能。4.removes_context(context)removes_context(OrderingFood) def handle_order_cancel(self, message): ...方法执行成功后调用args[0].remove_context(context)清除指定上下文用于在对话流程结束时释放语境。四、mycroft.audio语音播放状态控制文档通过 doc/source/mycroft.audio.rst 引入mycroft.audio模块的三个核心函数实现在 mycroft/audio/utils.py并从 mycroft/audio/init.py 导出is_speaking()返回布尔值True表示 TTS 仍在播报。底层实现是check_for_signal(isSpeaking, -1)即检查 IPC 信号目录中的isSpeaking标志因此不依赖总线往返性能开销极低。wait_while_speaking()先time.sleep(0.3)等待排队的播报真正开始再以 0.1 秒间隔轮询is_speaking()直到结束。MycroftSkill.speak(waitTrue)正是复用它实现阻塞播报。stop_speaking()若正在播报则通过send(mycroft.audio.speech.stop)总线消息请求停止并阻塞轮询至播报确实终止。源码 TODO 注释也指出目前技能可停止任意播报未来应限制为「只能停止自己发起的播报」。五、mycroft.filesystemFileSystemAccess 沙箱文档指向 doc/source/mycroft.filesystem.rst核心类FileSystemAccess实现在 mycroft/filesystem/init.py意图是给每个技能一个隔离的命名空间目录防止技能之间互相读写文件。fs FileSystemAccess(myskill) # 构造时即创建命名空间目录 handle fs.open(config.json, w) # 在命名空间内打开文件 fs.exists(config.json) # 检查文件是否存在实现细节构造时把传入的path映射到 XDG 配置目录xdg.BaseDirectory.save_config_path(mycroft)/path若旧位置~/.mycroft/path存在会自动迁移源码中有 TODO 注明该迁移将在 22.02 移除open(filename, mode)与exists(filename)都只接受相对文件名不支持子目录从设计上限制了越界访问path为空或非字符串时抛ValueError(path must be initialized as a non empty string)。MycroftSkill初始化时会为每个技能创建对应的FileSystemAccess实例技能可通过self.file_system或类似成员读写自己的私有数据。六、mycroft.util技能开发的常备工具doc/source/mycroft.util.rst 明确说明该包汇集了播放音频、解析/生成自然语言文本、缓存目录查询、路径解析等技能开发高频操作。以下函数由 mycroft/util/init.py 统一导出。1. LOG随调用位置自动命名的日志器LOG定义于 mycroft/util/log.py是一个行为类似logging.Logger的类级日志器。它的特性是日志名自动取调用者的模块与行号LOG.debug(My message: %s, debug_str) # 输出: 13:12:43.673 - :module:1 - DEBUG - My message: hi LOG(custom_name).debug(Another message) # 输出: 13:13:10.462 - custom_name - DEBUG - Another message支持debug / info / warning / error / exception五个级别方法。默认日志级别与输出格式只能在配置文件~/.config/mycroft/mycroft.conf或/etc/mycroft/mycroft.conf中设置log_level控制级别默认INFOlog_format覆盖输出格式默认{asctime} | {levelname:8} | {process:5} | {name} | {message}。LOG.init()会在导入mycroft包时自动执行以读取配置。2. play_wav / play_mp3 / play_ogg后台播放音频三个函数实现在 mycroft/util/audio_utils.py共同特征是立即返回、后台播放返回subprocess.Popen对象失败返回None播放器命令行来自配置play_wav(uri)→ 使用config[play_wav_cmdline]play_mp3(uri)→ 使用config[play_mp3_cmdline]play_ogg(uri)→ 使用config[play_ogg_cmdline]命令行中的%1会被替换为实际 uri_play_cmd的实现。此外还有按扩展名自动分发的play_audio_file(uri)以及录音用的record(file_path, duration, rate, channels)底层调用arecord和find_input_device(device_name)。播放子进程会注入PULSE_PROPmedia.rolemusic环境变量以便与 TTS 角色区分源码注释说明这可用于电话角色下的音频闪避。3. resolve_resource_file资源路径解析实现在 mycroft/util/file_utils.py。给定形如snd/beep.wav或path/filename.ext的资源名按以下顺序查找并返回第一个存在的绝对路径直接可用的完整文件路径如用户配置指定的绝对路径$XDG_DATA_DIRS/mycroft/res_name默认~/.local/share/mycroft/...旧位置~/.mycroft/res_nameconfig[data_dir]/res/res_name默认/opt/mycroft/res/...源码包内mycroft/res/res_name即仓库 mycroft/res 目录如snd/acknowledge.mp3。全部找不到则返回None。MycroftSkill.acknowledge()播放确认音正是用resolve_resource_file定位sounds.acknowledge音频文件。4. get_cache_directory缓存目录实现在 mycroft/util/file_utils.py。返回缓存根目录优先取配置cache_path否则get_temp_path(mycroft, cache)即/tmp/mycroft/cachedomain参数作为子目录用于隔离不同用途的缓存。配套函数curate_cache(directory, min_free_percent5.0, min_free_disk50)会在磁盘可用百分比低于min_free_percent且可用空间低于min_free_diskMB 时按修改时间从旧到新删除文件释放空间。由于缓存目录可能位于小容量 RAM 盘且随时可能被清空依赖缓存数据的代码必须能回退重建。5. 其他值得关注的工具mycroft/util/__init__.py还批量导出了read_stripped_lines/read_dict/create_file/get_temp_path文件与临时路径工具connected()网络连通性检测check_for_signal/create_signal/get_ipc_directoryIPC 信号机制is_speaking()依赖它create_daemon/reset_sigint_handler/start_message_bus_client进程管理工具get_arch()平台架构识别。七、mycroft.util.parse从自然语言提取结构化数据doc/source/mycroft.util.parse.rst 列出了 8 个解析函数。模块 docstringmycroft/util/parse.py说明实际解析工作由 lingua-franca 库完成本模块针对 Mycroft 技能场景做包装与默认语言注入。函数清单函数用途extract_datetime(text, anchorDateDEFAULT, langNone, default_timeNone)从句子中提取日期时间extract_duration(text, langNone)提取时长如 5 minutesextract_number(text, langNone)/extract_numbers(...)提取单个/多个数字get_gender(text, langNone)判断性别词汇normalize(text, langNone)文本归一化去标点、小写化等fuzzy_match(x, against, langNone)模糊匹配评分match_one(x, arr, langNone)从候选列表中返回最佳匹配(confidence, item)以extract_datetime为例L65-L128它解析 tomorrow、Tuesday、5 days from today 等相对日期并对模糊时段赋默认值morning 8 AM、afternoon 3 PM、evening 7 PM未提供时间时默认 12 AM。返回值是[datetime, leftover_string]元组leftover_string为剔除时间关键词后的剩余文本解析不到任何时间信息时返回None extract_datetime(What is the weather like the day after tomorrow?, ... datetime(2017, 6, 30, 0, 0)) [datetime.datetime(2017, 7, 2, 0, 0), what is weather like] extract_datetime(Set up an appointment 2 weeks from Sunday at 5 pm, ... datetime(2016, 2, 19, 0, 0)) [datetime.datetime(2016, 3, 6, 17, 0), set up appointment]anchorDate缺省时使用now_local()即用户配置时区的当前时间传入None会触发 DeprecationWarning。若指定语言不在 lingua-franca 支持列表会通过_log_unsupported_language打印告警并列出全部支持语言。八、mycroft.util.format把数据格式化为人性化表达doc/source/mycroft.util.format.rst 列出 9 个格式化函数模块 docstringmycroft/util/format.py强调其目标是生成「可被人类消化」的内容语音或屏幕显示并支持本地化。函数清单函数用途join_list(items, sep, langNone)把列表按语言习惯连接成自然语句nice_date(dt, langNone)/nice_date_time(...)/nice_time(...)/nice_year(...)日期/时间/年份的友好格式化nice_number(num, langNone)/pronounce_number(...)数字的显示与朗读形式nice_duration(duration, ...)秒数/timedelta→ 时长文本nice_duration_dt(date1, date2, ...)两个datetime之间的时长文本nice_duration与nice_duration_dt共用内部实现_duration_handlerL62-L299参数最为丰富speechTrue输出口语two minutes forty three secondsFalse输出显示格式2:43use_yearsTrue输出年天False只输出总天数clockTrue强制输出数码时钟样式1:00对 DAYS/YEARS 分辨率无效resolution为TimeResolution枚举YEARS/DAYS/HOURS/MINUTES/SECONDS/MILLISECONDS作为输出精度的下限nice_duration只有传入 MILLISECONDS 才会产出毫秒nice_duration_dt不支持毫秒静默回退到 SECONDS。示例行为nice_duration(60) # 60 秒 # → speech: one minutedisplay: 1:00 nice_duration(163) # → speech: two minutes forty three secondsdisplay: 2:43 nice_duration_dt(datetime(2019, 3, 12), datetime(2019, 1, 1)) # → seventy days实现细节上_duration_handler会区分输入类型两个datetime相减得到timedelta并自动处理闰年天数leapdaysfloat秒数会拆出小数部分作为毫秒整型会先转为timedelta。当speechFalse且结果为空时会回退为0/0m/0:00等零值表达。九、mycroft.util.time本地/系统/UTC 时间处理doc/source/mycroft.util.time.rst 将mycroft.util.time描述为「处理本地、系统与全局时间」的函数集合实现在 mycroft/util/time.py。该模块的时区基准不是操作系统时区而是Mycroft 配置中用户的位置设置default_timezone()优先取配置location.timezone.code如America/Chicago也支持location.timezone.name与offset取不到则回退系统时区tzlocal()now_utc()当前 UTC 时间等价 GMTnow_local(tzNone)当前用户本地时间缺省用default_timezone()to_utc(dt)带时区信息的时间转 UTCnaive datetime 先按 UTC 处理再转换to_local(dt)任意时间转用户本地时区naive 输入视为 UTCto_system(dt)转操作系统时区。这套工具的意义在于即使设备系统时区与实际用户不符extract_datetime、nice_date_time等解析/格式化函数仍能基于用户配置的时区保持一致体验。mycroft.util.parse.extract_datetime缺省锚点now_local()正是来自此模块。十、配套文档与测试继续深入的方向mycroft.rst通过toctree指令引用了 7 份配套 API 文档对应关系如下可供继续查阅doc/source/mycroft.audio.rst —— 音频状态控制三函数doc/source/mycroft.filesystem.rst ——FileSystemAccessdoc/source/mycroft.util.rst —— util 常用函数doc/source/mycroft.util.log.rst ——LOG模块doc/source/mycroft.util.parse.rst —— 解析函数doc/source/mycroft.util.format.rst —— 格式化函数doc/source/mycroft.util.time.rst —— 时间函数若想验证上述 API 的真实行为仓库自带测试是最佳佐证技能类的行为可参考 test/unittests/skills/test_mycroft_skill.py、test/unittests/skills/test_common_play_skill.py、test/unittests/skills/test_common_query_skill.py 与 test/unittests/skills/test_fallback_skill.py工具函数的测试覆盖在 test/unittests/util/test_parse.py、test/unittests/util/test_format.py、test/unittests/util/test_time.py、test/unittests/util/test_file_utils.py 与 test/unittests/util/test_log.py 中。结合这些测试阅读可以快速理解每个函数的边界行为与本地化处理。结语mycroft.rst虽然只是一页 API 索引但它精准勾勒了 Mycroft 技能开发的全部公共编程面以MycroftSkill为基类、四个装饰器声明意图与上下文、四类通用技能抽象应对 IoT / 播放 / 问答 / 兜底场景再辅以audio、filesystem、util三块基础设施完成语音交互、持久化与文本处理。开发新技能时从本文的任一章节定位到对应源码与测试即可获得最权威的行为定义。赞分享人工智能语音交互助手智能硬件【免费下载链接】mycroft-coreMycroft Core, the Mycroft Artificial Intelligence platform.项目地址https://gitcode.com/gh_mirrors/my/mycroft-core点击查看免费下载相关推荐gRPC Core 工具库全景解析src/core/util 目录的结构、核心组件与使用指南gRPC Core 工具库全景解析src/core/util 目录的结构、核心组件与使用指南 gRPC 是一个高性能、开源、通用的 RPC 框架其 C后端RPC框架微服务通信gRPC C Core 实用工具库src/core/util源码指南平台抽象、并发原语与通用基础设施gRPC C Core 实用工具库src/core/util源码指南平台抽象、并发原语与通用基础设施 本篇文章系统讲解 gRPCC 实现核心代后端RPC框架微服务通信Vega Utilities API 完全指南vega-util 工具函数库深度解析Vega Utilities API 完全指南vega util 工具函数库深度解析 Vega 在其整个数据流引擎、解析器与场景图渲染的实现中大量依赖一组数据可视化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考