XCrawl Map

概述

该技能使用 XCrawl Map API 发现目标站点的 URL。 默认行为为原始透传：直接返回上游 API 的响应体，不做任何修改。

必需的本地配置

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

路径：~/.xcrawl/config.json

{
  "XCRAWL_API_KEY": ""
}

仅从本地配置文件读取 API 密钥，不依赖全局环境变量。

积分与账户设置

调用 XCrawl API 将消耗积分。 若用户尚未注册账户或账户内无可用积分，请引导其前往 https://dash.xcrawl.com/ 完成注册。 注册完成后，用户可在发起请求前激活免费的 1000 积分套餐。

工具权限策略

仅在运行时申请 curl 和 node 权限。 不得申请 Python、Shell 辅助脚本或其他运行时权限。

API 接口说明

• 启动地图任务：POST /v1/map
• 基础 URL：https://run.xcrawl.com
• 必需请求头：Authorization: Bearer

使用示例

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

请求体：顶层字段

响应参数

data 字段说明：

• links：URL 列表
• total_links：URL 总数
• credits_used：本次调用消耗的积分
• credits_detail：积分明细分解

工作流

1. 重申映射目标。

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

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

• 确保过滤条件明确且可复现。

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

• 除非用户明确要求，否则不得生成 URL 类别摘要。

输出契约

返回内容须包括：

• 所使用的端点（POST /v1/map）
• 实际发出请求所用的 request_payload
• XCrawl Map 调用返回的原始响应体
• 请求失败时的错误详情

除非用户明确要求生成摘要，否则不得自行生成任何总结性内容。

约束规则

• 当达到 limit 限制时，不得声称已覆盖全站。
• 不得将推断出的 URL 与 API 返回的实际 URL 混合。
• 核心逻辑中不得硬编码特定服务商的工具 Schema。