xcrawl-map

XCrawl Map

概述

此技能使用 XCrawl Map API 发现网站的 URL。 默认行为是原样透传：直接返回上游 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 概览

• 启动 map 任务：POST /v1/map
• 基础 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/map" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{"url":"https://example.com","filter":"/docs/.*","limit":2000,"include_subdomains":true,"ignore_query_parameters":false}'

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",filter:"/docs/.*",limit:3000,include_subdomains:true,ignore_query_parameters:false};
fetch("https://run.xcrawl.com/v1/map",{
  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/map
• 请求头：
• Content-Type: application/json
• Authorization: Bearer <api_key>

请求正文：顶层字段

字段	类型	必填	默认值	说明
url	string	是	-	网站入口 URL
filter	string	否	-	URL 的正则表达式筛选条件
limit	integer	否	5000	URL 数量上限（最多 100000）
include_subdomains	boolean	否	true	包含子域名
ignore_query_parameters	boolean	否	true	忽略带查询参数的 URL

响应参数

字段	类型	说明
map_id	string	任务 ID
endpoint	string	始终为 map
version	string	版本
status	string	completed
url	string	入口 URL
data	object	URL 列表数据
started_at	string	开始时间（ISO 8601）
ended_at	string	结束时间（ISO 8601）
total_credits_used	integer	使用的总额度

data 字段：

• links：URL 列表
• total_links：URL 数量
• credits_used：已用额度
• credits_detail：额度明细

工作流

1. 重述映射目标。

• 仅发现 URL、规划选择性爬取，或分析网站结构。

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

• 明确设置筛选条件，确保可重复执行。

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

• 除非用户提出要求，否则不要合成 URL 类别摘要。

输出约定

返回：

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

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

使用限制

• 如果达到 limit，不要声称已覆盖整个网站。
• 不要将推断得出的 URL 与返回的 URL 混在一起。
• 不要在核心逻辑中硬编码特定提供商的工具模式。