如何为open-websearch贡献一个新搜索引擎：面向开发者的完整接入教程

MCP 服务AI 应用网页爬虫AI 技能【免费下载链接】open-webSearchMulti-engine MCP server, CLI, and local daemon for agent web search and content retrieval — skill-guided workflows, no API keys.项目地址https://gitcode.com/gh_mirrors/op/open-webSearch点击查看免费下载open-websearch 是一个无需 API Key 的多引擎网页搜索工具同时提供 MCP 服务器、CLI 命令行和本地守护进程三种使用方式。本教程带你完整走一遍为 open-websearch 贡献一个新搜索引擎的全流程从理解架构、编写引擎实现到注册、测试与文档同步让开发者即使是首次参与开源也能顺利提交自己的搜索引擎。1. 先了解项目open-websearch 能做什么 open-websearch 的核心价值是免密钥、多引擎、结构化结果多引擎聚合搜索内置 11 个搜索引擎bing、baidu、duckduckgo、brave、exa、csdn、juejin、startpage、sogou、hackernews、linuxdo三种接入形态MCP Server供 AI 客户端调用、CLI一次性命令、Local Daemon常驻本地 HTTP 服务文章内容抓取支持 CSDN、掘金、GitHub README 及通用网页正文提取结构化返回统一输出title / url / description / source / engine五个字段你贡献的每个新搜索引擎都会自动出现在search工具的可选引擎列表、CLI 参数和本地守护进程的/search接口中所有接入方共享同一套实现。2. 读懂架构一个引擎是如何被集成的 在动手前先理解代码中四个关键接力点。整体链路非常简洁接力点文件作用① 引擎实现src/engines/ 下的独立目录每个引擎一个目录导出searchXxx(query, limit)函数② 执行器注册createRuntime.ts把引擎函数挂到engineMap供调度服务调用③ 引擎白名单searchEngines.tsSUPPORTED_SEARCH_ENGINES列表 名称归一化④ 配置校验config.ts默认引擎类型与validSearchEngines校验列表调度层 searchService.ts 会按引擎数量自动分配条数distributeLimit单个引擎失败只会记录partialFailures不会拖垮其他引擎——所以你的实现要健壮地处理空结果与反爬页面。推荐直接阅读两个成熟范例HTML 抓取型brave.ts —— axios 请求 cheerio 解析 翻页循环结构最典型JSON API 型hackernews.ts —— 调用官方 JSON 接口附带 URL 安全校验与可注入的测试钩子统一的结果类型定义在 SearchResultinterface SearchResult { title: string; url: string; description: string; source: string; engine: string; // 填你的引擎名 }3. 一键搭建开发环境克隆仓库最快步骤 git clone https://gitcode.com/gh_mirrors/op/open-webSearch cd open-webSearch npm install npm run build三步即可克隆仓库、安装依赖、构建产物。构建完成后可以先跑一遍现有搜索确认环境正常npm run search:cli -- open web search --json4. 第一步创建你的引擎目录 ✍️约定俗成的目录结构参考 src/engines/brave/src/engines/你的引擎/ ├── 你的引擎.ts # 核心搜索实现 └── index.ts # 仅一行export { searchXxx } from ./xxx.js;实现时遵循项目约定能少走 90% 的弯路统一走共享请求构建器用 buildAxiosRequestOptions 生成请求配置它已内置代理USE_PROXY/PROXY_URL、TLS、私网拦截与 fake-IP 放行等跨切面能力。不要为单个引擎私自定义代理逻辑。请求头保持克制只带必要 UA 与语言头参考 brave.ts。翻页要能优雅终止循环请求直到凑够limit条但一旦某页解析出 0 条结果就break避免死循环。做好反爬识别检测验证页/风控页搜狗的实现见 sogou.ts命中时返回空结果并给出可读错误而不是抛出半截数据。URL 安全校验解析出的链接必须是公网http/https可复用 urlSafety.ts 中的isPrivateOrLocalHostname。5. 第二步在 3 个文件里注册引擎 这是新引擎生效的关键缺一不可① 引擎白名单 名称归一化—— searchEngines.ts在SUPPORTED_SEARCH_ENGINES数组中加入引擎名如果你的引擎有常见别名大小写、连字符、中文名在normalizeEngineName中补充映射。用户输入My Engine或my-engine都能被正确识别。② 配置校验—— config.ts把引擎名加入validSearchEngines并在defaultSearchEngine类型联合中补上若允许设为默认引擎。这样DEFAULT_SEARCH_ENGINE与ALLOWED_SEARCH_ENGINES环境变量会自动支持你的新引擎。③ 执行器映射—— createRuntime.ts在createDefaultSearchExecutors()中导入并注册import { searchXxx } from ../engines/xxx/index.js; // 在 engineMap 中加一行 xxx: searchXxx,至此MCP 的search工具、CLI 的search命令、本地守护进程的POST /search三端无需任何改动即可暴露你的新引擎——这正是本项目的架构优势。6. 第三步编写测试并本地验证 参考 test-brave.ts 的写法在 src/test/ 下新增test-你的引擎.ts调用你的searchXxx函数打印前若干条结果验证字段完整性。建议覆盖四类场景✅ 正常关键词能返回limit条结果且字段齐全✅limit小于实际结果数时正确截断⚠️ 命中验证页/空结果时不抛异常、不死循环️ 解析出的 URL 均为公网 http(s) 地址验证顺序来自维护者工作流 workflow.mdnpm run build # 先过 TypeScript 类型检查 node build/test/test-你的引擎.js # 再跑引擎专项测试 npm test # 最后跑全量测试7. 第四步同步文档并提交 维护者技能open-websearch-maintainer明确要求加引擎必须同步文档。提交前对照检查清单src/config.ts、src/core/search/searchEngines.ts已更新src/runtime/createRuntime.ts已注册执行器src/test/下新增引擎测试README.md 与 README-zh.md 的引擎列表、环境变量说明已同步若新增测试脚本在 package.json 的 scripts 中补充test:你的引擎入口未改动共享网络层与 MCP 工具契约保持 PR 范围最小提交后仓库的 CI 会自动执行构建与测试。8. 常见坑与最佳实践 引擎名冲突命名用小写无空格风格如sogou而非sou gou别名交给归一化函数处理。限流是常态目标站点有反爬频率限制测试时控制请求频率建议给引擎加保守的超时15s 左右与maxContentLength上限。不要把解析问题扩大成网络层重构只改解析逻辑就只动引擎目录内的文件这是项目维护纪律见 validation.md。JSON API 优先于 HTML 抓取如果目标站点有公开 JSON 接口如 Hacker News 的 Algolia API优先使用稳定性和可测试性都更好且建议像 hackernews.ts 一样预留可注入的 HTTP 钩子便于单测。描述字段要有信息量description 直接影响 AI Agent 的结果选取质量尽量拼入正文摘要、作者、时间等元信息参考 hackernews.ts 的buildDescription做法。9. 项目赞助商 感谢 Swiftproxy 为 open-websearch 多搜索引擎搜索与网页抓取能力提供的网络与代理基础设施支持。完成以上 4 步环境准备 → 引擎实现 → 三处注册 → 测试与文档同步你就为 open-websearch 贡献了一个可被 MCP、CLI、本地守护进程同时调用的新搜索引擎。祝你的 PR 顺利合入 赞分享MCP 服务AI 应用网页爬虫AI 技能【免费下载链接】open-webSearchMulti-engine MCP server, CLI, and local daemon for agent web search and content retrieval — skill-guided workflows, no API keys.项目地址https://gitcode.com/gh_mirrors/op/open-webSearch点击查看免费下载相关推荐img2vec图像聚类实战:PCA降维KMeans自动给图片分类,猫狗一键分离img2vec图像聚类实战:PCA降维KMeans自动给图片分类,猫狗一键分离 img2vec 是一个基于 PyTorch 的开源 Python 库能调用预Sodium开发者入门如何为Sodium贡献代码的完整教程Sodium开发者入门如何为Sodium贡献代码的完整教程 想要为Minecraft最强大的渲染优化模组Sodium贡献代码吗本指南将带你从零开始了解如何图形学游戏开发如何快速搭建Hound代码搜索引擎面向开发者的完整指南如何快速搭建Hound代码搜索引擎面向开发者的完整指南 Hound是一个 极速代码搜索引擎 基于Russ Cox的正则表达式匹配算法构建能够为开发者提供闪搜索引擎开发者工具后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考