xcrawl

XCrawl

概述

当用户直接请求 XCrawl，但未指定具体 API 或子技能时，此技能是默认的 XCrawl 入口。 目前，此技能通过 XCrawl Scrape API 执行单页提取。 默认行为是原样透传：直接返回上游 API 响应正文。

路由指南

• 如果用户想提取一个或多个特定 URL，请使用此技能，并默认使用 XCrawl Scrape。
• 如果用户想发现网站 URL，优先使用 XCrawl Map API。
• 如果用户想进行多页面或全站爬取，优先使用 XCrawl Crawl API。
• 如果用户想基于关键词进行发现，优先使用 XCrawl Search 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/scrape
• 读取异步结果：GET /v1/scrape/{scrape_id}
• 基础 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/scrape" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{"url":"https://example.com","mode":"sync","output":{"formats":["markdown","links"]}}'

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)")"

CREATE_RESP="$(curl -sS -X POST "https://run.xcrawl.com/v1/scrape" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{"url":"https://example.com/product/1","mode":"async","output":{"formats":["json"]},"json":{"prompt":"Extract title and price."}}')"

echo "$CREATE_RESP"

SCRAPE_ID="$(node -e 'const s=process.argv[1];const j=JSON.parse(s);process.stdout.write(j.scrape_id||"")' "$CREATE_RESP")"

curl -sS -X GET "https://run.xcrawl.com/v1/scrape/${SCRAPE_ID}" \
  -H "Authorization: Bearer ${API_KEY}"

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={url:"https://example.com",mode:"sync",output:{formats:["markdown","json"]},json:{prompt:"Extract title and publish date."}};
fetch("https://run.xcrawl.com/v1/scrape",{
  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/scrape
• 标头：
• Content-Type: application/json
• Authorization: Bearer <api_key>

请求正文：顶层字段

字段	类型	必填	默认值	描述
url	string	是	-	目标 URL
mode	string	否	sync	sync 或 async
proxy	object	否	-	代理配置
request	object	否	-	请求配置
js_render	object	否	-	JS 渲染配置
output	object	否	-	输出配置
webhook	object	否	-	异步 Webhook 配置（mode=async）

proxy

字段	类型	必填	默认值	描述
location	string	否	US	ISO-3166-1 alpha-2 国家代码，例如 US / JP / SG
sticky_session	string	否	自动生成	粘性会话 ID；相同 ID 会尝试复用出口

request

字段	类型	必填	默认值	描述
locale	string	否	en-US,en;q=0.9	影响 Accept-Language
device	string	否	desktop	desktop / mobile；影响 UA 和视口
cookies	object map	否	-	Cookie 键值对
headers	object map	否	-	标头键值对
only_main_content	boolean	否	true	仅返回主要内容
block_ads	boolean	否	true	尝试屏蔽广告资源
skip_tls_verification	boolean	否	true	跳过 TLS 验证

js_render

字段	类型	必填	默认值	描述
enabled	boolean	否	true	启用浏览器渲染
wait_until	string	否	load	load / domcontentloaded / networkidle
viewport.width	integer	否	-	视口宽度（桌面端为 1920，移动端为 402）
viewport.height	integer	否	-	视口高度（桌面端为 1080，移动端为 874）

output

Field	Type	Required	Default	Description
formats	string[]	No	["markdown"]	输出格式
screenshot	string	No	viewport	full_page / viewport（仅当 formats 包含 screenshot 时）
json.prompt	string	No	-	提取提示词
json.json_schema	object	No	-	JSON Schema

output.formats 枚举：

• html
• raw_html
• markdown
• links
• summary
• screenshot
• json

webhook

Field	Type	Required	Default	Description
url	string	No	-	回调 URL
headers	object map	No	-	自定义回调标头
events	string[]	No	["started","completed","failed"]	事件：started / completed / failed

响应参数

同步创建响应（mode=sync）

Field	Type	Description
scrape_id	string	任务 ID
endpoint	string	始终为 scrape
version	string	版本
status	string	completed / failed
url	string	目标 URL
data	object	结果数据
started_at	string	开始时间（ISO 8601）
ended_at	string	结束时间（ISO 8601）
total_credits_used	integer	使用的总点数

data 字段（根据 output.formats 而定）：

• html、raw_html、markdown、links、summary、screenshot、json
• metadata（页面元数据）
• traffic_bytes
• credits_used
• credits_detail

credits_detail 字段：

Field	Type	Description
base_cost	integer	基础抓取费用
traffic_cost	integer	流量费用
json_extract_cost	integer	JSON 提取费用

异步创建响应（mode=async）

Field	Type	Description
scrape_id	string	任务 ID
endpoint	string	始终为 scrape
version	string	版本
status	string	始终为 pending

异步结果响应（GET /v1/scrape/{scrape_id}）

Field	Type	Description
scrape_id	string	任务 ID
endpoint	string	始终为 scrape
version	string	版本
status	string	pending / crawling / completed / failed
url	string	目标 URL
data	object	与同步 data 结构相同
started_at	string	开始时间（ISO 8601）
ended_at	string	结束时间（ISO 8601）

工作流

1. 通过默认 XCrawl 入口行为对请求进行分类。

• 如果用户提供了用于提取的具体 URL，默认使用 XCrawl Scrape。
• 如果用户明确要求 map、crawl 或 search 行为，则路由到专用的 XCrawl API，而不是假装此端点支持这些功能。

2. 将用户目标重述为提取约定。

• URL 范围、必需字段、可接受的空值以及精度预期。

3. 构建抓取请求正文。

• 仅保留必要选项。
• 优先明确指定 output.formats。

4. 执行抓取并记录任务元数据。

• 跟踪 scrape_id、status 和时间戳。
• 如果是异步任务，则轮询直至状态变为 completed 或 failed。

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

• 默认不要合成或精简字段。

输出约定

返回：

• 使用的端点和模式（sync 或 async）
• 使用的 request_payload
• 每次 API 调用的原始响应正文
• 请求失败时的错误详情

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

防护规则

• 不要将 XCrawl Scrape 描述成也支持 map、crawl 或 search 语义。
• 只有在用户意图是提取 URL 内容时，才默认使用 scrape。
• 不要编造不受支持的输出字段。
• 不要在核心逻辑中硬编码特定提供商的工具架构。
• 页面结构不稳定时，应指出不确定性。