Wox 插件体系全解析系统插件、脚本插件、单文件 SDK 插件与全功能插件的分类与选型指南【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox本篇技术指南以 Wox 官方文档《插件概览》为骨架系统梳理 Wox 的插件分类系统插件 / 用户插件与三种实现形态脚本插件、单文件 SDK 插件、全功能插件的定位、能力边界与适用场景并结合wox.core/plugin源码剖析各形态的底层通信与生命周期实现。读者读完后能够准确判断自己的需求应该选择哪一种插件形态掌握各形态的能力清单、局限性及选型决策方法并能理解 Wox 内部插件加载与执行的运作原理。插件分类按安装来源划分Wox 首先按安装来源将插件分为两大类这一分类直接决定了用户对插件的管理权限。系统插件 (System Plugin)系统插件是 Wox 捆绑随附的插件无法卸载。它们为 Wox 提供基础能力其元数据与实现均由 Wox 本体代码维护。例如wpm就是用于插件管理的系统插件。从源码来看系统插件通过注册到全局列表plugin.AllSystemPlugin的方式挂载例如 wox.core/plugin/system/wpm.go 中执行plugin.AllSystemPlugin append(...)。当前仓库中已注册的系统插件覆盖了大量常用功能例如应用启动与窗口管理app、window_manager浏览器书签与网页操作browser_bookmark、browser、url计算器、单位换算、颜色、计时器calculator、converter、color、timer剪贴板历史、文件搜索、快速跳转clipboard、file_search、quickjumpAI 命令与 AI 聊天ai_command、chat云同步、备份、反馈、OCR、截图cloudsync、backup、feedback、ocr_setting、screenshot主题、更新、插件安装器、WebView 等theme、update、plugin_installer、webview系统插件遵循核心的Plugin接口Init(ctx, InitParams)与Query(ctx, Query) QueryResponse见 wox.core/plugin/plugin.go并额外实现GetMetadata()以暴露其元数据。用户插件 (User Plugin)用户插件由用户自行安装用户可以自由地安装、卸载、更新或禁用。它们可以来自 Wox 插件商店、本地开发目录dev.add添加的本地插件目录或手动放入插件目录。插件实现类型三种形态的对比从如何实现的角度Wox 支持三种插件实现方法。官方文档建议如果使用 Codex 或其他兼容的 agent可查看用于插件开发的 AI Skills借助内置的wox-plugin-creatorskill 快速搭建脚手架。三种形态的核心差异可以用一句话概括脚本插件Script Plugin 单文件 每次调用启动新进程 stdin/stdout JSON-RPC 单文件 SDK 插件Single-file SDK Plugin 单文件 常驻 SDK runtime host 完整 Public API 全功能插件Full-featured Plugin .wox 包或多文件目录 常驻专用宿主进程 WebSocket 完整 Public API维度脚本插件单文件 SDK 插件全功能插件文件数量单文件单文件多文件 /.wox包进程模型每次 query 启动新进程复用常驻 Python/Node host专用宿主进程常驻通信方式stdin/stdout JSON-RPChost 内部 RPCWebSocketPublic API有限环境变量 JSON-RPC完整设置、AI、UpdateResult 等完整状态管理无状态query/action 间保留对象状态完全支持依赖支持无用系统解释器无 pip/npm 依赖支持依赖、资源、TypeScript适合场景简单自动化、快速实用程序单文件但需要 Wox API复杂业务、高性能、商业插件脚本插件 (Script Plugin)脚本插件是轻量级的单文件插件非常适合简单的自动化任务和快速实用程序。详细开发指南见脚本插件开发指南。特点单文件实现整个插件逻辑包含在一个脚本文件中元数据以 JSON 注释块形式写在文件头部。按需执行脚本按查询执行不需要持久运行进程。多语言支持支持 Python、JavaScript、Bash 以及其他可通过 shebang 或扩展名识别的脚本语言源码中还支持.rb→ ruby、.pl→ perl。简化开发通过注释定义元数据无需复杂的plugin.json配置文件。即时生效修改脚本文件后立即生效无需重启 Wox。JSON-RPC 通信使用 JSON-RPC 2.0 通过标准输入/输出stdin/stdout与 Wox 通信。底层执行机制源码视角在 wox.core/plugin/host/host_script.go 中ScriptHost是一个无常驻进程的 hostStart()不启动任何后台进程IsStarted()恒为true。每次查询时ScriptPlugin.Query会构造一个 JSON-RPC 请求方法query参数含search、trigger_keyword、command、raw_query通过 stdin 注入脚本然后执行脚本进程并解析其 stdout 输出。其解释器解析逻辑getInterpreter先按文件扩展名判断扩展名无法识别时再回退读取 shebang 行。脚本插件可访问的环境变量均在executeScriptRaw中注入WOX_DIRECTORY_USER_SCRIPT_PLUGINS— 脚本插件存储目录WOX_DIRECTORY_USER_DATA— 用户数据目录WOX_DIRECTORY_WOX_DATA— Wox 应用数据目录WOX_DIRECTORY_PLUGINS— 插件目录WOX_DIRECTORY_THEMES— 主题目录WOX_DIRECTORY_PLUGIN_CACHE— 当前插件缓存目录WOX_PLUGIN_ID、WOX_PLUGIN_NAME— 插件标识与名称WOX_LANG— 当前语言代码WOX_SETTING_*— 每个插件设置项以WOX_SETTING_前缀 大写键名注入如api_key→WOX_SETTING_API_KEY用例简单的文件操作和系统命令快速文本处理和格式转换调用外部 API 进行简单数据检索个人自动化脚本和实用程序学习和原型开发不需要复杂状态管理的功能局限性性能脚本为每个查询重新执行每次调用都启动全新进程性能相对较低。超时限制默认执行超时 10 秒。从源码看该超时可通过环境变量WOX_SCRIPT_EXECUTION_TIMEOUT调整defaultScriptExecutionTimeout 10 * time.Second该变量主要用于健康检查等需要更长等待时间的场景正常交互仍以 10 秒为上限。不支持复杂的异步操作和状态管理如需复用状态请自行落盘缓存。API 功能有限query仅收到 search/trigger_keyword/command/raw_query不包含 selection 或查询环境数据。不支持插件设置界面设置项仅能通过环境变量读取。脚本结果可携带preview对象静态 HTML 使用type: webviewdata填 JSON 字符串例如JSON.stringify({ html: h1Hello Wox/h1 })MRU 恢复、结果动态更新等能力请使用全功能插件。元数据示例Python#!/usr/bin/env python3 # { # Id: my-calculator, # Name: My Calculator, # Author: Your Name, # Version: 1.0.0, # MinWoxVersion: 2.0.0, # Description: A simple calculator plugin, # Icon: emoji:, # TriggerKeywords: [calc], # SettingDefinitions: [ # { # Type: textbox, # Value: { # Key: precision, # Label: Decimal Precision, # Tooltip: Number of decimal places to show, # DefaultValue: 2 # } # } # ], # Features: [ # { Name: debounce, Params: { intervalMs: 300 } } # ] # }JSON 元数据块必须放置在文件开头的注释中shebang 行之后Python/Bash 使用#JavaScript 使用//包含具有所有元数据字段的完整 JSON 对象。内置操作由 Wox 自动处理使用内置操作时无需在脚本中实现action方法处理逻辑Wox 会直接处理action方法仍会作为钩子被调用可返回空结果。这些操作在源码 wox.core/plugin/host/host_script.go 的handleBuiltInAction中实现copy-to-clipboard复制文本到剪贴板参数text或dataopen-url在默认浏览器打开 URL参数urlopen-directory在文件管理器中打开目录参数pathnotify显示通知消息参数messagechange-query改变当前查询框内容参数query/text/queryText单文件 SDK 插件 (Single-file SDK Plugin)单文件 SDK 插件是一个.py或 CommonJS.js文件拥有完整的 Wox Public API并加载到 Wox 现有的 Python / Node.js runtime host 中。它不需要.wox包也不会为每次 query 启动新进程。详见单文件 SDK 插件。特点和脚本插件一样只维护一个文件。host 进程常驻query/action 复用 host 进程Wox 不会为插件单独创建 Python 或 Node 进程host 崩溃恢复沿用现有 watchdog 机制。完整 Public API设置、AI、UpdateResult、PushResults、深度链接、unload callback 等能力一应俱全。保存后自动 reload保存文件后约 500ms 防抖自动重载每次加载/reload 都会调用一次init()query/action 之间保留插件对象状态但保存后的内存状态会重置不提供状态迁移。Python 可以直接import wox_plugin使用 SDKNode.js 通过params.API使用能力第一版固定为 CommonJS使用module.exports.plugin不要import/requirewox-launcher/wox-pluginWoxImage等简单类型用对象字面量。与脚本插件的区别需求选择一次性 shell / 命令包装脚本插件只要一个文件但需要 Wox API单文件 SDK 插件需要依赖、资源、TypeScript 或多文件SDK 插件全功能插件官方文档明确说明脚本插件不是这个功能的 v1也不会被废弃。Metadata 要点文件头注释里放 JSON 对象允许第一行 shebang。必须显式提供Id、Name、Version、MinWoxVersion、Runtime、TriggerKeywords。也支持Author、Description、Icon、Website、Commands、SupportedOS、Features、Glances、SettingDefinitions、QueryRequirements、I18n。Wox 会把Entry设为当前文件名把Directory设为plugins/single-file文件头不允许声明Entry或Directory。Runtime 必须和后缀匹配不会猜测或降级.py→PYTHON.js→NODEJS。不要把PYTHON/NODEJS文件放进plugins/scripts/在 scripts 目录里显式声明PYTHON/NODEJS会被拒绝并提示移动。局限性不支持 pip/npm 依赖、额外文件或相对路径图片图标支持 emoji、URL、SVG、base64、绝对路径。Node.js 第一版必须是 CommonJS.js不支持.mjs、ESM、TypeScript、npm 依赖和 SDK npm helper。所有单文件插件共享plugins/single-file/目录不加载共享的lang/目录只支持文件头内联I18n。商店发布时Wox 根据Runtime和 URL path 后缀分类PYTHON.py/NODEJS.js为单文件 SDK 插件PYTHON/NODEJS.wox为普通 SDK 插件SCRIPT脚本文件为脚本插件未知后缀或PYTHON.js这类组合会被拒绝且同一插件 ID 不允许在.wox与单文件形态之间切换交付。全功能插件 (Full-featured Plugin)全功能插件是为复杂应用场景和高性能要求设计的综合插件。它运行在专用宿主进程Python 或 Node.js中通过 WebSocket 与wox.core通信。详细开发指南见全功能插件开发指南完整字段定义见插件规范查询模型见查询模型。特点完整架构通过专用插件宿主进程运行插件目录包含plugin.json与入口文件main.py、index.js或构建产物如dist/index.js。持久运行插件保持加载和运行状态支持跨查询状态管理。丰富 API支持 AI 集成、预览、设置界面、MRU、深度链接、截图能力等高级功能。WebSocket 通信通过 WebSocket 与 Wox 核心进行高效通信。源码 wox.core/plugin/host/host_websocket.go 展示了宿主进程的启动流程Wox 先获取可用 TCP 端口随后启动宿主进程并传入 entry、端口、宿主日志目录与 Wox PID最后建立 WebSocket 连接而 wox.core/plugin/host/host_websocket_plugin.go 中的WebsocketPlugin通过invokeMethod将init、action、formAction、toolbarMsgAction等调用代理到宿主进程。异步支持完全支持异步操作与网络请求。生命周期管理完整的插件初始化、查询和卸载生命周期。用例需要复杂状态管理的应用程序高频查询和实时数据处理具有 AI 集成的智能插件需要自定义设置界面的插件复杂的异步操作和网络请求性能敏感的应用场景商业级插件开发支持语言与 SDKPython使用wox-pluginSDK安装命令uv add wox-plugin源码见 wox.plugin.python/src/wox_plugin。Node.js使用wox-launcher/wox-pluginSDK安装命令pnpm add wox-launcher/wox-plugin源码见 wox.plugin.nodejs。插件命令与能力开关plugin.json中的Runtime取PYTHON或NODEJSEntry指向 Wox 实际执行的文件Features只声明真正需要的能力。常见能力开关包括querySelection接收文本/文件选择查询queryEnv接收活动窗口或浏览器上下文ai使用 Wox 配置好的 AI 能力deepLink注册插件深度链接mru从 Wox 的最近使用记录恢复结果resultPreviewWidthRatio/gridLayout已 deprecated改用QueryResponse.Layout中的对应字段从源码 wox.core/plugin/metadata.go 可以看到Metadata中Features数组的每一项都是{Name, Params}结构管理器通过IsSupportFeature判断能力是否开启并针对debounceIntervalMs、queryEnv如requireActiveWindowName、requireActiveBrowserUrl、mruHashBy等 feature 解析具体参数。这解释了为什么文档强调只打开真正需要的能力——它们会直接影响 Wox 如何路由查询和构建插件上下文。高级能力速览静态 HTML 预览使用webview类型把 HTML 放进 JSON 数据的html字段无需启动 HTTP 服务或写临时文件可选字段包括injectCss、userAgent、cacheDisabled、cacheKey。内联 HTML 没有相对于插件目录的基础 URL资源应内嵌或使用绝对 URL且插入不可信文本前需先做 HTML 转义。结果动态更新action 执行后继续原地更新用GetUpdatableResult/UpdateResult针对当前查询追加或流式推送结果用PushResults。截图 APIScreenshot()返回Success、ScreenshotPath、ErrMsgScreenshotOption支持HideAnnotationToolbar只保留纯粹选区流程与AutoConfirm有效选区完成后立即结束。第三方插件触发截图时悬浮工具栏会自动显示插件自己的图标。选择指南官方文档给出的选型决策如下选择脚本插件当功能相对简单逻辑清晰不需要复杂的状态管理只需要包装一条命令或一次性脚本快速原型设计和个人工具学习 Wox 插件开发选择单文件 SDK 插件当只要一个文件但需要 Wox API需要设置、AI、UpdateResult或 unload callback可以停留在 Python或 CommonJS Node.js并且不需要额外文件选择全功能插件当需要依赖、资源、TypeScript 或多文件需要复杂的业务逻辑高频查询和实时响应商业插件开发此外文档也给出了迁移路径脚本插件复杂度上升后可迁移到全功能插件Python SDKwox-plugin或 Node.js SDKwox-launcher/wox-plugin以获得持久状态、完整 API、设置 UI、AI 集成与自定义预览能力。插件命令 (Plugin Commands)Wox 插件可以拥有提供特定功能的命令。例如wpm插件具有install、remove等用于插件管理的命令。从源码 wox.core/plugin/system/wpm.go 可以看到WPMPlugin的元数据中声明了完整的命令集install— 安装插件uninstall— 卸载插件create— 创建新插件可选择 Python / JavaScript / Bash 脚本模板或 Python/Node.js 单文件 SDK 插件模板dev.list— 列出本地开发插件目录dev.add— 添加本地开发插件目录dev.remove— 移除本地开发插件目录dev.reload— 重载开发插件同时wpm声明了wpm、store、pm、*四个触发关键字且命令对象MetadataCommand定义于 wox.core/plugin/metadata.go还支持Aliases别名与QueryHint查询提示字段UI 会基于这些信息在用户输入时给出命令候选与参数建议。命令机制本身是通用能力任意插件都可以在元数据的Commands数组中声明自己的命令。当用户在查询框输入触发关键字 命令名时Wox 会把查询拆分为TriggerKeyword、Command、Search三段后分发到插件详见查询模型插件据此在query中按命令分支处理逻辑。总结Wox 的三层插件体系呈现出清晰的由轻到重梯度脚本插件用最少的代价换取最快的原型与简单自动化单文件 SDK 插件在不增加文件数量的前提下补齐了完整 Public API全功能插件则以多文件和常驻宿主进程为代价换取最高性能与最全能力。选型时遵循从需求倒推形态的原则即可——先看是否需要状态、依赖、AI 与高级 UI再看愿意维护多少文件就能在三种形态之间做出准确判断。官方文档始终建议让插件的核心路径尽量小而稳只在确实需要时才引入更重的形态。【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Wox 插件体系全解析：系统插件、脚本插件、单文件 SDK 插件与全功能插件的分类与选型指南
Wox 插件体系全解析系统插件、脚本插件、单文件 SDK 插件与全功能插件的分类与选型指南【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox本篇技术指南以 Wox 官方文档《插件概览》为骨架系统梳理 Wox 的插件分类系统插件 / 用户插件与三种实现形态脚本插件、单文件 SDK 插件、全功能插件的定位、能力边界与适用场景并结合wox.core/plugin源码剖析各形态的底层通信与生命周期实现。读者读完后能够准确判断自己的需求应该选择哪一种插件形态掌握各形态的能力清单、局限性及选型决策方法并能理解 Wox 内部插件加载与执行的运作原理。插件分类按安装来源划分Wox 首先按安装来源将插件分为两大类这一分类直接决定了用户对插件的管理权限。系统插件 (System Plugin)系统插件是 Wox 捆绑随附的插件无法卸载。它们为 Wox 提供基础能力其元数据与实现均由 Wox 本体代码维护。例如wpm就是用于插件管理的系统插件。从源码来看系统插件通过注册到全局列表plugin.AllSystemPlugin的方式挂载例如 wox.core/plugin/system/wpm.go 中执行plugin.AllSystemPlugin append(...)。当前仓库中已注册的系统插件覆盖了大量常用功能例如应用启动与窗口管理app、window_manager浏览器书签与网页操作browser_bookmark、browser、url计算器、单位换算、颜色、计时器calculator、converter、color、timer剪贴板历史、文件搜索、快速跳转clipboard、file_search、quickjumpAI 命令与 AI 聊天ai_command、chat云同步、备份、反馈、OCR、截图cloudsync、backup、feedback、ocr_setting、screenshot主题、更新、插件安装器、WebView 等theme、update、plugin_installer、webview系统插件遵循核心的Plugin接口Init(ctx, InitParams)与Query(ctx, Query) QueryResponse见 wox.core/plugin/plugin.go并额外实现GetMetadata()以暴露其元数据。用户插件 (User Plugin)用户插件由用户自行安装用户可以自由地安装、卸载、更新或禁用。它们可以来自 Wox 插件商店、本地开发目录dev.add添加的本地插件目录或手动放入插件目录。插件实现类型三种形态的对比从如何实现的角度Wox 支持三种插件实现方法。官方文档建议如果使用 Codex 或其他兼容的 agent可查看用于插件开发的 AI Skills借助内置的wox-plugin-creatorskill 快速搭建脚手架。三种形态的核心差异可以用一句话概括脚本插件Script Plugin 单文件 每次调用启动新进程 stdin/stdout JSON-RPC 单文件 SDK 插件Single-file SDK Plugin 单文件 常驻 SDK runtime host 完整 Public API 全功能插件Full-featured Plugin .wox 包或多文件目录 常驻专用宿主进程 WebSocket 完整 Public API维度脚本插件单文件 SDK 插件全功能插件文件数量单文件单文件多文件 /.wox包进程模型每次 query 启动新进程复用常驻 Python/Node host专用宿主进程常驻通信方式stdin/stdout JSON-RPChost 内部 RPCWebSocketPublic API有限环境变量 JSON-RPC完整设置、AI、UpdateResult 等完整状态管理无状态query/action 间保留对象状态完全支持依赖支持无用系统解释器无 pip/npm 依赖支持依赖、资源、TypeScript适合场景简单自动化、快速实用程序单文件但需要 Wox API复杂业务、高性能、商业插件脚本插件 (Script Plugin)脚本插件是轻量级的单文件插件非常适合简单的自动化任务和快速实用程序。详细开发指南见脚本插件开发指南。特点单文件实现整个插件逻辑包含在一个脚本文件中元数据以 JSON 注释块形式写在文件头部。按需执行脚本按查询执行不需要持久运行进程。多语言支持支持 Python、JavaScript、Bash 以及其他可通过 shebang 或扩展名识别的脚本语言源码中还支持.rb→ ruby、.pl→ perl。简化开发通过注释定义元数据无需复杂的plugin.json配置文件。即时生效修改脚本文件后立即生效无需重启 Wox。JSON-RPC 通信使用 JSON-RPC 2.0 通过标准输入/输出stdin/stdout与 Wox 通信。底层执行机制源码视角在 wox.core/plugin/host/host_script.go 中ScriptHost是一个无常驻进程的 hostStart()不启动任何后台进程IsStarted()恒为true。每次查询时ScriptPlugin.Query会构造一个 JSON-RPC 请求方法query参数含search、trigger_keyword、command、raw_query通过 stdin 注入脚本然后执行脚本进程并解析其 stdout 输出。其解释器解析逻辑getInterpreter先按文件扩展名判断扩展名无法识别时再回退读取 shebang 行。脚本插件可访问的环境变量均在executeScriptRaw中注入WOX_DIRECTORY_USER_SCRIPT_PLUGINS— 脚本插件存储目录WOX_DIRECTORY_USER_DATA— 用户数据目录WOX_DIRECTORY_WOX_DATA— Wox 应用数据目录WOX_DIRECTORY_PLUGINS— 插件目录WOX_DIRECTORY_THEMES— 主题目录WOX_DIRECTORY_PLUGIN_CACHE— 当前插件缓存目录WOX_PLUGIN_ID、WOX_PLUGIN_NAME— 插件标识与名称WOX_LANG— 当前语言代码WOX_SETTING_*— 每个插件设置项以WOX_SETTING_前缀 大写键名注入如api_key→WOX_SETTING_API_KEY用例简单的文件操作和系统命令快速文本处理和格式转换调用外部 API 进行简单数据检索个人自动化脚本和实用程序学习和原型开发不需要复杂状态管理的功能局限性性能脚本为每个查询重新执行每次调用都启动全新进程性能相对较低。超时限制默认执行超时 10 秒。从源码看该超时可通过环境变量WOX_SCRIPT_EXECUTION_TIMEOUT调整defaultScriptExecutionTimeout 10 * time.Second该变量主要用于健康检查等需要更长等待时间的场景正常交互仍以 10 秒为上限。不支持复杂的异步操作和状态管理如需复用状态请自行落盘缓存。API 功能有限query仅收到 search/trigger_keyword/command/raw_query不包含 selection 或查询环境数据。不支持插件设置界面设置项仅能通过环境变量读取。脚本结果可携带preview对象静态 HTML 使用type: webviewdata填 JSON 字符串例如JSON.stringify({ html: h1Hello Wox/h1 })MRU 恢复、结果动态更新等能力请使用全功能插件。元数据示例Python#!/usr/bin/env python3 # { # Id: my-calculator, # Name: My Calculator, # Author: Your Name, # Version: 1.0.0, # MinWoxVersion: 2.0.0, # Description: A simple calculator plugin, # Icon: emoji:, # TriggerKeywords: [calc], # SettingDefinitions: [ # { # Type: textbox, # Value: { # Key: precision, # Label: Decimal Precision, # Tooltip: Number of decimal places to show, # DefaultValue: 2 # } # } # ], # Features: [ # { Name: debounce, Params: { intervalMs: 300 } } # ] # }JSON 元数据块必须放置在文件开头的注释中shebang 行之后Python/Bash 使用#JavaScript 使用//包含具有所有元数据字段的完整 JSON 对象。内置操作由 Wox 自动处理使用内置操作时无需在脚本中实现action方法处理逻辑Wox 会直接处理action方法仍会作为钩子被调用可返回空结果。这些操作在源码 wox.core/plugin/host/host_script.go 的handleBuiltInAction中实现copy-to-clipboard复制文本到剪贴板参数text或dataopen-url在默认浏览器打开 URL参数urlopen-directory在文件管理器中打开目录参数pathnotify显示通知消息参数messagechange-query改变当前查询框内容参数query/text/queryText单文件 SDK 插件 (Single-file SDK Plugin)单文件 SDK 插件是一个.py或 CommonJS.js文件拥有完整的 Wox Public API并加载到 Wox 现有的 Python / Node.js runtime host 中。它不需要.wox包也不会为每次 query 启动新进程。详见单文件 SDK 插件。特点和脚本插件一样只维护一个文件。host 进程常驻query/action 复用 host 进程Wox 不会为插件单独创建 Python 或 Node 进程host 崩溃恢复沿用现有 watchdog 机制。完整 Public API设置、AI、UpdateResult、PushResults、深度链接、unload callback 等能力一应俱全。保存后自动 reload保存文件后约 500ms 防抖自动重载每次加载/reload 都会调用一次init()query/action 之间保留插件对象状态但保存后的内存状态会重置不提供状态迁移。Python 可以直接import wox_plugin使用 SDKNode.js 通过params.API使用能力第一版固定为 CommonJS使用module.exports.plugin不要import/requirewox-launcher/wox-pluginWoxImage等简单类型用对象字面量。与脚本插件的区别需求选择一次性 shell / 命令包装脚本插件只要一个文件但需要 Wox API单文件 SDK 插件需要依赖、资源、TypeScript 或多文件SDK 插件全功能插件官方文档明确说明脚本插件不是这个功能的 v1也不会被废弃。Metadata 要点文件头注释里放 JSON 对象允许第一行 shebang。必须显式提供Id、Name、Version、MinWoxVersion、Runtime、TriggerKeywords。也支持Author、Description、Icon、Website、Commands、SupportedOS、Features、Glances、SettingDefinitions、QueryRequirements、I18n。Wox 会把Entry设为当前文件名把Directory设为plugins/single-file文件头不允许声明Entry或Directory。Runtime 必须和后缀匹配不会猜测或降级.py→PYTHON.js→NODEJS。不要把PYTHON/NODEJS文件放进plugins/scripts/在 scripts 目录里显式声明PYTHON/NODEJS会被拒绝并提示移动。局限性不支持 pip/npm 依赖、额外文件或相对路径图片图标支持 emoji、URL、SVG、base64、绝对路径。Node.js 第一版必须是 CommonJS.js不支持.mjs、ESM、TypeScript、npm 依赖和 SDK npm helper。所有单文件插件共享plugins/single-file/目录不加载共享的lang/目录只支持文件头内联I18n。商店发布时Wox 根据Runtime和 URL path 后缀分类PYTHON.py/NODEJS.js为单文件 SDK 插件PYTHON/NODEJS.wox为普通 SDK 插件SCRIPT脚本文件为脚本插件未知后缀或PYTHON.js这类组合会被拒绝且同一插件 ID 不允许在.wox与单文件形态之间切换交付。全功能插件 (Full-featured Plugin)全功能插件是为复杂应用场景和高性能要求设计的综合插件。它运行在专用宿主进程Python 或 Node.js中通过 WebSocket 与wox.core通信。详细开发指南见全功能插件开发指南完整字段定义见插件规范查询模型见查询模型。特点完整架构通过专用插件宿主进程运行插件目录包含plugin.json与入口文件main.py、index.js或构建产物如dist/index.js。持久运行插件保持加载和运行状态支持跨查询状态管理。丰富 API支持 AI 集成、预览、设置界面、MRU、深度链接、截图能力等高级功能。WebSocket 通信通过 WebSocket 与 Wox 核心进行高效通信。源码 wox.core/plugin/host/host_websocket.go 展示了宿主进程的启动流程Wox 先获取可用 TCP 端口随后启动宿主进程并传入 entry、端口、宿主日志目录与 Wox PID最后建立 WebSocket 连接而 wox.core/plugin/host/host_websocket_plugin.go 中的WebsocketPlugin通过invokeMethod将init、action、formAction、toolbarMsgAction等调用代理到宿主进程。异步支持完全支持异步操作与网络请求。生命周期管理完整的插件初始化、查询和卸载生命周期。用例需要复杂状态管理的应用程序高频查询和实时数据处理具有 AI 集成的智能插件需要自定义设置界面的插件复杂的异步操作和网络请求性能敏感的应用场景商业级插件开发支持语言与 SDKPython使用wox-pluginSDK安装命令uv add wox-plugin源码见 wox.plugin.python/src/wox_plugin。Node.js使用wox-launcher/wox-pluginSDK安装命令pnpm add wox-launcher/wox-plugin源码见 wox.plugin.nodejs。插件命令与能力开关plugin.json中的Runtime取PYTHON或NODEJSEntry指向 Wox 实际执行的文件Features只声明真正需要的能力。常见能力开关包括querySelection接收文本/文件选择查询queryEnv接收活动窗口或浏览器上下文ai使用 Wox 配置好的 AI 能力deepLink注册插件深度链接mru从 Wox 的最近使用记录恢复结果resultPreviewWidthRatio/gridLayout已 deprecated改用QueryResponse.Layout中的对应字段从源码 wox.core/plugin/metadata.go 可以看到Metadata中Features数组的每一项都是{Name, Params}结构管理器通过IsSupportFeature判断能力是否开启并针对debounceIntervalMs、queryEnv如requireActiveWindowName、requireActiveBrowserUrl、mruHashBy等 feature 解析具体参数。这解释了为什么文档强调只打开真正需要的能力——它们会直接影响 Wox 如何路由查询和构建插件上下文。高级能力速览静态 HTML 预览使用webview类型把 HTML 放进 JSON 数据的html字段无需启动 HTTP 服务或写临时文件可选字段包括injectCss、userAgent、cacheDisabled、cacheKey。内联 HTML 没有相对于插件目录的基础 URL资源应内嵌或使用绝对 URL且插入不可信文本前需先做 HTML 转义。结果动态更新action 执行后继续原地更新用GetUpdatableResult/UpdateResult针对当前查询追加或流式推送结果用PushResults。截图 APIScreenshot()返回Success、ScreenshotPath、ErrMsgScreenshotOption支持HideAnnotationToolbar只保留纯粹选区流程与AutoConfirm有效选区完成后立即结束。第三方插件触发截图时悬浮工具栏会自动显示插件自己的图标。选择指南官方文档给出的选型决策如下选择脚本插件当功能相对简单逻辑清晰不需要复杂的状态管理只需要包装一条命令或一次性脚本快速原型设计和个人工具学习 Wox 插件开发选择单文件 SDK 插件当只要一个文件但需要 Wox API需要设置、AI、UpdateResult或 unload callback可以停留在 Python或 CommonJS Node.js并且不需要额外文件选择全功能插件当需要依赖、资源、TypeScript 或多文件需要复杂的业务逻辑高频查询和实时响应商业插件开发此外文档也给出了迁移路径脚本插件复杂度上升后可迁移到全功能插件Python SDKwox-plugin或 Node.js SDKwox-launcher/wox-plugin以获得持久状态、完整 API、设置 UI、AI 集成与自定义预览能力。插件命令 (Plugin Commands)Wox 插件可以拥有提供特定功能的命令。例如wpm插件具有install、remove等用于插件管理的命令。从源码 wox.core/plugin/system/wpm.go 可以看到WPMPlugin的元数据中声明了完整的命令集install— 安装插件uninstall— 卸载插件create— 创建新插件可选择 Python / JavaScript / Bash 脚本模板或 Python/Node.js 单文件 SDK 插件模板dev.list— 列出本地开发插件目录dev.add— 添加本地开发插件目录dev.remove— 移除本地开发插件目录dev.reload— 重载开发插件同时wpm声明了wpm、store、pm、*四个触发关键字且命令对象MetadataCommand定义于 wox.core/plugin/metadata.go还支持Aliases别名与QueryHint查询提示字段UI 会基于这些信息在用户输入时给出命令候选与参数建议。命令机制本身是通用能力任意插件都可以在元数据的Commands数组中声明自己的命令。当用户在查询框输入触发关键字 命令名时Wox 会把查询拆分为TriggerKeyword、Command、Search三段后分发到插件详见查询模型插件据此在query中按命令分支处理逻辑。总结Wox 的三层插件体系呈现出清晰的由轻到重梯度脚本插件用最少的代价换取最快的原型与简单自动化单文件 SDK 插件在不增加文件数量的前提下补齐了完整 Public API全功能插件则以多文件和常驻宿主进程为代价换取最高性能与最全能力。选型时遵循从需求倒推形态的原则即可——先看是否需要状态、依赖、AI 与高级 UI再看愿意维护多少文件就能在三种形态之间做出准确判断。官方文档始终建议让插件的核心路径尽量小而稳只在确实需要时才引入更重的形态。【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考