x-research

X 研究（xAI/Grok）

使用 xAI 的 Grok API 进行 AI 驱动的研究。返回的是带引用的 AI 摘要，而非原始推文数据。

想要原始推文吗？ 请使用以下技能：

• x-user-timeline - 获取用户的原始推文
• x-tweet-search - 获取原始搜索结果
• x-tweet-fetch - 获取单条原始推文
• x-user-lookup - 获取用户个人资料数据

如果可以使用 X 官方的 XMCP 服务工具，请优先使用它们获取原始 X 数据。XMCP 通常在本地运行于 http://127.0.0.1:8000/mcp；https://docs.x.com/mcp 则是独立托管的 文档服务。否则请使用上述技能。这两种原始数据途径都需要 X 凭据；此综合技能则使用 XAI_API_KEY。

适用场景

在以下场景使用此技能：

• 带有 AI 分析的研究摘要
• 时事和突发新闻
• 社交舆情（“开发者们对 Y 有何看法？”）
• X/Twitter 热门话题和爆款帖子
• 尚未写入文档的新兴工具/框架
• 社区对最佳实践的看法

请勿用于：

• 原始推文数据（请使用 x-user-timeline、x-tweet-search）
• 某位特定用户帖子的原文（请使用 x-user-timeline）
• 文档完善的 API（请改用 WebFetch）

设置要求

检查 API 密钥是否已设置：

if [ -z "$XAI_API_KEY" ]; then
  echo "ERROR: XAI_API_KEY is not set"
  echo "1. Get API key from https://x.ai/api"
  echo "2. Add to profile: export XAI_API_KEY=\"your-key\""
  echo "3. Restart terminal and Claude Code"
  exit 1
else
  echo "XAI_API_KEY is configured"
fi

如果密钥不可用，请告知用户，使用此技能前必须配置 XAI_API_KEY。

API 概览

端点：https://api.x.ai/v1/responses

每次 shell 调用时，解析一次已加载技能的目录，然后使用其请求封装脚本。 对于 Claude Code 插件，请从 CLAUDE_PLUGIN_ROOT 获取目录。对于 Codex，请使用此已加载 SKILL.md 所在目录的绝对路径：

X_RESEARCH_SKILL_DIR="${CLAUDE_PLUGIN_ROOT}/skills/x-research"
"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON'
{"input":"[YOUR QUERY]","tools":[{"type":"web_search"},{"type":"x_search"}]}
JSON

请将 XAI_RESEARCH_MODEL 留空，或将其设为 auto、latest 或 grok-latest/grok-4-latest，以选择当前 API 密钥可用的最新规范通用 Grok 模型。该选择器目前会根据此策略解析为 grok-4.5；当 xAI 发布更新的规范模型时，它会自动升级。不要仅因某个别名的名称包含 latest 就信任它——实时目录中可能仍有滞后的别名。只有在明确要固定版本时，才设置 grok-4.5 这样的带版本 ID，或设置 grok-4.5-latest 这样的带版本别名。选择器会验证显式指定的固定版本，并始终输出规范模型 ID。该封装脚本会在同一进程中选择并调用模型，因此模型选择不会在单独的 shell 工具调用之间丢失。它会从标准输入接收一个请求 JSON 对象，覆盖其中任何嵌入的 model，并返回原始 Responses API JSON。

可用的搜索工具：

• web_search - 搜索互联网并浏览网页
• x_search - 对 X 帖子进行语义和关键词搜索

基本用法

使用搜索工具进行简单查询

"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON' \
  | tr -d '\000-\010\013\014\016-\037' \
  | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'
{
    "input": [{"role": "user", "content": "[YOUR QUERY]"}],
    "tools": [{"type": "web_search"}, {"type": "x_search"}]
}
JSON

查询并跟踪用量（推荐）

RESPONSE=$("$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON'
{
    "input": [{"role": "user", "content": "[YOUR QUERY]"}],
    "tools": [{"type": "web_search"}, {"type": "x_search"}]
}
JSON
)

# Extract usage stats
TOOL_CALLS=$(echo "$RESPONSE" | jq -r '.usage.num_server_side_tools_used // 0')
COST_TICKS=$(echo "$RESPONSE" | jq -r '.usage.cost_in_usd_ticks // 0')
COST_USD=$(jq -n --argjson ticks "$COST_TICKS" '$ticks / 10000000000')
echo "Tool calls: $TOOL_CALLS | Estimated cost: \$$COST_USD"
echo ""
echo "$RESPONSE" | tr -d '\000-\010\013\014\016-\037' | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'

搜索工具参数

网页搜索选项

"tools": [{
  "type": "web_search",
  "allowed_domains": ["github.com", "stackoverflow.com"],
  "excluded_domains": ["pinterest.com"],
  "enable_image_understanding": true
}]

• allowed_domains - 仅限这些域名（最多 5 个）
• excluded_domains - 排除这些域名（最多 5 个）
• enable_image_understanding - 分析搜索中发现的图片

X 搜索选项

"tools": [{
  "type": "x_search",
  "allowed_x_handles": ["elikimonimus", "anthropaboris"],
  "excluded_x_handles": ["spambot"],
  "from_date": "2025-01-01",
  "to_date": "2025-01-16",
  "enable_image_understanding": true,
  "enable_video_understanding": true
}]

• allowed_x_handles - 仅包含这些账号发布的帖子（最多 20 个）
• excluded_x_handles - 排除这些账号发布的帖子（最多 20 个）
• from_date / to_date - ISO8601 日期范围（YYYY-MM-DD）
• enable_image_understanding - 分析帖子中的图片
• enable_video_understanding - 分析帖子中的视频

示例

X/Twitter 热门话题

"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON' \
  | tr -d '\000-\010\013\014\016-\037' \
  | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'
{
    "input": [{"role": "user", "content": "What is currently trending on X? Include viral posts and major discussions."}],
    "tools": [{"type": "x_search"}]
}
JSON

开发者对某个话题的舆情

"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON' \
  | tr -d '\000-\010\013\014\016-\037' \
  | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'
{
    "input": [{"role": "user", "content": "What are developers saying about [TOPIC] on X? Include recent discussions and opinions."}],
    "tools": [{"type": "x_search"}, {"type": "web_search"}]
}
JSON

新闻和网页研究

"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON' \
  | tr -d '\000-\010\013\014\016-\037' \
  | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'
{
    "input": [{"role": "user", "content": "Latest news and developments about [TOPIC]"}],
    "tools": [{"type": "web_search"}]
}
JSON

指定日期范围的历史研究

"$X_RESEARCH_SKILL_DIR/scripts/research.sh" <<'JSON' \
  | tr -d '\000-\010\013\014\016-\037' \
  | jq -r '[.output[] | select(.type=="message")][-1].content[0].text'
{
    "input": [{"role": "user", "content": "What happened with [TOPIC] from January 9 through January 16, 2025?"}],
    "tools": [{
      "type": "x_search",
      "from_date": "2025-01-09",
      "to_date": "2025-01-16"
    }, {
      "type": "web_search"
    }]
}
JSON

响应结构

响应包含：

{
  "output": [
    {"type": "web_search_call", "status": "completed", ...},
    {"type": "custom_tool_call", "name": "x_semantic_search", ...},
    {
      "type": "message",
      "content": [{
        "type": "output_text",
        "text": "The actual response with [[1]](url) inline citations",
        "annotations": [{"type": "url_citation", "url": "...", ...}]
      }]
    }
  ],
  "citations": ["url1", "url2", ...],
  "usage": {
    "input_tokens": 11408,
    "output_tokens": 2846,
    "num_server_side_tools_used": 8,
    "cost_in_usd_ticks": 429052500
  }
}

提取内容：jq -r '[.output[] | select(.type=="message")][-1].content[0].text' — 显式选择最后一个 MESSAGE 元素；在 grok-4.5 上，最后一个 output[] 元素是推理块，而推理摘要可能包含原始控制字符，导致对整个负载进行严格 JSON 解析时出错。每个示例中的 tr 清理操作都会移除 grok-4.5 推理摘要可能输出的原始控制字符；否则，在 jq 进行选择之前，对整个负载进行严格 JSON 解析就会出错。

提取引用：jq -r '.citations[]'

定价

搜索和令牌定价的变动与此技能无关。读取 response.usage.cost_in_usd_ticks 中的确切费用；xAI 将 1 美元定义为 10,000,000,000 个 ticks。估算未来请求的费用前，请查阅提供商的定价页面。

错误处理

如果 API 返回错误：

1. 检查 XAI_API_KEY 是否已设置且有效
2. 使用 GET /v1/models 验证当前 API 密钥对应的模型是否可用
3. 检查是否超出速率限制
4. 确保 tools 数组的格式正确
5. 将 API 响应中的错误报告给用户

常见错误：

• "Internal error" — 通常是模型名称错误或请求格式错误
• 超时 — 请求耗时过长（在 Agentic API 中较少见）

迁移说明

已弃用（2026 年 1 月 12 日）：旧版使用 search_parameters 的 Live Search API 即将弃用。此技能使用新的 Agentic 工具调用 API，速度更快、功能更强。

旧格式（已弃用）：

{
  "model": "grok-4-latest",
  "messages": [...],
  "search_parameters": {"mode": "on"}
}

新格式（验证当前模型 ID 后使用）：

{
  "model": "<verified-current-model-id>",
  "input": [...],
  "tools": [{"type": "web_search"}, {"type": "x_search"}]
}

参考资料

• LLMs.txt（针对 AI 优化的文档）：https://docs.x.com/llms.txt
• xAI API 文档
• 搜索工具指南
• 模型参考
• X.com API v2