searchio

searchio

searchio 是一个用于搜索、阅读网页和查询产品的工具。可通过命令行、Python 或 HTTP 使用。既可供个人使用，也可供 AI Agent 使用。搜索和阅读无需 API 密钥。

AI Agent 快速入门

AI Agent 可以一次性为用户设置 searchio。请按顺序完成以下步骤。验证通过后即可停止。

1. Docker 可用时，使用 Docker。 请尝试：

docker run -i --rm ghcr.io/ioserviceslabs/searchio-mcp

该镜像包含完整系统：抓取阶梯、Rust 引擎 sidecar，以及用于挑战层的 Chromium。无需其他安装步骤。转到第 3 步。

2. 没有 Docker：从源代码安装。 需要 Python 3.10 或更高版本。

pip install "searchio[mcp]"
curl -fsSL https://raw.githubusercontent.com/IOServicesLabs/searchio-engine/main/scripts/install.sh | sh

pip 命令会从 PyPI 安装 searchio 包及 MCP 服务。curl 命令会将 Rust 引擎 sidecar 安装到 ~/.searchio/bin/se-serve（linux、macOS、带 Git Bash 的 Windows）。该 sidecar 是快速的第 2 层后端。它是可选的，但建议安装。 如需使用最新开发版本，请运行 pip install "searchio[mcp] @ git+https://github.com/IOServicesLabs/searchio"。

3. 将 MCP 服务添加到客户端。 Claude Desktop 和 Cursor 使用以下配置格式。

Docker：

{
  "mcpServers": {
    "searchio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/ioserviceslabs/searchio-mcp"]
    }
  }
}

从源代码安装：

{
  "mcpServers": {
    "searchio": { "command": "searchio-mcp" }
  }
}

4. 验证。 重启客户端。询问：“使用 searchio 搜索东京当前时间。”如果返回真实结果，说明设置成功。若出现缺少命令的错误，说明配置指向了不存在的路径；请修正配置后重试。

注意：也可以在第 3 步中将 npx @ioserviceslabs/searchio-mcp 用作客户端命令。Docker 运行时，启动器会启动 Docker 镜像；否则会启动第 2 步中的本地安装。

1. 安装

需要 Python 3.10 或更高版本。

路径 A——pip（一个命令）：

pip install "searchio[mcp]"
searchio-mcp        # MCP server on stdio, ready for an LLM client

searchio doctor 会检查安装情况。Rust 引擎 sidecar 是可选的。请使用快速入门第 2 步中的 curl 命令安装。

路径 B——Docker（无需 Python）：

docker run -i --rm ghcr.io/ioserviceslabs/searchio-mcp              # stdio MCP
docker run -p 8080:8080 ghcr.io/ioserviceslabs/searchio-mcp \
  searchio-mcp --transport sse --host 0.0.0.0 --port 8080

没有适用于你平台的预构建镜像？请从源代码构建：

docker build -t searchio https://github.com/IOServicesLabs/searchio.git

该镜像包含完整的抓取阶梯：Python 各层、Rust 引擎 sidecar，以及用于挑战层的 Chromium。状态（通行许可、会话）会持久保存在 /root/.searchio 卷中：

docker run -i --rm -v searchio-state:/root/.searchio ghcr.io/ioserviceslabs/searchio-mcp

路径 C——从源代码安装：

git clone https://github.com/IOServicesLabs/searchio.git
cd searchio
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS / Linux
pip install -e '.[mcp]'
searchio doctor

searchio doctor 会显示哪些抓取层可在你的计算机上运行。第 0 层使用普通 HTTP。第 1 层添加 TLS 伪装。第 2 层为会屏蔽机器人的网页添加真实浏览器。首次需要时，第 2 层会自动启动。

引擎层（可选，建议安装）

如果存在 se-serve 二进制文件，第 2 层会使用 Rust searchio-engine sidecar。它可在几毫秒内启动，且无需 Chromium。Docker 镜像已包含该组件。在主机上安装时，只需运行一个命令即可添加：

curl -fsSL https://raw.githubusercontent.com/IOServicesLabs/searchio-engine/main/scripts/install.sh | sh

安装程序会将二进制文件放在 ~/.searchio/bin/se-serve，searchio 会自动找到它。你也可以将 SEARCHIO_ENGINE_BIN 设置为任意二进制文件。

MCP 客户端设置

将任意 MCP 客户端指向该服务：

{
  "mcpServers": {
    "searchio": {
      "command": "searchio-mcp"
    }
  }
}

使用 Docker 时，请设置 "command": "docker", "args": ["run", "-i", "--rm", "searchio"]。

完全没有 Python？npm 封装器会为你选择后端（有 Docker 时使用 Docker，否则使用本地安装）：

{
  "mcpServers": {
    "searchio": {
      "command": "npx",
      "args": ["-y", "@ioserviceslabs/searchio-mcp"]
    }
  }
}

2. 搜索

searchio search "best noise cancelling headphones 2026"
searchio search "rust async runtime comparison" --intent code
searchio search "artemis mission" --domains nasa.gov
searchio search "heat pump retrofit" --k 20 --json

你可以设置意图：web（默认）、news、video、shopping、academic、code、forum、reference、local。也可以在查询中加入 site:nasa.gov。

3. 阅读网页

searchio read https://example.com/some/article
searchio read https://example.com/paper.pdf --chars 20000

该命令会输出可读文本。它会自动突破付费墙、机器人检测和仅支持 JavaScript 的网页。如果无法阅读某个页面，你会收到明确原因，而不会得到空白页面。

4. 产品和商品列表

searchio items "sony wh-1000xm5"                    # one row per product across retailers
searchio items "dyson v15" --domains bestbuy.com --json
searchio marketplace "ford f-150" --city seattle    # Facebook Marketplace, browser-backed

5. 使用 AI 集群进行研究

此部分需要付费。设置一个密钥：

set ANTHROPIC_API_KEY=...            # Windows
# export ANTHROPIC_API_KEY=...       # macOS / Linux
searchio research "What changed in the EU battery regulation this year, and who is affected?"

如需改用 DeepSeek，请设置 SEARCHIO_LLM_PROVIDER=deepseek 和 DEEPSEEK_API_KEY=...。返回的答案包含研究结果。每条结果都会引用工作者阅读过的网页。

6. 将其作为 MCP 服务运行

searchio 也是一个 MCP（模型上下文协议）服务。AI Agent 通过 MCP 调用它。CLI 使用的工具同样可供 Agent 使用。

安装 MCP 附加组件：

pip install -e '.[mcp]'

通过 stdio 启动服务：

searchio mcp
# or
python -m searchio.mcp

通过 HTTP 启动服务：

searchio mcp --transport streamable-http --host 127.0.0.1 --port 8080 --path /mcp

6.1 MCP 工具

服务提供以下工具：

工具	功能
search	使用无需密钥的服务提供商进行融合排序的网页搜索。
search_items	合并多个零售商商品列表并显示价格。
search_local	搜索城市附近的 Facebook Marketplace 分类信息（由浏览器提供支持）。
youtube_transcript	获取一段 YouTube 视频的字幕文本：包含带时间戳的片段和完整文本。
read_url	通过抗拦截阶梯读取一个 URL。返回 Markdown。
research	针对某个问题运行多步骤研究集群（需要 LLM 密钥）。
stats	阶梯和服务提供商的健康状况（各域名已学习的层级、拦截率）。

服务还提供一个资源：searchio://health，返回一个简短的 JSON 对象，包含服务健康状况。

6.2 搜索和研究的付费机制（x402）

MCP 服务设有付费网关。它采用 x402 格式。网关开启时，可计费工具会返回 402（Payment Required）和 X-Payment 挑战，直到调用方完成付款。

通过 SEARCHIO_MCP_PAYMENT 设置网关：

值	结果
``（空，默认值）	网关开放。不收取费用。适用于本地和开发用途。
static:<token>	调用方必须发送 Authorization: Bearer <token>。否则，工具会返回 402 + X-Payment 挑战。

真实验证器使用的就是这种格式。它没有账本。将服务托管给他人使用时，请在前面接入真实的 x402 验证器。验证器会检查付款，然后运行工具。这正是 searchio 与 SwarmIO 一同托管、提供搜索和研究额度的方式。

7. 将其作为 HTTP 服务运行

searchio serve --port 8080

端点	功能
GET /search?q=...&intent=web&k=10&domains=a.com,b.org&freshness=week&locale=de-DE	搜索结果
GET /read?url=...&session=me	一个网页的可读文本
GET /items?q=...&domains=...	按商品合并的商品列表
GET /marketplace?q=...&city=seattle	Facebook Marketplace 列表
GET /transcript?url=...&lang=en	YouTube 字幕文本（400 无效视频 · 404 无字幕 · 451 已拒绝）
POST /research {"question": "..."}	AI 研究集群
GET /providers、GET /stats、GET /healthz	状态

错误会如实返回状态码：请求无效时返回 422，目标违反策略时返回 400，网页被反机器人墙拦截时返回 451，服务提供商故障或全部因故障进入冷却状态时返回 502 或 503。搜索结果会列出 providers_used、providers_failed 和 providers_skipped（熔断器已开启，并显示剩余冷却时间）。

如果多人或多个 Agent 共用一台服务，请为每个调用方在 /read 上分配各自的 session。这样，一个调用方的 Cookie 就不会随另一个调用方的请求发送。

8. 在 Docker 中运行

此仓库中的 Dockerfile 会构建完整阶梯：Python 层级、Rust 引擎辅助进程，以及用于挑战层的 Chromium。请参阅第 1 节中的路径 B，了解构建和运行命令。docker compose up 会执行相同操作，并配置好状态卷。

在容器内，第 2 层首先使用引擎辅助进程；需要真实浏览器的网页则交由 patchright Chromium 处理（挑战层）。缓存、按域名学习的层级和通行 Cookie 都存放在 searchio-state 卷中，因此容器重启后仍会保留。研究集群所需的密钥通过环境变量传入，变量名与第 10 节中的相同。

9. 在 Python 中使用

import asyncio
from searchio.engine import Engine

async def main():
    eng = Engine()
    res = await eng.search("lithium iron phosphate battery lifespan", intent="web", k=5)
    for doc in res.docs:
        print(doc.title, doc.url)

    doc = await eng.read("https://example.com/article")
    print(doc.text[:500])

    items = await eng.find_items("sony wh-1000xm5")
    for it in items:
        print(it.title, it.price, it.url)

    await eng.close()

asyncio.run(main())

10. 设置

所有配置均为带有 SEARCHIO_ 前缀的环境变量，或是与运行位置同目录下 .env 文件中的一行。人们最常修改的配置：

变量	默认值	含义
SEARCHIO_MAX_TIER	2	0 仅使用 HTTP，1 增加 TLS 模拟，2 增加浏览器
SEARCHIO_ROBOTS_POLICY	warn	enforce、warn 或 off
SEARCHIO_PROXY	none	HTTP 层使用的代理 URL
SEARCHIO_FACEBOOK_CITY	none	Marketplace 搜索的默认城市
SEARCHIO_CACHE_ENABLED	true	将获取的页面缓存一小时
SEARCHIO_STATE_DIR	~/.searchio	缓存、配置文件和 clearance Cookie 的存放位置
SEARCHIO_MCP_PAYMENT	``	MCP 付费门控（参见 6.2）
SEARCHIO_MCP_BEARER	none	MCP 门控检查的 Bearer 令牌

11. 须知

• 搜索和阅读无需密钥，也不收费。只有 research 会调用付费模型。
• 此工具绝不会将你的凭据发送到任何地方。Marketplace 和其他依赖浏览器的查询均以匿名方式运行。
• searchio providers 会列出所有来源及其配置状态。
• 遇到异常时，首先运行 searchio doctor。