my-websearch

---

**一个服务，四种用法：**通过 MCP 连接 AI 客户端、运行一次性 CLI 查询、保持本地守护进程运行，或在正式使用前运行内置诊断。

快速跳转：快速开始 · MCP 工具 · CLI · 配置 · 诊断 · 开发

✨ 功能特性

my-websearch 是一款专为 AI 编码 Agent（Claude Desktop、Cursor、Cherry Studio、Windsurf、Cline、ZCode 等）打造的全栈搜索与技术文档引擎。开箱即用，适配多种主流 AI 客户端：

• 🌐 16 个引擎的联邦搜索与智能路由
  聚合国内直连引擎（Bing、Baidu、CSDN、Juejin、Sogou）、全球引擎（DuckDuckGo、Brave、Startpage、Yahoo、Exa、Bing News）以及专业开发者平台（GitHub、StackOverflow、Hacker News、arXiv）。支持自动语言感知路由（auto）、并行执行多个查询（queries: string[]）、URL 去重，以及自动逐级回退的 minResults。当 DuckDuckGo 不可用时，Yahoo 会自动从回退池加入英文首选组。
• ⚡ 原生 Web 协议与工作量证明求解器（零浏览器快速通道）
  基于 wreq-js 构建，支持原生现代 TLS/HTTP2 握手模拟和持久会话 Cookie。内置纯 JS/Rust 求解器，可处理 Startpage 的 Anubis SHA-256 PoW 挑战以及 DuckDuckGo 的 d.js（isJsaChallenge）HTML5/算术挑战，无需启动 400MB 的浏览器，即可在毫秒内解析结构化挑战响应。请求栈因引擎而异：DuckDuckGo 必须通过 GET 使用 wreq Chrome 配置（axios POST 会收到 HTTP 202 挑战响应）；而 Brave 则有意使用普通 HTTP/1.1（axios），因为 CloudFront 会对 HTTP/2 模拟返回 429——请勿将两者统一。注意：DuckDuckGo 页面级的 HTTP 202 异常 CAPTCHA（“选择所有包含鸭子的方块”）属于人工验证，我们有意不予绕过，并将其报告为 bot_challenge。支持解析 Sogou 重定向链接、Baidu Location 和 Bing Base64 链接中的真实 URL。
• 📄 高纯度 Markdown 文章提取与专用站点净化器
  结合 Mozilla Readability 与智能页面噪声清理。针对 WeChat Official Accounts（mp.weixin.qq.com）、StackOverflow 问题及已采纳答案提供专用净化规则，并对 CSDN 和 Juejin 进行透明的内部路由。移除 <nav>、<aside>、<footer> 和面包屑，同时忠实保留文章标题、代码块和 GFM 表格。支持无缝分页（startIndex），并提供三种节省 Token 的模式：按 BM25 相关性排序的 focus、通过 CSS 选择器提取为 JSON（无需大模型）的 extract，以及带编号引用的 citations。
• 📚 统一的 Context7 库文档查询（queryDocs）
  可直接使用自然语言包名（例如 "next.js"、"vue"）或 Context7 ID 查询官方文档，无需单独执行解析步骤。包含自动候选项排序、猜测错误时自动修复 404，以及相关替代项发现功能。
• 🐙 扩展的 GitHub / Gitee 资源获取器
  fetchGithubContent（原名 fetchGithubReadme）同时支持 GitHub 和 Gitee：仓库 README、任意源文件（/blob/...，支持使用 lines/#L120-L180 切片）、目录树（/tree/...）、完整的 Issue / PR 讨论、提交（/commit/<sha>）、比较视图（/compare/a...b）和发布内容（/releases、/releases/tag/<tag>）。
• 🌏 零配置网络检测与 Fake-IP 就绪
  自动检测操作系统代理（Windows Registry / macOS scutil / Linux env）。自动通过代理路由海外引擎，同时让国内引擎通过高速直连线路访问。预先将 198.18.0.0/15 加入白名单，以兼容 TUN / Fake-IP，同时严格执行 SSRF 安全边界。 默认支持不使用代理：在中国大陆以外的地区，保持 PROXY_URL 未设置，即可直接查询所有引擎——使用此服务无需 Clash/v2ray。
• 🔌 灵活多样的部署模式
  可无缝用于 MCP STDIO（Claude Desktop/Cursor）、Streamable HTTP / SSE（Cherry Studio/远程客户端）、CLI 单次命令，以及支持连接池复用和 Prometheus /metrics 监控的本地 HTTP 守护进程。

---

🌍 16 个搜索引擎

引擎	中国大陆连接方式	API 密钥	核心技术	最适合的场景
bing	🇨🇳 直连	无	Chrome TLS 模拟 + Base64 真实 URL 解析 + 隐身回退	通用技术搜索、中英文混合查询
bing-news	🌐 在中国使用代理	无	Bing News RSS + pubDate 24 小时筛选 + apiclick.aspx?url= 解码；直连可能 302 跳转到 HTML 页面，因此默认可使用代理；可选垂直搜索引擎	突发新闻、最近 24 小时的动态
baidu	🇨🇳 直连	无	并发解析 Location 重定向 + 挑战检测	中文新闻、文档、国内论坛
csdn	🇨🇳 直连	无	WAF Cookie jar 持久化 + 空响应自动重试	中文错误日志、调试教程
juejin	🇨🇳 直连	无	直接查询官方 API，获取整洁的长文	现代前端/后端技术博客
sogou	🇨🇳 直连	无	桌面版与移动版双重解析 + 重定向链接解码 + 广告移除	微信生态链接与长尾查询
duckduckgo	🌐 在中国使用代理	无	使用 wreq Chrome 配置文件向 HTML 端点发起 GET 请求（仅 axios 回退路径会遇到 202 异常验证码）；保留 d.js 求解器，用于预加载回退	英文技术搜索与开源讨论
startpage	🌐 在中国使用代理	无	多工作线程 Anubis SHA-256 PoW 求解器（难度 ≤ 6）+ Cookie 会话（无需浏览器）	由 Google 提供支持的高隐私搜索结果
yahoo	🌐 在中国使用代理	无	SSR HTML + 首页 Cookie 预热 + RU= 重定向解码；英文回退池（DuckDuckGo 不稳定时自动替换）	稳定的 Bing 索引英文回退
brave	🌐 在中国使用代理	无	纯 HTTP/1.1（axios）请求路径（wreq/HTTP2 模拟会收到 CloudFront 返回的 429）+ 严格移除赞助广告	独立英文索引与技术博客
exa	🌐 优先使用代理	可选免费密钥	官方语义搜索 API（未设置密钥时跳过）；直连也可用，但实测代理约需 0.77 秒，直连约需 1.17 秒	语义相似度、AI 研究与论文
github	🌐 直连 API	无	官方 GitHub Search REST API + 所有者/仓库精确匹配快速路径（问题与仓库）	GitHub 问题、错误报告、仓库及精确仓库查询
stackoverflow	🌐 直连 API	无	官方 StackExchange 2.3 API，并解码 HTML 实体	开发者故障排查、堆栈跟踪与解答
hackernews	🌐 直连 API	无	Algolia HN Search API，提供评分、评论与作者元数据	技术讨论、初创公司发布与工程新闻
arxiv	🌐 直连 API	无	解析标题、作者与摘要的官方 arXiv Atom XML API	科学论文、机器学习与 AI 研究
code	🌐 在中国使用代理	无	通过 grep.app API 搜索全球 GitHub 代码，并提供仓库、路径与精确行号	源代码实现、API 使用模式

版本说明：此 README 与当前源代码树（1.3.10）保持同步。Yahoo、Bing News、DDG wreq-GET 路径、Brave HTTP/1.1 路径和 raw-CDP 浏览器回退均随 1.3.10 发布；npm 最新版本可能要等到软件包发布后才会更新。

---

🛠️ 4 个核心 MCP 工具（精简且节省 Token）

💡 Token 预算与精简：所有工具描述严格控制在 250 个字符以内（描述字符总数 ≤ 1000）。详细的路由指南交由 McpServer({ instructions }) 处理，大幅降低大模型上下文占用。

工具名称	用途	主要特点
search	联合搜索网页与代码（16 个引擎）	支持并行查询、timeRange: day|week|month|year 日期筛选、site: string[] 筛选、fetchTop 预览注入、code 引擎（grep.app）；显式指定 engines 时，minResults 默认为 0（不进行无约束级联）；失败时返回内联 diagnostics
fetchWebContent	网页内容提取、Markdown 与透明 PDF 解析	一站式内容提取器：内置磁盘级 Markdown 缓存（Node 22 node:sqlite / 分区 JSON 回退方案，200MB LRU，cache: default|reload）；透明 PDF 解析（最多 20MB / 50 页，[page N] 标签，可检测扫描文档）；分页与 focus 关键词定位（默认使用 bm25 按相关性排序内容块，window 使用旧版固定窗口）；使用 selector 将提取范围限定到 CSS 子树（遇到错误时会报错，不会静默返回整个页面）；使用 extract 提取 CSS 选择器 JSON，无需大模型；使用 citations 添加编号引用；使用 retainLinks 移除 URL（索引页减少 50%）
fetchGithubContent	全面的 GitHub / Gitee 内容读取器	获取 README、单个源文件（/blob/<ref>/<path>，可选 lines/#L120-L180 切片，最多 400 行）、目录树（/tree/）、Issue / PR 讨论、提交（/commit/<sha>）、比较（/compare/a...b，限制补丁内容并过滤锁文件）和版本发布（/releases[/tag/<tag>]）；ref 可以是分支、标签或提交；通过 API 支持 Gitee（可选 GITEE_TOKEN）；返回 warnings
queryDocs	一站式官方库文档查询	解析库名称或 Context7 ID；可选的 version 固定 Context7/npm/PyPI 版本；24 小时本地缓存（cache: reload 可绕过缓存）；回退链为 npm → PyPI → crates.io → Go 模块代理 → GitHub README；返回 source、confidence 和 warnings

💡 向后兼容：旧版 fetchCsdnArticle 和 fetchJuejinArticle 会自动路由到 fetchWebContent；旧版 resolveLibraryId 已合并到 queryDocs（后者接受 library 名称或旧版 libraryId 别名）。已移除独立的旧版工具——REGISTER_LEGACY_ARTICLE_TOOLS 开关已取消，因为保留三个未注册的处理程序仍会白白占用工具描述预算。

---

🚀 快速开始

1. 使用 NPX 运行（零配置）

无需安装：

npx -y my-websearch@latest

💡 自动发现代理：服务会自动检测操作系统的代理设置。如果本地代理环境处于活动状态，海外引擎会自动使用代理，而国内引擎仍通过快速直连线路访问。198.18.0.0/15 已默认列入 Fake-IP 环境白名单。

2. 在 AI 客户端中配置

🔹 自动配置（推荐）

init 会检测已安装的 MCP 客户端，将服务条目写入其配置文件，并保留 .bak 备份：

npx -y my-websearch@latest init                      # auto-detect and write
npx -y my-websearch@latest init --dry-run            # preview the diff, write nothing
npx -y my-websearch@latest init --client cursor,code # target specific clients

开箱即支持：Claude Desktop、Cursor 和 VS Code（工作区 .vscode/mcp.json）。除非传入 --force，否则不会覆盖现有条目；损坏的配置文件会保持原样；在 Windows 上会自动为你写入 cmd /c npx。重启客户端，然后使用 my-websearch doctor 验证。

🔹 手动配置

Claude Desktop / Cursor / Windsurf / Cline（STDIO 模式）

将以下内容添加到 MCP 设置文件中：

{
  "mcpServers": {
    "my-websearch": {
      "command": "npx",
      "args": ["-y", "my-websearch@latest"],
      "env": {
        "MODE": "stdio"
      }
    }
  }
}

（对于 Windows：init 会自动处理。手动配置时，如果 npx 不在系统路径中，请将 command 设为 cmd，并将 args 设为 ["/c", "npx", "-y", "my-websearch@latest"]）

🔹 Cherry Studio（流式 HTTP 模式）

在终端中使用 npx my-websearch@latest 启动服务（默认端口为 3211），然后进行配置：

{
  "mcpServers": {
    "web-search": {
      "name": "MyWebSearch",
      "type": "streamableHttp",
      "baseUrl": "http://localhost:3211/mcp"
    }
  }
}

---

💻 CLI 与本地守护进程

my-websearch 可直接在终端中用作独立 CLI 工具或持久守护进程。在自动化场景中使用 --json，除非明确需要远程访问，否则请将守护进程保持在 127.0.0.1：

# Global install
npm install -g my-websearch

# Detect installed MCP clients and write their config (--dry-run to preview)
my-websearch init

# Start persistent local HTTP daemon (port 3210 by default)
my-websearch serve

# One-shot terminal search (reuses running daemon automatically)
my-websearch search "Model Context Protocol best practices" --limit 5 --min-results 5 --json

# Only results published within the last week (day|week|month|year)
my-websearch search "typescript 5.9 release" --time-range week --json

# Extract web page as clean Markdown
my-websearch fetch-web "https://blog.vuejs.org/posts/vue-3-5" --max-chars 15000 --json

# View daemon status and Prometheus metrics (/health, /status, /metrics)
my-websearch status --json

# Clear in-memory search cache
my-websearch cache-clear

---

🩺 诊断

排查代理、浏览器或引擎问题之前，请先使用内置的 doctor 命令：

# Local configuration and browser checks
my-websearch doctor

# Real proxy/engine probes (may contact upstream services)
my-websearch doctor --network

# Limit network probes to selected engines
my-websearch doctor --network --engine bing,duckduckgo --json

# Reset and clear cached engine circuit breaker / health state
my-websearch doctor --reset-health

报告会分别列出配置、代理 TCP 可达性、HTTP 可达性、应用解析、浏览器启动和挑战验证状态。网络模式会发起真实请求，不应将其用作高频健康检查。

🌐 代理故障排查与上游速率限制

配置或诊断代理连接时，请留意以下常见边缘情况：

1. 明明设置了 proxy.url，启动日志却显示 🌐 Proxy: disabled？
   • 检查 useProxy 标志：在 ~/.my-websearch/config.json 中，设置 "useProxy": false 会优先生效，并且明确覆盖并禁用 url（相当于设置 PROXY_URL='false'）。将其改为 "useProxy": true，或直接省略此字段（提供有效的 url 会自动启用代理）。
   • 系统代理会自动检测：未配置显式代理时，操作系统的系统代理（Windows 注册表 / macOS scutil / HTTPS_PROXY）会用于海外引擎和通用抓取——仅仅因为代理客户端正在运行，并不意味着你需要设置 PROXY_URL。如果检测失败，或你想固定使用某个代理，请设置 PROXY_URL（例如 http://127.0.0.1:7897）。
   • 优先使用 ~/.my-websearch/config.json，而非客户端 env：将 proxy.url 和 API 密钥放入配置文件。某些 MCP 客户端（例如 WorkBuddy）会根据 command + args + env key names + cwd 对服务进行指纹识别，因此添加 PROXY_URL 环境变量会改变信任指纹，服务可能会悄然从会话中消失。配置文件中的设置会在启动时读取，可避免此问题。
   • 代理应配置在哪里（错误消息曾只写“支持 MCP 客户端配置”，含义不明确）：

     位置	适用情况
     ~/.my-websearch/config.json → "proxy": { "url": "http://127.0.0.1:7897" }	推荐。 适用于所有客户端（CLI、守护进程、MCP），且不会改变客户端信任指纹。
     MCP 客户端 env → PROXY_URL	针对单个客户端的覆盖设置。重启客户端；某些客户端会将环境变量键纳入信任指纹。
     代理客户端的“系统代理”开关	无需任何配置。自 1.3.8 起，系统代理会自动用于海外引擎和通用抓取。

2. 代理可用，但海外引擎仍然失败或超时？（按引擎诊断，而非配置错误）
   • DuckDuckGo 返回 HTTP 202 / challenge：202 响应正文是 DDG 的异常验证码（人工验证），而非简单的 IP 限流；d.js 算术求解器无法绕过它。该引擎首先使用 wreq Chrome 配置文件 GET 请求 HTML 端点，即使 axios POST 路径遇到 202 challenge，通常也会返回 200。因此，现在只有在该路径失败并使用 axios 回退方案时才会出现 202。如果仍看到 202，请确认构建版本包含 wreq GET 路径（1.3.8 及更早版本不包含），然后重试或检查代理是否已连接。DDG 仍是尽力而为：同一出口仍可能间歇性遇到 challenge，因此不要将其视为 SLA；如需稳定性，请使用 Bing/Startpage，或配置 BRAVE_API_KEY/EXA_API_KEY。注意：不支持 SEARCH_MODE=playwright:duckduckgo（DDG 没有浏览器渲染路径），因此会回退到 HTTP。
   • Bing 返回 HTTP 200，但结果数为 0：wreq 模拟路径现在会在解析到空页面时自动回退到 axios SERP 路径。如果两条路径都没有结果，则该查询/IP 可能已被限流。
   • Brave 返回 HTTP 429 Too Many Requests：CloudFront 会在持续数分钟的时间段内限制出口 IP。此情况并非永久性——冷却后发出的请求可以返回 200（已验证：同一节点先返回 429，之后连续 6 次均返回 200），但突发请求会再次触发限流。在同一节点上的测量结果：wreq（HTTP/2 Chrome 指纹）→ 429，axios/curl（HTTP/1.1）→ 200——因此当前 main 特意使用 axios。如需稳定的路径，请设置 BRAVE_API_KEY（官方 API，免费层级），以完全跳过 WAF。
   • Startpage 超时或 Anubis PoW 难度飙升：现在会使用最多 4 个工作线程，在行内求解难度为 6 的 PoW（约 3–12 秒）；高于 6 则跳过。Pass-challenge 套接字错误 / 暂时性 5xx 会自动重试。
   • 💡 解决方法：这些是上游反机器人/限流行为，并非 MCP 配置损坏。请按引擎分别处理：DDG 202 → 升级/重试（使用 wreq GET 路径；在 auto 模式下，回退池也会用 Yahoo 替换状态不佳的 DDG）；Brave 429 → 等待数分钟的限流时段结束，或设置 BRAVE_API_KEY；Bing 结果为 0 → 重试或调整查询；Startpage PoW → 重试。只有在引擎专属处理步骤失败后才切换出口 IP。作为最后手段，可使用 engines: ["bing", "baidu"]，或配置官方密钥（BRAVE_API_KEY / EXA_API_KEY）以获得 SLA 路径。

🔐 安全模型（公开服务前请阅读）

默认设置作为一个软件包是安全的，而且每项设置都很重要：

默认设置	保护内容
绑定到 127.0.0.1	机器外部无法访问该端口
无身份验证	仅在绑定到回环地址时可接受
Host 标头验证	阻止同一机器上的浏览器发起 DNS 重绑定攻击
禁用 CORS	禁止跨源浏览器访问

单独放宽其中一项而不调整其他设置，会在不提示的情况下移除保护：

• HOST=0.0.0.0（Docker）→ Host 允许列表会自动跟随绑定地址；如果还使用公共域名，请通过 OPEN_WEBSEARCH_ALLOWED_HOSTS 添加（以逗号分隔）。
• 向公共互联网公开 → 将服务置于带身份验证的反向代理（或 SSH 隧道）后面。守护进程绑定到非回环地址时会打印警告。
• MCP 会话 ID 是标识符，不是凭据——任何能够访问该端口的人都可以恢复会话。
• FETCH_WEB_INSECURE_TLS=true 会禁用对用户提供的 URL的证书验证；仅在可信网络中启用。
• 首次运行时，应用会将其在 ~/.gemini/config/mcp_config.json / ~/.workbuddy/mcp.json 中找到的 API 密钥复制到 ~/.my-websearch/config.json（模式 0600）。运行 my-websearch doctor 查看每个密钥的来源；设置 MYWEBSEARCH_NO_AUTO_BOOTSTRAP=1 可禁用复制操作。

⚙️ 配置与环境变量

全局配置（~/.my-websearch/config.json）

要在所有 MCP 客户端之间共享设置，避免重复配置：

{
  "apiKeys": {
    "context7": "ctx7sk-...",
    "exa": "..."
  },
  "proxy": {
    "url": "http://127.0.0.1:7897",
    "useProxy": true,
    "engines": ["duckduckgo", "exa", "brave", "startpage"]
  }
}

⚠️ 关于 useProxy 的说明：配置 "url" 时，会自动启用代理。将 "useProxy": false 会显式覆盖并禁用 url。如果要启用代理，请设置 "useProxy": true，或完全省略此字段。

📋 环境变量完整参考

可通过全局配置文件（~/.my-websearch/config.json）、本地 .env 或系统环境变量进行设置：

优先级（从高到低）：进程环境变量 → 项目 .env → 项目 .my-websearch.json → ~/.my-websearch/config.json → 内置默认值。

0. 🖥️ 服务与运行时

变量	默认值	允许的值／说明
MODE	both	both／http／stdio。http 会启用 Streamable HTTP + SSE。
HOST / OPEN_WEBSEARCH_HOST	127.0.0.1	MCP HTTP 绑定地址。绑定到非环回地址时，也会将该主机注册到 Host 允许列表，并显示无身份验证警告。
PORT	3211	MCP HTTP 端口
OPEN_WEBSEARCH_ALLOWED_HOSTS	空	额外的 Host 标头允许列表条目（以逗号分隔）；通过公共域名／反向代理提供服务时需要设置
OPEN_WEBSEARCH_DAEMON_HOST / OPEN_WEBSEARCH_DAEMON_PORT	127.0.0.1 / 3210	本地 REST 守护进程绑定地址（无身份验证：请将其保留在环回地址上）
METRICS_ENABLED	false	启用进程内计数器和守护进程的 /metrics 端点
FETCH_WEB_DEADLINE_MS	45000	一次 fetchWebContent 调用的硬截止时间（合并计算 Cookie、浏览器和重试耗时）
GITHUB_CONTENT_CDN_FIRST	false	对README 和源文件优先使用 jsDelivr，而非 raw.githubusercontent.com（仅限公共仓库）。旧别名 GITHUB_README_CDN_FIRST 仍可使用。
GITHUB_CONTENT_BUDGET_MS	12000（CDN 优先时为 6000）	一次 fetchGithubContent 调用的总时间预算；每次尝试的超时时间上限为 4.5 秒。
BING_PLAYWRIGHT_BUDGET_MS	6000	为兼容性保留的旧名称：Bing 浏览器回退的时间预算（现在由原始 CDP 提供支持）；超出后保留 HTTP 结果
MYWEBSEARCH_NO_AUTO_BOOTSTRAP	未设置	设置为 1，可阻止首次运行时从其他应用的 MCP 配置中复制 API 密钥

1. 🔍 搜索与路由编排

变量	默认值	允许的值 / 说明
DEFAULT_SEARCH_ENGINE	auto	默认引擎：auto（智能查询路由：中文使用 baidu,sogou，英文／其他语言使用 bing,duckduckgo）。支持全部 16 个引擎：auto、bing、bing-news、baidu、sogou、duckduckgo、brave、csdn、juejin、startpage、yahoo、exa、github、stackoverflow、hackernews、arxiv、code（可将垂直领域的开发者引擎配置为默认引擎，但建议将 auto 或通用网页搜索引擎设为全局默认值）
ALLOWED_SEARCH_ENGINES	all	以逗号分隔的允许使用的搜索引擎白名单（例如 bing,baidu,duckduckgo）
BING_BASE_URL	https://cn.bing.com/search	Bing 查询的基础 URL。海外用户或反向代理节点可设置为 https://www.bing.com/search（支持旧别名 OPEN_WEBSEARCH_BING_HOST）
DEFAULT_MIN_RESULTS	5	级联阈值：可用结果少于此值时触发备用引擎
DEFAULT_SEARCH_LIMIT	10	工具调用未明确指定时的默认结果数量上限（最多 50 条）
SEARCH_DEADLINE_MS	30000	多引擎搜索执行的全局硬性截止时间（毫秒）
SEARCH_FUSION	legacy	结果融合模式：legacy（引擎命中数 + 到达顺序）或 rrf（基于各引擎排名的 Reciprocal Rank Fusion，也会替换重排中的位置／共识项）。在有更大规模的评估结果之前，RRF 默认不启用。
SEARCH_FUSION_RRF_K	20	RRF 常数 k；值越低，排名差异的影响越大。仅在 SEARCH_FUSION=rrf 时使用。
ENGINE_CIRCUIT_BASE_COOLDOWN_MS	30000	引擎的首次熔断冷却时间（429 / 202 / bot_challenge）。重复失败时采用指数退避（30 秒 → 60 秒 → 120 秒……）。
ENGINE_CIRCUIT_MAX_COOLDOWN_MS	300000	熔断指数退避的上限（默认 5 分钟）。
SEARCH_AUTHORITY_DOMAINS	empty	用于结果重排的额外权威域名白名单（以逗号分隔，追加到内置列表）
SEARCH_MODE	auto	搜索模式和浏览器策略。支持单一模式、每种模式使用多个引擎，以及多种模式的复合组合： • 全局模式：auto（默认回退模式）、request/none（纯 HTTP）、playwright（强制使用浏览器；旧版值名称，现在由 CDP 提供支持） • 单一模式，多个引擎：playwright:bing,startpage、auto:bing,startpage、bing,startpage • 多种模式复合组合：playwright:bing;auto:startpage（bing 强制使用浏览器，startpage 使用 auto 回退）、auto;request:startpage（全局使用 auto，但 startpage 使用纯 HTTP）
AUTO_ROUTE_EN_ENGINES	bing,duckduckgo	默认英文自动路由使用的引擎，以逗号分隔
AUTO_ROUTE_ZH_ENGINES	baidu,sogou	默认中文自动路由使用的引擎，以逗号分隔

2. 🌐 代理与网络安全

变量	默认值	允许的值 / 说明
PROXY_URL	空（关闭）	统一的上游代理配置（合并了之前的 USE_PROXY 和 PROXY_ENGINES）。TUN 模式下无需设置。 • 默认代理：传入空的 PROXY_URL="" 或 PROXY_URL=true，即可启用默认代理 http://127.0.0.1:7897（常见的本地代理端口包括 7897、7890、10809；海外引擎使用代理，国内引擎保持直连） • 自定义地址：PROXY_URL=http://127.0.0.1:10809 • 自定义引擎：PROXY_URL="http://127.0.0.1:7897;duckduckgo,brave"，或指定所有引擎 PROXY_URL=";all"
FAKE_IP_CIDRS	198.18.0.0/15	Fake-IP / TUN 模式的白名单 CIDR，用于避免 SSRF 误拦截
IMPERSONATE_BROWSER	chrome_149	wreq-js 浏览器 TLS/H2 指纹配置（例如 chrome_149、safari_18）
IMPERSONATE_OS	windows	指纹模拟使用的操作系统平台（windows、macos、linux）
BING_IMPERSONATE	true	为 Bing HTTP 模式启用 Chrome TLS 模拟（连续出现空结果后会自动触发熔断器）
ANUBIS_MAX_POW_DIFFICULTY	6	Startpage Anubis PoW 求解器的最大难度阈值；超过此阈值时跳过或回退
DIRECT_FIRST_PROBE_TIMEOUT_MS	3500	直连优先的连接探测在回退到代理前的超时时间，单位为 ms
FETCH_WEB_INSECURE_TLS	false	仅对 fetchWebContent 禁用 TLS 证书验证（用于证书异常的旧版网站）
GITHUB_README_CDN_FIRST	false	设为 true 时，强制跳过对 raw.githubusercontent.com 的直连探测，优先查询 jsDelivr CDN（加速中国大陆网络访问）

自定义代理引擎列表：如果在 ~/.my-websearch/config.json 中设置 proxy.engines，或使用 PROXY_URL 的 ;engine1,engine2 后缀，请务必包含 yahoo。沿用 1.3.7 时代的旧列表（8 个引擎，不含 yahoo）会导致 Yahoo 直连——在中国大陆实测：直连 15–20s 后超时，而通过代理约 2s 即可返回。建议完全移除列表：现在默认配置已包含 Yahoo，并让 GitHub / Stack Overflow / Hacker News / arXiv 等直连 API 引擎绕过代理。

3. 🔐 凭据与 API 密钥

变量	默认值	允许的值 / 说明
CONTEXT7_API_KEY	空	Context7 API 密钥（强烈建议代理 / TUN 用户设置，以避免共享 IP 配额限制）
EXA_API_KEY	空	Exa 免费 API 密钥（仅在使用 exa 语义搜索引擎时需要）
BRAVE_API_KEY	空	Brave Search API 密钥（可选；设置后会使用官方高可靠性 API）
GITHUB_TOKEN	空	GitHub 个人访问令牌（可选；将速率限制提高至 5,000 req/hr）
GITEE_TOKEN	空	Gitee 个人访问令牌（可选；提高 Gitee API 速率限制并启用私有仓库访问）
STACKOVERFLOW_API_KEY	空	Stack Apps 密钥（可选；将配额提高至 10,000 req/day）

4. 🖥️ 服务模式、并发与会话清理器

变量	默认值	允许的值／说明
MODE	both	MCP 传输模式：stdio（仅标准输入／输出）、http（仅 HTTP/SSE）、both（并发）
PORT	3211	MCP HTTP/SSE 监听端口（本地持久守护进程默认使用 3210）
MAX_CONCURRENT_SEARCHES	20	守护进程模式下的最大并发搜索数（0 表示不限制）
MCP_MAX_SESSIONS	100	返回 HTTP 429 Too Many Requests 前保留的最大 MCP HTTP 会话数
MCP_SESSION_TTL_MS	1800000	会话清理前的空闲过期时长（默认 30 分钟）
MCP_SESSION_REAPER_MS	300000	会话清理器的扫描间隔（默认 5 分钟）
LOG_LEVEL	info	日志级别：quiet（完全静默）、debug、info、warn、error
SECURITY_AUDIT	false	启用 SSRF 阻止和主机标头安全审计日志记录
OPEN_WEBSEARCH_ALLOWED_HOSTS	loopback	HTTP 服务的主机标头白名单（防止 DNS 重绑定，以逗号分隔）

5. 🧭 CDP 浏览器与隐身控制（保留旧版 Playwright 环境变量名称）

说明

浏览器回退方案现在通过 chrome-remote-interface 使用原始 Chrome DevTools Protocol；它会启动系统上已安装的 Chrome/Edge。PLAYWRIGHT_* 环境变量名称和 SEARCH_MODE=playwright 值仅为向后兼容而保留。BING_PLAYWRIGHT_FALLBACK 和 STARTPAGE_PLAYWRIGHT_FALLBACK 已合并到 SEARCH_MODE 中。

变量	默认值	允许的值／说明
BROWSER_DRIVER	cdp	浏览器后端。cdp（默认，原始 CDP）。playwright 是旧版应急选项，需要手动安装 playwright-core；该依赖不再随包提供。
PLAYWRIGHT_CDP_ENDPOINT	empty	远程 Chrome/Edge CDP 端点 URL（例如 http://127.0.0.1:9222 或 ws://...）；旧版名称，由 CDP 驱动使用
PLAYWRIGHT_EXECUTABLE_PATH	auto	浏览器可执行文件的绝对路径（默认自动检测系统中的 Edge/Chrome）；旧版名称
PLAYWRIGHT_HEADLESS	true	以无头模式运行（在 Windows 上使用独立的隐藏桌面窗口）；旧版名称
PLAYWRIGHT_NAVIGATION_TIMEOUT_MS	20000	页面导航的硬性超时时间（毫秒）；旧版名称，应用于 CDP 导航

6. 🛠️ 应用目录与工具自定义

变量	默认值	允许的值／说明
MYWEBSEARCH_DATA_DIR	~/.my-websearch	配置和持久化 Cookie 文件的根目录
OPEN_WEBSEARCH_RESPONSE_CAP_BYTES	60000	返回给大模型的最大字符数限制，以防止提示词上下文膨胀
MCP_TOOL_SEARCH_NAME	search	MCP 中搜索工具的自定义注册名称
MCP_TOOL_FETCH_WEB_NAME	fetchWebContent	内容提取工具的自定义注册名称
MCP_TOOL_FETCH_GITHUB_NAME	fetchGithubContent	GitHub/Gitee 内容工具的自定义注册名称（设为 fetchGithubReadme 可保持向后兼容）

💡 零配置升级（已移除冗余变量）：

• CORS 开关（ENABLE_CORS/CORS_ORIGIN）：默认禁用 CORS；当浏览器客户端需要跨源访问时，请显式启用并限制来源。
• 浏览器后端：通过 chrome-remote-interface 使用原始 CDP；不再随包提供 playwright-core。PLAYWRIGHT_* 名称和 SEARCH_MODE=playwright 仍作为兼容别名保留。
• Emoji 开关（OPEN_WEBSEARCH_NO_EMOJI）：自动检测控制台代码页，并在旧版终端上平滑回退为 ASCII 标签。
• 零散的调试标记（OPEN_WEBSEARCH_DEBUG）：已统一为标准的 LOG_LEVEL=debug。
• Cookie 持久化 TTL（MYWEBSEARCH_COOKIE_TTL_DAYS）：已固定为 30 天，并通过自动滑动续期进行更新。

---

🤝 贡献与测试

欢迎提交拉取请求和问题！如需在本地运行测试套件：

npm install
npm run build
npm test              # Run the Vitest suite (88 files, 684 tests at the current baseline)
npm run test:live     # Run bounded-concurrency live integration tests
npm run eval:live     # Run 23-case live STDIO JSON-RPC evaluation suite

致谢

作者：wtznicy

本项目由 Open-WebSearch（最初由 Aas-ee 创建）发展而来，特别感谢原作者。也感谢：

• wreq-js 提供原生 Chrome TLS/HTTP2 指纹模拟
• Context7 提供官方文档检索支持
• Mozilla Readability & Turndown 提供内容提取和 GFM Markdown 格式化