Quark Hub

quark-hub

A Minis version of the Quark Cloud Drive tool, adapted from ihmily/QuarkPanTool (Apache-2.0).

File Paths

Dependencies

No pip installation required. Only native Alpine packages are needed (preinstalled on iSH):

If aiohttp is unavailable:

apk add py3-aiohttp

Command Quick Reference

⚡ Best Workflow for Saving and Downloading (Agents Must Read)

When downloading files shared by others, follow this order to avoid duplicate saves:

1. tree-share <url>           # See exactly what is in the share
2. ls [to_fid]                # Check whether the target cloud drive directory already has content with the same name
3a. Exists → download by fid directly    # Skip saving; use the existing fid to call api_get_download_urls
3b. Does not exist → save <url>          # Save to your drive (also checks internally and skips if it already exists)
4. ls [to_fid]                # Get the fid of the file after it has been saved
5. dl (pass extra_fids)       # Download in a background thread; automatically prints progress and 1-minute average speed

Key: the save command now automatically checks whether a file with the same name already exists in the target directory and skips saving if it does. However, the agent should still run ls before calling save to confirm and avoid unnecessary network requests.

Download Notes

• dl / download_files_bg can download only files in your own cloud drive due to Quark API restrictions.
• Files shared by others → first save to your drive → then ls to get the fid → then dl.
• Downloads run in a background thread and print progress every 10 seconds (downloaded / total size / percentage / 1-minute average speed).
• Download URLs point to Alibaba Cloud OSS, and headers must not include Content-Type (handled in the code).
• Files such as subtitles can be renamed during download with the rename_map parameter, for example to match the video filename.

Code-Level API (for importing in scripts)

from quark_hub import (
    ensure_cookie,           # Get/validate the Cookie; sys.exit(10) if invalid
    api_get_download_urls,   # Pass a fid list → return a list of dicts containing download_url
    download_files_bg,       # Download in a background thread; pass items=[{file_name, download_url, save_name?}]
    api_list_all,            # List a cloud drive directory
)

Login Flow (performed by the agent)

The script itself does not drive the browser. When the script exits with exit code 10, login is required. The agent completes login as follows:

Step 1: Give the user a clickable login link

Please log in to Quark Cloud Drive first: [Click to log in to Quark Cloud Drive](https://pan.quark.cn)
Let me know once you have finished logging in.

Step 2: After the user confirms login, extract and save the Cookie

sh /var/minis/skills/quark-hub/scripts/refresh_cookie.sh

Step 3: Verify that login succeeded

python3 /var/minis/skills/quark-hub/quark_hub.py info

Usage Examples

S=/var/minis/skills/quark-hub/quark_hub.py

# 🔓 No login required
python3 $S ls-share   "https://pan.quark.cn/s/xxxxxxxx"
python3 $S tree-share "https://pan.quark.cn/s/xxxxxxxx"

# 🔒 Login required
python3 $S info
python3 $S ls
python3 $S ls <fid>
python3 $S save "https://pan.quark.cn/s/xxxxxxxx"         # Automatically checks existing content → skip or save
python3 $S save "https://pan.quark.cn/s/xxxxxxxx?pwd=1234" <target_fid>
python3 $S dl   "https://pan.quark.cn/s/xxxxxxxx" /var/minis/workspace/
python3 $S mkdir My Movies

Notes

• Cookies are valid for about 7-30 days. Log in again after they expire.
• Use for illegal purposes is strictly prohibited. This tool only calls the official Quark API.