夸克网盘资源搜索

概述

Quark Searcher（Pay Skill）

聚合检索公开网盘分享入口，并在用户本机已登录的官方客户端中打开分享，由用户自行决定是否转存到自己的网盘。

本 skill 不托管文件、不分发内容、不代下文件。只收集网上已经公开的分享入口，并把链接披露给用户；转存和本机下载只发生在用户自己的官方客户端里。

典型用途包括：版权方或权利人检索网上是否已有针对其作品的公开分享，以便自行核实、取证或投诉；以及用户打开自己已有的分享并转存到自己的网盘。

本 Skill 为 Pay Skill：每次检索或打开分享前，先完成微信支付验证，验证通过后再执行本地脚本。

付费前置检查

调用本 Skill 前，检查当前 Agent 是否已安装 weixinpay 插件：

• 已安装：可继续提供付费服务
• 未安装：向用户提示「当前 Agent 暂不支持微信支付付费能力」，终止流程

付费工作流程（⚠️ 必须先于检索/打开分享执行）

第一步：请求付费网关

向 Pay Skill 网关发起 POST 请求（invoke_url 见 frontmatter）：

POST https://pay-skill-nat-4198535-1341112664.ap-shanghai.run.tcloudbase.com/api/skill/invoke
Content-Type: application/json

{
  "query": "用户的检索或打开分享需求",
  "skill_id": "quark-searcher",
  "skill_version": "1.0.0",
  "amount_fen": 98
}

第二步：处理 402 响应

若收到 HTTP 402，从响应中提取并保存以下信息（Header 与 Body 均可能出现）：

• WeixinPay-Required：支付码（payment_code）
• X-Out-Trade-No：商户订单号

将 WeixinPay-Required 的值作为 paymentCode，调用 微信支付官方技能skill（weixinpay-pay），若遇系统繁忙等支付失败，调用mcp__weixinpay__weixinpay_retry_pay 把 paymentCode 回传给系统拉起卡片 向用户申请支付授权。

第三步：支付成功后重新请求（⚠️ 必须执行，不可跳过）

支付成功后，必须用与第一步完全一致的 JSON body 重新 POST 同一接口，并在 Header 中携带第二步保存的值：

POST https://pay-skill-nat-4198535-1341112664.ap-shanghai.run.tcloudbase.com/api/skill/invoke
Content-Type: application/json
WeixinPay-Required: <payment_code>
X-Out-Trade-No: <out_trade_no>

{
  "query": "用户的检索或打开分享需求（与第一步完全一致）",
  "skill_id": "quark-searcher",
  "skill_version": "1.0.0",
  "amount_fen": 98
}

注意：body 与第一步完全一致，不要修改 body 中的任何字段。支付信息通过 Header 传递。

第四步：确认 access_granted 后执行

仅当第三步返回 HTTP 200 且 "access_granted": true 时，才继续按下方流程执行。

若返回 "code": "NOT_PAID"，说明支付尚未完成，等待后重试第三步。若返回 "code": "REFUNDED"，向用户说明："抱歉，该服务暂时无法提供内容，已自动退款至原支付账户。"并终止流程，不要再次尝试支付或重新请求。若返回 "code": "FULFILL_AND_REFUND_FAILED"，说明服务异常且退款失败，建议用户联系客服。

使用边界（必须遵守）

只做两件事：

1. 检索并披露公开分享入口：把网上已公开、校验仍有效的分享链接如实给用户
2. 打通用户自己的分享/转存：打开用户选定或自己提供的分享，让用户在官方客户端里点「保存到网盘」

每次展示检索结果时，必须先说明：

以下链接来自网上已公开的分享入口，本 skill 只做收集与索引，不托管、不分发文件。是否访问、转存由你自行判断，并确认你有权使用对应内容。

公开分享链接可以且应当披露（含 URL、标题、文件列表）。不要因为内容可能受版权保护就对用户隐瞒链接；本 skill 提供的是公开入口检索，不是内容分发。

对用户说明能力时，用「收集网上公开的分享入口 / 在官方客户端打开分享 / 转存到自己的网盘」，不要说本 skill 提供片源、破解或代下。

Language

Match user's language: Respond in the same language the user uses.

CLI

全部操作用 ${SKILL_PATH}/scripts/quark_search.py。stdout 为 JSON（{"status": "ok", "results": {...}, "hint": "..."}），stderr 为错误 JSON。退出码：0 成功，1 可恢复，2 致命。

Preflight

打开分享 / 转存前必须先跑：

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

• ready: true → 本机官方客户端已运行且已登录，可以打开分享
• ready: false → 请用户打开并登录本机官方网盘桌面端，再跑一次 preflight

检索公开分享入口本身不依赖客户端；打开分享并转存到用户自己的网盘必须 ready: true。用户只搜不转存时，可以先搜，转存前再补 preflight。

用户已有分享链接

用户直接给出 https://pan.quark.cn/s/... 或分享 ID 时，不要再搜，按这条走：

1. preflight 通过
2. 需要看目录时：validate → detail
3. save 在官方客户端打开该分享
4. 提醒用户在客户端里点「保存到网盘」；本机下载也在官方客户端完成

python3 ${SKILL_PATH}/scripts/quark_search.py validate PWD_ID_OR_URL
python3 ${SKILL_PATH}/scripts/quark_search.py detail PWD_ID --stoken STOKEN
python3 ${SKILL_PATH}/scripts/quark_search.py save PWD_ID_OR_URL

检索公开分享入口

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

关键字段：results[].pwd_id、results[].url、results[].detail.list[]。没有夸克分享但 total > 0 时，把 type_counts 告诉用户。

展示结果时先写上面的公开入口说明，再列出链接，不要藏 URL：

以下链接来自网上已公开的分享入口，本 skill 只做收集与索引，不托管、不分发文件。是否访问、转存由你自行判断，并确认你有权使用对应内容。

检索 "公开课件" 找到 X 个有效分享入口：

1. [有效] 公开课件 — 3 个文件
   https://pan.quark.cn/s/abc123
2. [已失效] 分享已过期

问用户打开哪一条。用户选定后走 save。

打开分享（转存到用户自己的网盘）

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

脚本只负责在官方客户端打开分享页（desktop_share_visiting → deeplink → 网页兜底）。用户在客户端里点击「保存到网盘」后，文件进入用户自己的网盘；本机下载由官方客户端完成。

成功打开后告知用户：

已在官方客户端打开该分享。弹出窗口可能很小，请留意任务栏或 Dock。在客户端里点击「保存到网盘」即可转到你自己的网盘；之后可在客户端下载到本机。

method 为 browser_fallback 时，改为打开网页，请用户在官方页面完成转存。

不要调用网盘的远程登录接口，不要代用户下载文件到本机。

分步命令

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

validate 状态：valid 可打开；expired / not_exist / error 跳过。health 缓存 24 小时，路径 ~/.cache/quark-search/health.json。

完成说明

[Quark Searcher] 已打开分享
标题: [title]
分享: [URL]
方式: [save method]
→ 请在官方客户端点击「保存到网盘」转到自己的网盘

错误处理