Wox 全功能插件开发实战指南：基于 Python / Node.js 宿主与 WebSocket 的持久化插件体系

桌面应用AI 应用插件系统【免费下载链接】WoxA cross-platform launcher that simply works项目地址https://gitcode.com/gh_mirrors/wo/Wox点击查看免费下载全功能插件Full-featured Plugin是 Wox 三类插件实现方式中能力最完整的一类它运行在独立的 Python 或 Node.js 宿主进程中通过 WebSocket 与wox.core通信常驻内存、可持续保有状态并可使用 Wox 公开 API 中的预览、设置 UI、工具栏消息、MRU 恢复、截图采集、AI 流式对话与深链等高级能力。本文以 Wox 官方文档 full-featured-plugin.md 为骨架结合仓库内 Python/Node.js SDK 源码与系统插件实现完整讲解全功能插件的选型依据、最小示例、plugin.json配置、查询与结果构建、设置系统、截图 API 以及本地开发调试闭环读完即可着手开发一个可商用级别的 Wox 插件。一、何时选择全功能插件Wox 将插件按安装形态分为系统插件随 Wox 内置、不可卸载与用户插件可安装、卸载、更新、禁用按实现方式分为脚本插件Script Plugin、单文件 SDK 插件Single-file SDK Plugin与全功能插件三类详细对比可参见 插件概览。当你的插件需要以下一项或多项能力时应当选择全功能插件模型跨多次查询保持持久状态persistent state across queries异步 / 网络密集型工作async/network-heavy work自定义设置 UIcustom settings UI更丰富的预览与动作richer previews and actions插件驱动的截图或剪贴板工作流plugin-driven screenshot or clipboard workflowsAI 或 MRU 集成AI or MRU integration。如果插件只是一个小型单文件自动化脚本应从 脚本插件指南 开始如果希望保持单文件但需要使用 Wox API请参考 单文件 SDK 插件指南。若使用 Codex 等兼容 Agent 辅助开发可参考 AI Skills For Plugin Development。从源码结构看全功能插件的核心契约定义在 Python SDK 的 plugin.py 中插件类只需实现init(ctx, init_params)与query(ctx, query)两个异步方法即可进入 Wox 的插件生命周期实例化 → 初始化 → 查询 → 卸载。二、快速开始全功能插件的最小落地步骤在~/.wox/plugins/your-plugin-id/下创建插件目录添加plugin.json与入口文件main.py、index.js或构建产物如dist/index.js安装对应语言的 SDK在 Wox 设置中重载插件或重启 Wox。SDK 安装命令Pythonuv add wox-pluginNode.jspnpm add wox-launcher/wox-pluginPython SDK 的包结构与类型标注位于 wox_plugin 包Node.js SDK 的入口与类型定义位于 wox.plugin.nodejs/src/index.ts 与 wox.plugin.nodejs/types/index.d.ts。三、最小示例Hello Wox以下两个示例均返回QueryResponse因此插件的plugin.json必须将MinWoxVersion声明为2.0.4或更新版本。如果同一份插件构建需要兼容更老版本的 Wox则直接返回list[Result]Python或Result[]Node.js。Python 最小示例from wox_plugin import Plugin, Query, QueryResponse, Result, Context, PluginInitParams from wox_plugin.models.image import WoxImage class MyPlugin(Plugin): async def init(self, ctx: Context, params: PluginInitParams) - None: self.api params.api self.plugin_dir params.plugin_directory async def query(self, ctx: Context, query: Query) - QueryResponse: return QueryResponse(results[ Result( titleHello Wox, sub_titleThis is a sample result, iconWoxImage.new_emoji(), score100, ) ]) plugin MyPlugin()Node.js 最小示例import { Plugin, Query, QueryResponse, Context, PluginInitParams } from wox-launcher/wox-plugin class MyPlugin implements Plugin { private api!: PluginInitParams[API] private pluginDir async init(ctx: Context, params: PluginInitParams): Promisevoid { this.api params.API this.pluginDir params.PluginDirectory } async query(ctx: Context, query: Query): PromiseQueryResponse { return { Results: [ { Title: Hello Wox, SubTitle: This is a sample result, Icon: { ImageType: emoji, ImageData: }, Score: 100, }, ], } } } export const plugin new MyPlugin()QueryResponse 与 list[Result] 的兼容性说明直接返回list[Result]/Result[]已被标记为 deprecated但 Python 与 Node.js 宿主仍会接受旧形态以兼容老版本 Wox。只有在plugin.json声明MinWoxVersion 2.0.4时才应使用QueryResponse。从 query_response.py 的实现可以看到原因QueryResponse将Results、Refinements查询级筛选/排序控件与Layout每查询的预览宽度、网格布局提示打包成一个归一化载荷一次下发旧形态无法携带这些信息。同理SDK 在 plugin.py 中将返回类型声明为QueryReturn Union[QueryResponse, List[Result]]即两种形态在类型层面都被接受。四、plugin.json 核心配置plugin.json位于每个全功能插件的根目录Wox 依据它决定插件能否在当前平台加载、使用哪个运行时与入口文件、如何注册触发关键词与命令。完整字段参考 插件规范全功能插件应遵循以下要点完整 schema 见 Specification即 www/docs/development/plugins/specification.mdRuntime取值为PYTHON或NODEJSEntry指向 Wox 应执行的入口文件Features只声明实际使用的能力。示例{ Id: my-awesome-plugin, Name: My Awesome Plugin, Description: Do awesome things, Author: You, Version: 1.0.0, MinWoxVersion: 2.0.4, Runtime: NODEJS, Entry: dist/index.js, TriggerKeywords: [awesome, ap], Features: [{ Name: querySelection }, { Name: ai }], SettingDefinitions: [ { Type: textbox, Value: { Key: api_key, Label: API Key, DefaultValue: } } ] }补充说明几个关键字段依据 规范字段是否必填说明示例Id✅稳定唯一 ID建议 UUIDcea0f...28855MinWoxVersion✅最低要求的 Wox 版本2.0.4Runtime✅PYTHON、NODEJS、SCRIPTGo 仅系统插件保留PYTHONEntry✅相对插件根的入口文件main.pyIcon✅WoxImage字符串emoji:、base64、相对路径均可emoji:TriggerKeywords✅一个或多个触发关键词*表示全局触发[calc]SupportedOS✅Windows、Linux、Darwin的任意组合[Windows,Darwin]Features⭕可选能力开关可带参数[{Name:debounce,Params:{IntervalMs:200}}]SettingDefinitions⭕渲染在 Wox 设置页的配置 schema[...]五、查询处理Query 对象模型Wox 会将每次用户交互归一化为一个Query对象传入query()核心字段如下详细拆分规则见 Query 模型Query.Type取值为input或selectionQuery.RawQuery保留原始输入Query.TriggerKeyword、Query.Command、Query.Search解析后的三个分段Query.Id做异步后续更新时必须保留的标识符Query.Env当启用queryEnv功能时携带的可选环境上下文如活动窗口信息、浏览器 URL。以wpm install wox为例的拆分结果TriggerKeywordwpmCommandinstallSearchwoxRawQuerywpm install woxselection类型仅在插件声明querySelection功能时才会送达载荷包含文本与文件路径Env仅在声明queryEnv时出现。SDK 侧对应的数据模型定义在 query.pyQuery、QueryType、Selection、QueryEnv等。六、构建结果Result、预览、Tails、Actions 与增量更新每个Result可包含IconPreviewTailsActionsGroup与GroupScore实用模式用Preview承载 markdown、纯文本、图片、文件、列表或内嵌 HTML/网页预览用Tails显示徽章或小型元数据当某个动作会持续原地更新同一结果时设置PreventHideAfterAction。若动作启动后需要更新一个已经可见的结果使用GetUpdatableResult获取结果当前状态若结果已不可见如用户改换了查询返回NoneUpdateResult应用更新并返回布尔值表示结果是否仍然可见。若需要为同一次活跃查询流式追加更多结果使用PushResults传入当前Query与结果批次查询仍活跃时返回true查询已切换时返回false且结果被忽略——这非常适合先返回部分结果、再异步补齐剩余结果的场景。这些方法的签名与使用示例可在 Python SDK 的 api.py 中直接查看。七、静态 HTML 预览webview使用webview渲染内联 HTML含 CSS无需启动 HTTP 服务器或创建临时 HTML 文件html是负载字段payload field不是一种预览类型。import type { WoxPreview, WoxPreviewWebviewData } from wox-launcher/wox-plugin const preview: WoxPreview { PreviewType: webview, PreviewData: JSON.stringify({ html: !doctype htmlhtmlbodyh1 stylecolor:tealHello Wox/h1/body/html } satisfies WoxPreviewWebviewData) } // Assign preview to Result.Preview.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 没有插件相对基 URL请内嵌 CSS/图片或使用绝对资源 URL这是浏览器内容而非经过净化的 Markdown在将不可信文本拼入 HTML 之前必须先转义。底层实现可在 Python SDK 的 preview.py 中确认WoxPreviewType枚举完整覆盖MARKDOWN、TEXT、IMAGE、URL、WEBVIEW、FILE、LIST、REMOTE八种类型其中WEBVIEW的preview_data是含url或html的 JSON 字符串FILE类型支持 markdown、图片、PDF、文本等格式LIST类型用WoxPreviewListData的行式载荷展示进度、状态等结构化信息适用于长时间运行的动作更新。八、设置系统SettingDefinitions 与运行时读写在plugin.json中用SettingDefinitions定义设置 UI。常用设置类型textboxcheckboxselectselectAIModeltabledynamicheadlabelnewline各类型的取值键说明可参考 规范例如head使用Contentselect使用Key、Label、DefaultValue与Options[] { Label, Value }selectAIModel的下拉项由 Wox 按已配置的 AI 提供商动态填充table支持Columns与可选的分组Groups[]可CollapsedByDefaultdynamic仅含Key由插件在运行时填充Style支持PaddingLeft/Top/Right/Bottom与Width。运行时读写约定用GetSetting读取值用SetSetting持久化要求 Wox 2.4.0对绝不允许进入云同步Cloud Sync的值设置IsLocalSaveSetting仅用于兼容更老版本的 Wox已标记 deprecated用OnSettingChanged响应设置变更回调签名(context, key, new_value)适用于热更新 API Key 等场景用OnGetDynamicSetting提供运行时生成的设置项。Python SDK 中 api.py 的SetSettingOption数据类进一步揭示了SetSetting的完整字段Key、Value、PlatformSpecific按平台分别存储与IsLocal仅本机保存、不进入云同步set_setting返回包含Success与ErrMsg的结果对象。OnGetDynamicSetting回调在设置页打开时按需拉取因此应保持回调快速且确定性必要时缓存远程数据避免拖慢 UI。九、常用 Feature flags全功能插件最可能用到的能力开关querySelection接收文本/文件选区查询queryEnv接收活动窗口或浏览器上下文ai使用 Wox 已配置的 AI APIdeepLink注册插件深链mru从 Wox 的 MRU 存储恢复条目resultPreviewWidthRatio已弃用改用QueryResponse.Layout.ResultPreviewWidthRatiogridLayout已弃用改用QueryResponse.Layout.GridLayout。其余可用开关还包括debounce参数IntervalMs避免输入过程中高频触发query、ignoreAutoScore退出 Wox 频率自动评分等完整列表见 规范。只启用确实需要的能力——它们会改变 Wox 对查询的路由方式与插件上下文的构建。布局类能力推荐通过QueryResponse.Layout按查询声明从 query_response.py 可以看到QueryLayout支持Icon、ResultPreviewWidthRatio与GridLayoutGridLayout含Columns、ImageWidth/ImageHeight、ItemPadding、ItemMargin、AspectRatio、ShowTitle等参数相比静态的 plugin.json 元数据开关能够针对每次查询结果集独立决定预览宽度与网格呈现。十、截图 API把选区绘制交给 WoxWox 为全功能插件内置了一套截图工作流。当插件需要用户绘制一个区域、再自行处理得到的图片路径时使用典型场景包括OCR 识别图片上传缺陷报告bug reportingWox 之外的视觉标注流水线。API 返回值Screenshot()返回Success采集是否成功完成ScreenshotPath成功时导出的图片路径ErrMsg失败原因若采集完成但存在注意项则为警告信息。选项ScreenshotOption支持HideAnnotationToolbar将流程聚焦于纯粹的选区绘制AutoConfirm用户完成一次有效选区后立即结束。Node.js 示例const capture await this.api.Screenshot(ctx, { HideAnnotationToolbar: true, AutoConfirm: true, }) if (!capture.Success) { await this.api.Notify(ctx, Screenshot failed: ${capture.ErrMsg}) return } await this.api.Notify(ctx, Saved to ${capture.ScreenshotPath})行为注意点导出的文件路径会返回给插件剪贴板处理由插件自行负责第三方插件会自动在浮动截图工具箱中显示自己的插件图标若需要 Wox 内置的标注 UI请不要设置HideAnnotationToolbar。Python SDK 中对应定义位于 api.pyScreenshotOptionhide_annotation_toolbar/auto_confirm序列化为HideAnnotationToolbar/AutoConfirm与ScreenshotResultsuccess/screenshot_path/errmsg。Wox 内置截图系统插件的实现可参考 screenshot.go其中展示了完整截图工作流采集 → 导出路径 → 生成缩略图 → OCR 侧车文件 → 通知如何在宿主层落地可作为插件侧截图流程对接的实际参照。十一、AI、深链与 MRUAI API 需要声明ai功能深链回调需要deepLink功能与OnDeepLink回调接收参数字典典型用法为解析wox://myplugin?actionopenid123之类的调用MRU 恢复需要mru功能与OnMRURestore回调返回Result以恢复条目返回None表示条目失效并从 MRU 移除。这些都是可选能力。如果首版还不需要它们保持插件尽量精简。对应 API 方法ai_chat_stream、on_deep_link、on_mru_restore的签名与完整示例见 api.py。十二、本地开发循环与调试开发循环将插件目录放在~/.wox/plugins/下或把你的工作目录软链接到那里修改plugin.json后从 Wox 设置中重载插件或重启 Wox修改 TypeScript 构建产物后重新构建插件并重载如果插件触及核心/宿主契约应重新构建 Wox 本体而不是指望宿主自动拾取类型变更。推荐的调试顺序当出现问题时的排查步骤先核对plugin.json确认正在使用正确的运行时宿主Python 还是 Node.js通过 SDK API 在插件侧添加日志查看核心日志~/.wox/log/wox.log必要时再查看同一日志目录下的 UI 或宿主日志如果问题跨层从仓库根目录执行make build重新构建。make build会依次执行清理、AI 技能同步、原生组件WoxMR、窗口钩子、崩溃处理器、文件索引服务构建与 Go 核心编译完整目标定义见 wox.core/Makefile。核心日志目录与插件目录约定同样适用于 Python/Node.js 宿主SDK 中的log(ctx, level, msg)方法会将日志写入 Wox 日志文件便于与核心日志交叉排查。赞分享桌面应用AI 应用插件系统【免费下载链接】WoxA cross-platform launcher that simply works项目地址https://gitcode.com/gh_mirrors/wo/Wox点击查看免费下载相关推荐Wox 全功能插件开发指南基于 WebSocket 常驻宿主的完整 API 实战Wox 全功能插件开发指南基于 WebSocket 常驻宿主的完整 API 实战 全功能插件Full featured Plugin是 Wox 插件体系中桌面应用AI 应用插件系统Wox 插件体系全解析系统插件、脚本插件、单文件 SDK 插件与全功能插件的分类与选型指南Wox 插件体系全解析系统插件、脚本插件、单文件 SDK 插件与全功能插件的分类与选型指南 本篇技术指南以 Wox 官方文档《插件概览》为骨架系统梳理 Wo桌面应用AI 应用插件系统Wox 单文件 SDK 插件开发指南一个文件、完整 Public API、常驻宿主进程Wox 单文件 SDK 插件开发指南一个文件、完整 Public API、常驻宿主进程 单文件 SDK 插件Single file SDK Plugin是桌面应用AI 应用插件系统上一篇探秘QArt4J二维码的艺术之旅下一篇Agent Zero模型配置从零到一的智能代理搭建之旅创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考