content-parser

使用するべき場合

• ユーザーがURLを提供し、そのコンテンツを抽出・読み込みたい場合
• 別のスキルが生成前にURLからソース資料を解析する必要がある場合
• ユーザーが「このURLを解析して」「このリンクからコンテンツを抽出」と言った場合
• ユーザーが「解析链接」「提取内容」と言った場合

使用しないべき場合

• ユーザーがテキストコンテンツを既に持っており、URL解析が不要な場合
• ユーザーが音声・動画コンテンツを生成したい場合（コンテンツ抽出ではない）
• ユーザーがローカルファイルを読み込みたい場合（標準ファイル読み込みツールを使用）

目的

サポートされているプラットフォーム全体のURLからコンテンツを抽出・正規化します。コンテンツ本文、メタデータ、参照を含む構造化データを返します。コンテンツ生成スキルの前処理ステップまたはスタンドアロンのコンテンツ抽出として有用です。

厳しい制約

• シェルスクリプト使用禁止。下記の「API リファレンス（インライン）」セクションのAPIリファレンスからcurlコマンドを構築してください
• APIキーとヘッダーは下記の「API リファレンス（インライン）」を参照してください
• ポーリング、エラー、インタラクションパターンは下記の「API リファレンス（インライン）」を参照してください
• URLは有効なHTTP(S) URLである必要があります
• 何らかのインタラクション前に、必ず shared/config-pattern.md に従って設定を読み込んでください
• ~/Downloads/ または .listenhub/ にファイルを保存しないでください。現在の作業ディレクトリに保存してください

<HARD-GATE> 複数選択の各ステップで AskUserQuestion ツールを使用してください。プレーンテキストとしてオプションを出力しないでください。一度に1つの質問を行い、次のステップに進む前にユーザーの回答を待ってください。URLとオプションを収集した後、APIを呼び出す前にユーザーに確認してください。 </HARD-GATE>

ステップ -1: APIキーチェック

shared/config-pattern.md § APIキーチェックに従ってください。キーが見つからない場合、直ちに停止してください。

ステップ 0: 設定セットアップ

shared/config-pattern.md ステップ 0（ゼロクエスチョンブート）に従ってください。

ファイルが存在しない場合 — サイレントにデフォルトで作成して続行します：

mkdir -p ".listenhub/content-parser"
echo '{"autoDownload":true}' > ".listenhub/content-parser/config.json"
CONFIG_PATH=".listenhub/content-parser/config.json"
CONFIG=$(cat "$CONFIG_PATH")

セットアップの質問をしないでください。 インタラクションフローに直接進んでください。

ファイルが存在する場合 — サイレントに設定を読み込んで続行します：

CONFIG_PATH=".listenhub/content-parser/config.json"
[ ! -f "$CONFIG_PATH" ] && CONFIG_PATH="$HOME/.listenhub/content-parser/config.json"
CONFIG=$(cat "$CONFIG_PATH")

セットアップフロー（ユーザーが明示的に再設定を要求した場合のみ）

ユーザーが明示的に再設定を要求した場合にのみ実行します。現在の設定を表示：

当前配置 (content-parser)：
  自动下载：{是 / 否}

その後、以下を質問：

1. autoDownload: 「提取的内容自动保存到当前目录？」
   • 「是（推荐）」→ autoDownload: true
   • 「否」→ autoDownload: false

直ちに保存：

NEW_CONFIG=$(echo "$CONFIG" | jq --argjson dl {true/false} '. + {"autoDownload": $dl}')
echo "$NEW_CONFIG" > "$CONFIG_PATH"
CONFIG=$(cat "$CONFIG_PATH")

インタラクションフロー

ステップ 1: URL入力

フリーテキスト入力。ユーザーに質問：

どのURLからコンテンツを抽出したいですか？

ステップ 2: オプション（オプション）

ユーザーに抽出オプションを設定するか質問：

Question: 「抽出オプションを設定したいですか？」
Options:
  - 「いいえ、デフォルトを使用」 — デフォルト設定で抽出
  - 「はい、オプションを設定」 — summarize、maxLength、またはTwitterツイート数を設定

「はい」の場合、フォローアップ質問をします：

• Summarize: 「コンテンツのサマリーを生成しますか？」（はい/いいえ）
• Max Length: 「最大コンテンツ長を設定しますか？」（フリーテキスト、例：「5000」）
• Twitter count（URLがTwitter/Xプロフィールの場合のみ）: 「何ツイート取得しますか？」（1-100、デフォルト20）

ステップ 3: 確認・抽出

以下のようにサマリー：

コンテンツ抽出の準備ができました：

  URL: {url}
  オプション: {summarize: true, maxLength: 5000, twitter.count: 50} / デフォルト

  続行しますか？

APIを呼び出す前に明示的な確認を待ってください。

ワークフロー

1. URL検証: HTTP(S)である必要があります。必要に応じて正規化（references/supported-platforms.md 参照）

2. リクエストボディを構築:

   {
     "source": {
       "type": "url",
       "uri": "{url}"
     },
     "options": {
       "summarize": true/false,
       "maxLength": 5000,
       "twitter": {
         "count": 50
       }
     }
   }
   

   ユーザーがデフォルトを選択した場合は options を省略します。

3. 送信（フォアグラウンド）: POST /v1/content/extract → taskId を抽出

4. ユーザーに抽出が進行中であることを告げます

5. ポーリング（バックグラウンド）: 以下の正確な bashコマンドを run_in_background: true および timeout: 300000 で実行。注：statusフィールドは .data.status（processStatus ではない）、間隔は5秒、値は processing/completed/failed:

   TASK_ID="<id-from-step-3>"
   for i in $(seq 1 60); do
     RESULT=$(curl -sS "https://api.marswave.ai/openapi/v1/content/extract/$TASK_ID" \
       -H "Authorization: Bearer $LISTENHUB_API_KEY" \
       -H "X-Source: skills" 2>/dev/null)
     STATUS=$(echo "$RESULT" | tr -d '\000-\037\177' | jq -r '.data.status // "processing"')
     case "$STATUS" in
       completed) echo "$RESULT"; exit 0 ;;
       failed) echo "FAILED: $RESULT" >&2; exit 1 ;;
       *) sleep 5 ;;
     esac
   done
   echo "TIMEOUT" >&2; exit 2
   

6. 通知されたら、結果をダウンロードして提示：

   autoDownload が true の場合、抽出されたタイトルからスラグを生成（タイトルがない場合はドメイン名にフォールバック）。shared/config-pattern.md § アーティファクト命名に従ってスラグ生成と重複排除を実行します。

   • {slug}.md を現在のディレクトリに書き込み — マークダウン形式の完全な抽出コンテンツ
   • {slug}.json を現在のディレクトリに書き込み — 完全な生API応答データ

   SLUG="{title-slug}"  # 例：「topology-wikipedia」
   # 重複排除：ファイルが存在するかチェック
   BASE="$SLUG"; i=2
   while [ -e "${SLUG}.md" ] || [ -e "${SLUG}.json" ]; do SLUG="${BASE}-${i}"; i=$((i+1)); done
   echo "$CONTENT_MD" > "${SLUG}.md"
   echo "$RESULT" > "${SLUG}.json"
   

   以下のように提示：

   内容提取完成！
   
   来源：{url}
   标题：{metadata.title}
   长度：~{character count} 字符
   消耗积分：{credits}
   
   已保存到当前目录：
     {slug}.md
     {slug}.json
   

7. 抽出されたコンテンツのプレビュー（最初の約500文字）を表示

8. 別のスキル（例：/podcast、/tts）でコンテンツを使用するオプションを提供

推定時間: コンテンツサイズとプラットフォームに応じて10〜30秒。

APIリファレンス（インライン）

認証

環境変数: LISTENHUB_API_KEY（形式：lh_sk_...）

~/.zshrc（macOS）または ~/.bashrc（Linux）に保存：

export LISTENHUB_API_KEY="lh_sk_..."

取得方法: https://listenhub.ai/settings/api-keys にアクセス（Proプラン必須）。

ベースURL: https://api.marswave.ai/openapi/v1

必須ヘッダー（すべてのリクエスト）:

Authorization: Bearer $LISTENHUB_API_KEY
Content-Type: application/json
X-Source: skills

X-Source: skills ヘッダーはリクエストがClaude Codeスキル（CLIツール）からのものであることを示します。

curlテンプレート:

curl -sS -X POST "https://api.marswave.ai/openapi/v1/{endpoint}" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Source: skills" \
  -d '{ ... }'

GETリクエストの場合、-d を省略し、-X POST を -X GET に変更。

セキュリティに関する注記：

• 完全なAPIキーを出力にログしたり表示したりしないでください
• APIキーはHTTPSのみで送信されます
• 機密情報や信頼できない情報をコンテンツ入力として渡さないでください — 外部APIで処理するために送信されます

---

POST /v1/content/extract

URLのコンテンツ抽出タスクを作成します。ポーリング用の taskId を返します。

リクエストボディ：

フィールド	必須	タイプ	説明
source	はい	object	抽出元
source.type	はい	string	"url" である必要があります
source.uri	はい	string	抽出するコンテンツの有効なHTTP(S) URL
options	いいえ	object	抽出オプション
options.summarize	いいえ	boolean	サマリーを生成するかどうか
options.maxLength	いいえ	integer	最大コンテンツ長
options.twitter	いいえ	object	Twitter/X固有オプション
options.twitter.count	いいえ	integer	取得するツイート数（1-100、デフォルト20）

応答：

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "69a7dac700cf95938f86d9bb"
  }
}

エラーコード：

コード	意味
29003	検証エラー（"source.uri" is required、"source.uri" must be a valid uri）
21007	無効なAPIキー

---

GET /v1/content/extract/{taskId}

抽出タスクのステータスと結果を取得します。

パスパラメータ：

パラメータ	タイプ	説明
taskId	string	24文字16進タスクID

応答ステート：

• processing — タスクはまだ実行中
• completed — 抽出完了、データ利用可能
• failed — 抽出失敗、failCode と message を確認

応答（処理中）:

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "69a7dac700cf95938f86d9bb",
    "status": "processing",
    "createdAt": "2025-04-09T12:00:00Z",
    "data": null,
    "credits": 0,
    "failCode": null,
    "message": null
  }
}

応答（完了）:

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "69a7dac700cf95938f86d9bb",
    "status": "completed",
    "createdAt": "2025-04-09T12:00:00Z",
    "data": {
      "content": "抽出されたテキストコンテンツ...",
      "metadata": {
        "title": "記事タイトル",
        "author": "著者名",
        "publishedAt": "2025-04-01T08:00:00Z"
      },
      "references": [
        "https://example.com/related-article"
      ]
    },
    "credits": 5,
    "failCode": null,
    "message": null
  }
}

応答（失敗）:

{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "69a7dac700cf95938f86d9bb",
    "status": "failed",
    "createdAt": "2025-04-09T12:00:00Z",
    "data": null,
    "credits": 0,
    "failCode": "EXTRACT_FAILED",
    "message": "提供されたURLからコンテンツを抽出できません"
  }
}

主要フィールド：

フィールド	タイプ	説明
status	string	processing、completed、または failed
data.data.content	string	抽出されたテキストコンテンツ
data.data.metadata	object	ページメタデータ（タイトル、著者、publishedAt）
data.data.references	array	参照URL（文字列の配列）
credits	integer	消費されたクレジット
failCode	string	エラーコード（成功時はnull）
message	string	エラーメッセージ（成功時はnull）

エラーコード：

コード	意味
29003	無効なtaskId形式
25002	タスクが見つかりません

---

ポーリングパターン

5秒間隔、最大60ポーリング。run_in_background: true および timeout: 300000 で実行します。

2段階パターン：

1. 送信（フォアグラウンド）: 作成リクエストをPOST、応答から taskId を抽出。
2. ポーリング（バックグラウンド）: run_in_background: true でポーリングループを実行。完了時に自動的に通知されます。

正確なポーリング bashコマンドは既にワークフローセクション（ステップ5）で指定されています。

---

エラーハンドリング

HTTPステータスコード：

コード	意味	アクション
200	成功	レスポンスボディを解析
400	不正なリクエスト	パラメータを確認
401	無効なAPIキー	LISTENHUB_API_KEY を再確認
402	クレジット不足	ユーザーにチャージを勧める
403	禁止	このリソースに対する権限がない
429	レート制限	指数バックオフ、遅延後に再試行
500/502/503/504	サーバーエラー	最大3回まで再試行

再試行戦略：

• 429レート制限: 15秒待機してから再試行（指数バックオフ）
• 5xxサーバーエラー: 5秒間隔で最大3回まで再試行
• ネットワークエラー: 最大3回まで再試行

アプリケーションエラーコード：

コード	意味
21007	無効なユーザーAPIキー
25429	レート制限（アプリケーションレベル）

例

ユーザー: 「このURL記事を解析してください: https://en.wikipedia.org/wiki/Topology」

エージェントワークフロー:

1. URL: https://en.wikipedia.org/wiki/Topology
2. オプション: デフォルト（optionsを省略）
3. 抽出を送信

curl -sS -X POST "https://api.marswave.ai/openapi/v1/content/extract" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Source: skills" \
  -d '{
    "source": {
      "type": "url",
      "uri": "https://en.wikipedia.org/wiki/Topology"
    }
  }'

4. 完了までポーリング：

curl -sS "https://api.marswave.ai/openapi/v1/content/extract/69a7dac700cf95938f86d9bb" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "X-Source: skills"

5. 抽出されたコンテンツプレビューを提示し、次のアクションを提供。

---

ユーザー: 「@elonmuskの最新ツイートを抽出、50ツイート取得」

エージェントワークフロー:

1. URL: https://x.com/elonmusk
2. オプション: {"twitter": {"count": 50}}
3. 抽出を送信

curl -sS -X POST "https://api.marswave.ai/openapi/v1/content/extract" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Source: skills" \
  -d '{
    "source": {
      "type": "url",
      "uri": "https://x.com/elonmusk"
    },
    "options": {
      "twitter": {
        "count": 50
      }
    }
  }'

4. 完了までポーリング、結果を提示。