quark-download

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quark Search — 网盘资源搜索与下载

Automate the full workflow: search resources → validate links → save to Quark cloud drive → download locally, by combining the PanSou aggregation API with the local Quark desktop APP.

All operations use the CLI script at

${SKILL_PATH}/scripts/quark_search.py

. It outputs JSON to stdout (

{"ok": true, "data": {...}}

{"ok": false, "error": "...", "code": "..."}

) and logs progress to stderr.

结合PanSou聚合API与本地Quark桌面APP，实现全工作流自动化：搜索资源→验证链接→保存到Quark网盘→本地下载。

所有操作均使用

${SKILL_PATH}/scripts/quark_search.py

路径下的CLI脚本。它会向标准输出(stdout)返回JSON（格式为

{"ok": true, "data": {...}}

或

{"ok": false, "error": "...", "code": "..."}

），并将进度日志输出到标准错误(stderr)。

Prerequisites Check

前置检查

Before any operation, verify the environment:

bash

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

Response:

{"ok": true, "data": {"isLogin": true, ...}}

— confirms APP is running and logged in.

If the command fails with

"code": "app_not_running"

, instruct the user to launch Quark APP. If

isLogin

false

, instruct the user to log in first.

执行任何操作前，先验证环境是否正常：

bash

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

响应：

{"ok": true, "data": {"isLogin": true, ...}}

— 确认APP正在运行且已登录。

如果命令执行失败，返回

"code": "app_not_running"

，请提示用户启动Quark APP。如果

isLogin

为

false

，请提示用户先登录账号。

Workflow — Quick Search (recommended)

工作流 — 快速搜索（推荐）

A single command searches PanSou, validates all links in parallel, and fetches file details for the top results:

bash

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

Options:

Flag	Default	Description
`--top N`	`5`	Number of top valid results to return with details
`--no-validate`	off	Skip validation (faster, but may include dead links)
`--limit N`	`30`	PanSou results per page
`--page N`	`1`	PanSou page number

Success response (
ok: true
):

json

{
  "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}
          ]
        }
      }
    ]
  }
}

Key fields:

```
total
```
— total results across all drive types from PanSou
```
valid_count
```
— how many quark links passed validation
```
results[].pwd_id
```
— share ID for save command
```
results[].detail.list[]
```
— files/folders in the share
```
results[].detail.list[].dir
```
—
```
true
```
if folder (more reliable than file_type)
```
results[].detail.list[].fid
```
— use with
```
detail
```
command to browse subfolders

No quark results: When

results

is empty but

total

> 0, the response includes

type_counts

showing available results on other drive types. Report these to the user.

Priority: Always prioritize

quark

type results since the user has Quark membership. The script handles this automatically.

单条命令即可完成PanSou搜索、并行验证所有链接、获取 top 结果的文件详情：

bash

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

可选参数：

Flag	默认值	描述
`--top N`	`5`	返回带详情的有效结果数量上限
`--no-validate`	关闭	跳过链接验证（速度更快，但可能包含死链）
`--limit N`	`30`	单页返回的PanSou结果数量
`--page N`	`1`	PanSou搜索页码

成功响应（
ok: true
）：

json

{
  "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

类型的结果，脚本已自动处理该逻辑。

Workflow — Step-by-step

工作流 — 分步执行

For granular control, use individual subcommands:

如需更精细的控制，可使用独立子命令：

Validate Links

验证链接

bash

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

Accepts multiple pwd_ids or full share URLs. Returns validation status for each:

`status`	Meaning	Action
`valid`	Share is alive	Proceed. Response includes `stoken` for detail query
`expired`	Share expired (code 41004)	Skip, mark as expired
`not_exist`	Share deleted (code 41006)	Skip, mark as invalid
`error`	Other error	Skip

bash

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

支持传入多个pwd_id或完整分享链接，返回每个链接的验证状态：

`status`	含义	后续操作
`valid`	分享链接有效	可继续操作，响应包含详情查询所需的 `stoken`
`expired`	分享已过期（错误码41004）	跳过，标记为过期
`not_exist`	分享已被删除（错误码41006）	跳过，标记为无效
`error`	其他错误	跳过

Get File Details

获取文件详情

bash

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

Fetches the file listing for a share. Use

--fid

to browse into a subfolder (pass the folder's

fid

from a previous detail response).

bash

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

获取分享链接的文件列表。如需浏览子文件夹，可传入

--fid

参数（值为上一次详情响应中对应文件夹的

fid

）。

Health Check

健康检查

bash

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

Shows PanSou API status and the

channels

plugins

lists used for search. Health data is cached for 24 hours at

~/.cache/quark-search/health.json

. Use

--refresh

to force a fresh fetch.

bash

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

展示PanSou API状态以及搜索使用的

channels

plugins

列表。健康数据会缓存24小时，存储路径为

~/.cache/quark-search/health.json

。使用

--refresh

参数可强制拉取最新数据。

Present Results to User

向用户展示结果

Format results clearly:

搜索 "三体" 找到 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. [已失效] 三体合集 — 分享已过期

Ask the user which one to save.

请清晰格式化搜索结果：

搜索 "三体" 找到 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. [已失效] 三体合集 — 分享已过期

询问用户想要保存哪个资源。

Save

保存资源

When the user selects a resource, trigger the Quark APP to open the share link:

bash

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

The script tries three methods in order:

desktop_share_visiting

(preferred) →

desktop_caller

deeplink → browser fallback. The response indicates which method succeeded.

After a successful APP save (method

desktop_share_visiting

desktop_caller

), inform the user:

已在夸克 APP 中打开分享链接窗口。注意：弹出的窗口可能很小，请留意任务栏/Dock 上的夸克图标。 在 APP 中点击「保存到网盘」按钮完成保存。保存后文件会出现在你的网盘中，可以直接在 APP 中下载到本地。

If the response method is

browser_fallback

, open the URL in the browser instead and inform the user to save from the web page.

当用户选定资源后，触发Quark APP打开分享链接：

bash

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

脚本会按顺序尝试三种打开方式：

desktop_share_visiting

（优先）→

desktop_caller

深度链接→浏览器兜底。响应会说明最终使用的成功方式。

如果通过

desktop_share_visiting

或

desktop_caller

方式成功唤起APP保存，请告知用户：

已在夸克 APP 中打开分享链接窗口。注意：弹出的窗口可能很小，请留意任务栏/Dock 上的夸克图标。 在 APP 中点击「保存到网盘」按钮完成保存。保存后文件会出现在你的网盘中，可以直接在 APP 中下载到本地。

如果响应显示使用了

browser_fallback

方式，请在浏览器中打开对应URL，并告知用户从网页端完成保存。

Batch Processing

批量处理

When the user wants to search and save multiple resources, loop through the search → present → save workflow for each keyword. Validate all links first via the

search

command, then trigger APP saves sequentially.

当用户需要搜索并保存多个资源时，可对每个关键词循环执行「搜索→展示结果→保存」的工作流。先通过

search

命令验证所有链接，再依次触发APP保存操作。

Error Handling

错误处理

Error	Detection	Resolution
Quark APP not running	`check` returns `code: "app_not_running"`	Tell user to launch Quark APP
Not logged in	`check` returns `isLogin: false`	Tell user to log in
No search results	`search` returns `total: 0`	Suggest different keywords
All links invalid	`search` returns `valid_count: 0`	Try alternative keywords or drive types
Share has password	`validate` returns password required error	Ask user for the extraction code (提取码)
PanSou API error	`search` returns `code: "pansou_error"`	Retry or try later

错误类型	检测方式	解决方法
Quark APP未运行	`check` 命令返回 `code: "app_not_running"`	告知用户启动Quark APP
未登录账号	`check` 命令返回 `isLogin: false`	告知用户先登录Quark账号
无搜索结果	`search` 命令返回 `total: 0`	建议用户更换关键词
所有链接均无效	`search` 命令返回 `valid_count: 0`	建议用户更换关键词或尝试其他类型网盘
分享需要密码	`validate` 命令返回需要密码的错误	向用户索要提取码
PanSou API错误	`search` 命令返回 `code: "pansou_error"`	建议重试或稍后再试

Important Notes

重要说明

All share validation APIs are public (no authentication needed)
The local Quark APP API at
```
localhost:9128
```
requires no authentication
The actual save-to-drive operation happens in the Quark APP UI (user clicks one button)
Download-to-local is handled by Quark APP's built-in download manager
Do not attempt to call Quark's authenticated remote APIs directly

所有分享链接验证API均为公开接口，无需认证
运行在
```
localhost:9128
```
的本地Quark APP API无需认证
实际保存到网盘的操作在Quark APP UI中完成（用户只需点击一次按钮）
下载到本地的操作由Quark APP内置的下载管理器处理
请勿直接调用Quark的需认证远程API