grok-search
Use when the user explicitly asks to search the web, check latest/current facts, fetch a URL, or discover pages on a website. Do not use for local code search or stable offline knowledge unless the user asks for live web access.
Install
npx skills add https://github.com/dengyie/awesome-skills/tree/main/grok-search
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dengyie-awesome-skills@llmmart
git clone https://github.com/dengyie/awesome-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole dengyie/awesome-skills collection as a plugin from our marketplace. Git is the plain clone.
README
grok-search
简体中文 | English
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
快速开始
先安装依赖一次,然后从项目根目录运行脚本:
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。
示例命令仍然是直接运行脚本:
./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。
文档
- 架构说明
- 功能说明
- Responses 搜索协议
- Smoke Tests
- 公开 Benchmark
- 评测方法研究
- Agent 侧说明:SKILL.md(每轮都读,≤5k 字)与按需阅读的 references/x-search.md、references/providers.md、references/planning.md
配置
推荐把长期使用的 key 放到:
~/.config/grok-search/config.json
可以从示例文件复制:
mkdir -p ~/.config/grok-search
cp config.example.json ~/.config/grok-search/config.json
chmod 600 ~/.config/grok-search/config.json
完整配置示例:
{
"apiUrl": "https://api.x.ai/v1",
"apiKey": "your-grok-api-key",
"apiProvider": "xai",
"model": "grok-4.20-multi-agent-0309",
"responsesMaxTurns": 3,
"responsesReasoningEffort": "low",
"responsesAllowedDomains": [],
"responsesExcludedDomains": [],
"responsesAllowedXHandles": [],
"responsesExcludedXHandles": [],
"responsesOpenRouterEngine": "auto",
"defaultExtra": 6,
"sourceChars": 400,
"tavilyApiKey": "",
"tavilyApiKeys": [],
"tavilyApiUrl": "https://api.tavily.com",
"tavilyProxyUrl": "",
"tavilyProxyKey": "",
"tavilyProxyTimeoutMs": 12000,
"firecrawlApiKey": "",
"firecrawlApiUrl": "https://api.firecrawl.dev/v2",
"exaApiKey": "",
"exaApiUrl": "https://api.exa.ai",
"outputDir": "",
"stateDir": "",
"runLog": true
}
常见填写规则:
apiUrl填支持/responses的 API base URL;脚本会请求{apiUrl}/responses,不要把/responses本身写进去。apiProvider一次只能填写一个值:xai:xAI 官方接口,按searchSource使用web_search与x_search。openrouter:OpenRouter 接口,改用openrouter:web_search;可通过responsesOpenRouterEngine选择搜索引擎。openai-compatible:支持 xAI 风格 Responses 与web_searchtool 的中转、反代或兼容服务。仅支持 Chat Completions 的接口不能使用。
apiProvider省略时会按 URL 推断:包含openrouter视为openrouter,包含api.x.ai视为xai,其他 URL 视为openai-compatible。中转服务建议显式填写,避免请求格式判断错误。model必须填写该 endpoint 实际支持的模型 ID;responsesMaxTurns是不小于 1 的整数。responsesReasoningEffort常见值为low、medium、high,但是否支持取决于具体模型与 provider。responsesAllowedDomains、responsesExcludedDomains、responsesAllowedXHandles、responsesExcludedXHandles都是数组,可以填写多个值,例如["github.com", "docs.python.org"];同一组 allowed 与 excluded 不能同时使用。domain 上限 5 个,X handle 上限 20 个。环境变量中的多值使用逗号分隔。searchSource可选web、x或both,决定默认挂载哪些检索工具;命令行--source优先。X 的日期窗口是按查询变化的,只能用--x-from-date/--x-to-date传入,没有对应配置项。- 旧配置项
responsesIncludeXSearch/GROK_RESPONSES_INCLUDE_X_SEARCH已移除(2026-08 弃用,2026-09 删除)。值为true时命令直接报CONFIG_OPTION_REMOVED而不是静默丢掉 X 检索,请改为searchSource: "both";false或缺失不受影响。 - 优先级为 命令行 > 环境变量 > 配置文件 > 默认值。注意配置文件由你书写、命令行参数由调用本工具的 agent 书写:标量配置(如
searchSource)是默认值,agent 可以覆盖,实际生效值见diagnostics.options;但配置里的限制不会被静默抹掉——allow-list 与 deny-list 都是限制,命令行只能收紧不能放宽。越界报RESPONSES_FILTER_FORBIDDEN,把 allow-list 减空报RESPONSES_FILTER_EMPTY,两个 deny-list 合并而非替换。规则见 docs/responses-mode.md。 responsesOpenRouterEngine可选auto、native、exa、firecrawl、parallel或perplexity,仅在apiProvider为openrouter时生效。tavilyApiKey可留空;多把官方 key 写进tavilyApiKeys(或环境变量TAVILY_API_KEYS,逗号分隔),配额或鉴权失败时才轮到下一把,游标在~/.cache/grok-search/tavily-rr.json。tavilyProxyUrl+tavilyProxyKey是另一套第三方兼容入口:先打代理(默认 12 秒、不重试),HTTP 失败或 search/map 空结果再回落官方 key。不要把代理 URL 写进tavilyApiUrl,两边的 key 不通用。firecrawlApiKey也可留空并使用 Firecrawl Keyless。exaApiKey可选,配置后 Exa 加入 search 的 extra 轮转与 fetch 的 auto 链(注意它与 OpenRouter 引擎值exa无关,后者仅在apiProvider为openrouter时生效)。outputDir留空时使用默认目录~/.cache/grok-search/outputs/;stateDir留空时使用~/.cache/grok-search/,存放 Firecrawl 冷却状态;runLog: false关闭每次调用的运行记录落盘。
如果使用 OpenRouter,核心字段可改为:
{
"apiUrl": "https://openrouter.ai/api/v1",
"apiKey": "your-openrouter-api-key",
"apiProvider": "openrouter",
"model": "your-openrouter-model-id",
"responsesOpenRouterEngine": "auto"
}
如果使用 Responses-compatible 中转服务,核心字段可改为:
{
"apiUrl": "https://your-endpoint.example/v1",
"apiKey": "your-api-key",
"apiProvider": "openai-compatible",
"model": "the-model-id-supported-by-your-endpoint"
}
然后编辑复制过去的文件,填入真实 key。环境变量仍然优先于配置文件,适合临时覆盖或 CI 使用。
本项目不会自动加载 .env 文件。如果你想用环境变量,请自己在 shell 里 export。
代理
Node 原生 fetch 默认不会可靠读取终端代理变量。本项目会在检测到代理环境变量时自动安装 undici 的 EnvHttpProxyAgent,让所有出站请求走你的终端代理配置。
支持的变量:
HTTP_PROXY/http_proxyHTTPS_PROXY/https_proxyALL_PROXY/all_proxyNO_PROXY/no_proxyGROK_PROXY:显式给本工具指定一个代理 URL;设为GROK_PROXY=off可强制直连。显式配置无效时命令会直接失败(PROXY_CONFIG_INVALID),不会静默退回直连;环境继承的代理失败则继续运行,并通过 search 的diagnostics.options.proxy_mode暴露状态
NO_PROXY 会被尊重,并且会始终把回环地址(localhost、127.0.0.1、::1)加入绕过列表。
| 环境变量 | 配置文件 key | 是否必需 | 用途 | 说明 |
|---|---|---|---|---|
GROK_API_URL |
apiUrl |
search 必需 | search.js |
支持 /responses 的 base URL。 |
GROK_API_KEY |
apiKey |
search 必需 | search.js |
GROK_API_URL 对应的 API key。 |
GROK_API_PROVIDER |
apiProvider |
否 | search.js |
选择 Responses tool 请求格式,而不是额外的搜索源;可选 xai、openrouter 或 openai-compatible。未配置时按 URL 推断。 |
GROK_MODEL |
model |
否 | search.js |
默认 grok-4.20-multi-agent-0309。该模型在 CPA 兼容上游会自己执行服务端 web_search;普通 Chat Completions 模型和免费 CLI 账号池不会。 |
GROK_RESPONSES_MAX_TURNS |
responsesMaxTurns |
否 | Responses | 默认 3,控制 Responses agentic turn 上限;只对 X 搜索是硬上限,web 搜索不受它约束。 |
GROK_RESPONSES_REASONING_EFFORT |
responsesReasoningEffort |
否 | Responses | 默认 low。 |
GROK_RESPONSES_PARALLEL_TOOL_CALLS |
responsesParallelToolCalls |
否 | Responses | true / false;默认不发送。false 让 Grok 每个 turn 只做一次服务端工具调用,官方 api.x.ai 与透传的中转都回显 false,X 搜索被压到每 turn 一次、max_turns 成为硬上限(2026-09-08 实测:grok-4.5 经中转 7–14 次降到 3 次、费用约三分之一;grok-4.6 无论官方还是中转自然只 3–4 次,降到 3 次费用持平,responses_tool_calls.total 超过 6 再加);不透传的中转会回显 true。max_tool_calls 官方与中转都不生效,未接入。命令行 --responses-parallel-tool-calls false。2026-11-03 补充:grok-4.20-multi-agent-0309 经透传中转,flag 生效于 agent 层(trace 4→1、费用 $0.64→$0.41),但上游 x_search 仍 19–21 次——多智能体在服务端扇出,total 不再被 max_turns 封顶,效果看 trace 而非 total。 |
GROK_RESPONSES_ALLOWED_DOMAINS |
responsesAllowedDomains |
否 | Responses | 逗号分隔 domain allow-list,最多 5 个;与 excluded 互斥。 |
GROK_RESPONSES_EXCLUDED_DOMAINS |
responsesExcludedDomains |
否 | Responses | 逗号分隔 domain deny-list,最多 5 个;与 allowed 互斥。 |
GROK_SEARCH_SOURCE |
searchSource |
否 | Responses | 默认检索源:web、x 或 both。默认 web。 |
GROK_RESPONSES_ALLOWED_X_HANDLES |
responsesAllowedXHandles |
否 | Responses | X handle allow-list,最多 20 个;与 excluded 互斥。 |
GROK_RESPONSES_EXCLUDED_X_HANDLES |
responsesExcludedXHandles |
否 | Responses | X handle deny-list,最多 20 个;与 allowed 互斥。 |
GROK_X_IMAGE_UNDERSTANDING |
xImageUnderstanding |
否 | Responses | 分析 X 帖子中的图片,按 token 额外计费。默认 false。 |
GROK_X_VIDEO_UNDERSTANDING |
xVideoUnderstanding |
否 | Responses | 分析 X 帖子中的视频,按 token 额外计费。默认 false。 |
GROK_RESPONSES_OPENROUTER_ENGINE |
responsesOpenRouterEngine |
否 | OpenRouter Responses | auto、native、exa、firecrawl、parallel 或 perplexity。默认 auto。 |
GROK_DEFAULT_EXTRA |
defaultExtra |
否 | search.js |
Tavily 与 Firecrawl 合计的默认 extra source 数量。默认 6。 |
GROK_SOURCE_CHARS |
sourceChars |
否 | search.js |
每条 source stdout snippet 长度。默认 400;0 表示不输出 snippet。 |
GROK_MAX_SOURCES |
maxSources |
否 | search.js |
stdout 返回的 source card 数量上限。默认 12;被裁剪的完整列表落盘到 sources.raw_path。 |
GROK_DEADLINE_SECONDS |
deadlineSeconds |
否 | 所有脚本 | 单条命令总耗时上限(秒)。默认 240,0 表示禁用;超时会先输出 DEADLINE_EXCEEDED JSON 再退出。 |
TAVILY_API_KEY |
tavilyApiKey |
否 | search.js、fetch.js、map.js |
启用 Tavily Search / Extract / Map。没有它时,search/fetch 仍可使用 Firecrawl Keyless,map 使用 Direct Map。 |
TAVILY_API_KEYS |
tavilyApiKeys |
否 | Tavily 路径 | 逗号分隔的官方 key 池。配额或鉴权失败才轮换;游标 ~/.cache/grok-search/tavily-rr.json。环境变量优先于配置文件。 |
TAVILY_API_URL |
tavilyApiUrl |
否 | Tavily 路径 | 官方 base,默认 https://api.tavily.com。不要改成第三方代理地址。 |
TAVILY_PROXY_URL |
tavilyProxyUrl |
否 | Tavily 路径 | 第三方兼容 base,去掉尾斜杠。与官方 key 分开配置。 |
TAVILY_PROXY_KEY |
tavilyProxyKey |
否 | Tavily 路径 | 代理 Bearer token。配齐 URL 和 key 后优先打代理。 |
TAVILY_PROXY_TIMEOUT_MS |
tavilyProxyTimeoutMs |
否 | Tavily 路径 | 代理 fail-fast 超时,默认 12000,不重试。search/map 空结果也回落官方;extract 空内容不回落。 |
FIRECRAWL_API_KEY |
firecrawlApiKey |
否 | search.js、fetch.js |
可选。未配置时使用 Firecrawl Keyless;配置后使用独立账户额度和更高限流。 |
FIRECRAWL_API_URL |
firecrawlApiUrl |
否 | Firecrawl 路径 | 默认 https://api.firecrawl.dev/v2。 |
EXA_API_KEY |
exaApiKey |
否 | search.js、fetch.js |
可选。配置后 Exa 加入 --extra 轮转,并作为 fetch.js --provider exa / auto 链的 Contents 渠道。 |
EXA_API_URL |
exaApiUrl |
否 | Exa 路径 | 默认 https://api.exa.ai。 |
GROK_OUTPUT_DIR |
outputDir |
否 | 所有脚本 | 覆盖长输出与运行记录的落盘目录。默认 ~/.cache/grok-search/outputs/。 |
GROK_STATE_DIR |
stateDir |
否 | 所有脚本 | 跨命令状态目录(Firecrawl 额度冷却文件 firecrawl-cooldown.json)。默认 ~/.cache/grok-search/。 |
GROK_RUN_LOG |
runLog |
否 | 所有脚本 | 默认 true,每次调用写一份运行记录 JSON;off / false 关闭后 sources.raw_path / diagnostics.run_path 为 null。 |
GROK_DEBUG_RAW |
— | 否 | search.js |
仅环境变量。设为 1 时把脱敏后的完整 Grok 响应作为 grok_raw 写进运行记录(--full-sources 亦然)。 |
GROK_DEBUG |
— | 否 | 所有脚本 | 仅环境变量。设为 true 时把重试 / 清理 / 代理调试日志写到 stderr。 |
GROK_PROXY |
— | 否 | 所有脚本 | 仅环境变量。显式代理 URL,或设为 off / direct 禁用代理。 |
OpenRouter 使用 openrouter:web_search server tool,不会给模型名追加 :online。
输出 schema
当前版本使用命令原生 JSON 输出。这是相对旧版 ok / kind envelope 的 breaking change。
失败时每个脚本都会返回:
{
"error": {
"message": "...",
"code": "FETCH_ERROR"
},
"diagnostics": {
"warnings": [],
"provider_attempts": []
}
}
成功时,provider attempts、warnings、时间戳和命令选项都放在 diagnostics 下。
Search
./scripts/search.js "What changed in the latest Node.js LTS?"
./scripts/search.js --instructions "只要官方 changelog 的原文和日期,找不到就说" "node lts changelog"
./scripts/search.js --platform GitHub "pi coding agent search skill"
./scripts/search.js --responses-allowed-domains github.com "pi coding agent search skill"
./scripts/search.js --extra 10 "latest pi coding agent docs"
./scripts/search.js --no-extra "query"
./scripts/search.js --source-chars 200 "query"
./scripts/search.js --max-sources 8 "query"
./scripts/search.js --deadline 120 "query"
./scripts/search.js --full-sources "debug provider raw"
./scripts/search.js --responses-openrouter-engine exa "strict web-only query"
./scripts/search.js --source x --responses-parallel-tool-calls false "query" # 每 turn 一次工具调用,省费用
--instructions TEXT 把"要什么"和"搜什么"分开:query 是 Tavily / Firecrawl 原样检索的关键词,指令只追加到发给 Grok 的 user message 末尾(system prompt 前缀不变,prompt cache 不受影响);带指令时 query 前会加一行 # Search query 标题,否则短 query 会被当成时间上下文的一行而丢失(2026-09-08 实测 Grok 回答"未指定主题")。diagnostics.options.instructions_chars 记录长度,运行记录保存全文;没有配置项默认值。
--responses-allowed-domains / --responses-excluded-domains 同时作用于三个通道:Grok 的 web_search filters、Tavily 的 include_domains / exclude_domains、Firecrawl 的 includeDomains / excludeDomains。上游仍漏进来的域外 extra 不丢弃,但排到所有 Grok 结果之后;diagnostics.options.extra_domain_filter 取 pushed / demoted / none,extra 的 provider attempt 带 off_domain 计数。
检索源
--source 选择挂载哪些 Grok 服务端工具,默认 web:
./scripts/search.js --source x "X 上怎么评价 grok-4.6" # 只查 X
./scripts/search.js --source both "grok-4.6 发布后的反响" # Grok 自行路由
./scripts/search.js --source x --responses-allowed-x-handles xai,OpenAI "query"
./scripts/search.js --source x --x-from-date 2026-08-01 --x-to-date 2026-08-16 "query"
./scripts/search.js --source x --x-images "query" # 分析帖子中的图片
x_search支持 handle allow/deny(互斥,各上限 20)、--x-from-date/--x-to-date(YYYY-MM-DD)、--x-images/--x-videos(默认关闭,按 token 额外计费;--no-x-images/--no-x-videos可关掉配置里打开的开关)。- 命令行的 X 过滤参数会把未显式指定的
--source提升为both;与显式--source web同时出现则报SEARCH_SOURCE_CONFLICT。配置文件里的 X 过滤项只在 X 检索开启时生效,不会自己把档位提升上去。 --responses-x-search保留为--source both的别名。- X 检索计费 $5 / 1k calls,与 web search 同价,实际次数见
diagnostics.responses_x_search_calls。 - Tavily / Firecrawl extra 源只搜网页,不搜 X。
--source x下两家默认关闭(diagnostics.options.extra_mode为off-x-only,并写一条 warning),显式--extra N可开启;--source both仍默认开启。 - OpenRouter 会自动把
x_search挂在 native web search 上,--source在该路径下只是提示,未被强制执行时会写入diagnostics.warnings。
X citation 只返回裸 URL、且 title 是 inline citation 序号,因此 source card 会从 URL 还原署名:
{
"provider": "grok-responses",
"source_type": "citation",
"tool": "x_search",
"url": "https://x.com/xai/status/2087942296721559607",
"title": "@xai",
"x_handle": "xai",
"x_post_id": "2087942296721559607"
}
帖子正文与日期不在 card 中,而在 answer.text 里按 handle + 日期署名。
search.js 只使用 Responses 协议,以 stream:false 调用 {GROK_API_URL}/responses,启用 provider-native web search,并返回:
answer.text、answer.chars、answer.original_chars、answer.truncated、answer.full_pathsources.items:单份去重合并后的短 source card 列表,默认最多12条(--max-sources可调);裁剪顺序为citation>opened: true(Grok 用open_page读过的页面)> 域内 extra >searched> 域外 extra。同一 URL 跨通道出现时合并成一张卡,merged_from列出补充了字段的 provider;"1"、[2]这类序号标题视为缺失:有真标题就替换,没有就不输出titlesources.returned/sources.total/sources.omitted:让调用方明确知道是否被截断sources.raw_path:总是有值(除非GROK_RUN_LOG=off),指向本次调用的运行记录:脱敏 argv、query、instructions、生效 options、完整 answer、未裁剪的 source 列表、grok_tool_calls、diagnostics;失败与DEADLINE_EXCEEDED也会写sources.raw,仅在使用--full-sources时出现diagnostics.responses_model:中转实际返回的模型;与请求的不同时warnings里会有一条(2026-09-08 发现某中转对每次grok-4.5请求都返回grok-4.5-build,调用次数和费用是 2–3 倍)diagnostics.grok_endpoint、diagnostics.usage/diagnostics.cost_usd(provider 返回时)、diagnostics.responses_*(responses_tool_calls为{ total, upstream: { web, x } | null, trace: { web, x }, by_action, failed? }摘要,完整列表在raw_path中)、diagnostics.search_budget(prompt 里的软预算与实际次数并列,enforced: false)、diagnostics.warnings、diagnostics.provider_attempts、diagnostics.options、diagnostics.duration_ms、diagnostics.searched_at
默认会同时发起 Grok Responses、Tavily Search(配置 key 时)、Firecrawl Search(keyless 可用)和 Exa Search(配置 key 时)。各渠道并行,extra 结果始终作为独立补充信源,不会注入 Grok input。
--extra N 是每个渠道各自的目标结果数,默认 6:所有配置了的渠道(Tavily / Firecrawl / Exa)各完整搜索 N 条,合并后按 URL 去重(归一化时剥离 utm_*、dub_id、fbclid、gclid 等追踪参数,同页多渠道命中合并为一张卡片、保留最干净的 URL,merged_from 列出所有命中该页的渠道),最终输出由 --max-sources(默认 12)裁剪。请求数与拆分分配相同,但两家按结果量计费:小名额时近乎固定(实测 2–6 条均为 Firecrawl 2 credits、Exa $0.007),名额增大后线性上涨(实测 25 条:Firecrawl 6 credits、Exa $0.022;Tavily 按官方 key/代理计费)。全渠道搜索给去重提供了最多的候选。--no-extra 严格关闭所有外部搜索通道。
当 Grok 明确返回额度耗尽(402/403、额度类错误码如 insufficient_user_usd_credit、正文提到 quota / credits / billing / 余额 / 积分的 4xx)时,无论 extra 是否可用都会得到明确的失败码;若 extra sources 可用,命令会返回标记为 diagnostics.degraded: true 的降级结果:QUOTA_EXHAUSTED(配额)、RATE_LIMITED(存活下来的 429 限流)、NO_SEARCH(中转丢弃了 web_search、只回散文)、EMPTY(空内容)、TIMEOUT(超时 / 408 / 504 / 524)、UPSTREAM(5xx)。answer.text 会明确说明当前仅为 Tavily/Firecrawl/Exa 原始搜索结果,diagnostics.grok_error 保留脱敏后的上游错误。纯认证与协议错误(401/403/422 且无配额特征)保持硬失败,不会被伪装成降级。
Firecrawl Keyless 提供每月 1,000 credits,并受按 IP 的每日限额约束。配置 FIRECRAWL_API_KEY 不会增加免费计划的月度 credits,但能获得更高限流、独立账户额度和更多 API 能力。
额度耗尽时 Firecrawl 返回 429 与 reason: credits、retry_after_seconds(通常数小时)。脚本不再重试,而是把 { until, auth_mode, reason, hit_at } 写进 <stateDir>/firecrawl-cooldown.json;冷却期内 search.js 与 fetch.js --provider auto 直接跳过 Firecrawl(provider attempt 记 skipped: true 与 cooldown until <ISO>),search 的名额转给其余渠道,没有可用渠道时 extra 为空并写 warning。显式 --provider firecrawl 仍会真打,成功后清除冷却。冷却按 auth_mode 区分,换上 API key 立即生效。Exa 余额耗尽(402)以同样机制记录在 <stateDir>/exa-cooldown.json。
通用重试规则:408 / 429 / 5xx 最多重试 3 次,Retry-After(header 或 Firecrawl 的 retry_after_seconds)在重试预算内照等,超出预算即停止而不是截短后继续;坏 JSON、success:false、403 等 4xx、scrape 超时都只请求一次。provider attempt 带 requests(实际 HTTP 次数)与 duration_ms。
Source card 不再输出长 description 或 content 字段,只输出短 snippet。完整 raw 数据可通过 sources.raw_path 按需读取。
Fetch
./scripts/fetch.js https://example.com
./scripts/fetch.js --provider direct https://example.com
fetch 默认只返回 12,000 字符 preview。--max-chars 50000 应作为看过 preview 后的显式深读使用,不是常规默认。
./scripts/fetch.js --max-chars 50000 https://example.com
--provider auto 的 provider 顺序:
Tavily Extract -> Firecrawl Scrape -> Exa Contents -> Direct Fetch
Direct Fetch 是普通 HTTP(S) 文本页面的 best-effort fallback。它会做简单 HTML 清理、尽量格式化 JSON、记录重定向,并拒绝二进制 / 附件 / 超大响应。
Firecrawl Scrape 无 key 时会使用 Keyless;配置 FIRECRAWL_API_KEY 后会自动发送 Bearer token。当前认证模式写入 diagnostics.firecrawl_auth_mode。Exa Contents 需要配置 EXA_API_KEY,按页计费(普通页约 $0.001),metadata 提供 title / author / published_at,attempt 携带 cost_usd;未配置时 auto 链里它只是一条 skipped 记录。
X 原帖(x.com/<handle>/status/<id>)在 --provider auto 下不论是否配置 key 都先走 Direct,校验页面含 @handle、日期与非登录页正文才算成功(只有主帖);校验不过再回到 Tavily → Firecrawl,都不可用时按原样返回 Direct 内容并写 warning。这样定的依据是 2026-09-08 的对照:Tavily 快且免费但三条里一条不带日期、另有一次超时;Firecrawl 每条约 30 credits、10 秒以上,换来 ISO 时间戳、互动数和 thread。需要 thread 时显式 --provider firecrawl。任何一次 credits_used >= 10 都会在 diagnostics.warnings 里说明成本。
X 会把 /<任意handle>/status/<id> 重定向到真实 handle,校验按重定向后的 URL 进行。
fetch 成功输出使用 content.text、content.chars、content.original_chars、content.truncated、content.full_path,metadata 归一为 { title, description, author, published_at, language, status, source_url }(Firecrawl)加 Direct 的 status / content_type / content_length / content_disposition,provider 相关信息放在 diagnostics,运行记录路径在 diagnostics.run_path。
Map
./scripts/map.js https://docs.example.com --limit 20
./scripts/map.js --provider direct https://docs.example.com
./scripts/map.js https://docs.example.com --instructions "only API reference pages" --max-depth 2
--provider auto 的 provider 顺序:
Tavily Map -> Direct Map
没有 TAVILY_API_KEY 时,Tavily Map 不可用,map.js 会 fallback 到 Direct Map。Direct Map 只检查同站点 /sitemap.xml,然后提取首页同域名链接。它会忽略 --instructions,且只支持 --max-depth 1。
--timeout(默认 150 秒)是交给 Tavily Map 的远端 crawl 预算;Direct Map 自己抓 sitemap 和首页时每个请求用独立的 --direct-timeout(默认 30 秒),一个卡住的请求不会吃掉整条命令的 deadline。两个值都记录在 diagnostics.options。
map 成功输出使用 urls 表示发现的 URL。provider、response time、ignored instructions、warnings、attempts 和 options 都放在 diagnostics,运行记录路径在 diagnostics.run_path。
输出文件
所有脚本都会保证 stdout 是完整 JSON。长文本字段会以 preview 形式返回,完整内容写入:
~/.cache/grok-search/outputs/
设置 GROK_OUTPUT_DIR 可以覆盖该路径。每次运行都会 best-effort 清理输出目录中超过 30 天的 grok-search-* 文件。
除 preview 溢出文件外,每次调用还会写一份运行记录 grok-search-<ts>-run-<kind>-<label>-<rand>.json(schema_version: 2,权限 0600),成功、失败、DEADLINE_EXCEEDED 都写;GROK_RUN_LOG=off 或 runLog: false 关闭。search 记录含脱敏 argv、query、instructions、生效 options、完整 answer、未裁剪 sources、grok_tool_calls、diagnostics;fetch 记录含正文全文、metadata、provider_attempts;map 记录含 urls。GROK_DEBUG_RAW=1 或 --full-sources 时再附 grok_raw。
只有 preview 不够时才读取这些路径:
answer.full_path:完整 search answercontent.full_path:完整 fetch 页面正文sources.raw_path:search 的运行记录(完整 source 列表 / provider raw)diagnostics.run_path:fetch / map 的运行记录
Smoke Tests
不需要 key:
./scripts/fetch.js --provider direct https://example.com
./scripts/map.js --provider direct https://example.com --limit 5
node tests/sources.test.js
node tests/proxy.test.js
node tests/responses.test.js
node tests/output.test.js
node tests/retry.test.js
node tests/firecrawl.test.js
node tests/argv.test.js
搜索需要 Grok 配置:
export GROK_API_URL="https://your-openai-compatible-endpoint/v1"
export GROK_API_KEY="your-key"
./scripts/search.js "What changed in the latest Node.js LTS?"
常见错误
GROK_API_URL 未配置:使用search.js前需要设置GROK_API_URL。GROK_API_KEY 未配置:使用search.js前需要设置GROK_API_KEY。GROK_QUOTA_EXHAUSTED:Grok 额度耗尽且 extra 被关闭,或 Tavily/Firecrawl 都没有返回可用降级结果。GROK_RATE_LIMITED:Grok 返回普通 429 限流(非额度信号),且没有可用降级结果。- provider attempt 出现
skipped: true与cooldown until …:Firecrawl 额度耗尽后的冷却期,删除<stateDir>/firecrawl-cooldown.json或显式--provider firecrawl可强制再试。 TAVILY_API_KEY 未配置:显式请求了--provider tavily,但没有配置 Tavily key。- Direct Fetch 返回二进制 / 附件错误:目标 URL 不是文本页面,或对 direct fallback 来说太大。
- Direct Map 返回很少或 0 个 URL:站点可能依赖 JavaScript、隐藏链接,或没有公开 sitemap。
项目边界
当前范围包括:
search.jssearch.js --extra N- 带 Direct Fetch fallback 的
fetch.js - 带 Direct Map fallback 的
map.js - 长输出 preview 和完整输出文件
SKILL.mdreferences/planning.md- smoke / fixture tests
不在范围内:
- 浏览器渲染
- PDF / 图片 / 压缩包解析
- Cookie、登录或反爬绕过
- MCP 会话状态,例如
get_sources - CLI 打包或 build 流程
致谢与来源
本项目参考并改造自 GuDaStudio/GrokSearch:一个基于 Python / MCP 的 Grok Search server。
感谢 GuDaStudio 提供原始项目与思路。本项目在保留核心搜索 / 抓取 / 站点映射能力的基础上,重写为更适合 agent skill 分发的 纯 JS、脚本直跑 形态。
本项目分享于Linuxdo社区。
协议
本项目使用 MIT 协议发布,详见 LICENSE。
原项目同样使用 MIT 协议。我们在 LICENSE 中保留了原项目版权声明,以遵守 MIT 协议要求。
Skill manifest
Grok Search
Node scripts for web search, URL fetch and site mapping. Run npm install once. Run scripts from the grok-search root (the directory of this SKILL.md): cd there or use absolute paths.
Choose The Script
- URL given →
scripts/fetch.js. - Site named, URL unknown →
scripts/map.js, thenfetch.json the URLs you pick. - Current/latest information, or URL unknown →
scripts/search.js. - Question about the user's local machine → inspect local files first; search only to interpret them.
Run the fewest commands that answer the question; run independent sub-questions in parallel. Do not chain map → fetch → search.
Commands
./scripts/search.js "plain keywords"
./scripts/search.js --days 7 "plain keywords"
./scripts/search.js --instructions "what to return, language, what to leave out" "plain keywords"
./scripts/search.js --responses-allowed-domains github.com "plain keywords"
./scripts/search.js --source x --x-from-date 2026-07-01 "what people say about ..."
./scripts/fetch.js https://example.com # --max-chars 50000 only for a deliberate deep read
./scripts/map.js https://docs.example.com --limit 20
Query rules:
- The query is a keyword string that Tavily/Firecrawl search verbatim, so keep it short. Everything else (fields wanted, language, "quote and date only, no advice, say if not found") goes in
--instructions; only Grok sees it. A bag of keywords likeGPT Codex 1M 272k context windowmakes Grok invent background;codex context windowplus an instruction asking for the current limit does not. - No code-search operators (
repo:,path:,language:). Scope with--responses-allowed-domains; it restricts Grok, Tavily, Firecrawl, and Exa alike, and off-domain leftovers rank last. - Budget about 2 searches per question. Before a second search, name the gap it closes. Do not carry the previous round's conclusion words into the keywords; for the same X handle, change the gap, not the phrasing.
Search Source
Default is web. --source x for what people are saying, a named account's posts, a thread, or a claim only circulating on X. --source both for a current event where reporting and reaction both matter. --source x cannot fall back to the web and turns Tavily/Firecrawl/Exa off (--extra N forces them).
- For "is it available now / current state" questions, start with
--x-from-date60–90 days back; widen only if empty. Old issues explain history, not the present. - X posts are personal statements: cite handle and date (both live in
answer.text, not the card), keep claims separate from confirmations, confirm facts at the official source. - Cost: when an X search reports
responses_tool_calls.totalabove 6, add--responses-parallel-tool-calls falsenext time: one agent call per turn on relays that honor it (2026-11-03, grok-4.20 multi-agent: trace 4→1, cost −35%). Multi-agent models still fan out server-side searches, sototalcan stay high — read the effect offtrace, nottotal. Below 6 it saves nothing. - Handle filters, dates, media flags, card fields:
references/x-search.md.
Fetch Cost
- X posts:
autotries Direct first (free, main post with date).--provider firecrawlonly for the thread or replies; about 30 credits per post. --provider exafetches a page through Exa Contents (needsEXA_API_KEY, ~$0.001/page); inautoit runs after Tavily and Firecrawl.- Firecrawl works without a key: Keyless gives 1,000 credits/month plus a small per-IP daily cap, so a 30-credit X fetch burns it fast.
- Fetch only evidence that would change the conclusion: one or two URLs per turn, a representative post or two for experience reports, never re-fetch text you have. Reddit and YouTube return shells from every provider.
- When citing decisive evidence, record date, model version, client, and login method.
Reading Results
Every script prints one JSON object, also on failure (non-zero exit, stderr line).
error: readerror.message,error.code,diagnostics.provider_attempts. Change something before retrying (query,--provider,--model).DEADLINE_EXCEEDED: the whole command hit its time budget (default 240s,--deadline N).diagnostics.warningsanddiagnostics.provider_attemptssay which providers were skipped (e.g. Firecrawl in cooldown), failed, or produced content, and whether the relay served another model than requested.- Search:
answer.text, thensources.items(merged and cross-channel deduped, max 12).source_typecitation= used in the answer,searched= only listed;opened: true= Grok read the page.sources.raw_pathalways points to the run record (full list, answer, tool calls); read it in chunks only when the cards are not enough. Checkdiagnostics.degraded,cost_usd, andsearch_budget(advisory budget vs. calls made). A degraded answer is built from raw Tavily/Firecrawl/Exa results when Grok quota is exhausted, the relay times out or returns 5xx, or Responses returns no usable sources. Auth and protocol errors (401/403/422 without a quota error body) stay errors even when extras exist. - Fetch:
content.text; ifcontent.truncated, readcontent.full_pathin chunks or rerun once with a larger--max-chars.metadatahas title/author/published_at when the provider had them. A non-2xx page (e.g. 404) still returns content — checkmetadata.statusbefore trusting it.diagnostics.run_pathis the run record. - Map:
urls; fetch the few you need.
Provider order, proxy, cooldown, config errors: references/providers.md. Multi-part or conflicting research: references/planning.md first.
Files (awesome-skills)
-
agents
-
openai.yaml 230 B
Loading…
-
-
benchmarks
-
lib
-
benchmark-15q-v2.mjs 16 KB · in bundle
-
-
public
-
2026-07-11-summary.json 969 B
Loading…
-
-
provider-compare.mjs 15.9 KB · in bundle
-
README.md 2.3 KB
Loading… -
run-responses-15q.mjs 3.6 KB · in bundle
-
score-responses-15q.mjs 5.3 KB · in bundle
-
tool-call-cap-experiment.mjs 8.4 KB · in bundle
-
-
docs
-
architecture.md 8.5 KB
Loading… -
benchmark.md 1.5 KB
Loading… -
features.md 7 KB
Loading… -
responses-mode.md 10.7 KB
Loading… -
smoke-tests.md 6.5 KB
Loading… -
web-search-evaluation-research.md 28.8 KB
Loading…
-
-
references
-
planning.md 3.5 KB
Loading… -
providers.md 8.5 KB
Loading… -
x-search.md 6.7 KB
Loading…
-
-
scripts
-
lib
-
config.js 15.9 KB
Loading… -
context.js 810 B
Loading… -
cooldown.js 4.5 KB
Loading… -
deadline.js 293 B
Loading… -
direct.js 16.6 KB
Loading… -
exa.js 6 KB
Loading… -
firecrawl.js 6.8 KB
Loading… -
grok-responses.js 24.2 KB
Loading… -
http.js 6.9 KB
Loading… -
output.js 5.4 KB
Loading… -
prompts.js 4.1 KB
Loading… -
providers.js 9.3 KB
Loading… -
proxy.js 5.3 KB
Loading… -
search-argv.js 13.5 KB
Loading… -
search-degrade.js 3.7 KB
Loading… -
search-extras.js 5.4 KB
Loading… -
search-filters.js 3.7 KB
Loading… -
search-options.js 7.3 KB
Loading… -
sources.js 10.7 KB
Loading… -
tavily.js 13.4 KB
Loading… -
usage.js 826 B
Loading…
-
-
fetch.js 8.2 KB
Loading… -
map.js 8.2 KB
Loading… -
search.js 12.5 KB
Loading…
-
-
tests
-
argv.test.js 64.1 KB
Loading… -
exa.test.js 10.1 KB
Loading… -
firecrawl.test.js 16.8 KB
Loading… -
output.test.js 3 KB
Loading… -
proxy.test.js 1.3 KB
Loading… -
request-json-fallback.test.js 2.7 KB
Loading… -
responses.test.js 21.2 KB
Loading… -
retry.test.js 5.7 KB
Loading… -
sources.test.js 9.2 KB
Loading… -
tavily-keys.test.js 8 KB
Loading… -
tavily-proxy-failfast.test.js 5 KB
Loading… -
test_skill_package.py 3.2 KB
Loading…
-
-
.gitignore 673 B · in bundle
-
config.example.json 986 B
Loading… -
LICENSE 1.1 KB · in bundle
-
package-lock.json 657 B
Loading… -
package.json 1008 B
Loading… -
README.en.md 31.6 KB
Loading… -
README.md 30.5 KB
# 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) - Agent 侧说明:[SKILL.md](SKILL.md)(每轮都读,≤5k 字)与按需阅读的 [references/x-search.md](references/x-search.md)、[references/providers.md](references/providers.md)、[references/planning.md](references/planning.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.20-multi-agent-0309", "responsesMaxTurns": 3, "responsesReasoningEffort": "low", "responsesAllowedDomains": [], "responsesExcludedDomains": [], "responsesAllowedXHandles": [], "responsesExcludedXHandles": [], "responsesOpenRouterEngine": "auto", "defaultExtra": 6, "sourceChars": 400, "tavilyApiKey": "", "tavilyApiKeys": [], "tavilyApiUrl": "https://api.tavily.com", "tavilyProxyUrl": "", "tavilyProxyKey": "", "tavilyProxyTimeoutMs": 12000, "firecrawlApiKey": "", "firecrawlApiUrl": "https://api.firecrawl.dev/v2", "exaApiKey": "", "exaApiUrl": "https://api.exa.ai", "outputDir": "", "stateDir": "", "runLog": true } ``` 常见填写规则: - `apiUrl` 填支持 `/responses` 的 API base URL;脚本会请求 `{apiUrl}/responses`,不要把 `/responses` 本身写进去。 - `apiProvider` 一次只能填写一个值: - `xai`:xAI 官方接口,按 `searchSource` 使用 `web_search` 与 `x_search`。 - `openrouter`:OpenRouter 接口,改用 `openrouter:web_search`;可通过 `responsesOpenRouterEngine` 选择搜索引擎。 - `openai-compatible`:支持 xAI 风格 Responses 与 `web_search` tool 的中转、反代或兼容服务。仅支持 Chat Completions 的接口不能使用。 - `apiProvider` 省略时会按 URL 推断:包含 `openrouter` 视为 `openrouter`,包含 `api.x.ai` 视为 `xai`,其他 URL 视为 `openai-compatible`。中转服务建议显式填写,避免请求格式判断错误。 - `model` 必须填写该 endpoint 实际支持的模型 ID;`responsesMaxTurns` 是不小于 1 的整数。`responsesReasoningEffort` 常见值为 `low`、`medium`、`high`,但是否支持取决于具体模型与 provider。 - `responsesAllowedDomains`、`responsesExcludedDomains`、`responsesAllowedXHandles`、`responsesExcludedXHandles` 都是数组,可以填写多个值,例如 `["github.com", "docs.python.org"]`;同一组 allowed 与 excluded 不能同时使用。domain 上限 5 个,X handle 上限 20 个。环境变量中的多值使用逗号分隔。 - `searchSource` 可选 `web`、`x` 或 `both`,决定默认挂载哪些检索工具;命令行 `--source` 优先。X 的日期窗口是按查询变化的,只能用 `--x-from-date` / `--x-to-date` 传入,没有对应配置项。 - 旧配置项 `responsesIncludeXSearch` / `GROK_RESPONSES_INCLUDE_X_SEARCH` 已移除(2026-08 弃用,2026-09 删除)。值为 `true` 时命令直接报 `CONFIG_OPTION_REMOVED` 而不是静默丢掉 X 检索,请改为 `searchSource: "both"`;`false` 或缺失不受影响。 - 优先级为 命令行 > 环境变量 > 配置文件 > 默认值。注意配置文件由你书写、命令行参数由调用本工具的 agent 书写:标量配置(如 `searchSource`)是**默认值**,agent 可以覆盖,实际生效值见 `diagnostics.options`;但配置里的**限制**不会被静默抹掉——allow-list 与 deny-list 都是限制,命令行只能收紧不能放宽。越界报 `RESPONSES_FILTER_FORBIDDEN`,把 allow-list 减空报 `RESPONSES_FILTER_EMPTY`,两个 deny-list 合并而非替换。规则见 [docs/responses-mode.md](docs/responses-mode.md#配置与命令行的优先级)。 - `responsesOpenRouterEngine` 可选 `auto`、`native`、`exa`、`firecrawl`、`parallel` 或 `perplexity`,仅在 `apiProvider` 为 `openrouter` 时生效。 - `tavilyApiKey` 可留空;多把官方 key 写进 `tavilyApiKeys`(或环境变量 `TAVILY_API_KEYS`,逗号分隔),配额或鉴权失败时才轮到下一把,游标在 `~/.cache/grok-search/tavily-rr.json`。`tavilyProxyUrl` + `tavilyProxyKey` 是另一套第三方兼容入口:先打代理(默认 12 秒、不重试),HTTP 失败或 search/map 空结果再回落官方 key。不要把代理 URL 写进 `tavilyApiUrl`,两边的 key 不通用。`firecrawlApiKey` 也可留空并使用 Firecrawl Keyless。`exaApiKey` 可选,配置后 Exa 加入 search 的 extra 轮转与 fetch 的 auto 链(注意它与 OpenRouter 引擎值 `exa` 无关,后者仅在 `apiProvider` 为 `openrouter` 时生效)。`outputDir` 留空时使用默认目录 `~/.cache/grok-search/outputs/`;`stateDir` 留空时使用 `~/.cache/grok-search/`,存放 Firecrawl 冷却状态;`runLog: false` 关闭每次调用的运行记录落盘。 如果使用 OpenRouter,核心字段可改为: ```json { "apiUrl": "https://openrouter.ai/api/v1", "apiKey": "your-openrouter-api-key", "apiProvider": "openrouter", "model": "your-openrouter-model-id", "responsesOpenRouterEngine": "auto" } ``` 如果使用 Responses-compatible 中转服务,核心字段可改为: ```json { "apiUrl": "https://your-endpoint.example/v1", "apiKey": "your-api-key", "apiProvider": "openai-compatible", "model": "the-model-id-supported-by-your-endpoint" } ``` 然后编辑复制过去的文件,填入真实 key。环境变量仍然优先于配置文件,适合临时覆盖或 CI 使用。 本项目**不会自动加载 `.env` 文件**。如果你想用环境变量,请自己在 shell 里 export。 ### 代理 Node 原生 `fetch` 默认不会可靠读取终端代理变量。本项目会在检测到代理环境变量时自动安装 `undici` 的 `EnvHttpProxyAgent`,让所有出站请求走你的终端代理配置。 支持的变量: - `HTTP_PROXY` / `http_proxy` - `HTTPS_PROXY` / `https_proxy` - `ALL_PROXY` / `all_proxy` - `NO_PROXY` / `no_proxy` - `GROK_PROXY`:显式给本工具指定一个代理 URL;设为 `GROK_PROXY=off` 可强制直连。显式配置无效时命令会直接失败(`PROXY_CONFIG_INVALID`),不会静默退回直连;环境继承的代理失败则继续运行,并通过 search 的 `diagnostics.options.proxy_mode` 暴露状态 `NO_PROXY` 会被尊重,并且会始终把回环地址(`localhost`、`127.0.0.1`、`::1`)加入绕过列表。 | 环境变量 | 配置文件 key | 是否必需 | 用途 | 说明 | | --- | --- | --- | --- | --- | | `GROK_API_URL` | `apiUrl` | search 必需 | `search.js` | 支持 `/responses` 的 base URL。 | | `GROK_API_KEY` | `apiKey` | search 必需 | `search.js` | `GROK_API_URL` 对应的 API key。 | | `GROK_API_PROVIDER` | `apiProvider` | 否 | `search.js` | 选择 Responses tool 请求格式,而不是额外的搜索源;可选 `xai`、`openrouter` 或 `openai-compatible`。未配置时按 URL 推断。 | | `GROK_MODEL` | `model` | 否 | `search.js` | 默认 `grok-4.20-multi-agent-0309`。该模型在 CPA 兼容上游会自己执行服务端 `web_search`;普通 Chat Completions 模型和免费 CLI 账号池不会。 | | `GROK_RESPONSES_MAX_TURNS` | `responsesMaxTurns` | 否 | Responses | 默认 `3`,控制 Responses agentic turn 上限;只对 X 搜索是硬上限,web 搜索不受它约束。 | | `GROK_RESPONSES_REASONING_EFFORT` | `responsesReasoningEffort` | 否 | Responses | 默认 `low`。 | | `GROK_RESPONSES_PARALLEL_TOOL_CALLS` | `responsesParallelToolCalls` | 否 | Responses | `true` / `false`;默认不发送。`false` 让 Grok 每个 turn 只做一次服务端工具调用,官方 `api.x.ai` 与透传的中转都回显 `false`,X 搜索被压到每 turn 一次、`max_turns` 成为硬上限(2026-09-08 实测:grok-4.5 经中转 7–14 次降到 3 次、费用约三分之一;grok-4.6 无论官方还是中转自然只 3–4 次,降到 3 次费用持平,`responses_tool_calls.total` 超过 6 再加);不透传的中转会回显 `true`。`max_tool_calls` 官方与中转都不生效,未接入。命令行 `--responses-parallel-tool-calls false`。2026-11-03 补充:grok-4.20-multi-agent-0309 经透传中转,flag 生效于 agent 层(trace 4→1、费用 $0.64→$0.41),但上游 x_search 仍 19–21 次——多智能体在服务端扇出,`total` 不再被 `max_turns` 封顶,效果看 `trace` 而非 `total`。 | | `GROK_RESPONSES_ALLOWED_DOMAINS` | `responsesAllowedDomains` | 否 | Responses | 逗号分隔 domain allow-list,最多 5 个;与 excluded 互斥。 | | `GROK_RESPONSES_EXCLUDED_DOMAINS` | `responsesExcludedDomains` | 否 | Responses | 逗号分隔 domain deny-list,最多 5 个;与 allowed 互斥。 | | `GROK_SEARCH_SOURCE` | `searchSource` | 否 | Responses | 默认检索源:`web`、`x` 或 `both`。默认 `web`。 | | `GROK_RESPONSES_ALLOWED_X_HANDLES` | `responsesAllowedXHandles` | 否 | Responses | X handle allow-list,最多 20 个;与 excluded 互斥。 | | `GROK_RESPONSES_EXCLUDED_X_HANDLES` | `responsesExcludedXHandles` | 否 | Responses | X handle deny-list,最多 20 个;与 allowed 互斥。 | | `GROK_X_IMAGE_UNDERSTANDING` | `xImageUnderstanding` | 否 | Responses | 分析 X 帖子中的图片,按 token 额外计费。默认 `false`。 | | `GROK_X_VIDEO_UNDERSTANDING` | `xVideoUnderstanding` | 否 | Responses | 分析 X 帖子中的视频,按 token 额外计费。默认 `false`。 | | `GROK_RESPONSES_OPENROUTER_ENGINE` | `responsesOpenRouterEngine` | 否 | OpenRouter Responses | `auto`、`native`、`exa`、`firecrawl`、`parallel` 或 `perplexity`。默认 `auto`。 | | `GROK_DEFAULT_EXTRA` | `defaultExtra` | 否 | `search.js` | Tavily 与 Firecrawl 合计的默认 extra source 数量。默认 `6`。 | | `GROK_SOURCE_CHARS` | `sourceChars` | 否 | `search.js` | 每条 source stdout snippet 长度。默认 `400`;`0` 表示不输出 snippet。 | | `GROK_MAX_SOURCES` | `maxSources` | 否 | `search.js` | stdout 返回的 source card 数量上限。默认 `12`;被裁剪的完整列表落盘到 `sources.raw_path`。 | | `GROK_DEADLINE_SECONDS` | `deadlineSeconds` | 否 | 所有脚本 | 单条命令总耗时上限(秒)。默认 `240`,`0` 表示禁用;超时会先输出 `DEADLINE_EXCEEDED` JSON 再退出。 | | `TAVILY_API_KEY` | `tavilyApiKey` | 否 | `search.js`、`fetch.js`、`map.js` | 启用 Tavily Search / Extract / Map。没有它时,search/fetch 仍可使用 Firecrawl Keyless,map 使用 Direct Map。 | | `TAVILY_API_KEYS` | `tavilyApiKeys` | 否 | Tavily 路径 | 逗号分隔的官方 key 池。配额或鉴权失败才轮换;游标 `~/.cache/grok-search/tavily-rr.json`。环境变量优先于配置文件。 | | `TAVILY_API_URL` | `tavilyApiUrl` | 否 | Tavily 路径 | 官方 base,默认 `https://api.tavily.com`。不要改成第三方代理地址。 | | `TAVILY_PROXY_URL` | `tavilyProxyUrl` | 否 | Tavily 路径 | 第三方兼容 base,去掉尾斜杠。与官方 key 分开配置。 | | `TAVILY_PROXY_KEY` | `tavilyProxyKey` | 否 | Tavily 路径 | 代理 Bearer token。配齐 URL 和 key 后优先打代理。 | | `TAVILY_PROXY_TIMEOUT_MS` | `tavilyProxyTimeoutMs` | 否 | Tavily 路径 | 代理 fail-fast 超时,默认 `12000`,不重试。search/map 空结果也回落官方;extract 空内容不回落。 | | `FIRECRAWL_API_KEY` | `firecrawlApiKey` | 否 | `search.js`、`fetch.js` | 可选。未配置时使用 Firecrawl Keyless;配置后使用独立账户额度和更高限流。 | | `FIRECRAWL_API_URL` | `firecrawlApiUrl` | 否 | Firecrawl 路径 | 默认 `https://api.firecrawl.dev/v2`。 | | `EXA_API_KEY` | `exaApiKey` | 否 | `search.js`、`fetch.js` | 可选。配置后 Exa 加入 `--extra` 轮转,并作为 `fetch.js --provider exa` / auto 链的 Contents 渠道。 | | `EXA_API_URL` | `exaApiUrl` | 否 | Exa 路径 | 默认 `https://api.exa.ai`。 | | `GROK_OUTPUT_DIR` | `outputDir` | 否 | 所有脚本 | 覆盖长输出与运行记录的落盘目录。默认 `~/.cache/grok-search/outputs/`。 | | `GROK_STATE_DIR` | `stateDir` | 否 | 所有脚本 | 跨命令状态目录(Firecrawl 额度冷却文件 `firecrawl-cooldown.json`)。默认 `~/.cache/grok-search/`。 | | `GROK_RUN_LOG` | `runLog` | 否 | 所有脚本 | 默认 `true`,每次调用写一份运行记录 JSON;`off` / `false` 关闭后 `sources.raw_path` / `diagnostics.run_path` 为 null。 | | `GROK_DEBUG_RAW` | — | 否 | `search.js` | 仅环境变量。设为 `1` 时把脱敏后的完整 Grok 响应作为 `grok_raw` 写进运行记录(`--full-sources` 亦然)。 | | `GROK_DEBUG` | — | 否 | 所有脚本 | 仅环境变量。设为 `true` 时把重试 / 清理 / 代理调试日志写到 stderr。 | | `GROK_PROXY` | — | 否 | 所有脚本 | 仅环境变量。显式代理 URL,或设为 `off` / `direct` 禁用代理。 | OpenRouter 使用 `openrouter:web_search` server tool,不会给模型名追加 `:online`。 ## 输出 schema 当前版本使用命令原生 JSON 输出。这是相对旧版 `ok` / `kind` envelope 的 **breaking change**。 失败时每个脚本都会返回: ```json { "error": { "message": "...", "code": "FETCH_ERROR" }, "diagnostics": { "warnings": [], "provider_attempts": [] } } ``` 成功时,provider attempts、warnings、时间戳和命令选项都放在 `diagnostics` 下。 ## Search ```bash ./scripts/search.js "What changed in the latest Node.js LTS?" ./scripts/search.js --instructions "只要官方 changelog 的原文和日期,找不到就说" "node lts changelog" ./scripts/search.js --platform GitHub "pi coding agent search skill" ./scripts/search.js --responses-allowed-domains github.com "pi coding agent search skill" ./scripts/search.js --extra 10 "latest pi coding agent docs" ./scripts/search.js --no-extra "query" ./scripts/search.js --source-chars 200 "query" ./scripts/search.js --max-sources 8 "query" ./scripts/search.js --deadline 120 "query" ./scripts/search.js --full-sources "debug provider raw" ./scripts/search.js --responses-openrouter-engine exa "strict web-only query" ./scripts/search.js --source x --responses-parallel-tool-calls false "query" # 每 turn 一次工具调用,省费用 ``` `--instructions TEXT` 把"要什么"和"搜什么"分开:query 是 Tavily / Firecrawl 原样检索的关键词,指令只追加到发给 Grok 的 user message 末尾(system prompt 前缀不变,prompt cache 不受影响);带指令时 query 前会加一行 `# Search query` 标题,否则短 query 会被当成时间上下文的一行而丢失(2026-09-08 实测 Grok 回答"未指定主题")。`diagnostics.options.instructions_chars` 记录长度,运行记录保存全文;没有配置项默认值。 `--responses-allowed-domains` / `--responses-excluded-domains` 同时作用于三个通道:Grok 的 `web_search` filters、Tavily 的 `include_domains` / `exclude_domains`、Firecrawl 的 `includeDomains` / `excludeDomains`。上游仍漏进来的域外 extra 不丢弃,但排到所有 Grok 结果之后;`diagnostics.options.extra_domain_filter` 取 `pushed` / `demoted` / `none`,extra 的 provider attempt 带 `off_domain` 计数。 ### 检索源 `--source` 选择挂载哪些 Grok 服务端工具,默认 `web`: ```bash ./scripts/search.js --source x "X 上怎么评价 grok-4.6" # 只查 X ./scripts/search.js --source both "grok-4.6 发布后的反响" # Grok 自行路由 ./scripts/search.js --source x --responses-allowed-x-handles xai,OpenAI "query" ./scripts/search.js --source x --x-from-date 2026-08-01 --x-to-date 2026-08-16 "query" ./scripts/search.js --source x --x-images "query" # 分析帖子中的图片 ``` - `x_search` 支持 handle allow/deny(互斥,各上限 20)、`--x-from-date` / `--x-to-date`(`YYYY-MM-DD`)、`--x-images` / `--x-videos`(默认关闭,按 token 额外计费;`--no-x-images` / `--no-x-videos` 可关掉配置里打开的开关)。 - **命令行**的 X 过滤参数会把未显式指定的 `--source` 提升为 `both`;与显式 `--source web` 同时出现则报 `SEARCH_SOURCE_CONFLICT`。配置文件里的 X 过滤项只在 X 检索开启时生效,不会自己把档位提升上去。 - `--responses-x-search` 保留为 `--source both` 的别名。 - X 检索计费 $5 / 1k calls,与 web search 同价,实际次数见 `diagnostics.responses_x_search_calls`。 - Tavily / Firecrawl extra 源只搜网页,不搜 X。`--source x` 下两家默认关闭(`diagnostics.options.extra_mode` 为 `off-x-only`,并写一条 warning),显式 `--extra N` 可开启;`--source both` 仍默认开启。 - OpenRouter 会自动把 `x_search` 挂在 native web search 上,`--source` 在该路径下只是提示,未被强制执行时会写入 `diagnostics.warnings`。 X citation 只返回裸 URL、且 `title` 是 inline citation 序号,因此 source card 会从 URL 还原署名: ```json { "provider": "grok-responses", "source_type": "citation", "tool": "x_search", "url": "https://x.com/xai/status/2087942296721559607", "title": "@xai", "x_handle": "xai", "x_post_id": "2087942296721559607" } ``` 帖子正文与日期不在 card 中,而在 `answer.text` 里按 handle + 日期署名。 `search.js` 只使用 Responses 协议,以 `stream:false` 调用 `{GROK_API_URL}/responses`,启用 provider-native web search,并返回: - `answer.text`、`answer.chars`、`answer.original_chars`、`answer.truncated`、`answer.full_path` - `sources.items`:单份去重合并后的短 source card 列表,默认最多 `12` 条(`--max-sources` 可调);裁剪顺序为 `citation` > `opened: true`(Grok 用 `open_page` 读过的页面)> 域内 extra > `searched` > 域外 extra。同一 URL 跨通道出现时合并成一张卡,`merged_from` 列出补充了字段的 provider;`"1"`、`[2]` 这类序号标题视为缺失:有真标题就替换,没有就不输出 `title` - `sources.returned` / `sources.total` / `sources.omitted`:让调用方明确知道是否被截断 - `sources.raw_path`:总是有值(除非 `GROK_RUN_LOG=off`),指向本次调用的运行记录:脱敏 argv、query、instructions、生效 options、完整 answer、未裁剪的 source 列表、`grok_tool_calls`、diagnostics;失败与 `DEADLINE_EXCEEDED` 也会写 - `sources.raw`,仅在使用 `--full-sources` 时出现 - `diagnostics.responses_model`:中转实际返回的模型;与请求的不同时 `warnings` 里会有一条(2026-09-08 发现某中转对每次 `grok-4.5` 请求都返回 `grok-4.5-build`,调用次数和费用是 2–3 倍) - `diagnostics.grok_endpoint`、`diagnostics.usage` / `diagnostics.cost_usd`(provider 返回时)、`diagnostics.responses_*`(`responses_tool_calls` 为 `{ total, upstream: { web, x } | null, trace: { web, x }, by_action, failed? }` 摘要,完整列表在 `raw_path` 中)、`diagnostics.search_budget`(prompt 里的软预算与实际次数并列,`enforced: false`)、`diagnostics.warnings`、`diagnostics.provider_attempts`、`diagnostics.options`、`diagnostics.duration_ms`、`diagnostics.searched_at` 默认会同时发起 Grok Responses、Tavily Search(配置 key 时)、Firecrawl Search(keyless 可用)和 Exa Search(配置 key 时)。各渠道并行,extra 结果始终作为独立补充信源,不会注入 Grok input。 `--extra N` 是**每个渠道各自**的目标结果数,默认 `6`:所有配置了的渠道(Tavily / Firecrawl / Exa)各完整搜索 N 条,合并后按 URL 去重(归一化时剥离 `utm_*`、`dub_id`、`fbclid`、`gclid` 等追踪参数,同页多渠道命中合并为一张卡片、保留最干净的 URL,`merged_from` 列出所有命中该页的渠道),最终输出由 `--max-sources`(默认 12)裁剪。请求数与拆分分配相同,但两家按结果量计费:小名额时近乎固定(实测 2–6 条均为 Firecrawl 2 credits、Exa $0.007),名额增大后线性上涨(实测 25 条:Firecrawl 6 credits、Exa $0.022;Tavily 按官方 key/代理计费)。全渠道搜索给去重提供了最多的候选。`--no-extra` 严格关闭所有外部搜索通道。 当 Grok 明确返回额度耗尽(402/403、额度类错误码如 `insufficient_user_usd_credit`、正文提到 quota / credits / billing / 余额 / 积分的 4xx)时,无论 extra 是否可用都会得到明确的失败码;若 extra sources 可用,命令会返回标记为 `diagnostics.degraded: true` 的降级结果:`QUOTA_EXHAUSTED`(配额)、`RATE_LIMITED`(存活下来的 429 限流)、`NO_SEARCH`(中转丢弃了 web_search、只回散文)、`EMPTY`(空内容)、`TIMEOUT`(超时 / 408 / 504 / 524)、`UPSTREAM`(5xx)。`answer.text` 会明确说明当前仅为 Tavily/Firecrawl/Exa 原始搜索结果,`diagnostics.grok_error` 保留脱敏后的上游错误。纯认证与协议错误(401/403/422 且无配额特征)保持硬失败,不会被伪装成降级。 Firecrawl Keyless 提供每月 1,000 credits,并受按 IP 的每日限额约束。配置 `FIRECRAWL_API_KEY` 不会增加免费计划的月度 credits,但能获得更高限流、独立账户额度和更多 API 能力。 额度耗尽时 Firecrawl 返回 429 与 `reason: credits`、`retry_after_seconds`(通常数小时)。脚本不再重试,而是把 `{ until, auth_mode, reason, hit_at }` 写进 `<stateDir>/firecrawl-cooldown.json`;冷却期内 `search.js` 与 `fetch.js --provider auto` 直接跳过 Firecrawl(provider attempt 记 `skipped: true` 与 `cooldown until <ISO>`),search 的名额转给其余渠道,没有可用渠道时 extra 为空并写 warning。显式 `--provider firecrawl` 仍会真打,成功后清除冷却。冷却按 `auth_mode` 区分,换上 API key 立即生效。Exa 余额耗尽(402)以同样机制记录在 `<stateDir>/exa-cooldown.json`。 通用重试规则:408 / 429 / 5xx 最多重试 3 次,`Retry-After`(header 或 Firecrawl 的 `retry_after_seconds`)在重试预算内照等,超出预算即停止而不是截短后继续;坏 JSON、`success:false`、403 等 4xx、scrape 超时都只请求一次。provider attempt 带 `requests`(实际 HTTP 次数)与 `duration_ms`。 Source card 不再输出长 `description` 或 `content` 字段,只输出短 `snippet`。完整 raw 数据可通过 `sources.raw_path` 按需读取。 ## Fetch ```bash ./scripts/fetch.js https://example.com ./scripts/fetch.js --provider direct https://example.com ``` fetch 默认只返回 12,000 字符 preview。`--max-chars 50000` 应作为看过 preview 后的显式深读使用,不是常规默认。 ```bash ./scripts/fetch.js --max-chars 50000 https://example.com ``` `--provider auto` 的 provider 顺序: ```text Tavily Extract -> Firecrawl Scrape -> Exa Contents -> Direct Fetch ``` Direct Fetch 是普通 HTTP(S) 文本页面的 best-effort fallback。它会做简单 HTML 清理、尽量格式化 JSON、记录重定向,并拒绝二进制 / 附件 / 超大响应。 Firecrawl Scrape 无 key 时会使用 Keyless;配置 `FIRECRAWL_API_KEY` 后会自动发送 Bearer token。当前认证模式写入 `diagnostics.firecrawl_auth_mode`。Exa Contents 需要配置 `EXA_API_KEY`,按页计费(普通页约 $0.001),`metadata` 提供 `title / author / published_at`,attempt 携带 `cost_usd`;未配置时 auto 链里它只是一条 `skipped` 记录。 X 原帖(`x.com/<handle>/status/<id>`)在 `--provider auto` 下不论是否配置 key 都先走 Direct,校验页面含 `@handle`、日期与非登录页正文才算成功(只有主帖);校验不过再回到 Tavily → Firecrawl,都不可用时按原样返回 Direct 内容并写 warning。这样定的依据是 2026-09-08 的对照:Tavily 快且免费但三条里一条不带日期、另有一次超时;Firecrawl 每条约 30 credits、10 秒以上,换来 ISO 时间戳、互动数和 thread。需要 thread 时显式 `--provider firecrawl`。任何一次 `credits_used >= 10` 都会在 `diagnostics.warnings` 里说明成本。 X 会把 `/<任意handle>/status/<id>` 重定向到真实 handle,校验按重定向后的 URL 进行。 fetch 成功输出使用 `content.text`、`content.chars`、`content.original_chars`、`content.truncated`、`content.full_path`,`metadata` 归一为 `{ title, description, author, published_at, language, status, source_url }`(Firecrawl)加 Direct 的 `status / content_type / content_length / content_disposition`,provider 相关信息放在 `diagnostics`,运行记录路径在 `diagnostics.run_path`。 ## Map ```bash ./scripts/map.js https://docs.example.com --limit 20 ./scripts/map.js --provider direct https://docs.example.com ./scripts/map.js https://docs.example.com --instructions "only API reference pages" --max-depth 2 ``` `--provider auto` 的 provider 顺序: ```text Tavily Map -> Direct Map ``` 没有 `TAVILY_API_KEY` 时,Tavily Map 不可用,`map.js` 会 fallback 到 Direct Map。Direct Map 只检查同站点 `/sitemap.xml`,然后提取首页同域名链接。它会忽略 `--instructions`,且只支持 `--max-depth 1`。 `--timeout`(默认 150 秒)是交给 Tavily Map 的远端 crawl 预算;Direct Map 自己抓 sitemap 和首页时每个请求用独立的 `--direct-timeout`(默认 30 秒),一个卡住的请求不会吃掉整条命令的 deadline。两个值都记录在 `diagnostics.options`。 map 成功输出使用 `urls` 表示发现的 URL。provider、response time、ignored instructions、warnings、attempts 和 options 都放在 `diagnostics`,运行记录路径在 `diagnostics.run_path`。 ## 输出文件 所有脚本都会保证 stdout 是完整 JSON。长文本字段会以 preview 形式返回,完整内容写入: ```text ~/.cache/grok-search/outputs/ ``` 设置 `GROK_OUTPUT_DIR` 可以覆盖该路径。每次运行都会 best-effort 清理输出目录中超过 30 天的 `grok-search-*` 文件。 除 preview 溢出文件外,每次调用还会写一份运行记录 `grok-search-<ts>-run-<kind>-<label>-<rand>.json`(`schema_version: 2`,权限 0600),成功、失败、`DEADLINE_EXCEEDED` 都写;`GROK_RUN_LOG=off` 或 `runLog: false` 关闭。search 记录含脱敏 argv、query、instructions、生效 options、完整 answer、未裁剪 sources、`grok_tool_calls`、diagnostics;fetch 记录含正文全文、metadata、provider_attempts;map 记录含 urls。`GROK_DEBUG_RAW=1` 或 `--full-sources` 时再附 `grok_raw`。 只有 preview 不够时才读取这些路径: - `answer.full_path`:完整 search answer - `content.full_path`:完整 fetch 页面正文 - `sources.raw_path`:search 的运行记录(完整 source 列表 / provider raw) - `diagnostics.run_path`:fetch / map 的运行记录 ## Smoke Tests 不需要 key: ```bash ./scripts/fetch.js --provider direct https://example.com ./scripts/map.js --provider direct https://example.com --limit 5 node tests/sources.test.js node tests/proxy.test.js node tests/responses.test.js node tests/output.test.js node tests/retry.test.js node tests/firecrawl.test.js node tests/argv.test.js ``` 搜索需要 Grok 配置: ```bash export GROK_API_URL="https://your-openai-compatible-endpoint/v1" export GROK_API_KEY="your-key" ./scripts/search.js "What changed in the latest Node.js LTS?" ``` ## 常见错误 - `GROK_API_URL 未配置`:使用 `search.js` 前需要设置 `GROK_API_URL`。 - `GROK_API_KEY 未配置`:使用 `search.js` 前需要设置 `GROK_API_KEY`。 - `GROK_QUOTA_EXHAUSTED`:Grok 额度耗尽且 extra 被关闭,或 Tavily/Firecrawl 都没有返回可用降级结果。 - `GROK_RATE_LIMITED`:Grok 返回普通 429 限流(非额度信号),且没有可用降级结果。 - provider attempt 出现 `skipped: true` 与 `cooldown until …`:Firecrawl 额度耗尽后的冷却期,删除 `<stateDir>/firecrawl-cooldown.json` 或显式 `--provider firecrawl` 可强制再试。 - `TAVILY_API_KEY 未配置`:显式请求了 `--provider tavily`,但没有配置 Tavily key。 - Direct Fetch 返回二进制 / 附件错误:目标 URL 不是文本页面,或对 direct fallback 来说太大。 - Direct Map 返回很少或 0 个 URL:站点可能依赖 JavaScript、隐藏链接,或没有公开 sitemap。 ## 项目边界 当前范围包括: - `search.js` - `search.js --extra N` - 带 Direct Fetch fallback 的 `fetch.js` - 带 Direct Map fallback 的 `map.js` - 长输出 preview 和完整输出文件 - `SKILL.md` - `references/planning.md` - smoke / fixture tests 不在范围内: - 浏览器渲染 - PDF / 图片 / 压缩包解析 - Cookie、登录或反爬绕过 - MCP 会话状态,例如 `get_sources` - CLI 打包或 build 流程 ## 致谢与来源 本项目参考并改造自 [GuDaStudio/GrokSearch](https://github.com/GuDaStudio/GrokSearch/):一个基于 Python / MCP 的 Grok Search server。 感谢 GuDaStudio 提供原始项目与思路。本项目在保留核心搜索 / 抓取 / 站点映射能力的基础上,重写为更适合 agent skill 分发的 **纯 JS、脚本直跑** 形态。 本项目分享于[Linuxdo社区](https://linux.do/)。 ## 协议 本项目使用 MIT 协议发布,详见 [LICENSE](LICENSE)。 原项目同样使用 MIT 协议。我们在 `LICENSE` 中保留了原项目版权声明,以遵守 MIT 协议要求。 -
SKILL.md 5.8 KB
--- name: grok-search description: Use when the user explicitly asks to search the web, check latest/current facts, fetch a URL, or discover pages on a website. Do not use for local code search or stable offline knowledge unless the user asks for live web access. --- # Grok Search Node scripts for web search, URL fetch and site mapping. Run `npm install` once. Run scripts from the grok-search root (the directory of this SKILL.md): `cd` there or use absolute paths. ## Choose The Script - URL given → `scripts/fetch.js`. - Site named, URL unknown → `scripts/map.js`, then `fetch.js` on the URLs you pick. - Current/latest information, or URL unknown → `scripts/search.js`. - Question about the user's local machine → inspect local files first; search only to interpret them. Run the fewest commands that answer the question; run independent sub-questions in parallel. Do not chain map → fetch → search. ## Commands ```bash ./scripts/search.js "plain keywords" ./scripts/search.js --days 7 "plain keywords" ./scripts/search.js --instructions "what to return, language, what to leave out" "plain keywords" ./scripts/search.js --responses-allowed-domains github.com "plain keywords" ./scripts/search.js --source x --x-from-date 2026-07-01 "what people say about ..." ./scripts/fetch.js https://example.com # --max-chars 50000 only for a deliberate deep read ./scripts/map.js https://docs.example.com --limit 20 ``` Query rules: - The query is a keyword string that Tavily/Firecrawl search verbatim, so keep it short. Everything else (fields wanted, language, "quote and date only, no advice, say if not found") goes in `--instructions`; only Grok sees it. A bag of keywords like `GPT Codex 1M 272k context window` makes Grok invent background; `codex context window` plus an instruction asking for the current limit does not. - No code-search operators (`repo:`, `path:`, `language:`). Scope with `--responses-allowed-domains`; it restricts Grok, Tavily, Firecrawl, and Exa alike, and off-domain leftovers rank last. - Budget about 2 searches per question. Before a second search, name the gap it closes. Do not carry the previous round's conclusion words into the keywords; for the same X handle, change the gap, not the phrasing. ## Search Source Default is web. `--source x` for what people are saying, a named account's posts, a thread, or a claim only circulating on X. `--source both` for a current event where reporting and reaction both matter. `--source x` cannot fall back to the web and turns Tavily/Firecrawl/Exa off (`--extra N` forces them). - For "is it available now / current state" questions, start with `--x-from-date` 60–90 days back; widen only if empty. Old issues explain history, not the present. - X posts are personal statements: cite handle and date (both live in `answer.text`, not the card), keep claims separate from confirmations, confirm facts at the official source. - Cost: when an X search reports `responses_tool_calls.total` above 6, add `--responses-parallel-tool-calls false` next time: one agent call per turn on relays that honor it (2026-11-03, grok-4.20 multi-agent: trace 4→1, cost −35%). Multi-agent models still fan out server-side searches, so `total` can stay high — read the effect off `trace`, not `total`. Below 6 it saves nothing. - Handle filters, dates, media flags, card fields: `references/x-search.md`. ## Fetch Cost - X posts: `auto` tries Direct first (free, main post with date). `--provider firecrawl` only for the thread or replies; about 30 credits per post. - `--provider exa` fetches a page through Exa Contents (needs `EXA_API_KEY`, ~$0.001/page); in `auto` it runs after Tavily and Firecrawl. - Firecrawl works without a key: Keyless gives 1,000 credits/month plus a small per-IP daily cap, so a 30-credit X fetch burns it fast. - Fetch only evidence that would change the conclusion: one or two URLs per turn, a representative post or two for experience reports, never re-fetch text you have. Reddit and YouTube return shells from every provider. - When citing decisive evidence, record date, model version, client, and login method. ## Reading Results Every script prints one JSON object, also on failure (non-zero exit, stderr line). - `error`: read `error.message`, `error.code`, `diagnostics.provider_attempts`. Change something before retrying (query, `--provider`, `--model`). `DEADLINE_EXCEEDED`: the whole command hit its time budget (default 240s, `--deadline N`). - `diagnostics.warnings` and `diagnostics.provider_attempts` say which providers were skipped (e.g. Firecrawl in cooldown), failed, or produced content, and whether the relay served another model than requested. - Search: `answer.text`, then `sources.items` (merged and cross-channel deduped, max 12). `source_type` `citation` = used in the answer, `searched` = only listed; `opened: true` = Grok read the page. `sources.raw_path` always points to the run record (full list, answer, tool calls); read it in chunks only when the cards are not enough. Check `diagnostics.degraded`, `cost_usd`, and `search_budget` (advisory budget vs. calls made). A degraded answer is built from raw Tavily/Firecrawl/Exa results when Grok quota is exhausted, the relay times out or returns 5xx, or Responses returns no usable sources. Auth and protocol errors (401/403/422 without a quota error body) stay errors even when extras exist. - Fetch: `content.text`; if `content.truncated`, read `content.full_path` in chunks or rerun once with a larger `--max-chars`. `metadata` has title/author/published_at when the provider had them. A non-2xx page (e.g. 404) still returns content — check `metadata.status` before trusting it. `diagnostics.run_path` is the run record. - Map: `urls`; fetch the few you need. Provider order, proxy, cooldown, config errors: `references/providers.md`. Multi-part or conflicting research: `references/planning.md` first.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.