Wox Python 插件 SDK 完整开发指南从 Plugin 基类到动态设置与查询精化【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox本篇指南以 Wox 官方 Python 插件 SDK 参考文档.agents/skills/wox-plugin-creator/references/sdk_python.md为核心骨架结合仓库中wox.plugin.python/src/wox_plugin/的源码实现系统讲解如何在 Wox 中开发 Python 插件从环境准备、安装wox-plugin包、实现Plugin基类与数据模型到熟练使用全部 Public API、编写可云同步的设置、配置 QueryRequirements、实现动态设置与静态 HTML 预览。读完本文你将能独立完成一个结构规范、功能完整的 Wox Python 插件并理解每个 API 背后的调用语义与版本约束。Wox 要求Python 3.10 或更高版本。这一约束在仓库源码中有双重印证wox.plugin.python/pyproject.toml中声明requires-python 3.10而 Python 宿主实现 中同样定义了minimumPythonVersion v3.10.0并在解析到低于该版本的解释器时直接报错保证 API 解析器与宿主进程使用同一套版本规则。环境准备与 SDK 安装安装 wox-plugin 包在插件项目目录中执行uv add wox-plugin该命令通过uv将wox-plugin加入项目依赖。包内部组织清晰顶层__init__.py统一导出Plugin、Query、QueryResponse、Result、Context、PluginInitParams以及WoxImage、WoxPreview、LogLevel、设置辅助函数等全部公开符号见 SDK 包导出因此from wox_plugin import ...一条导入即可覆盖绝大多数场景。插件元数据 plugin.json插件根目录需要plugin.json声明元数据其中Runtime必须为python、Entry指向插件入口脚本如main.py。若插件返回QueryResponse则MinWoxVersion必须声明为 2.0.4参见 SDK 元数据示例。Plugin 基类与最小可运行插件所有 Wox Python 插件的入口都实现Plugin协议协议定义至少包含两个异步方法from wox_plugin import Plugin, Query, QueryResponse, Result, Context, PluginInitParams class MyPlugin(Plugin): async def init(self, ctx: Context, params: PluginInitParams) - None: self.api params.api async def query(self, ctx: Context, query: Query) - QueryResponse: return QueryResponse(results[])init(ctx, params)插件加载时调用一次应尽快返回。params.api是PublicAPI实例类型见 PublicAPI 协议params.plugin_directory是插件目录绝对路径可用于加载配置文件与资源。query(ctx, query)用户输入命中插件时调用。返回QueryResponse要求MinWoxVersion 2.0.4或直接返回List[Result]兼容旧版本 Wox 的弃用路径。文件末尾实例化单例plugin MyPlugin()返回值的版本语义从源码注释Plugin 协议兼容性说明可以确认直接返回List[Result]仍被宿主接受但属于弃用路径只有QueryResponse能把结果、refinements 与 layout 提示放在同一个载荷中一并上送。因此新插件应统一使用QueryResponse。查询作用域布局query-scoped layoutQueryResponse.layout是查询级的布局声明包含result_preview_width_ratio与grid_layout两个可选字段QueryLayout 实现from wox_plugin import QueryResponse, QueryLayout, QueryGridLayout return QueryResponse( resultsresults, layoutQueryLayout( result_preview_width_ratio0.6, grid_layoutQueryGridLayout(columns3, image_width200, image_height200, show_titleTrue), ), )QueryGridLayout还支持item_padding、item_margin、aspect_ratio、commands等字段QueryGridLayout 实现。旧版的resultPreviewWidthRatio与gridLayout元数据特性已被弃用原因正如源码注释所指它们只能描述静态的插件或命令默认值无法像QueryResponse.layout一样按每次查询动态决策。核心数据模型Queryclass Query: type: str # input 或 selection raw_query: str trigger_keyword: str command: str search: str refinements: dict[str, str] # 已选中的 refinement 值type对应QueryType.INPUT在搜索框输入或QueryType.SELECTION在外部应用选中文本/文件后唤起 Wox见 QueryType 定义。trigger_keyword是插件触发词command是已注册的子命令关键字search是去除触发词与命令后的实际搜索文本。refinements保存用户在查询作用域精化控件上的选择。QueryRefinementclass QueryRefinement: id: str title: str type: QueryRefinementType # singleSelect | multiSelect | toggle | sort hotkey: str # macOS 上为 cmdtWindows/Linux 上为 ctrlt options: list[QueryRefinementOption] default_value: list[str] [] persist: bool Falsetype为QueryRefinementType枚举SINGLE_SELECT/MULTI_SELECT/TOGGLE/SORT见 query_response.py。hotkey必须是真实的平台组合键macOS 用cmdkeyWindows/Linux 用ctrlkey。代码中应检测sys.platform darwin后输出对应字符串切勿直接写死字面量ctrl/cmdt。插件通过QueryResponse.refinements返回精化控件并在下一次查询时从query.refinements读取已选值详见references/refinements.md。Resultclass Result: title: str # 支持 i18n:key 前缀自动翻译 icon: WoxImage sub_title: str # 支持 i18n:key 前缀 actions: List[ResultAction] [] score: float 0.0 context_data: Any None源码中的 Result 模型 还提供了更多字段id跨更新追踪结果、preview详情面板预览、group/group_score结果分组与组排序、tails文本/图片尾巴元素、drag_data原生文件拖拽等。score决定排序数值越高越靠前。ResultAction支持EXECUTE立即执行与FORM先展示表单再提交回调收到FormActionContext.values两种类型并可用prevent_hide_after_actionTrue保持 Wox 窗口在执行动作后不隐藏详见 ResultAction 模型。WoxImageclass WoxImage: classmethod def new_emoji(cls, char: str) - WoxImage classmethod def new_absolute(cls, path: str) - WoxImage classmethod def new_relative(cls, path: str) - WoxImageWoxImage 实现 支持多种图片类型ABSOLUTE、RELATIVE相对插件目录、BASE64完整 data URI、SVG内联 SVG 标记、EMOJI、URL、THEME内置主题图标随明暗主题自适应、FILE_ICON按文件扩展名取系统图标。对应工厂方法还包括new_base64()、new_svg()、new_url()、new_theme()等。Action 图标应使用可适配主题的 SVGsvg:或使用var(--wox-theme-icon-color)的内联标记而不是 emoji详见references/icons.md。Public API 方法全览所有方法均为异步且需要ctx。以下是 SDK 参考文档列出的核心 API按类别整理通用控制方法作用change_query(ctx, query: PlainQuery)更新搜索栏内容支持ChangeQueryParam指定查询类型与文本/选区hide_app(ctx)隐藏 Woxshow_app(ctx)显示 Woxnotify(ctx, message)显示系统通知支持 i18n keylog(ctx, level, msg)写日志level取LogLevel枚举INFO/ERROR/DEBUG/WARNINGcopy(ctx, params: CopyParams)复制文本或图片到剪贴板is_visible(ctx)检查 Wox 窗口是否可见缓存插件需要磁盘缓存时优先使用get_cache_folder不要自创目录get_cache_folder(ctx)返回~/.wox/cache/plugins/plugin-id/。Wox 会在需要时自动创建并在插件卸载时删除。在init()中调用一次并保存路径把下载文件、缩略图、搜索结果等写入其下。不要在插件文件旁、用户数据目录下或硬编码文件夹名下自行发明cache/、tmp/、downloads/目录。用户偏好与收藏属于设置而非缓存请使用get_setting/set_setting。该 API 在 PublicAPI 协议 中有完整的路径语义注释。设置插件设置应优先使用以下 API——这些值可以通过 Wox 云同步跨设备同步不要把普通设置持久化到本地文件或自定义存储中get_setting(ctx, key)读取设置值未设置时返回默认值。save_setting(ctx, key, value, is_platform_specific)保存设置。普通插件设置可参与云同步对于本地路径、可执行文件路径、shell 命令、热键、浏览器配置、应用路径、系统集成等仅限当前平台的值is_platform_specific传True。on_setting_changed(ctx, callback)注册设置变更回调回调签名(ctx, key, new_value)。on_get_dynamic_setting(ctx, callback)为dynamic类型设置提供运行时生成的设置定义回调返回PluginSettingDefinitionItem。save_setting在源码中已被标注为 Deprecatedapi.py 中的说明新插件在MinWoxVersion 2.4.0时应改用set_setting(ctx, SetSettingOption(...))后者通过platform_specific与is_local两个布尔字段显式控制跨平台与设备本地行为见 SetSettingOption 实现。UI 实时更新update_result(ctx, result: UpdatableResult)实时更新结果用于动作处理中的长任务进度展示。push_results(ctx, query, results)向当前查询追加结果适合流式返回、分批加载。refresh_query(ctx, param)以现有文本重新执行查询RefreshQueryParam.preserve_selected_index控制是否保持选中项。get_updatable_result(ctx, result_id)获取某结果的当前 UI 状态结果已不可见时返回None。AI 与国际化ai_chat_stream(ctx, model, convs, options, callback)流式获取 LLM 响应。model为AIModel(name..., provider...)convs为Conversation列表可用user_message()/assistant_message()便捷构造回调接收ChatStreamData状态为STREAMING/FINISHED/ERROR。get_translation(ctx, key)获取原始翻译字符串。注意返回的是原始字符串参数替换需自行用 f-string 或.format()完成。设置编写要点插件设置一律走get_setting/save_setting/on_setting_changed以便参与 Wox 云同步不要让用户期望换设备还在的值落入本地文件。缓存文件放在get_cache_folder(ctx)下不要在插件目录或用户数据树下自造缓存目录。Python SDK 内置以下设置构建辅助函数定义见 setting.pycreate_textbox_setting(key, label, default_value, tooltip)单行文本框设置。create_checkbox_setting(key, label, default_valuefalse, tooltip)布尔开关true为选中。create_label_setting(content, tooltip)只读说明文字。目前没有内置create_select_setting()辅助函数。对于select、table、校验器、dynamic等高级设置需要直接构造PluginSettingDefinitionItem与对应的值对象如PluginSettingValueTable、PluginSettingValueTableColumn、PluginSettingValueTableGroup或手动输出期望的 JSON 结构。设置类型枚举见 PluginSettingDefinitionTypehead/textbox/checkbox/select/label/newline/table/dynamic。精确的plugin.json与校验器结构请阅读references/plugin_json_schema.md可直接复制的高级设置示例见references/settings_patterns.md。运行时save_setting(ctx, key, value, is_platform_specific)调用必须与设置元数据保持一致如果对应SettingDefinitions条目声明了IsPlatformSpecific: true不要对动态保存的设置硬编码False。DisabledInPlatforms只控制设置在哪些平台被禁用不会隔离云同步的值。当查询依赖 API Key 等设置时在plugin.json中使用静态QueryRequirements。Wox 会在调用query()之前拦截查询仅显示内置的query_requirement_settings配置预览。不存在运行时的register_query_requirementsAPI查询需求一律在元数据中声明。QueryRequirements 数据类与元数据示例from dataclasses import dataclass, field dataclass class PluginQueryRequirement: setting_key: str validators: list[dict] field(default_factorylist) message: str dataclass class PluginQueryRequirements: any_query: list[PluginQueryRequirement] field(default_factorylist) query_without_command: list[PluginQueryRequirement] field(default_factorylist) query_with_command: dict[str, list[PluginQueryRequirement]] field(default_factorydict)其语义在 PluginQueryRequirements 源码 中有明确注释any_query作用于所有查询query_without_command仅作用于无子命令的查询query_with_command按命令关键字分别配置。to_dict()会转换成plugin.json使用的 PascalCase 字段名。元数据示例{ SettingDefinitions: [ { Type: textbox, Value: { Key: accessKey, Label: i18n:access_key, DefaultValue: , Validators: [{ Type: not_empty, Value: {} }] } } ], QueryRequirements: { AnyQuery: [ { SettingKey: accessKey, Message: i18n:access_key_required } ], QueryWithoutCommand: [], QueryWithCommand: {} } }校验器类型除not_empty外仓库setting/validator/目录还提供is_number、is_url、unique等实现可供参考。动态设置Dynamic Setting示例动态设置由on_get_dynamic_setting回调在运行时生成定义适合值取决于当前状态如预览、可选列表的场景from wox_plugin import ( PluginSettingDefinitionItem, PluginSettingDefinitionType, PluginSettingValueLabel, ) async def _on_get_dynamic_setting(ctx, key): if key separator_preview: return PluginSettingDefinitionItem( typePluginSettingDefinitionType.LABEL, valuePluginSettingValueLabel(contentPreview: 1,234.56), ) return PluginSettingDefinitionItem( typePluginSettingDefinitionType.LABEL, valuePluginSettingValueLabel(contentUnknown setting), )回调在init()中注册await self.api.on_get_dynamic_setting(ctx, self._on_get_dynamic_setting)。完整使用示例带 i18n 格式化的 Hello 插件from wox_plugin import Plugin, Query, Result, WoxImage class HelloPlugin(Plugin): async def init(self, ctx, params): self.api params.api async def query(self, ctx, query): # I18n with formatting raw_fmt await self.api.get_translation(ctx, hello_format) # Hello {name} title raw_fmt.format(namequery.search) return [Result( titletitle, iconWoxImage.new_emoji(), actions[] )] plugin HelloPlugin()注意get_translation返回的是包含{name}占位符的原始字符串需用.format()完成替换——这正是 SDK 参考中强调的要点。静态 HTML 预览WEBVIEW预览结果时使用WoxPreviewType.WEBVIEW并传入 JSON 编码的html字段即可无需 HTTP 服务器或临时 HTML 文件也不存在独立的html预览类型import json from wox_plugin import WoxPreview, WoxPreviewType preview WoxPreview( preview_typeWoxPreviewType.WEBVIEW, preview_datajson.dumps({ html: !doctype htmlhtmlbodyh1 stylecolor:tealHello Wox/h1/body/html }), ) # Assign preview to Result(previewpreview, ...).html与url二选一。可选 JSON 字段injectCss、userAgent、cacheDisabled、cacheKey默认取 URL 或 HTML 内容。内联 HTML 没有相对插件的 base URL请内联 CSS/图片或使用绝对资源 URL。这是浏览器内容而非经过净化的 Markdown拼接不可信文本前务必使用html.escape。WoxPreview模型还支持MARKDOWN、TEXT、IMAGE、URL、FILE、LIST、REMOTE等类型WoxPreviewType 定义其中LIST可通过WoxPreviewListData展示带图标、副标题与尾巴的结构化行。结构化查询参数与命令块命令的别名配置在Commands[].Aliases后缀模板配置在Commands[].QueryHint完整的ChangeQuery实例与 SDK 用法详见.agents/skills/wox-plugin-creator/SKILL.md的QueryHint章节。QueryHint对input查询仍是可选项不要在QueryText中嵌入标记也不要从粘贴文本中推断参数边界。常用参考路径SDK 参考文档本文依据Python SDK 包导出PublicAPI 协议与全部方法签名Plugin 协议与生命周期Result / ResultAction / UpdatableResult 模型QueryResponse / Refinement / Layout 模型设置定义模型与辅助函数WoxImage 图片模型WoxPreview 预览模型Python 宿主版本校验配套参考插件 JSON Schema、设置模式、精化控件、图标规范、i18n【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Wox Python 插件 SDK 完整开发指南：从 Plugin 基类到动态设置与查询精化
Wox Python 插件 SDK 完整开发指南从 Plugin 基类到动态设置与查询精化【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox本篇指南以 Wox 官方 Python 插件 SDK 参考文档.agents/skills/wox-plugin-creator/references/sdk_python.md为核心骨架结合仓库中wox.plugin.python/src/wox_plugin/的源码实现系统讲解如何在 Wox 中开发 Python 插件从环境准备、安装wox-plugin包、实现Plugin基类与数据模型到熟练使用全部 Public API、编写可云同步的设置、配置 QueryRequirements、实现动态设置与静态 HTML 预览。读完本文你将能独立完成一个结构规范、功能完整的 Wox Python 插件并理解每个 API 背后的调用语义与版本约束。Wox 要求Python 3.10 或更高版本。这一约束在仓库源码中有双重印证wox.plugin.python/pyproject.toml中声明requires-python 3.10而 Python 宿主实现 中同样定义了minimumPythonVersion v3.10.0并在解析到低于该版本的解释器时直接报错保证 API 解析器与宿主进程使用同一套版本规则。环境准备与 SDK 安装安装 wox-plugin 包在插件项目目录中执行uv add wox-plugin该命令通过uv将wox-plugin加入项目依赖。包内部组织清晰顶层__init__.py统一导出Plugin、Query、QueryResponse、Result、Context、PluginInitParams以及WoxImage、WoxPreview、LogLevel、设置辅助函数等全部公开符号见 SDK 包导出因此from wox_plugin import ...一条导入即可覆盖绝大多数场景。插件元数据 plugin.json插件根目录需要plugin.json声明元数据其中Runtime必须为python、Entry指向插件入口脚本如main.py。若插件返回QueryResponse则MinWoxVersion必须声明为 2.0.4参见 SDK 元数据示例。Plugin 基类与最小可运行插件所有 Wox Python 插件的入口都实现Plugin协议协议定义至少包含两个异步方法from wox_plugin import Plugin, Query, QueryResponse, Result, Context, PluginInitParams class MyPlugin(Plugin): async def init(self, ctx: Context, params: PluginInitParams) - None: self.api params.api async def query(self, ctx: Context, query: Query) - QueryResponse: return QueryResponse(results[])init(ctx, params)插件加载时调用一次应尽快返回。params.api是PublicAPI实例类型见 PublicAPI 协议params.plugin_directory是插件目录绝对路径可用于加载配置文件与资源。query(ctx, query)用户输入命中插件时调用。返回QueryResponse要求MinWoxVersion 2.0.4或直接返回List[Result]兼容旧版本 Wox 的弃用路径。文件末尾实例化单例plugin MyPlugin()返回值的版本语义从源码注释Plugin 协议兼容性说明可以确认直接返回List[Result]仍被宿主接受但属于弃用路径只有QueryResponse能把结果、refinements 与 layout 提示放在同一个载荷中一并上送。因此新插件应统一使用QueryResponse。查询作用域布局query-scoped layoutQueryResponse.layout是查询级的布局声明包含result_preview_width_ratio与grid_layout两个可选字段QueryLayout 实现from wox_plugin import QueryResponse, QueryLayout, QueryGridLayout return QueryResponse( resultsresults, layoutQueryLayout( result_preview_width_ratio0.6, grid_layoutQueryGridLayout(columns3, image_width200, image_height200, show_titleTrue), ), )QueryGridLayout还支持item_padding、item_margin、aspect_ratio、commands等字段QueryGridLayout 实现。旧版的resultPreviewWidthRatio与gridLayout元数据特性已被弃用原因正如源码注释所指它们只能描述静态的插件或命令默认值无法像QueryResponse.layout一样按每次查询动态决策。核心数据模型Queryclass Query: type: str # input 或 selection raw_query: str trigger_keyword: str command: str search: str refinements: dict[str, str] # 已选中的 refinement 值type对应QueryType.INPUT在搜索框输入或QueryType.SELECTION在外部应用选中文本/文件后唤起 Wox见 QueryType 定义。trigger_keyword是插件触发词command是已注册的子命令关键字search是去除触发词与命令后的实际搜索文本。refinements保存用户在查询作用域精化控件上的选择。QueryRefinementclass QueryRefinement: id: str title: str type: QueryRefinementType # singleSelect | multiSelect | toggle | sort hotkey: str # macOS 上为 cmdtWindows/Linux 上为 ctrlt options: list[QueryRefinementOption] default_value: list[str] [] persist: bool Falsetype为QueryRefinementType枚举SINGLE_SELECT/MULTI_SELECT/TOGGLE/SORT见 query_response.py。hotkey必须是真实的平台组合键macOS 用cmdkeyWindows/Linux 用ctrlkey。代码中应检测sys.platform darwin后输出对应字符串切勿直接写死字面量ctrl/cmdt。插件通过QueryResponse.refinements返回精化控件并在下一次查询时从query.refinements读取已选值详见references/refinements.md。Resultclass Result: title: str # 支持 i18n:key 前缀自动翻译 icon: WoxImage sub_title: str # 支持 i18n:key 前缀 actions: List[ResultAction] [] score: float 0.0 context_data: Any None源码中的 Result 模型 还提供了更多字段id跨更新追踪结果、preview详情面板预览、group/group_score结果分组与组排序、tails文本/图片尾巴元素、drag_data原生文件拖拽等。score决定排序数值越高越靠前。ResultAction支持EXECUTE立即执行与FORM先展示表单再提交回调收到FormActionContext.values两种类型并可用prevent_hide_after_actionTrue保持 Wox 窗口在执行动作后不隐藏详见 ResultAction 模型。WoxImageclass WoxImage: classmethod def new_emoji(cls, char: str) - WoxImage classmethod def new_absolute(cls, path: str) - WoxImage classmethod def new_relative(cls, path: str) - WoxImageWoxImage 实现 支持多种图片类型ABSOLUTE、RELATIVE相对插件目录、BASE64完整 data URI、SVG内联 SVG 标记、EMOJI、URL、THEME内置主题图标随明暗主题自适应、FILE_ICON按文件扩展名取系统图标。对应工厂方法还包括new_base64()、new_svg()、new_url()、new_theme()等。Action 图标应使用可适配主题的 SVGsvg:或使用var(--wox-theme-icon-color)的内联标记而不是 emoji详见references/icons.md。Public API 方法全览所有方法均为异步且需要ctx。以下是 SDK 参考文档列出的核心 API按类别整理通用控制方法作用change_query(ctx, query: PlainQuery)更新搜索栏内容支持ChangeQueryParam指定查询类型与文本/选区hide_app(ctx)隐藏 Woxshow_app(ctx)显示 Woxnotify(ctx, message)显示系统通知支持 i18n keylog(ctx, level, msg)写日志level取LogLevel枚举INFO/ERROR/DEBUG/WARNINGcopy(ctx, params: CopyParams)复制文本或图片到剪贴板is_visible(ctx)检查 Wox 窗口是否可见缓存插件需要磁盘缓存时优先使用get_cache_folder不要自创目录get_cache_folder(ctx)返回~/.wox/cache/plugins/plugin-id/。Wox 会在需要时自动创建并在插件卸载时删除。在init()中调用一次并保存路径把下载文件、缩略图、搜索结果等写入其下。不要在插件文件旁、用户数据目录下或硬编码文件夹名下自行发明cache/、tmp/、downloads/目录。用户偏好与收藏属于设置而非缓存请使用get_setting/set_setting。该 API 在 PublicAPI 协议 中有完整的路径语义注释。设置插件设置应优先使用以下 API——这些值可以通过 Wox 云同步跨设备同步不要把普通设置持久化到本地文件或自定义存储中get_setting(ctx, key)读取设置值未设置时返回默认值。save_setting(ctx, key, value, is_platform_specific)保存设置。普通插件设置可参与云同步对于本地路径、可执行文件路径、shell 命令、热键、浏览器配置、应用路径、系统集成等仅限当前平台的值is_platform_specific传True。on_setting_changed(ctx, callback)注册设置变更回调回调签名(ctx, key, new_value)。on_get_dynamic_setting(ctx, callback)为dynamic类型设置提供运行时生成的设置定义回调返回PluginSettingDefinitionItem。save_setting在源码中已被标注为 Deprecatedapi.py 中的说明新插件在MinWoxVersion 2.4.0时应改用set_setting(ctx, SetSettingOption(...))后者通过platform_specific与is_local两个布尔字段显式控制跨平台与设备本地行为见 SetSettingOption 实现。UI 实时更新update_result(ctx, result: UpdatableResult)实时更新结果用于动作处理中的长任务进度展示。push_results(ctx, query, results)向当前查询追加结果适合流式返回、分批加载。refresh_query(ctx, param)以现有文本重新执行查询RefreshQueryParam.preserve_selected_index控制是否保持选中项。get_updatable_result(ctx, result_id)获取某结果的当前 UI 状态结果已不可见时返回None。AI 与国际化ai_chat_stream(ctx, model, convs, options, callback)流式获取 LLM 响应。model为AIModel(name..., provider...)convs为Conversation列表可用user_message()/assistant_message()便捷构造回调接收ChatStreamData状态为STREAMING/FINISHED/ERROR。get_translation(ctx, key)获取原始翻译字符串。注意返回的是原始字符串参数替换需自行用 f-string 或.format()完成。设置编写要点插件设置一律走get_setting/save_setting/on_setting_changed以便参与 Wox 云同步不要让用户期望换设备还在的值落入本地文件。缓存文件放在get_cache_folder(ctx)下不要在插件目录或用户数据树下自造缓存目录。Python SDK 内置以下设置构建辅助函数定义见 setting.pycreate_textbox_setting(key, label, default_value, tooltip)单行文本框设置。create_checkbox_setting(key, label, default_valuefalse, tooltip)布尔开关true为选中。create_label_setting(content, tooltip)只读说明文字。目前没有内置create_select_setting()辅助函数。对于select、table、校验器、dynamic等高级设置需要直接构造PluginSettingDefinitionItem与对应的值对象如PluginSettingValueTable、PluginSettingValueTableColumn、PluginSettingValueTableGroup或手动输出期望的 JSON 结构。设置类型枚举见 PluginSettingDefinitionTypehead/textbox/checkbox/select/label/newline/table/dynamic。精确的plugin.json与校验器结构请阅读references/plugin_json_schema.md可直接复制的高级设置示例见references/settings_patterns.md。运行时save_setting(ctx, key, value, is_platform_specific)调用必须与设置元数据保持一致如果对应SettingDefinitions条目声明了IsPlatformSpecific: true不要对动态保存的设置硬编码False。DisabledInPlatforms只控制设置在哪些平台被禁用不会隔离云同步的值。当查询依赖 API Key 等设置时在plugin.json中使用静态QueryRequirements。Wox 会在调用query()之前拦截查询仅显示内置的query_requirement_settings配置预览。不存在运行时的register_query_requirementsAPI查询需求一律在元数据中声明。QueryRequirements 数据类与元数据示例from dataclasses import dataclass, field dataclass class PluginQueryRequirement: setting_key: str validators: list[dict] field(default_factorylist) message: str dataclass class PluginQueryRequirements: any_query: list[PluginQueryRequirement] field(default_factorylist) query_without_command: list[PluginQueryRequirement] field(default_factorylist) query_with_command: dict[str, list[PluginQueryRequirement]] field(default_factorydict)其语义在 PluginQueryRequirements 源码 中有明确注释any_query作用于所有查询query_without_command仅作用于无子命令的查询query_with_command按命令关键字分别配置。to_dict()会转换成plugin.json使用的 PascalCase 字段名。元数据示例{ SettingDefinitions: [ { Type: textbox, Value: { Key: accessKey, Label: i18n:access_key, DefaultValue: , Validators: [{ Type: not_empty, Value: {} }] } } ], QueryRequirements: { AnyQuery: [ { SettingKey: accessKey, Message: i18n:access_key_required } ], QueryWithoutCommand: [], QueryWithCommand: {} } }校验器类型除not_empty外仓库setting/validator/目录还提供is_number、is_url、unique等实现可供参考。动态设置Dynamic Setting示例动态设置由on_get_dynamic_setting回调在运行时生成定义适合值取决于当前状态如预览、可选列表的场景from wox_plugin import ( PluginSettingDefinitionItem, PluginSettingDefinitionType, PluginSettingValueLabel, ) async def _on_get_dynamic_setting(ctx, key): if key separator_preview: return PluginSettingDefinitionItem( typePluginSettingDefinitionType.LABEL, valuePluginSettingValueLabel(contentPreview: 1,234.56), ) return PluginSettingDefinitionItem( typePluginSettingDefinitionType.LABEL, valuePluginSettingValueLabel(contentUnknown setting), )回调在init()中注册await self.api.on_get_dynamic_setting(ctx, self._on_get_dynamic_setting)。完整使用示例带 i18n 格式化的 Hello 插件from wox_plugin import Plugin, Query, Result, WoxImage class HelloPlugin(Plugin): async def init(self, ctx, params): self.api params.api async def query(self, ctx, query): # I18n with formatting raw_fmt await self.api.get_translation(ctx, hello_format) # Hello {name} title raw_fmt.format(namequery.search) return [Result( titletitle, iconWoxImage.new_emoji(), actions[] )] plugin HelloPlugin()注意get_translation返回的是包含{name}占位符的原始字符串需用.format()完成替换——这正是 SDK 参考中强调的要点。静态 HTML 预览WEBVIEW预览结果时使用WoxPreviewType.WEBVIEW并传入 JSON 编码的html字段即可无需 HTTP 服务器或临时 HTML 文件也不存在独立的html预览类型import json from wox_plugin import WoxPreview, WoxPreviewType preview WoxPreview( preview_typeWoxPreviewType.WEBVIEW, preview_datajson.dumps({ html: !doctype htmlhtmlbodyh1 stylecolor:tealHello Wox/h1/body/html }), ) # Assign preview to Result(previewpreview, ...).html与url二选一。可选 JSON 字段injectCss、userAgent、cacheDisabled、cacheKey默认取 URL 或 HTML 内容。内联 HTML 没有相对插件的 base URL请内联 CSS/图片或使用绝对资源 URL。这是浏览器内容而非经过净化的 Markdown拼接不可信文本前务必使用html.escape。WoxPreview模型还支持MARKDOWN、TEXT、IMAGE、URL、FILE、LIST、REMOTE等类型WoxPreviewType 定义其中LIST可通过WoxPreviewListData展示带图标、副标题与尾巴的结构化行。结构化查询参数与命令块命令的别名配置在Commands[].Aliases后缀模板配置在Commands[].QueryHint完整的ChangeQuery实例与 SDK 用法详见.agents/skills/wox-plugin-creator/SKILL.md的QueryHint章节。QueryHint对input查询仍是可选项不要在QueryText中嵌入标记也不要从粘贴文本中推断参数边界。常用参考路径SDK 参考文档本文依据Python SDK 包导出PublicAPI 协议与全部方法签名Plugin 协议与生命周期Result / ResultAction / UpdatableResult 模型QueryResponse / Refinement / Layout 模型设置定义模型与辅助函数WoxImage 图片模型WoxPreview 预览模型Python 宿主版本校验配套参考插件 JSON Schema、设置模式、精化控件、图标规范、i18n【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考