quark-search

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桌面端应用，实现全流程自动化：搜索资源→校验链接→保存到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, ...}}

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

如果命令返回失败且错误码为

"code": "app_not_running"

，请引导用户启动Quark应用。如果

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搜索、并行校验所有链接、获取靠前结果的文件详情：

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应用打开分享链接：

bash

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

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

desktop_share_visiting

（优先）→

desktop_caller

深度链接→ 浏览器兜底。响应会告知哪种方式执行成功。

当应用保存成功（使用

desktop_share_visiting

或

desktop_caller

方式）时，告知用户：

已在夸克 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

命令校验所有链接，再按顺序触发应用保存。

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应用未运行	`check` 接口返回 `code: "app_not_running"`	告知用户启动Quark应用
未登录账号	`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应用API无需鉴权
实际保存到网盘的操作在Quark应用UI中完成（用户仅需点击一次按钮）
下载到本地的操作由Quark应用内置的下载管理器处理
请勿直接调用Quark的鉴权远程API