quark-download

夸克搜索 — 网盘资源搜索与下载

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

所有操作都使用 ${SKILL_PATH}/scripts/quark_search.py 中的 CLI 脚本。脚本将 JSON 输出到 stdout（{"ok": true, "data": {...}} 或 {"ok": false, "error": "...", "code": "..."}），并将进度日志输出到 stderr。

前置条件检查

执行任何操作前，请验证环境：

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

响应： {"ok": true, "data": {"isLogin": true, ...}} — 确认 APP 正在运行且已登录。

如果命令失败并返回 "code": "app_not_running"，请让用户启动夸克 APP。如果 isLogin 为 false，请让用户先登录。

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

一条命令即可搜索 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 — 通过验证的夸克链接数量
• results[].pwd_id — 用于保存命令的分享 ID
• results[].detail.list[] — 分享中的文件/文件夹
• results[].detail.list[].dir — 如果是文件夹则为 true（比 file_type 更可靠）
• results[].detail.list[].fid — 与 detail 命令搭配使用，可浏览子文件夹

没有夸克结果： 当 results 为空但 total > 0 时，响应会包含 type_counts，显示其他网盘类型的可用结果。请将这些结果告知用户。

优先级： 始终优先选择 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 可浏览子文件夹（传入之前 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 打开分享链接：

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 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 均为公开接口（无需身份验证）
• 本地 Quark APP API（localhost:9128）无需身份验证
• 实际的保存到网盘操作在 Quark APP UI 中完成（用户点击一个按钮）
• 下载到本地由 Quark APP 内置的下载管理器处理
• 请勿尝试直接调用 Quark 的身份验证远程 API