felo-web-fetch

Felo Web Fetch スキル

使用する場面

ユーザーが URL からウェブページのコンテンツを抽出または変換したい場合に、このスキルを使用します。

• ウェブページの URL からコンテンツを取得またはスクレイピングする
• ウェブページのコンテンツを html、markdown、または text に変換する
• CSS セレクターを使って特定のブロックを抽出する
• 可読性モードを使って、リンクから記事またはメインテキストを取得する
• クロールモード（fast／fine）で抽出動作を調整する
• Cookie、ユーザーエージェント、タイムアウトなどのリクエスト詳細を渡す

トリガーとなるキーワード（例）：

• ウェブページを取得、URL をスクレイピング、ページのコンテンツを取得、ウェブ取得、URL を Markdown に変換
• 明示的な指定：/felo-web-fetch、「felo web fetch を使って」、「felo でこの URL を抽出して」
• 他の言語での同じ意図（例：网页抓取、提取网页内容）でも、このスキルが起動します

次の場合は、このスキルを使用しないでください。

• リアルタイムの Q&A 検索の要約（felo-search を使用）
• スライド生成タスク（felo-slides を使用）
• 現在のワークスペースにあるローカルファイルの解析

セットアップ

1. API キーを取得する

1. felo.ai にアクセスします
2. ［設定］→［API Keys］を開きます
3. API キーを作成してコピーします

2. 環境変数を設定する

Linux/macOS：

export FELO_API_KEY="your-api-key-here"

Windows PowerShell：

$env:FELO_API_KEY="your-api-key-here"

実行方法

オプション A：同梱スクリプトまたはパッケージ化された CLI を使用する

スクリプト（リポジトリから）：

node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/article" [options]

パッケージ化された CLI（npm install -g felo-ai の実行後）：同じオプションを使用でき、短縮形も使えます。

felo web-fetch -u "https://example.com" [options]
# Short forms: -u (url), -f (format), -t (timeout, seconds), -j (json)

必須パラメーター：

• --url

主なオプションパラメーター：

• --output-format html|markdown|text
• --crawl-mode fast|fine
• --target-selector "article.main-content"
• --wait-for-selector ".content-ready"

その他の主なオプションパラメーター：

• --cookie "session_id=xxx"（繰り返し指定可能）
• --set-cookies-json '[{"name":"sid","value":"xxx","domain":"example.com"}]'
• --user-agent "Mozilla/5.0 ..."
• --timeout 60（HTTP リクエストのタイムアウト、秒単位）
• --request-timeout-ms 15000（API ペイロードの timeout、ミリ秒単位）
• --with-readability true
• --with-links-summary true
• --with-images-summary true
• --with-images-readability true
• --with-images true
• --with-links true
• --ignore-empty-text-image true
• --with-cache false
• --with-stypes true
• --json（完全な JSON レスポンスを出力）

指示の書き方（target_selector + output_format）

ユーザーがページの特定の部分または特定の出力形式を求めている場合は、次のようにコマンドを指定します。

• 出力形式：「text として取得」／「markdown を取得」／「html を返す」→ --output-format text、--output-format markdown、または --output-format html を使用します。
• 1 つの要素を指定：「メイン記事のみ」／「#main 内のコンテンツだけ」／「article.main-content のみ取得」→ --target-selector "article.main"、またはユーザーが指定したセレクターを使用します。

例：

# Basic: fetch as Markdown
node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --output-format markdown

# Article-style with readability
node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/article" --with-readability true --output-format markdown

# Only the element matching a CSS selector
node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --target-selector "article.main" --output-format markdown

# With cookies and custom user-agent
node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/private" --cookie "session_id=abc123" --with-readability true --json

# Full JSON response
node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --output-format text --json

オプション B：curl で API を呼び出す

curl -X POST "https://openapi.felo.ai/v2/web/extract" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "output_format": "markdown", "with_readability": true}'

API リファレンス（概要）

• エンドポイント：POST /v2/web/extract
• ベース URL：https://openapi.felo.ai。必要に応じて FELO_API_BASE 環境変数で上書きします。
• 認証：Authorization: Bearer YOUR_API_KEY

リクエストボディ（JSON）

パラメーター	型	必須	デフォルト	説明
url	string	はい	-	取得するウェブページの URL
crawl_mode	string	いいえ	fast	fast または fine
output_format	string	いいえ	html	html、text、markdown
with_readability	boolean	いいえ	-	可読性モード（メインコンテンツ）を使用
with_links_summary	boolean	いいえ	-	リンクの概要を含める
with_images_summary	boolean	いいえ	-	画像の概要を含める
target_selector	string	いいえ	-	対象要素の CSS セレクター
wait_for_selector	string	いいえ	-	取得前にセレクターを待機
timeout	integer	いいえ	-	タイムアウト（ミリ秒）
with_cache	boolean	いいえ	true	キャッシュを使用
set_cookies	array	いいえ	-	Cookie エントリー
user_agent	string	いいえ	-	カスタムユーザーエージェント

レスポンス

成功時（200）：

{
  "code": 0,
  "message": "success",
  "data": {
    "content": { ... }
  }
}

取得したコンテンツは data.content に格納されます。構造は output_format によって異なります。

エラーコード

HTTP	Code	Description
400	-	パラメーターの検証に失敗しました
401	INVALID_API_KEY	API キーが無効または失効しています
500/502	WEB_EXTRACT_FAILED	取得に失敗しました（サーバーまたはページのエラー）

出力形式

• デフォルトでは、抽出したコンテンツのみを出力します（直接使用またはパイプ処理用）。
• レスポンスのコンテンツが文字列でない場合、スクリプトは JSON を出力します。
• メタデータとレスポンスオブジェクト全体が必要な場合は、--json を使用します。

エラーレスポンス形式：

## Web Fetch Failed
- Message: <error message>
- Suggested Action: verify URL/parameters and retry

重要な注意事項

• 実行前に必ず URL を指定してください。
• 列挙値を検証してください：
  • output_format：html、markdown、text
  • crawl_mode：fast、fine
• ページの特定の部分のみが必要な場合は、--target-selector を使用してください。
• ページのレンダリングや抽出の待機時間には --request-timeout-ms を、ローカルの HTTP タイムアウトには --timeout を使用してください。
• 長い記事や応答の遅いサイトでは、--timeout を増やすことを検討してください。
• API は結果をキャッシュすることがあります。最新のコンテンツが必要な場合にのみ、--with-cache false を使用してください。

参考資料

• Web Extract API
• Felo Open Platform