xcrawl-scrape

XCrawl Scrape

概述

此技能使用 XCrawl Scrape 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/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

字段	类型	必填	默认值	说明
formats	string[]	否	["markdown"]	输出格式
screenshot	string	否	viewport	full_page / viewport（仅当 formats 包含 screenshot 时）
json.prompt	string	否	-	提取提示词
json.json_schema	object	否	-	JSON Schema

output.formats 枚举值：

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

webhook

字段	类型	必填	默认值	说明
url	string	否	-	回调 URL
headers	object map	否	-	自定义回调请求头
events	string[]	否	["started","completed","failed"]	事件：started / completed / failed

响应参数

同步创建响应（mode=sync）

字段	类型	描述
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 字段：

字段	类型	描述
base_cost	integer	基础抓取费用
traffic_cost	integer	流量费用
json_extract_cost	integer	JSON 提取费用

异步创建响应（mode=async）

字段	类型	描述
scrape_id	string	任务 ID
endpoint	string	始终为 scrape
version	string	版本
status	string	始终为 pending

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

字段	类型	描述
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. 将用户目标重述为提取约定。

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

2. 构建抓取请求正文。

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

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

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

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

• 默认不要合成或压缩字段。

输出约定

返回：

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

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

防护措施

• 不要编造不受支持的输出字段。
• 不要在核心逻辑中硬编码特定提供商的工具架构。
• 页面结构不稳定时，说明不确定性。