# Brave Search

> |

- **Type:** Skill
- **Install:** `agentstack add skill-bushuhui-skills-brave-search`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bushuhui](https://agentstack.voostack.com/s/bushuhui)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bushuhui](https://github.com/bushuhui)
- **Source:** https://github.com/bushuhui/skills/tree/master/brave-search

## Install

```sh
agentstack add skill-bushuhui-skills-brave-search
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Brave Search Skill

通过 Brave Search API 进行网页搜索和新闻搜索。

## 环境

- API Key 从环境变量 `BRAVE_API_KEY` 读取（已在 ~/scripts/shell_conf 配置）
- 支持代理：自动读取 `HTTPS_PROXY` / `HTTP_PROXY`

## 搜索脚本

```bash
# 基础搜索
python3 scripts/brave_search.py "query"

# 限制结果数
python3 scripts/brave_search.py "query" -n 5

# 搜新闻
python3 scripts/brave_search.py "AI agent" --news

# 时间过滤：pd=过去一天, pw=过去一周, pm=过去一月, py=过去一年
python3 scripts/brave_search.py "LLM benchmark" --freshness pw

# 指定国家
python3 scripts/brave_search.py "量化交易" --country CN

# 批量搜索（多关键词）
python3 scripts/brave_search.py "placeholder" --queries "query1" "query2" "query3"

# 翻页
python3 scripts/brave_search.py "query" --offset 10
```

输出 JSON 数组，每条含 `title`, `href`, `body`, `age`。

## 使用流程

1. 分析用户需求，拆解为搜索关键词（中英文各一组效果更好）
2. 运行 `brave_search.py` 搜索
3. 从结果中挑选最相关的 URL
4. 用 `web_fetch` 抓取正文获取详细内容
5. 整合信息回复用户

## 与 deep-research 配合

本 skill 可作为 deep-research 的搜索后端替代 DuckDuckGo：
- Brave API 质量更高、更稳定
- 支持时间过滤和国家过滤
- 有 `age` 字段标注结果时效性

## 网络问题排查

**⚠️ Brave API 端口 443 可能不可达**：在某些网络环境下 `api.search.brave.com:443` 连接超时（Connection timed out）。诊断方法：

```bash
curl -sv --connect-timeout 5 "https://api.search.brave.com/res/v1/web/search?q=test&count=1" \
  -H "X-Subscription-Token: ${BRAVE_API_KEY}" 2>&1 | grep "connect"
```

如果显示 `Connection timed out`，说明该端口不可达。回退方案：
- 使用 `web-access` skill 的 CDP 浏览器通过 Bing/Google 搜索
- 或直接使用 GitHub Search API（无需外部搜索）

## 注意事项

- 免费 API 限制：每月 2000 次请求，每秒 1 次
- 单次最多返回 20 条结果
- 批量搜索自动间隔 0.5 秒避免频率限制

## ⚠️ 代理依赖（关键）

**`api.search.brave.com` 在国内无法直连**，必须通过代理访问。即使 API Key 已配置，没有代理会导致 `Connection timed out`。

### 可用性诊断

```bash
# 检查代理是否生效
source ~/scripts/shell_conf
curl -sI --connect-timeout 5 "https://api.search.brave.com/" \
  -H "X-Subscription-Token: ${BRAVE_API_KEY}"
# 返回 HTTP 200/403 = 通，Connection timed out = 需要切代理
```

### 兜底方案

Brave 不可用时，按以下优先级降级：

1. **CDP + Bing/Google 搜索** — 通过 `cdp-cli.mjs` 打开 Bing 页面，用 JS 提取搜索结果中的链接（见 web-access skill）
2. **DuckDuckGo HTML** — `curl https://html.duckduckgo.com/html/?q=query` 解析 HTML 结果
3. **Jina Reader** — `curl "https://r.jina.ai/"` 作为单页抓取兜底

**CDP + Bing 搜索示例**（搜索 GitHub 仓库时最有效）：

```bash
SCRIPT="/home/bushuhui/.agents/skills/web-access/scripts/cdp-cli.mjs"
TARGET=$(node "$SCRIPT" new "https://www.bing.com/search?q=" 2>&1 | grep -oP '"targetId":"\K[A-F0-9]+')
sleep 5
node "$SCRIPT" eval "$TARGET" "Array.from(document.querySelectorAll('li.b_algo')).slice(0,8).map(li=>{const a=li.querySelector('h2 a'); return a ? {title:a.textContent.trim().substring(0,100), href:a.href} : null}).filter(Boolean)"
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bushuhui](https://github.com/bushuhui)
- **Source:** [bushuhui/skills](https://github.com/bushuhui/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bushuhui-skills-brave-search
- Seller: https://agentstack.voostack.com/s/bushuhui
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.