xcrawl-crawl

XCrawl Crawl

概述

此技能通过 XCrawl Crawl 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/crawl
• 读取结果：GET /v1/crawl/{crawl_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)")"

CREATE_RESP="$(curl -sS -X POST "https://run.xcrawl.com/v1/crawl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{"url":"https://example.com","crawler":{"limit":100,"max_depth":2},"output":{"formats":["markdown","links"]}}')"

echo "$CREATE_RESP"

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

curl -sS -X GET "https://run.xcrawl.com/v1/crawl/${CRAWL_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",crawler:{limit:300,max_depth:3,include:["/docs/.*"],exclude:["/blog/.*"]},request:{locale:"ja-JP"},output:{formats:["markdown","links","json"]}};
fetch("https://run.xcrawl.com/v1/crawl",{
  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/crawl
• 请求头：
• Content-Type: application/json
• Authorization: Bearer <api_key>

请求正文：顶层字段

字段	类型	必填	默认值	说明
url	string	是	-	网站入口 URL
crawler	object	否	-	爬虫配置
proxy	object	否	-	代理配置
request	object	否	-	请求配置
js_render	object	否	-	JS 渲染配置
output	object	否	-	输出配置
webhook	object	否	-	异步回调配置

crawler

字段	类型	必填	默认值	说明
limit	integer	否	100	最大页面数
include	string[]	否	-	仅包含匹配的 URL（支持正则表达式）
exclude	string[]	否	-	排除匹配的 URL（支持正则表达式）
max_depth	integer	否	3	距离入口 URL 的最大深度
include_entire_domain	boolean	否	false	爬取整个网站，而非仅爬取子路径
include_subdomains	boolean	否	false	包含子域名
include_external_links	boolean	否	false	包含外部链接
sitemaps	boolean	否	true	使用网站站点地图

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

响应参数

创建响应（POST /v1/crawl）

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

结果响应（GET /v1/crawl/{crawl_id}）

字段	类型	描述
crawl_id	string	任务 ID
endpoint	string	始终为 crawl
version	string	版本
status	string	pending / crawling / 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

工作流

1. 确认业务目标和抓取边界。

• 明确需要哪些内容、必须排除哪些内容，以及完成信号是什么。

2. 起草范围明确的抓取请求。

• 尽量设置明确的限制和路径约束。

3. 启动抓取并记录任务元数据。

• 记录 crawl_id、初始状态和请求负载。

4. 轮询 GET /v1/crawl/{crawl_id}，直至进入终止状态。

• 跟踪 pending、crawling、completed 或 failed 状态。

5. 返回原始创建/结果响应。

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

输出约定

返回：

• 端点流程（POST /v1/crawl + GET /v1/crawl/{crawl_id}）
• 创建请求使用的 request_payload
• 创建调用的原始响应正文
• 结果调用的原始响应正文
• 请求失败时的错误详情

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

防护措施

• 未设置明确约束时，绝不执行无界抓取。
• 不要将推测的页面数量作为最终覆盖范围呈现。
• 不要在核心逻辑中硬编码特定提供商的工具架构。
• 相关时，应指出政策、法律或网站使用方面的风险。