企业官网建设流程全解析

wigolo 提取器插件开发指南：3步接入自己的内容解析逻辑

【免费下载链接】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

wigolo 是一个本地优先的 AI 编程代理上网工具，提供搜索、抓取、爬取与研究能力，全程无需 API 密钥、不依赖云端，每次查询成本为 $0。当你常抓的某些网站（公司文档站、内部 Wiki、结构奇特的页面）提取效果不佳时，wigolo 允许你通过提取器插件（extractor plugin）接入自己的内容解析逻辑，用不到 100 行代码让指定 URL 由你的解析器接管。本文带你完成一次完整的实战。

wigolo 提取器插件是什么

wigolo 从~/.wigolo/plugins目录加载两类插件（可用WIGOLO_PLUGINS_DIR环境变量覆盖）：

提取器插件的定位是"站点专属解析器"：内置提取流水线在遇到某个网站提取质量差时，你不需要改 wigolo 源码，只需提供一个插件，它会在通用流水线之前被咨询。插件就是普通的 Node 模块，没有构建步骤、没有框架依赖。

相关设计文档：docs/plugins.md

提取器插件契约的 3 个要素

一个合法的提取器插件必须导出一个extractor对象，契约定义见 src/types.ts：

export const extractor = { name: 'my-docs-extractor', // 1. 唯一名称，重名会被跳过 canHandle(url, html) { /* 2. 判断是否认领该 URL */ }, extract(html, url) { /* 3. 返回结构化结果，或 null 交回内置流水线 */ }, };

三个要素缺一不可，加载时会被 src/plugins/validate.ts 逐项校验：

• name：非空字符串。重复名称会在注册时被 src/plugins/loader.ts 检测并跳过；
• canHandle(url, html)：决定哪些 URL 归你处理，例如只认领https://docs.example.com/*；
• extract(html, url)：返回ExtractionResult对象，返回null表示"我不处理，交回内置提取流水线"。

ExtractionResult的核心字段（完整定义见 src/types.ts）：

{ "title": "页面标题", "markdown": "提取出的正文 Markdown", "metadata": { "description": "可选描述", "author": "可选作者" }, "links": [], "images": [], "extractor": "site-specific" }

💡 小技巧：返回的site_data字段还可以携带站点专属的结构化数据（如价格、帖子分数），调用方无需再从 Markdown 正文里反解析。

编写你的第一个内容解析插件

一个插件就是一个目录，package.json的main指向入口模块。以仓库自带的 examples/plugin-search-engine 为起点，把导出换成extractor即可。

目录结构：

my-docs-extractor/ ├── package.json └── index.mjs

package.json只需三行：

{ "name": "my-docs-extractor", "version": "1.0.0", "main": "index.mjs" }

index.mjs最小可用示例（示意，实际解析逻辑自写）：

export const extractor = { name: 'my-docs-extractor', canHandle(url) { return url.startsWith('https://docs.example.com/'); }, extract(html, url) { const title = html.match(/<title>(.*)<\/title>/)?.[1] ?? url; const body = html.match(/<main>([\s\S]*?)<\/main>/)?.[1] ?? ''; return { title, markdown: body.replace(/<[^>]+>/g, '').trim(), metadata: {}, links: [], images: [], extractor: 'site-specific', }; }, };

3 个命令安装与验证插件

把插件放进插件目录后，用命令行完成信任与验证（详见 docs/plugins.md）：

wigolo plugin add <插件仓库的 git 地址> # 克隆前会提示确认信任 wigolo plugin list [--json] # 查看已装插件 wigolo plugin validate [--json] # 校验导出是否符合契约

⚠️plugin add会要求你确认后才安装——插件代码会运行在你的 wigolo 进程内，拥有你的凭据与网络访问权限，只安装你信任或已读过的代码。validate会逐个加载插件并精确报告不符合契约的原因，例如：

extractor export exists but does not match the Extractor interface (requires: name: string, canHandle: function, extract: function)

插件提取器与内置流水线的协作顺序

理解执行顺序，你才能判断该写canHandle还是该优化extract。wigolo 内置了一批站点提取器（GitHub、Stack Overflow、MDN、Reddit、YouTube、Amazon 等），统一注册在 src/extraction/v1/site-extractors.ts，插件提取器通过注册表并入同一列表，v1 路由 src/extraction/v1/routed.ts 会先让它们跑：

1. 插件/站点提取器先跑：canHandle返回true的提取器拿到首发机会；
2. 返回null即交棒：没处理成功就自动回落内置的 defuddle/readability 通用流水线，页面不会"死"在你的插件里；
3. 失败防御到底：package.json缺失、入口报错、导出非法……都只会让这一个插件被跳过并记录错误，其他插件和服务本身照常工作（见 src/plugins/loader.ts）。

装好后，把 wigolo 接进 Claude Code、Codex 等 AI 编程代理，代理抓取页面时就会走你的解析逻辑：

常见问题与排查清单

排查入口与完整故障说明：docs/troubleshooting.md、docs/configuration.md

小结

• 提取器插件 = 一个目录 +package.json+ 导出extractor的模块，无构建、无框架；
• 契约只有三要素：name/canHandle/extract，返回null自动交回内置流水线；
• 用wigolo plugin add/list/validate三命令完成安装、查看与契约校验；
• 插件在通用流水线之前执行，是"修复某个站点提取效果差"的官方推荐姿势。

至此，你已经掌握了为 wigolo 接入自己内容解析逻辑的完整流程——从契约理解、插件编写到安装验证，全部本地完成、零 API 成本。

【免费下载链接】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