# grok-search

**简体中文** | [English](README.en.md)

`grok-search` 是一个通用 AI agent skill / 脚本包，用轻量 Node.js 脚本提供三类网络访问能力：

- **Search**：通过 Responses API 调用 Grok / OpenRouter / Responses-compatible 接口，并行返回 Tavily / Firecrawl 独立信源。 - **Fetch**：抓取指定 URL 的可读内容，优先使用 Tavily / Firecrawl，最后 fallback 到无 key 的 Direct Fetch。 - **Map**：发现站点内的候选页面 URL，优先使用 Tavily Map，最后 fallback 到轻量 Direct Map。

## 要求

- Node.js `>=18.17` - 需要先运行一次 `npm install` 安装 `undici` 传输依赖 - `search.js` 需要配置 `GROK_API_URL` 和 `GROK_API_KEY`

## 快速开始

先安装依赖一次，然后从项目根目录运行脚本：

```bash npm install ./scripts/search.js "latest Node.js LTS" ./scripts/fetch.js https://example.com ./scripts/map.js https://docs.example.com --limit 20 ```

## 在 pi 中使用（示例）

把本目录 clone 或复制到你的 pi skills 位置，然后通过 `SKILL.md` 启用这个 skill。

示例命令仍然是直接运行脚本：

```bash ./scripts/search.js "latest Node.js LTS" ./scripts/fetch.js https://example.com ./scripts/map.js https://docs.example.com --limit 20 ```

其他 agent harness 也可以采用同样方式：读取 `SKILL.md`，再按需运行 `scripts/search.js`、`scripts/fetch.js`、`scripts/map.js`。

## 文档

- [架构说明](docs/architecture.md) - [功能说明](docs/features.md) - [Responses 搜索协议](docs/responses-mode.md) - [Smoke Tests](docs/smoke-tests.md) - [公开 Benchmark](docs/benchmark.md) - [评测方法研究](docs/web-search-evaluation-research.md)

## 配置

推荐把长期使用的 key 放到：

```text ~/.config/grok-search/config.json ```

可以从示例文件复制：

```bash mkdir -p ~/.config/grok-search cp config.example.json ~/.config/grok-search/config.json chmod 600 ~/.config/grok-search/config.json ```

完整配置示例：

```json { "apiUrl": "https://api.x.ai/v1", "apiKey": "your-grok-api-key", "apiProvider": "xai", "model": "grok-4.3", "responsesMaxTurns": 3, "responsesReasoningEffort": "low", "responsesAllowedDomains": [], "responsesExcludedDomains": [], "responsesIncludeXSearch": false, "responsesAllowedXHandles": [], "responsesExcludedXHandles": [], "responsesOpenRouterEngine": "auto", "defaultExtra": 6, "sourceChars": 400, "tavilyApiKey": "", "tavilyApiUrl": "https://ap