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、シェルのヘルパースクリプト、その他の実行時権限は要求しないでください。

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

Field	Type	Required	Default	Description
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

Field	Type	Required	Default	Description
url	string	いいえ	-	コールバック URL
headers	object map	いいえ	-	カスタムコールバックヘッダー
events	string[]	いいえ	["started","completed","failed"]	イベント：started / completed / failed

レスポンスパラメーター

作成レスポンス（POST /v1/crawl）

Field	Type	Description
crawl_id	string	タスク ID
endpoint	string	常に crawl
version	string	バージョン
status	string	常に pending

結果レスポンス（GET /v1/crawl/{crawl_id}）

Field	Type	Description
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
• 作成リクエストの生レスポンス本文
• 結果リクエストの生レスポンス本文
• リクエストが失敗した場合のエラー詳細

ユーザーが明示的に要約を要求しない限り、要約を生成しないでください。

ガードレール

• 明示的な制約なしに、範囲を限定しないクロールを実行しないでください。
• 推定ページ数を最終的な網羅範囲として提示しないでください。
• プロバイダー固有のツールスキーマをコアロジックにハードコードしないでください。
• 該当する場合は、ポリシー、法的事項、またはウェブサイト利用上のリスクを明示してください。