wigolo 插件开发实战为 AI Agent 接入自定义搜索引擎与内容提取器【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolowigolo 是一套面向 AI 编码 Agent 的本地优先检索方案通过 MCP 提供搜索、抓取、爬取与研究能力。本文聚焦其插件体系如何用纯 Node 模块为 wigolo 接入自定义搜索引擎内部 Wiki、私有索引、垂直领域引擎和站点级内容提取器修复提取质量差的站点并深入解析插件加载、校验、注册的完整链路与失败隔离机制。读完本文你将掌握从wigolo plugin add到编写完整插件、再到用plugin validate排查问题的全套实战能力。插件体系一览两类插件、一个目录wigolo 从~/.wigolo/plugins目录加载两类插件目录位置可用环境变量WIGOLO_PLUGINS_DIR覆盖搜索搜索引擎search engine加入多引擎搜索调度池与内置引擎并列参与融合、去重与端上重排内容提取器content extractor在通用提取流水线之前获得优先机会把页面转成 Markdown 结构化结果。两类插件都是普通 Node 模块——不需要构建步骤不依赖任何框架一个目录加一个入口文件即可。从配置实现看插件目录的解析位于 src/config.ts优先读取WIGOLO_PLUGINS_DIR若以~开头会展开为主目录否则回退到dataDir/plugins即~/.wigolo/plugins。因此安装插件前确认WIGOLO_PLUGINS_DIR是否被设置就能准确判断实际生效的插件目录。插件管理命令add / list / validate / remove插件管理的 CLI 入口在 src/cli/plugin.ts完整用法如下wigolo plugin add https://github.com/you/your-plugin # clone安装前会弹出信任确认 wigolo plugin list [--json] # 列出已安装插件 wigolo plugin validate [--json] # 校验插件能否正确加载与导出 wigolo plugin remove name # 卸载插件plugin add先确认信任再执行 cloneplugin add会把 git 仓库克隆进插件目录。因为插件是会在 wigolo 进程内运行、且拥有你的凭据与网络访问权限的代码所以命令在 clone 之前必须经过用户确认——只安装你信任或阅读过源码的插件。从 src/cli/plugin.ts 的实现看信任边界被刻意做得非常显眼未传--yes时会先在 stderr 打印安装横幅展示url、解析出的repo名和目标目录target并明确警告克隆的仓库会在每次 wigolo 服务启动时以 Node 代码运行随后从 TTY 读取一行确认Install this plugin? [y/N]只有输入y/yes才继续非交互式CI、管道环境下默认拒绝安装必须显式传--yes才会放行WIGOLO_PLUGIN_AUTO_YES1环境变量是脚本化安装的等价开关clone 使用git clone --depth 1浅克隆超时 60 秒。安装完成后命令会检查目标目录的package.json是否存在、是否有main字段缺任一都会给出 WARNING提示插件可能无法正常加载——这是 add 阶段的第一道体检。plugin list结构化盘点list扫描插件目录读取每个子目录的package.json输出插件名与版本缺失时回退为目录名与unknown。加--json时向 stdout 输出单条 JSON 文档{plugins: [...]}便于脚本消费。plugin validate加载与导出契约校验validate会对每个已安装插件做静态校验package.json是否存在、main字段是否存在且指向的文件真实存在于磁盘。值得注意的是注释明确说明这是lint 而非 load——它刻意不 import 插件import 会执行插件代码因此可以在不运行任意代码的前提下给出快速体检。命令以退出码表达结果全部通过返回 0任一失败返回 1--json模式输出{status: ok|error, plugins: [...]}。plugin remove安全卸载remove会先做名称合法性校验拒绝路径分隔符、..、绝对路径再删除对应目录插件不存在时报错退出。插件包结构package.json 入口模块一个插件就是一个目录其package.json的main指向入口模块{ name: my-wigolo-plugin, version: 1.0.0, main: index.mjs }入口模块导出searchEngine、extractor或两者同时导出。导出会在加载时被校验无效的插件会被报告并跳过绝不会拖垮服务器。加载器 src/plugins/loader.ts 的具体流程是读取并解析package.json缺失或 JSON 解析失败 → 记错误并跳过要求存在main字段用pathToFileURL把入口路径转成file://URL 后await import()——这意味着插件可以用 ESM也可以从 CommonJS 模块导出。加载成功的模块进入validatePluginExports校验。搜索引擎插件把私有索引送进多引擎调度池搜索引擎插件遵循的契约定义在 src/types.tsinterface SearchEngine { name: string; search(query: string, options?: SearchEngineOptions): PromiseRawSearchResult[]; }其中SearchEngineOptionssrc/types.ts携带调度器传入的丰富上下文maxResults结果数上限、timeRange、language、timeoutMs、includeDomains/excludeDomains、fromDate/toDate、categorygeneral/news/code/docs/papers/images、countryISO 3166-1 alpha-2 国家码等。一个尊重这些选项的插件才能与内置引擎在同等条件下公平竞争。返回值RawSearchResultsrc/types.ts的核心字段为title、url、snippet、relevance_score、engine可选的published_dateISO 日期串会在解析成功时驱动freshness_signalimage_url/image_alt会在调用方开启include_images时汇入图片聚合。evidence_score、_score_breakdown等字段则由核心编排器在排序后统一填充插件无需关心。一个完整可用的搜索引擎插件仓库自带的 examples/plugin-search-engine/index.mjs 就是整个插件的全部内容可直接复制作为起点export const searchEngine { name: example-search-engine, async search(query) { return [ { title: Example result for ${query}, url: https://example.com/search-engine-example, snippet: Minimal search engine plugin example., relevance_score: 1, engine: example-search-engine, }, ]; }, };就是这样——一个内部 Wiki、一个私有索引、一个垂直领域引擎用不到 100 行就能进入调度池。插件返回的结果会与内置引擎一起走完全相同的**融合fusion、去重dedup、端上重排on-device reranking**流程并像其他引擎一样出现在engines_used/engine_telemetry字段中。搜索引擎插件的运行时接入在服务器启动阶段src/server.tswigolo 先构造内置引擎BingEngine、DuckDuckGoEngine随后调用loadPlugins()每个通过校验的插件搜索引擎会被推入searchEngines数组参与后续的统一调度。这也解释了为什么插件引擎的返回结果能天然进入engines_used贡献了至少 1 条去重后结果的引擎与engine_telemetry每个被尝试引擎的原始延迟、结果数、结果、dedup_kept——因为它在调度器眼中与内置引擎没有任何区别。内容提取器插件站点级修复的优先通道提取器插件的契约同样定义在 src/types.tsinterface Extractor { name: string; canHandle(url: string, html?: string): boolean; extract(html: string, url: string): ExtractionResult | null; }canHandle(url, html?)决定你的提取器认领哪些 URL——典型场景是公司文档平台的特殊 DOM 结构extract(html, url)返回结构化结果返回null则把页面交还给内置提取器组合defuddle → readability → turndown 的兜底链。插件提取器在通用流水线之前被咨询所以站点专属提取器正是修复某个站点提取质量差的官方手段。ExtractionResultsrc/types.ts要求返回title、markdown、metadata可选description/author/date/language/og_image/canonical_url/keywords等、links、images、extractor类型。额外的site_data字段Reddit、YouTube、Amazon 等站点提取器会填充的每站点结构化 JSON可被后续调用方直接消费而无需再从 Markdown 里反向抓取。提取器插件的调用链从源码看插件提取器与内置站点提取器共享同一注册表服务器启动时src/server.ts对每个插件提取器调用registerExtractor(ext)而 src/extraction/pipeline.ts 的registerExtractor是兼容别名真正写入 src/extraction/v1/site-extractors.ts 的共享列表——因此 v1 路由同样能看到插件注册的提取器。在 v1 提取路由中src/extraction/v1/routed.tstrySiteExtractors用extractors.find((e) e.canHandle(url, originalHtml))找到第一个认领该 URL 的提取器并调用其extract没有匹配则落入 defuddle/readability/turndown 的兜底链。这意味着插件提取器拥有最高优先权canHandle返回true即接管该 URL 的提取任务。加载与校验机制源码解析插件加载的核心实现在 src/plugins/loader.ts整体结构清晰读取配置得到插件目录目录不存在或读取失败时静默返回空结果服务器正常启动遍历目录下每个子目录statSync会跟随符号链接因此符号链接的插件目录同样被支持读取package.json——缺失或解析失败记入错误列表无main字段报no main fieldmain指向的文件不存在报entry point not found通过import()加载入口模块抛错则记入错误并continue用validatePluginExportssrc/plugins/validate.ts校验导出收集所有不满足契约的原因。校验规则本身很直接extractor导出必须是对象且name为非空字符串、canHandle与extract均为函数searchEngine导出同理要求name非空、search为函数两者都不合法时给出neither a valid extractor nor a valid searchEngine的提示。校验通过后进入 src/plugins/registry.ts 的PluginRegistry登记。值得注意的细节是名称去重loader 与 registry 两层都会用Set拦截同名 extractor / search engine重复名称的注册会被警告并跳过避免调度时发生歧义。加载完成后服务器日志会汇总加载了 X 个提取器、Y 个搜索引擎、Z 个错误同时plugin validate会以退出码 1 反映失败状态便于 CI 集成。失败行为端到端防御性设计插件加载是全程防御性的package.json缺失、main错误、import 抛异常、导出无效——每一种失败都会在plugin validate以及服务器日志中产生针对该插件的独立错误信息而其他所有插件与服务器本体继续正常工作。这一设计的证据贯穿全链路加载器对单个插件任何一步失败都continue到下一个绝不中断整体循环src/plugins/loader.ts服务器启动对loadPlugins()的整体调用也包在 try/catch 里即便最坏情况出现也只是记录错误而不会终止启动src/server.tsplugin validate的静态校验甚至刻意不 import 插件把检查插件与执行插件彻底分离让体检过程本身零风险。实战路线从复制示例到生产插件复制起点拷贝 examples/plugin-search-engine/含index.mjs与配套package.json按需改名本地调试把插件目录放入~/.wigolo/plugins或WIGOLO_PLUGINS_DIR指向的目录重启 wigolo观察日志中loaded plugin search engine静态体检wigolo plugin validate确认契约完整非交互环境直接wigolo plugin add git-url --yes走脚本化安装发布与安装推送到 git 仓库后用wigolo plugin add git-url在目标机器安装会再次经过信任确认回归检查仓库的插件测试见 tests/integration/plugins/ 与 tests/unit/plugins/覆盖了加载、校验、注册的典型路径可作为你编写插件时验证行为预期的重要参考。插件目录相关的问题排查可结合 docs/troubleshooting.md插件体系与搜索、提取功能的整体关系见 docs/README.md。【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 wigolo 插件开发实战：为 AI Agent 接入自定义搜索引擎与内容提取器
wigolo 插件开发实战为 AI Agent 接入自定义搜索引擎与内容提取器【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolowigolo 是一套面向 AI 编码 Agent 的本地优先检索方案通过 MCP 提供搜索、抓取、爬取与研究能力。本文聚焦其插件体系如何用纯 Node 模块为 wigolo 接入自定义搜索引擎内部 Wiki、私有索引、垂直领域引擎和站点级内容提取器修复提取质量差的站点并深入解析插件加载、校验、注册的完整链路与失败隔离机制。读完本文你将掌握从wigolo plugin add到编写完整插件、再到用plugin validate排查问题的全套实战能力。插件体系一览两类插件、一个目录wigolo 从~/.wigolo/plugins目录加载两类插件目录位置可用环境变量WIGOLO_PLUGINS_DIR覆盖搜索搜索引擎search engine加入多引擎搜索调度池与内置引擎并列参与融合、去重与端上重排内容提取器content extractor在通用提取流水线之前获得优先机会把页面转成 Markdown 结构化结果。两类插件都是普通 Node 模块——不需要构建步骤不依赖任何框架一个目录加一个入口文件即可。从配置实现看插件目录的解析位于 src/config.ts优先读取WIGOLO_PLUGINS_DIR若以~开头会展开为主目录否则回退到dataDir/plugins即~/.wigolo/plugins。因此安装插件前确认WIGOLO_PLUGINS_DIR是否被设置就能准确判断实际生效的插件目录。插件管理命令add / list / validate / remove插件管理的 CLI 入口在 src/cli/plugin.ts完整用法如下wigolo plugin add https://github.com/you/your-plugin # clone安装前会弹出信任确认 wigolo plugin list [--json] # 列出已安装插件 wigolo plugin validate [--json] # 校验插件能否正确加载与导出 wigolo plugin remove name # 卸载插件plugin add先确认信任再执行 cloneplugin add会把 git 仓库克隆进插件目录。因为插件是会在 wigolo 进程内运行、且拥有你的凭据与网络访问权限的代码所以命令在 clone 之前必须经过用户确认——只安装你信任或阅读过源码的插件。从 src/cli/plugin.ts 的实现看信任边界被刻意做得非常显眼未传--yes时会先在 stderr 打印安装横幅展示url、解析出的repo名和目标目录target并明确警告克隆的仓库会在每次 wigolo 服务启动时以 Node 代码运行随后从 TTY 读取一行确认Install this plugin? [y/N]只有输入y/yes才继续非交互式CI、管道环境下默认拒绝安装必须显式传--yes才会放行WIGOLO_PLUGIN_AUTO_YES1环境变量是脚本化安装的等价开关clone 使用git clone --depth 1浅克隆超时 60 秒。安装完成后命令会检查目标目录的package.json是否存在、是否有main字段缺任一都会给出 WARNING提示插件可能无法正常加载——这是 add 阶段的第一道体检。plugin list结构化盘点list扫描插件目录读取每个子目录的package.json输出插件名与版本缺失时回退为目录名与unknown。加--json时向 stdout 输出单条 JSON 文档{plugins: [...]}便于脚本消费。plugin validate加载与导出契约校验validate会对每个已安装插件做静态校验package.json是否存在、main字段是否存在且指向的文件真实存在于磁盘。值得注意的是注释明确说明这是lint 而非 load——它刻意不 import 插件import 会执行插件代码因此可以在不运行任意代码的前提下给出快速体检。命令以退出码表达结果全部通过返回 0任一失败返回 1--json模式输出{status: ok|error, plugins: [...]}。plugin remove安全卸载remove会先做名称合法性校验拒绝路径分隔符、..、绝对路径再删除对应目录插件不存在时报错退出。插件包结构package.json 入口模块一个插件就是一个目录其package.json的main指向入口模块{ name: my-wigolo-plugin, version: 1.0.0, main: index.mjs }入口模块导出searchEngine、extractor或两者同时导出。导出会在加载时被校验无效的插件会被报告并跳过绝不会拖垮服务器。加载器 src/plugins/loader.ts 的具体流程是读取并解析package.json缺失或 JSON 解析失败 → 记错误并跳过要求存在main字段用pathToFileURL把入口路径转成file://URL 后await import()——这意味着插件可以用 ESM也可以从 CommonJS 模块导出。加载成功的模块进入validatePluginExports校验。搜索引擎插件把私有索引送进多引擎调度池搜索引擎插件遵循的契约定义在 src/types.tsinterface SearchEngine { name: string; search(query: string, options?: SearchEngineOptions): PromiseRawSearchResult[]; }其中SearchEngineOptionssrc/types.ts携带调度器传入的丰富上下文maxResults结果数上限、timeRange、language、timeoutMs、includeDomains/excludeDomains、fromDate/toDate、categorygeneral/news/code/docs/papers/images、countryISO 3166-1 alpha-2 国家码等。一个尊重这些选项的插件才能与内置引擎在同等条件下公平竞争。返回值RawSearchResultsrc/types.ts的核心字段为title、url、snippet、relevance_score、engine可选的published_dateISO 日期串会在解析成功时驱动freshness_signalimage_url/image_alt会在调用方开启include_images时汇入图片聚合。evidence_score、_score_breakdown等字段则由核心编排器在排序后统一填充插件无需关心。一个完整可用的搜索引擎插件仓库自带的 examples/plugin-search-engine/index.mjs 就是整个插件的全部内容可直接复制作为起点export const searchEngine { name: example-search-engine, async search(query) { return [ { title: Example result for ${query}, url: https://example.com/search-engine-example, snippet: Minimal search engine plugin example., relevance_score: 1, engine: example-search-engine, }, ]; }, };就是这样——一个内部 Wiki、一个私有索引、一个垂直领域引擎用不到 100 行就能进入调度池。插件返回的结果会与内置引擎一起走完全相同的**融合fusion、去重dedup、端上重排on-device reranking**流程并像其他引擎一样出现在engines_used/engine_telemetry字段中。搜索引擎插件的运行时接入在服务器启动阶段src/server.tswigolo 先构造内置引擎BingEngine、DuckDuckGoEngine随后调用loadPlugins()每个通过校验的插件搜索引擎会被推入searchEngines数组参与后续的统一调度。这也解释了为什么插件引擎的返回结果能天然进入engines_used贡献了至少 1 条去重后结果的引擎与engine_telemetry每个被尝试引擎的原始延迟、结果数、结果、dedup_kept——因为它在调度器眼中与内置引擎没有任何区别。内容提取器插件站点级修复的优先通道提取器插件的契约同样定义在 src/types.tsinterface Extractor { name: string; canHandle(url: string, html?: string): boolean; extract(html: string, url: string): ExtractionResult | null; }canHandle(url, html?)决定你的提取器认领哪些 URL——典型场景是公司文档平台的特殊 DOM 结构extract(html, url)返回结构化结果返回null则把页面交还给内置提取器组合defuddle → readability → turndown 的兜底链。插件提取器在通用流水线之前被咨询所以站点专属提取器正是修复某个站点提取质量差的官方手段。ExtractionResultsrc/types.ts要求返回title、markdown、metadata可选description/author/date/language/og_image/canonical_url/keywords等、links、images、extractor类型。额外的site_data字段Reddit、YouTube、Amazon 等站点提取器会填充的每站点结构化 JSON可被后续调用方直接消费而无需再从 Markdown 里反向抓取。提取器插件的调用链从源码看插件提取器与内置站点提取器共享同一注册表服务器启动时src/server.ts对每个插件提取器调用registerExtractor(ext)而 src/extraction/pipeline.ts 的registerExtractor是兼容别名真正写入 src/extraction/v1/site-extractors.ts 的共享列表——因此 v1 路由同样能看到插件注册的提取器。在 v1 提取路由中src/extraction/v1/routed.tstrySiteExtractors用extractors.find((e) e.canHandle(url, originalHtml))找到第一个认领该 URL 的提取器并调用其extract没有匹配则落入 defuddle/readability/turndown 的兜底链。这意味着插件提取器拥有最高优先权canHandle返回true即接管该 URL 的提取任务。加载与校验机制源码解析插件加载的核心实现在 src/plugins/loader.ts整体结构清晰读取配置得到插件目录目录不存在或读取失败时静默返回空结果服务器正常启动遍历目录下每个子目录statSync会跟随符号链接因此符号链接的插件目录同样被支持读取package.json——缺失或解析失败记入错误列表无main字段报no main fieldmain指向的文件不存在报entry point not found通过import()加载入口模块抛错则记入错误并continue用validatePluginExportssrc/plugins/validate.ts校验导出收集所有不满足契约的原因。校验规则本身很直接extractor导出必须是对象且name为非空字符串、canHandle与extract均为函数searchEngine导出同理要求name非空、search为函数两者都不合法时给出neither a valid extractor nor a valid searchEngine的提示。校验通过后进入 src/plugins/registry.ts 的PluginRegistry登记。值得注意的细节是名称去重loader 与 registry 两层都会用Set拦截同名 extractor / search engine重复名称的注册会被警告并跳过避免调度时发生歧义。加载完成后服务器日志会汇总加载了 X 个提取器、Y 个搜索引擎、Z 个错误同时plugin validate会以退出码 1 反映失败状态便于 CI 集成。失败行为端到端防御性设计插件加载是全程防御性的package.json缺失、main错误、import 抛异常、导出无效——每一种失败都会在plugin validate以及服务器日志中产生针对该插件的独立错误信息而其他所有插件与服务器本体继续正常工作。这一设计的证据贯穿全链路加载器对单个插件任何一步失败都continue到下一个绝不中断整体循环src/plugins/loader.ts服务器启动对loadPlugins()的整体调用也包在 try/catch 里即便最坏情况出现也只是记录错误而不会终止启动src/server.tsplugin validate的静态校验甚至刻意不 import 插件把检查插件与执行插件彻底分离让体检过程本身零风险。实战路线从复制示例到生产插件复制起点拷贝 examples/plugin-search-engine/含index.mjs与配套package.json按需改名本地调试把插件目录放入~/.wigolo/plugins或WIGOLO_PLUGINS_DIR指向的目录重启 wigolo观察日志中loaded plugin search engine静态体检wigolo plugin validate确认契约完整非交互环境直接wigolo plugin add git-url --yes走脚本化安装发布与安装推送到 git 仓库后用wigolo plugin add git-url在目标机器安装会再次经过信任确认回归检查仓库的插件测试见 tests/integration/plugins/ 与 tests/unit/plugins/覆盖了加载、校验、注册的典型路径可作为你编写插件时验证行为预期的重要参考。插件目录相关的问题排查可结合 docs/troubleshooting.md插件体系与搜索、提取功能的整体关系见 docs/README.md。【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考