quark-download

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

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

すべての操作には、CLI スクリプト ${SKILL_PATH}/scripts/quark_search.py を使用します。JSON を標準出力に出力し（{"ok": true, "data": {...}} または {"ok": false, "error": "...", "code": "..."}）、進行状況を標準エラー出力にログとして記録します。

前提条件の確認

操作を始める前に、環境を確認します。

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

応答： {"ok": true, "data": {"isLogin": true, ...}} — APP が起動していて、ログイン済みであることを示します。

コマンドが "code": "app_not_running" で失敗した場合は、ユーザーに Quark APP の起動を案内します。isLogin が false の場合は、まずログインするよう案内します。

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

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 のページ番号

成功時の応答（ok: true）：

{
  "ok": true,
  "data": {
    "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 タイプの検索結果を優先します。スクリプトが自動で処理します。

ワークフロー — ステップごとの操作

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

リンクの検証

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 で共有リンクを開きます。

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

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

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

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

応答の方法が browser_fallback の場合は、代わりに URL をブラウザーで開き、Web ページから保存するようユーザーに案内します。

バッチ処理

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

エラー処理

エラー	検出方法	対処方法
Quark APP が起動していない	check が code: "app_not_running" を返す	Quark APP を起動するようユーザーに伝えます
ログインしていない	check が isLogin: false を返す	ログインするようユーザーに伝えます
検索結果がない	search が total: 0 を返す	別のキーワードを提案します
すべてのリンクが無効	search が valid_count: 0 を返す	別のキーワードまたはドライブの種類を試します
共有リンクにパスワードが設定されている	validate がパスワード必須エラーを返す	抽出コード（提取码）をユーザーに尋ねます
PanSou API エラー	search が code: "pansou_error" を返す	再試行するか、後で試します

重要な注意事項

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