quark-download

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

语言

匹配用户使用的语言：使用与用户相同的语言回复。

通过结合 PanSou 聚合 API 与本地 Quark 桌面 APP，自动完成整个工作流：搜索资源 → 验证链接 → 保存到 Quark 网盘 → 下载到本地。

所有操作均使用 CLI 脚本 ${SKILL_PATH}/scripts/quark_search.py。脚本将 JSON 输出到 stdout（{"status": "ok", "results": {...}, "hint": "..."}），并将错误输出到 stderr（{"error": "code", "message": "...", "hint": "...", "recoverable": true/false}）。退出代码：0 = 成功，1 = 可恢复错误，2 = 致命错误。

预检（必须先运行）

执行任何业务命令（搜索、验证、保存等）之前，都要运行预检：

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

响应： 标准化 JSON，包含 ready: true/false、dependencies 和 services 状态。

• 如果 ready: true → 继续工作流。
• 如果 ready: false → 按照下方的检查／修复表操作，然后重新运行预检，直到通过。预检通过前，不要进行搜索或保存。

检查	修复
Quark APP 未运行	启动 Quark 桌面 APP，并等待几秒使其启动
Quark APP 未登录	在 Quark APP 中使用会员账号登录

为什么要设置预检关卡？ 搜索本身不需要 Quark APP（它会调用 PanSou Web API），但 save 需要 Quark APP 正在运行且已登录。先运行预检，能避免找到资源后才发现无法保存的糟心情况。

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

前提条件： 预检必须返回 ready: true。

一条命令即可搜索 PanSou、并行验证所有链接，并获取排名靠前结果的文件详情：

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

选项：

标志	默认值	描述
--top N	5	返回详情的有效结果数量上限
--no-validate	off	跳过验证（速度更快，但可能包含失效链接）
--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 — save 命令使用的分享 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 浏览子文件夹（传入之前 detail 响应中的文件夹 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. [已失效] 三体合集 — 分享已过期

询问用户要保存哪一个。

保存

需要夸克 APP 正在运行并已登录。 尝试保存前，请确认本次会话的预检已通过。如不确定，请重新运行预检。

用户选择资源后，触发夸克 APP 打开分享链接：

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

脚本会按顺序尝试三种方法：desktop_share_visiting（首选）→ desktop_caller 深层链接 → 浏览器回退。响应会指明哪种方法成功。

通过 APP 成功保存后（方法为 desktop_share_visiting 或 desktop_caller），告知用户：

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

如果响应中的方法为 browser_fallback，则改为在浏览器中打开 URL，并告知用户在网页中保存。

批量处理

用户要搜索并保存多个资源时，请针对每个关键词循环执行搜索 → 展示 → 保存工作流。先通过 search 命令验证所有链接，再依次触发 APP 保存。

完成报告

成功保存后，向用户展示以下摘要：

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

错误处理

错误	检测方式	解决方法
夸克 APP 未运行	preflight 返回 ready: false，服务为 not_running	告知用户启动夸克 APP
未登录	preflight 返回 ready: false，提示中提到登录	告知用户登录
APP 在会话中断开连接	之前预检已通过，但 save 返回 app_not_running 错误	重新运行预检；如果失败，告知用户重启夸克 APP 并重新登录
没有搜索结果	search 返回 total: 0	建议更换关键词
所有链接均无效	search 返回 valid_count: 0	尝试其他关键词或网盘类型
分享链接设有密码	validate 返回需要密码错误	向用户索要提取码
PanSou API 错误	search 返回 error: "pansou_error"	重试或稍后再试

故障排查

现象	可能原因	解决方法
localhost:9128 refused	夸克 APP 未运行	启动夸克桌面 APP
preflight 通过但 save 失败	APP 窗口已最小化或隐藏	检查任务栏/Dock 上的夸克图标，并将窗口切到前台
搜索返回结果，但所有结果均无效	资源已过期或被移除	尝试其他关键词或扩大搜索范围
每次搜索都出现 pansou_error	PanSou API 宕机或网络问题	稍后重试；检查网络连接
使用了 browser_fallback 方法	夸克 APP 本地 API 无响应	重启夸克 APP；确保使用的是桌面版（而非手机版）
详情返回的文件列表为空	分享需要提取码	向用户索要提取码，并使用密码重新验证

重要说明

• 所有分享验证 API 均为公开 API（无需身份验证）
• localhost:9128 上的夸克 APP 本地 API 无需身份验证
• 实际的保存到网盘操作在夸克 APP 界面中完成（用户点击一个按钮）
• 下载到本地由夸克 APP 内置的下载管理器处理
• 不要尝试直接调用夸克需要身份验证的远程 API