企业官网建设流程全解析

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、quickjump）
• AI 命令与 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

脚本插件 (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是一个"无常驻进程"的 host：Start()不启动任何后台进程，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: "webview"，data填 JSON 字符串，例如JSON.stringify({ html: "<h1>Hello 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或data）
• open-url：在默认浏览器打开 URL（参数url）
• open-directory：在文件管理器中打开目录（参数path）
• notify：显示通知消息（参数message）
• change-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使用 SDK；Node.js 通过params.API使用能力（第一版固定为 CommonJS，使用module.exports.plugin，不要import/require@wox-launcher/wox-plugin，WoxImage等简单类型用对象字面量）。

与脚本插件的区别

官方文档明确说明：脚本插件不是这个功能的 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 集成的智能插件
• 需要自定义设置界面的插件
• 复杂的异步操作和网络请求
• 性能敏感的应用场景
• 商业级插件开发

支持语言与 SDK

• Python：使用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或NODEJS，Entry指向 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判断能力是否开启，并针对debounce（IntervalMs）、queryEnv（如requireActiveWindowName、requireActiveBrowserUrl）、mru（HashBy）等 feature 解析具体参数。这解释了为什么文档强调"只打开真正需要的能力"——它们会直接影响 Wox 如何路由查询和构建插件上下文。

高级能力速览

• 静态 HTML 预览：使用webview类型，把 HTML 放进 JSON 数据的html字段，无需启动 HTTP 服务或写临时文件；可选字段包括injectCss、userAgent、cacheDisabled、cacheKey。内联 HTML 没有相对于插件目录的基础 URL，资源应内嵌或使用绝对 URL，且插入不可信文本前需先做 HTML 转义。
• 结果动态更新：action 执行后继续原地更新用GetUpdatableResult/UpdateResult；针对当前查询追加或流式推送结果用PushResults。
• 截图 API：Screenshot()返回Success、ScreenshotPath、ErrMsg；ScreenshotOption支持HideAnnotationToolbar（只保留纯粹选区流程）与AutoConfirm（有效选区完成后立即结束）。第三方插件触发截图时悬浮工具栏会自动显示插件自己的图标。

选择指南

官方文档给出的选型决策如下：

选择脚本插件，当：

• 功能相对简单，逻辑清晰
• 不需要复杂的状态管理
• 只需要包装一条命令或一次性脚本
• 快速原型设计和个人工具
• 学习 Wox 插件开发

选择单文件 SDK 插件，当：

• 只要一个文件，但需要 Wox API
• 需要设置、AI、UpdateResult或 unload callback
• 可以停留在 Python，或 CommonJS Node.js，并且不需要额外文件

选择全功能插件，当：

• 需要依赖、资源、TypeScript 或多文件
• 需要复杂的业务逻辑
• 高频查询和实时响应
• 商业插件开发

此外，文档也给出了迁移路径：脚本插件复杂度上升后，可迁移到全功能插件（Python SDKwox-plugin或 Node.js SDK@wox-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