企业官网建设流程全解析

• MCP 服务
• AI 应用
• 网页爬虫
• AI 技能

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. 读懂架构：一个引擎是如何被集成的 🔍

在动手前，先理解代码中四个关键"接力点"。整体链路非常简洁：

调度层 searchService.ts 会按引擎数量自动分配条数（distributeLimit），单个引擎失败只会记录partialFailures，不会拖垮其他引擎——所以你的实现要健壮地处理空结果与反爬页面。

推荐直接阅读两个成熟范例：

• HTML 抓取型：brave.ts —— axios 请求 + cheerio 解析 + 翻页循环，结构最典型
• JSON API 型：hackernews.ts —— 调用官方 JSON 接口，附带 URL 安全校验与可注入的测试钩子

统一的结果类型定义在 SearchResult：

interface 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" --json

4. 第一步：创建你的引擎目录 ✍️

约定俗成的目录结构（参考 src/engines/brave/）：

src/engines/<你的引擎>/ ├── <你的引擎>.ts # 核心搜索实现 └── index.ts # 仅一行：export { searchXxx } from './xxx.js';

实现时遵循项目约定，能少走 90% 的弯路：

1. 统一走共享请求构建器：用 buildAxiosRequestOptions 生成请求配置，它已内置代理（USE_PROXY/PROXY_URL）、TLS、私网拦截与 fake-IP 放行等跨切面能力。不要为单个引擎私自定义代理逻辑。
2. 请求头保持克制：只带必要 UA 与语言头，参考 brave.ts。
3. 翻页要能优雅终止：循环请求直到凑够limit条，但一旦某页解析出 0 条结果就break，避免死循环。
4. 做好反爬识别：检测验证页/风控页（搜狗的实现见 sogou.ts），命中时返回空结果并给出可读错误，而不是抛出半截数据。
5. 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.md）：

npm 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. 常见坑与最佳实践 💡

1. 引擎名冲突：命名用小写无空格风格（如sogou而非sou gou），别名交给归一化函数处理。
2. 限流是常态：目标站点有反爬频率限制，测试时控制请求频率；建议给引擎加保守的超时（15s 左右）与maxContentLength上限。
3. 不要把解析问题扩大成网络层重构：只改解析逻辑就只动引擎目录内的文件，这是项目维护纪律（见 validation.md）。
4. JSON API 优先于 HTML 抓取：如果目标站点有公开 JSON 接口（如 Hacker News 的 Algolia API），优先使用，稳定性和可测试性都更好，且建议像 hackernews.ts 一样预留可注入的 HTTP 钩子便于单测。
5. 描述字段要"有信息量"：description 直接影响 AI Agent 的结果选取质量，尽量拼入正文摘要、作者、时间等元信息（参考 hackernews.ts 的buildDescription做法）。

9. 项目赞助商 🙏

感谢 Swiftproxy 为 open-websearch 多搜索引擎搜索与网页抓取能力提供的网络与代理基础设施支持。

完成以上 4 步（环境准备 → 引擎实现 → 三处注册 → 测试与文档同步），你就为 open-websearch 贡献了一个可被 MCP、CLI、本地守护进程同时调用的新搜索引擎。祝你的 PR 顺利合入 🚀

• MCP 服务
• AI 应用
• 网页爬虫
• AI 技能