xcrawl-api/xcrawl-skills

XCrawl Skills

可重複使用的 XCrawl 技能定義，專為多代理執行環境設計，聚焦於 API 優先的網頁資料工作流程。 官方儲存庫：https://github.com/xcrawl-api/xcrawl-skills

English | 中文

什麼是 XCrawl

XCrawl 是一個專為搜尋、擷取、URL 映射與站點爬取設計的網頁資料基礎設施產品。 此儲存庫提供面向生產環境的技能定義，幫助代理以一致的方式呼叫 XCrawl API。

此儲存庫提供的內容

• 針對常見 XCrawl 工作流程的現成技能
• 附帶請求/回應參數文件的 API 導向指令說明
• 適用於執行環境的 cURL 與 Node.js 範例
• 多代理編排的一致合約

技能目錄

• xcrawl：預設 XCrawl 入口技能，用於直接查詢與單一 URL 擷取
• xcrawl-scrape：單一 URL 擷取與結構化資料工作流程
• xcrawl-map：站台 URL 發現與範圍規劃工作流程
• xcrawl-crawl：大量站台爬取與非同步結果處理工作流程
• xcrawl-search：基於查詢的發現，支援地點/語言控制

快速開始

1. 前置需求

• XCrawl API 金鑰
• 在 https://dash.xcrawl.com/ 註冊並啟用免費的 1000 額度方案
• 執行環境二進位檔：curl 與 node
• 可存取此儲存庫

2. 設定本地 API 金鑰

建立本地設定檔：

路徑：~/.xcrawl/config.json

{
  "XCRAWL_API_KEY": "<your_api_key>"
}

此儲存庫中的技能設計為從此本地檔案讀取 XCRAWL_API_KEY。

3. 選擇一個技能

開啟下列其中一個檔案：

• skills/xcrawl/SKILL.md
• skills/xcrawl-scrape/SKILL.md
• skills/xcrawl-map/SKILL.md
• skills/xcrawl-crawl/SKILL.md
• skills/xcrawl-search/SKILL.md

每個技能包含：

• 適用情境
• 請求參數
• 回應參數
• cURL / Node.js 範例

4. 執行請求

直接使用每個 SKILL.md 中的範例，然後根據您的業務情境調整請求內容。

使用者意圖範例

• "以同步模式擷取此頁面，並回傳 Markdown 與連結。"
• "僅映射此網域下的 /docs/ URL，限制為 2000 個。"
• "啟動受限制的爬取（深度 2，限制 100），並輪詢直到完成。"
• "以美國英文搜尋，並回傳此查詢的前 20 筆結果。"

跨代理合約

每個技能可透過執行環境適配層執行。

• 輸入正常化：goal、inputs、constraints、credentials_ref、runtime_context
• 輸出正常化：status、request_payload、raw_response 或非同步配對、task_ids、error

預設行為為原始穿透：直接回傳上游 API 回應主體。

共享 XCrawl 慣例

• 基礎 URL：https://run.xcrawl.com
• 本地設定檔：~/.xcrawl/config.json
• 本地設定中的 API 金鑰欄位：XCRAWL_API_KEY
• 認證標頭：Authorization: Bearer <XCRAWL_API_KEY>
• 主要端點：
  • POST /v1/scrape 與 GET /v1/scrape/{scrape_id}
  • POST /v1/map
  • POST /v1/crawl 與 GET /v1/crawl/{crawl_id}
  • POST /v1/search

支援

• XCrawl 首頁
• XCrawl 文件