核心用法
XCrawl 是面向网页数据抓取的 API 服务，本技能作为其默认入口，专注于单页内容提取场景。核心能力包括：
1. 单页抓取（Scrape）：通过 POST /v1/scrape 提取指定 URL 内容，支持同步（sync）和异步（async）两种执行模式
2. 多格式输出：支持 markdown、html、raw_html、links、summary、screenshot、json 七种格式，可自由组合
3. 结构化提取：通过 json.prompt 或 json.json_schema 实现 LLM 驱动的字段提取
4. 高级渲染：内置浏览器渲染（js_render），支持自定义 viewport、等待策略（load/domcontentloaded/networkidle）
5. 代理与区域：支持代理配置（proxy.location），可指定出口国家/地区
典型调用流程
- 从本地配置文件
~/.xcrawl/config.json读取XCRAWL_API_KEY - 构建请求体：指定
url、mode、output.formats，可选json提取配置 - 同步模式直接返回结果；异步模式返回
scrape_id，需轮询GET /v1/scrape/{scrape_id}获取结果
显著优点
- 官方原生接入：直接对接 XCrawl 官方 API，无需中转，数据新鲜度和稳定性有保障
- 灵活的输出格式：原生支持 Markdown 和结构化 JSON，适合大模型上下文注入场景
- 异步任务支持：适合耗时页面或批量任务，避免阻塞
- 精细化渲染控制：可模拟桌面/移动端、自定义语言环境、处理动态内容
- 透明计费：响应体包含详细学分消耗明细（credits_detail），便于成本追踪
潜在缺点与局限性
- 范围限定：仅覆盖单页抓取（Scrape），站点地图（Map）、全站爬取（Crawl）、关键词搜索（Search）需使用其他专用 API
- 本地配置依赖：必须预置
~/.xcrawl/config.json，不支持环境变量，增加初次使用门槛 - 异步轮询成本：异步任务需自行实现轮询逻辑，未内置 Webhook 处理机制
- JSON 提取额外计费：使用
json.prompt或json_schema会产生json_extract_cost，高频调用成本累积较快 - 页面结构不稳定风险：目标站点反爬策略变更可能导致抓取失败，需人工介入调整参数
适合人群
- 需要从特定 URL 快速提取结构化内容的开发者
- 构建 RAG/Agent 工作流、需 Markdown/JSON 格式网页内容的 AI 应用开发者
- 有一定 API 集成经验、能处理异步任务轮询的技术用户
- 愿意预配置本地文件、追求官方直连而非第三方封装方案的用户
常规风险
- API Key 本地存储风险：密钥以明文形式存储在本地 JSON 文件，多用户环境需注意权限隔离
- 学分消耗失控：浏览器渲染、JSON 提取、流量费用均为按量计费，高频或错误重试可能导致快速耗尽（新用户仅 1000 免费学分）
- 数据合规风险：抓取第三方网站需遵守目标站点的 robots.txt 及服务条款，敏感数据抓取存在法律边界
- 服务依赖风险：单一供应商方案，官方服务可用性直接影响业务连续性
- TLS 验证默认跳过：
skip_tls_verification默认为true，存在中间人攻击理论风险，敏感场景建议显式关闭