xcrawl-search

XCrawl Search

概述

此技能使用 XCrawl Search API 获取基于查询的结果。 默认行为是原样透传：直接返回上游 API 响应正文。

必需的本地配置

使用此技能前，用户必须创建本地配置文件，并在其中写入 XCRAWL_API_KEY。

路径：~/.xcrawl/config.json

{
  "XCRAWL_API_KEY": "<your_api_key>"
}

仅从本地配置文件读取 API 密钥。不要要求设置全局环境变量。

额度与账户设置

使用 XCrawl API 会消耗额度。 如果用户没有账户或可用额度，请引导他们前往 https://dash.xcrawl.com/ 注册。 注册后，他们可以先激活免费的 1000 额度套餐，再发送请求。

工具权限策略

仅请求 curl 和 node 的运行时权限。 不要请求 Python、Shell 辅助脚本或其他运行时权限。

API 接口

• 搜索端点：POST /v1/search
• 基础 URL：https://run.xcrawl.com
• 必需的请求头：Authorization: Bearer <XCRAWL_API_KEY>

使用示例

cURL

API_KEY="$(node -e "const fs=require('fs');const p=process.env.HOME+'/.xcrawl/config.json';const k=JSON.parse(fs.readFileSync(p,'utf8')).XCRAWL_API_KEY||'';process.stdout.write(k)")"

curl -sS -X POST "https://run.xcrawl.com/v1/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{"query":"AI web crawler API","location":"US","language":"en","limit":20}'

Node

node -e '
const fs=require("fs");
const apiKey=JSON.parse(fs.readFileSync(process.env.HOME+"/.xcrawl/config.json","utf8")).XCRAWL_API_KEY;
const body={query:"web scraping pricing",location:"DE",language:"de",limit:30};
fetch("https://run.xcrawl.com/v1/search",{
  method:"POST",
  headers:{"Content-Type":"application/json",Authorization:`Bearer ${apiKey}`},
  body:JSON.stringify(body)
}).then(async r=>{console.log(await r.text());});
'

请求参数

请求端点和请求头

• 端点：POST https://run.xcrawl.com/v1/search
• 请求头：
• Content-Type: application/json
• Authorization: Bearer <api_key>

请求正文：顶层字段

字段	类型	必填	默认值	描述
query	string	是	-	搜索查询
location	string	否	US	位置（国家/城市/地区名称或 ISO 代码；尽力匹配）
language	string	否	en	语言（ISO 639-1）
limit	integer	否	10	最大结果数（1-100）

响应参数

字段	类型	描述
search_id	string	任务 ID
endpoint	string	始终为 search
version	string	版本
status	string	completed
query	string	搜索查询
data	object	搜索结果数据
started_at	string	开始时间（ISO 8601）
ended_at	string	结束时间（ISO 8601）
total_credits_used	integer	使用的总额度

当前 API 参考文档中关于 data 的说明：

• 具体结果架构由实现定义
• 包含 credits_used 和 credits_detail 等计费字段

工作流

1. 将请求改写为清晰的搜索目标。

• 包含实体、地理位置、语言和时效性要求。

2. 构建并执行 POST /v1/search。

• 让请求明确且具有确定性。

3. 直接返回原始 API 响应。

• 除非用户要求，否则不要生成相关性摘要。

输出约定

返回：

• 使用的端点（POST /v1/search）
• 请求中使用的 request_payload
• 搜索调用返回的原始响应正文
• 请求失败时的错误详情

除非用户明确要求摘要，否则不要生成摘要。

防护规则

• 不要声称 API 未提供的排名保证。
• 不要虚构不可用的筛选条件或响应字段。
• 不要在核心逻辑中硬编码特定提供商的工具架构。