quark-download

Quark Search — ネットドライブのリソース検索とダウンロード

言語

ユーザーの言語に合わせてください：ユーザーが使用する言語で応答します。

PanSou 集約 API とローカルの Quark デスクトップ APP を組み合わせて、リソースの検索 → リンクの検証 → Quark クラウドドライブへの保存 → ローカルへのダウンロードという一連のワークフローを自動化します。

すべての操作には、CLI スクリプト ${SKILL_PATH}/scripts/quark_search.py を使用します。標準出力には JSON（{"status": "ok", "results": {...}, "hint": "..."}）を出力し、標準エラーにはエラー（{"error": "code", "message": "...", "hint": "...", "recoverable": true/false}）を出力します。終了コード：0 = 成功、1 = 回復可能なエラー、2 = 致命的なエラー。

事前確認（最初に必ず実行）

業務コマンド（検索、検証、保存など）を実行する前に、事前確認を実行します。

python3 ${SKILL_PATH}/scripts/quark_search.py preflight

応答： ready: true/false、dependencies、services の状態を含む標準化された JSON です。

• ready: true の場合 → ワークフローに進みます。
• ready: false の場合 → 以下の確認／修正表に従ってから、事前確認を再実行します。事前確認に合格するまで、検索や保存に進まないでください。

確認項目	修正方法
Quark APP が起動していない	Quark デスクトップ APP を起動し、起動するまで数秒待ちます
Quark APP にログインしていない	Quark APP で会員アカウントにログインします

事前確認を必須にする理由： 検索自体は Quark APP がなくても動作します（PanSou ウェブ API を呼び出します）が、save には起動中でログイン済みの Quark APP が必要です。最初に事前確認を実行すれば、リソースを見つけた後で保存できないとわかる、もどかしい状況を防げます。

ワークフロー — クイック検索（推奨）

前提条件： 事前確認で ready: true が返されていること。

1 つのコマンドで PanSou を検索し、すべてのリンクを並列で検証し、上位の結果についてファイル詳細を取得します。

python3 ${SKILL_PATH}/scripts/quark_search.py search "KEYWORD" --top 5

オプション：

フラグ	デフォルト	説明
--top N	5	詳細情報とともに返す、有効な結果の上位件数
--no-validate	オフ	検証をスキップします（高速になりますが、無効なリンクが含まれる場合があります）
--limit N	30	ページあたりの PanSou 結果数
--page N	1	PanSou のページ番号

成功時の応答：

{
  "status": "ok",
  "hint": "Found 8 valid Quark links for '三体', returning top 5.",
  "results": {
    "keyword": "三体",
    "total": 1234,
    "valid_count": 8,
    "results": [
      {
        "pwd_id": "abc123def",
        "url": "https://pan.quark.cn/s/abc123def",
        "note": "三体全集 4K",
        "source": "plugin:libvio",
        "datetime": "2025-01-15",
        "stoken": "xxx",
        "detail": {
          "pwd_id": "abc123def",
          "pdir_fid": "0",
          "total": 3,
          "list": [
            {"file_name": "三体S01E01.mkv", "size": 4294967296, "dir": false, "fid": "f1"},
            {"file_name": "Extras", "size": 0, "dir": true, "fid": "f2", "include_items": 5}
          ]
        }
      }
    ]
  }
}

主なフィールド：

• total — PanSou による、すべてのドライブタイプを合計した結果数
• valid_count — 検証に合格した Quark リンクの件数
• results[].pwd_id — 保存コマンドで使用する共有 ID
• results[].detail.list[] — 共有内のファイル／フォルダー
• results[].detail.list[].dir — フォルダーの場合は true です（file_type よりも信頼性があります）
• results[].detail.list[].fid — サブフォルダーを参照する detail コマンドで使用します

Quark の結果がない場合： results が空で total が 0 より大きい場合、他のドライブタイプで利用可能な結果を示す type_counts が応答に含まれます。これらをユーザーに伝えてください。

優先順位： ユーザーは Quark の会員であるため、常に quark タイプの結果を優先してください。スクリプトがこの処理を自動的に行います。

ワークフロー — ステップごとの実行

前提条件： 事前確認で ready: true が返されていること。

細かく制御するには、個別のサブコマンドを使用します。

リンクの検証

python3 ${SKILL_PATH}/scripts/quark_search.py validate PWD_ID_OR_URL [...]

複数の pwd_id または完全な共有 URL を指定できます。それぞれの検証結果が返されます。

status	意味	対応
valid	共有が有効です	続行します。応答には詳細情報の取得に使用する stoken が含まれます
expired	共有の期限が切れています（コード 41004）	スキップし、期限切れとして扱います
not_exist	共有が削除されています（コード 41006）	スキップし、無効として扱います
error	その他のエラー	スキップします

ファイル詳細の取得

python3 ${SKILL_PATH}/scripts/quark_search.py detail PWD_ID --stoken STOKEN [--fid FID]

共有のファイル一覧を取得します。サブフォルダーを参照するには --fid を使用します（前回の詳細応答にあるフォルダーの fid を指定します）。

ヘルスチェック

python3 ${SKILL_PATH}/scripts/quark_search.py health [--refresh]

PanSou API の状態と、検索に使用する channels／plugins の一覧を表示します。ヘルスチェックのデータは ~/.cache/quark-search/health.json に 24 時間キャッシュされます。最新の情報を取得するには --refresh を使用します。

結果をユーザーに提示

結果をわかりやすく整形します。

搜索 "三体" 找到 X 个有效夸克网盘资源：

1. [有效] 三体全集 4K — 3个文件，来源: plugin:libvio
   https://pan.quark.cn/s/abc123
2. [有效] 三体 第一季 1080P — 1个文件夹(42项)，来源: channel:yunpanx
   https://pan.quark.cn/s/def456
3. [已失效] 三体合集 — 分享已过期

どれを保存するか、ユーザーに尋ねます。

保存

Quark APP が起動し、ログインしている必要があります。 保存を試みる前に、このセッションで事前チェックに合格していることを確認してください。不明な場合は、事前チェックをもう一度実行してください。

ユーザーがリソースを選択したら、Quark APP を起動して共有リンクを開きます。

python3 ${SKILL_PATH}/scripts/quark_search.py save PWD_ID_OR_URL

スクリプトは次の3つの方法を順番に試します：desktop_share_visiting（推奨）→ desktop_caller ディープリンク → ブラウザーのフォールバック。応答には、成功した方法が示されます。

APP への保存に成功した場合（方法が desktop_share_visiting または desktop_caller）、ユーザーに次のように伝えます。

Quark APP で共有リンクのウィンドウを開きました。注意：ポップアップしたウィンドウが小さい場合があります。タスクバー／Dock にある Quark アイコンをご確認ください。 APP で「保存到网盘」ボタンをクリックすると保存が完了します。保存後、ファイルはご利用のネットドライブに表示され、APP から直接ローカルにダウンロードできます。

応答の方法が browser_fallback の場合は、代わりにブラウザーで URL を開き、ウェブページから保存するようユーザーに伝えてください。

一括処理

ユーザーが複数のリソースを検索して保存する場合は、キーワードごとに検索 → 提示 → 保存のワークフローを繰り返します。まず search コマンドですべてのリンクを検証してから、順番に APP で保存します。

完了レポート

保存に成功した後、次の概要をユーザーに提示してください。

[Quark Download] Complete!
Resource: [title]
Share: [URL]
Method: [save method used]
→ Click "保存到网盘" in Quark APP to complete

エラー処理

エラー	検出方法	解決方法
Quark APP が起動していない	preflight が ready: false、サービスが not_running を返す	Quark APP を起動するようユーザーに伝えます
ログインしていない	preflight が ready: false を返し、ヒントにログインについての記載がある	ログインするようユーザーに伝えます
セッション中に APP の接続が切れた	事前チェック合格後に save が app_not_running エラーを返す	事前チェックを再実行します。失敗した場合は、Quark APP を再起動して再度ログインするようユーザーに伝えます
検索結果がない	search が total: 0 を返す	別のキーワードを提案します
すべてのリンクが無効	search が valid_count: 0 を返す	別のキーワードまたはドライブの種類を試します
共有にパスワードが設定されている	validate がパスワードが必要というエラーを返す	ユーザーに抽出コード（提取码）を尋ねます
PanSou API エラー	search が error: "pansou_error" を返す	再試行するか、時間をおいて試します

トラブルシューティング

症状	考えられる原因	対処方法
localhost:9128 refused	Quark APP が起動していない	Quark デスクトップ APP を起動します
preflight は成功するが save が失敗する	APP ウィンドウが最小化または非表示になっている	タスクバー／Dock で Quark アイコンを確認し、ウィンドウを前面に表示します
検索結果は返るが、すべて無効	リソースの有効期限が切れたか、削除されている	別のキーワードを試すか、検索語句の範囲を広げます
どの検索でも pansou_error が発生する	PanSou API の停止またはネットワークの問題	時間をおいて再試行し、ネットワーク接続を確認します
browser_fallback が使用された	Quark APP のローカル API が応答していない	Quark APP を再起動し、モバイル版ではなくデスクトップ版であることを確認します
Detail が空のファイル一覧を返す	共有に抽出コード（提取码）が必要	ユーザーにコードを尋ね、パスコードを使って再検証します

重要な注意事項

• すべての共有検証 API は公開されており、認証は不要です
• localhost:9128 の Quark APP ローカル API に認証は不要です
• 実際のネットドライブへの保存処理は Quark APP の UI 内で行われます（ユーザーがボタンを1つクリックします）
• ローカルへのダウンロードは Quark APP 内蔵のダウンロードマネージャーが処理します
• Quark の認証が必要なリモート API を直接呼び出さないでください