网络工具

AggRoot 提供三个核心网络工具，覆盖搜索、抓取和 HTTP 请求，外加图片搜索和文件下载工具。

---

WebSearch — 搜索网页

使用 Bing 搜索引擎查询网络信息，基于 Playwright 后端实现。

参数

参数	类型	必填	默认值	说明
query	string	是	—	搜索关键词
intent	string	否	—	搜索意图描述
expected	string	否	—	期望结果及失败后的备选方案
num	number	否	10	结果数量（最大 10）
tbs	string	否	—	时间范围过滤器

时间范围过滤器（tbs）

值	含义
qdr:h	过去 1 小时
qdr:d	过去 1 天
qdr:d3	过去 3 天
qdr:w	过去 1 周
qdr:m	过去 1 个月
qdr:y	过去 1 年

搜索优化技巧

1. 中文关键词不加空格："深圳天气预报15天" 而非 "深圳天气 15天"
2. 避免泛泛关键词：用 "热点新闻排行榜" 而非 "热点新闻"（后者易返回知乎）
3. 不要自动添加时间：时间过滤用 tbs 参数，不在 query 中加年份
4. 搜索词要简洁：控制在 10 个字以内，不拼接多个同义词
5. 使用 site: 限定网站：site:sina.com.cn 限定新闻源

示例

// 基本搜索
WebSearch({"query": "TypeScript 5.0 新特性"})

// 限定时间范围
WebSearch({"query": "AI技术突破", "tbs": "qdr:w"})

// 限定权威网站
WebSearch({"query": "React 19 site:react.dev"})

// 带意图和期望
WebSearch({
  "query": "Node.js性能优化最佳实践",
  "intent": "寻找生产环境下的性能调优指南",
  "expected": "找到官方或权威博客的优化建议"
})

返回结果

每个结果包含：标题（title）、URL、摘要（snippet）。返回数据中 urls 字段可直接传递给 WebFetch。

---

WebFetch — 获取网页

获取网页内容，支持多 URL 自动重试，基于 Playwright 渲染 JavaScript。

参数

参数	类型	必填	说明
url	string[]	是	URL 数组，按顺序尝试直到成功
selector	string	否	CSS 选择器，提取页面特定区域
waitFor	string	否	CSS 选择器，等待特定元素加载完成

功能特性

• 多 URL 重试：传入多个 URL，按顺序尝试，成功一个就返回
• JS 渲染：使用 Playwright 渲染页面，支持 SPA 和动态内容
• 内容清洗：自动移除 script、style、nav、header、footer、广告等噪声元素
• 智能等待：waitFor 参数等待特定元素出现后再抓取内容
• 选择器提取：selector 参数只提取页面指定区域的内容
• 长度截断：超过 8000 字符的内容自动截断

示例

// 从搜索结果获取内容
WebFetch({"url": ["https://react.dev/blog", "https://react.dev/docs"]})

// 使用搜索结果 URL
WebSearch({"query": "React 19"})
// 然后使用 WebSearch 返回的 urls
WebFetch({"url": data.urls})

// 提取特定区域
WebFetch({"url": ["https://example.com"], "selector": ".article-content"})

// 等待动态内容加载
WebFetch({"url": ["https://spa-example.com"], "waitFor": ".loaded-content"})

最佳实践

• 至少传入 2-3 个 URL，提高成功率
• 搜索后立即 Fetch：WebFetch({"url": data.urls})
• SPA 页面使用 waitFor 等待内容渲染完成
• 长文章使用 selector 只提取正文区域

---

HttpRequest — HTTP 请求

发送 HTTP 请求，支持所有常用方法和自定义请求头。

参数

参数	类型	必填	默认值	说明
url	string	是	—	请求 URL
method	string	否	GET	HTTP 方法：GET/POST/PUT/DELETE/PATCH
headers	object	否	—	自定义请求头（key-value）
body	string	否	—	请求体（POST/PUT/PATCH 时使用）
timeout	number	否	30	超时秒数

示例

// GET 请求
HttpRequest({"url": "https://api.example.com/users"})

// POST 请求
HttpRequest({
  "url": "https://api.example.com/users",
  "method": "POST",
  "headers": {"Authorization": "Bearer token123"},
  "body": "{\"name\": \"test\"}"
})

// PUT 请求更新资源
HttpRequest({
  "url": "https://api.example.com/users/1",
  "method": "PUT",
  "body": "{\"name\": \"updated\"}"
})

// DELETE 请求
HttpRequest({
  "url": "https://api.example.com/users/1",
  "method": "DELETE"
})

// 带自定义请求头
HttpRequest({
  "url": "https://api.example.com/data",
  "headers": {
    "Authorization": "Bearer abc123",
    "Accept": "application/json"
  }
})

返回结果

字段	说明
status	HTTP 状态码
statusText	状态描述
headers	响应头
body	响应体（JSON 自动格式化，其他截断到 10KB）

注意事项

• JSON 请求默认添加 Content-Type: application/json
• 响应体超过 10KB 自动截断
• 超时后返回错误信息

---

ImageSearch — 搜索图片

搜索网络图片，返回图片 URL 和缩略图。

参数

参数	类型	必填	默认值	说明
query	string	是	—	搜索关键词
count	number	否	5	图片数量（最大 10）
safeSearch	boolean	否	true	启用安全搜索

示例

ImageSearch({"query": "TypeScript logo"})
ImageSearch({"query": "架构图", "count": 3})

---

FileDownload — 下载文件

从 URL 下载文件到本地。

参数

参数	类型	必填	说明
url	string	是	文件下载 URL
filename	string	否	保存的文件名（不指定则自动获取）
saveDir	string	否	保存目录（默认 ./downloads）
headers	object	否	自定义请求头

支持的文件类型

图片、文档（PDF/Word/Excel/PPT）、压缩包、音视频文件等。

示例

// 下载文件
FileDownload({"url": "https://example.com/report.pdf"})

// 指定文件名和目录
FileDownload({
  "url": "https://example.com/data.csv",
  "filename": "report.csv",
  "saveDir": "/projects/data"
})

// 带认证头下载
FileDownload({
  "url": "https://api.example.com/export",
  "headers": {"Authorization": "Bearer token123"}
})

---

工作流：搜索 + 获取

WebSearch 和 WebFetch 的典型搭配流程：

1. WebSearch → 获取搜索结果（标题 + URL + 摘要）
2. 分析相关性，选择最有价值的 URL
3. WebFetch → 获取完整页面内容
4. 根据内容决定是否需要补充搜索

// Step 1: 搜索
WebSearch({"query": "Next.js App Router 教程"})

// Step 2: 获取最佳结果
WebFetch({"url": ["https://nextjs.org/docs/app", "https://nextjs.org/learn"]})

// Step 3: 如果需要更多信息，补充搜索
WebSearch({"query": "Next.js App Router vs Pages Router site:nextjs.org"})

关键规则：搜索到结果后，必须立即调用 WebFetch 获取内容，不要在未 Fetch 的情况下连续调用 WebSearch。