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 SkillsWox 将项目特有的插件开发知识封装为内置 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-creatorwox-plugin-creator是 Wox 插件工作的主技能覆盖以下范围插件脚手架scaffoldingSDK 用法SDK usageplugin.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.mdscripts/下则有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/skillswox.core/util/location.go 中可确认该路径用户配置的本地或远程技能从设置中读取AISkills列表本地目录直接加入根远程 git URL 则先克隆到缓存目录再扫描且同一 URL 只克隆一次。扫描时会跳过.git、node_modules、vendor、build、dist、target等目录。每个技能的 ID 由“来源 名称 slug 路径哈希”生成保证跨会话稳定见 stableSkillId。注册与检索进程级注册表发现结果被写入进程级的SkillRegistrywox.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_skillwox.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与GetSingleFilePluginTemplatesDirectorywox.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 的硬性约定首个版本必须保持 CommonJSmodule.exports.plugin不得import wox-launcher/wox-plugin。选择运行时语言当用户没有明确指定语言时技能要求 Agent 先检测本机环境而非默认选择 Python运行python3 scripts/detect_local_runtime.py缺失python3时用python输出nodejs、python或none脚本无法运行时自行检查版本node --version要求 Node.js 20python3 --version要求 Python 3.10Windows 上还可尝试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: falsePython 设置 API 的辅助构造器有限复杂设置通常需要直接构造PluginSettingDefinitionItem与 value 对象占位符placeholder支持i18n:前缀且永远不会进入查询值或剪贴板。其余主题可继续查阅references/下的settings_patterns.md设置与校验器模式、plugin_i18n.md国际化、icons.md图标、refinements.mdQueryResponse 细化与结构化查询槽等引用文档。发布到 Wox 商店wox-plugin-creator负责“开发与本地打包”正式提交商店请使用wox-plugin-submit2store技能避免职责混淆。注意事项在对话中使用技能是可选的Wox 中的内置副本始终可用不受会话影响当 Agent 处于 Wox 相关工作区并能跟随捆绑的引用文件时技能效果最佳——引用文档与本地模板同源存放路径稳定可循内置技能在 Wox 设置中只读不能被编辑或删除外部 Agent 若需同样能力可从仓库安装同一份技能包。延伸阅读插件开发总览www/docs/development/plugins/overview.md完整插件规范www/docs/development/plugins/specification.md查询模型与 QueryResponsewww/docs/development/plugins/query-model.md脚本插件开发www/docs/development/plugins/script-plugin.md单文件 SDK 插件开发www/docs/development/plugins/single-file-plugin.md完整功能插件示例www/docs/development/plugins/full-featured-plugin.md【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考