Claude Skill

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.

LLM Mart · 0 points · 3 views 0 listing impressions 0 install-command copies
Download dengyie-awesome-skills-grok-search-da7227d.zip · 191 KB

Install

skills CLI npx skills add https://github.com/dengyie/awesome-skills/tree/main/grok-search
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dengyie-awesome-skills@llmmart
Git 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。

文档

配置

推荐把长期使用的 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_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。
  • 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_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。

失败时每个脚本都会返回:

{
  "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_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

./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 answer
  • content.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.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:一个基于 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, 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

./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.

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.

No comments yet.

Reviews (0)

No reviews yet.