Wox AI Skills 实战指南：用 `wox-plugin-creator` 让 Agent 高效开发插件-二趣网

Wox AI Skills 实战指南：用`wox-plugin-creator`让 Agent 高效开发插件

【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox

本篇指南讲解 Wox 为插件开发内置的 AI Skill 体系，核心聚焦随发行版捆绑、开箱即用的wox-plugin-creator技能：它把 Wox 插件的脚手架、SDK 用法、plugin.json元数据、SettingDefinitions 与校验器、脚本插件与单文件 SDK 插件模板、商店发布规范等工程知识打包成 Agent 可读取的本地指令包。读完本文，你将掌握 Wox AI Skill 的运行时机制（发现、注册、注入与按需加载）、wox-plugin-creator的推荐用法与适用场景，并能在实际 Wox 工作区中让 Agent 快速完成从“一个想法”到“可发布插件”的完整流程。

什么是 Wox AI Skills

Wox 将项目特有的插件开发知识封装为内置 AI Skill，随发行版一起分发。wox-plugin-creator就是 Wox 为插件开发内置的 AI 技能，它在 Wox 设置中始终可用，且不能被编辑或删除；外部 Agent（例如在 IDE 或命令行环境中运行的编码代理）也可以从仓库中安装同一份技能，从而在 Wox 之外复用相同的插件开发知识。

从源码结构看，技能是一套以SKILL.md清单为核心的本地知识包。Wox 的构建脚本通过 wox.core/Makefile 中的sync-ai-skills目标，把仓库 .agents/skills/wox-plugin-creator 整目录复制到resource/ai/skills/wox-plugin-creator，再嵌入发行产物；wox.core/resource/resource.go 会在启动时校验内嵌技能存在并解压到数据目录，缺失时直接提示“run make sync-ai-skills”。

为什么使用它们

Wox Skills 将项目特有的插件知识打包，Agent 不必在每次会话中都从零推断 Wox 约定。对插件开发而言，这意味着：

更快的脚手架搭建：覆盖 Python、Node.js、脚本插件（script plugin）与单文件 SDK 插件
更准确的plugin.json编写
更完善的SettingDefinitions、校验器（validators）、动态设置（dynamic settings）与 i18n 指导
更清晰的 Wox 商店发布指引

在仓库的 .agents/skills/wox-plugin-creator/SKILL.md 中可以看到这一知识打包的粒度：技能描述明确列出其职责边界——“创建、脚手架、实现并打包 Wox 插件（nodejs、python、script-nodejs、script-python、singlefile-python、singlefile-nodejs）”，并约定：若用户想发布到官方商店或查询是否已上架，应优先使用wox-plugin-submit2store技能。也就是说，技能之间有明确分工，wox-plugin-creator只管“造”不管“发”。

推荐技能：wox-plugin-creator

wox-plugin-creator是 Wox 插件工作的主技能，覆盖以下范围：

插件脚手架（scaffolding）
SDK 用法（SDK usage）
plugin.json元数据
设置与校验器模式（settings and validator patterns）
脚本插件模板（script-plugin templates）
单文件 SDK 插件模板（single-file SDK plugin templates）
发布到 Wox 商店

从技能包目录结构看，知识被拆成多个引用文件，便于 Agent 按需读取：references/下有plugin_json_schema.md、settings_patterns.md、plugin_i18n.md、icons.md、refinements.md、scaffold_nodejs.md、scaffold_python.md、sdk_nodejs.md、sdk_python.md、plugin_overview.md；scripts/下则有scaffold_wox_plugin.py、detect_local_runtime.py、search_iconify.py等可执行工具。

何时使用它

当你想让 Agent 协助处理以下任务时，应使用该技能：

创建一个新插件
把一个想法转换成 Wox 插件脚手架
编辑plugin.json
实现设置界面（settings UI）
添加校验器或动态设置
为商店发布准备插件

在 wox.core/plugin/system/wpm_command_test.go 的端到端测试中，可以看到系统对这条技能链路的实际断言：测试文本校验了 WPM 命令输出应包含“My Plugin”“single-file SDK”“SKILL.md”以及wox-plugin-creator、wox-plugin-submit2store两个技能说明，这印证了“技能文件随发行版就位、Agent 可读取”是 Wox 官方测试覆盖的行为。

底层机制：Skill 如何在 Wox 中运转

wox-plugin-creator之所以“开箱即用”，依赖 Wox AI 子系统对本地技能的完整生命周期支持，以下机制均可在源码中验证。

发现：扫描 SKILL.md 清单

Wox 通过 wox.core/ai/skill_discovery.go 的DiscoverSkills扫描已知目录，寻找每个目录下的SKILL.md文件作为技能清单。扫描根由 discoverSkillRoots 决定，包括：

内置技能目录：来自GetAISkillsDirectory()（即数据目录下的ai/skills），wox.core/util/location.go 中可确认该路径；
用户配置的本地或远程技能：从设置中读取AISkills列表，本地目录直接加入根，远程 git URL 则先克隆到缓存目录再扫描，且同一 URL 只克隆一次。

扫描时会跳过.git、node_modules、vendor、build、dist、target等目录。每个技能的 ID 由“来源 + 名称 slug + 路径哈希”生成，保证跨会话稳定（见 stableSkillId）。

注册与检索：进程级注册表

发现结果被写入进程级的SkillRegistry（wox.core/ai/skill_registry.go），提供按 ID 精确获取、按名称查询（忽略大小写）、列出全部/仅启用技能等线程安全操作。聊天消息中持久化的是轻量引用AISkillRef，后续可通过 ID、清单路径或名称回解析到当前注册表（见 wox.core/ai/skill_runtime.go 的ResolveSkillRef）。

注入与按需加载：从清单到模型上下文

Wox 不会一次性把完整技能内容塞进提示词，而是采用“目录 + 按需加载”两级策略：

模型侧提示词中只注入一个精简目录available_skills，每个条目包含 id、name、source、path 与截断后的描述（上限 12000 字符，见 FormatAvailableSkillsPrompt），并明确指示“使用read_skill工具按 id 读取后再遵循技能，不要仅凭这份摘要假设完整指令”；
当模型需要真正执行技能时，调用内置工具read_skill（wox.core/ai/builtintool/read_skill.go），它会读取完整的SKILL.md正文，剥离 YAML front matter 后包装成<skill id=... name=... source=...>块注入当前模型请求（见 FormatSkillInvocation）。

read_skill的参数只有两个：id（优先，来自 available_skills 上下文）和name（精确技能名兜底）；当名称命中多个技能时工具会报错并列出候选 ID，要求改用 id 重试。

前端交互中的技能标记

在 Wox 聊天界面中，技能以{skill:xxx}标签形式呈现，发送给模型前会被 StripSkillTags 剥离，技能内容另行注入，避免标签污染模型输入。

实操：使用 wox-plugin-creator 开发插件

当 Agent 在 Wox 相关工作区中运行并遵循捆绑引用时，wox-plugin-creator的实战价值最大。以下流程来自技能包 .agents/skills/wox-plugin-creator/SKILL.md 的 Quick Start，可直接复用。

快速开始：脚手架命令

技能包内置的scripts/scaffold_wox_plugin.py支持多种插件类型：

# 脚手架一个 Node.js SDK 插件（克隆官方模板仓库） python3 scripts/scaffold_wox_plugin.py --type nodejs --output-dir ./MyPlugin --name "My Plugin" --trigger-keywords my # 脚手架一个 Python SDK 插件（克隆官方模板仓库） python3 scripts/scaffold_wox_plugin.py --type python --output-dir ./MyPlugin --name "My Plugin" --trigger-keywords my # 脚手架一个单文件 SDK 插件（使用本地模板，自动生成插件 id，输出单个文件） # 自动检测本机运行时： python3 scripts/scaffold_wox_plugin.py --type singlefile --output-dir ./Wox.Plugin.Weather --name "Weather" --trigger-keywords weather # 显式指定 Node.js： python3 scripts/scaffold_wox_plugin.py --type singlefile-nodejs --output-dir ./Wox.Plugin.Weather.js --name "Weather" --trigger-keywords weather # 显式指定 Python： python3 scripts/scaffold_wox_plugin.py --type singlefile-python --output-dir ./Wox.Plugin.Weather.py --name "Weather" --trigger-keywords weather # 脚手架一个脚本插件（使用本地模板，自动生成插件 id，输出单个文件） python3 scripts/scaffold_wox_plugin.py --type script --output-dir ./Wox.Plugin.Script.MyScript --name "My Script" --trigger-keywords my

单文件与脚本插件模板在 Wox 中亦有对应目录常量：GetScriptPluginTemplatesDirectory与GetSingleFilePluginTemplatesDirectory（wox.core/util/location.go），两者都位于ai/skills/wox-plugin-creator/assets/下，与技能包同源。

选择插件类型

技能对三种插件形态给出了清晰的取舍建议：

脚本插件（Script plugin）：一次性 shell/命令封装，Wox 每次查询都通过 stdin/stdout JSON-RPC 启动一个进程，公开 API 有限；脚本插件不使用plugin.json，而是在脚本头部注释中内嵌 JSON 元数据块。
单文件 SDK 插件（Single-file SDK plugin）：单个.py或 CommonJS.js文件，拥有完整 Public API，加载进现有的 Python/Node 运行时宿主，无需为每次查询启动额外进程，保存即重载；需要 Wox 2.4.2+，且头部MinWoxVersion必须为"2.4.2"。
SDK 插件（.wox包）：多文件包，可带依赖、资源、TypeScript 与plugin.json。

另有一条 Node.js 的硬性约定：首个版本必须保持 CommonJS（module.exports.plugin），不得import @wox-launcher/wox-plugin。

选择运行时语言

当用户没有明确指定语言时，技能要求 Agent 先检测本机环境而非默认选择 Python：

运行python3 scripts/detect_local_runtime.py（缺失python3时用python），输出nodejs、python或none；
脚本无法运行时，自行检查版本：node --version要求 Node.js 20+，python3 --version要求 Python 3.10+（Windows 上还可尝试py -3 --version、python --version）；
决策规则：只有一个运行时达标就用它；两者都达标优先 Node.js；都不达标则询问用户。

编辑 plugin.json 与设置模式

技能对元数据与设置编写有强约束：

编写plugin.json、SettingDefinitions、QueryRequirements、校验器、动态设置与特性开关时，先读references/plugin_json_schema.md；
编写SettingDefinitions时，必须先判断每个设置是否平台相关再交付。Wox 云同步会跨设备复制普通插件设置，因此本地路径、可执行文件路径、shell 命令、热键、系统集成、浏览器配置、应用路径等应设置IsPlatformSpecific: true；账号 ID、API 密钥、远程服务主机、跨平台用户偏好则应保持IsPlatformSpecific: false；
Python 设置 API 的辅助构造器有限，复杂设置通常需要直接构造PluginSettingDefinitionItem与 value 对象；
占位符（placeholder）支持i18n:前缀，且永远不会进入查询值或剪贴板。

其余主题可继续查阅references/下的settings_patterns.md（设置与校验器模式）、plugin_i18n.md（国际化）、icons.md（图标）、refinements.md（QueryResponse 细化与结构化查询槽）等引用文档。

发布到 Wox 商店

wox-plugin-creator负责“开发与本地打包”，正式提交商店请使用wox-plugin-submit2store技能，避免职责混淆。

注意事项

在对话中使用技能是可选的，Wox 中的内置副本始终可用，不受会话影响；
当 Agent 处于 Wox 相关工作区并能跟随捆绑的引用文件时，技能效果最佳——引用文档与本地模板同源存放，路径稳定可循；
内置技能在 Wox 设置中只读，不能被编辑或删除；外部 Agent 若需同样能力，可从仓库安装同一份技能包。

企业官网建设流程全解析