夸克网盘操作技能

通过 Python 脚本操作夸克网盘，支持扫码登录、文件管理、分享、转存等功能。

⚠️ 使用前必读

1. 首次使用必须先登录：运行 python3 scripts/quark_cli.py login 获取 Cookie
2. Cookie 有效期：约 7 天，过期后需重新登录
3. 文件大小限制：单文件最大 40GB（超级会员）
4. 并发限制：避免同时进行多个上传/下载任务
5. COS 上传限制：pds.quark.cn 是阿里云内网地址，外部无法直接解析。实际上传域名是 {bucket}.pds.quark.cn（如 ul-sz.pds.quark.cn），该子域名可正常解析。分片上传流程：pre→hash→PUT parts→commit（含 callback）
6. QQ Bot 图片发送：MEDIA: 语法不支持 qqbot。需直接调用 QQ Bot API：1) 获取 access_token；2) 上传图片到 /v2/users/{chat_id}/files（file_type=1, file_data=base64）；3) 发送消息（msg_type=7, media.file_info）

功能路由表

用户需求	命令	说明
"登录夸克网盘"	python3 scripts/quark_cli.py login	扫码登录获取 Cookie
"列出文件"	python3 scripts/quark_cli.py list [路径]	列出目录内容
"搜索文件"	python3 scripts/quark_cli.py search <关键词>	搜索文件
"上传文件"	python3 scripts/quark_cli.py upload <本地路径> <网盘路径>	上传文件
"下载文件"	python3 scripts/quark_cli.py download <网盘路径> <本地路径>	下载文件
"删除文件"	python3 scripts/quark_cli.py delete <路径>	删除文件/文件夹
"清空文件"	python3 scripts/quark_cli.py clear [路径]	清空指定目录
"创建文件夹"	python3 scripts/quark_cli.py mkdir <名称> [父目录]	创建文件夹
"查看用户信息"	python3 scripts/quark_cli.py user	显示用户信息和容量
"分享文件"	python3 scripts/quark_cli.py share <路径> --expire 7d --passcode 1234	创建分享链接（可设密码）
"查看我的分享"	python3 scripts/quark_cli.py share-list	列出所有分享
"取消分享"	python3 scripts/quark_cli.py share-cancel <分享ID或链接>	取消分享
"转存资源"	python3 scripts/quark_cli.py share-save <分享链接> --to /目标目录	转存他人分享到我的网盘
"批量上传目录"	python3 scripts/quark_cli.py batch-upload <本地目录> --remote-dir /远程目录	批量上传整个目录

分享功能详解

创建分享（带密码）

# 无密码分享，7天有效
python3 scripts/quark_cli.py share /文档/report.pdf --expire 7d

# 带密码分享，30天有效
python3 scripts/quark_cli.py share /文档/report.pdf --expire 30d --passcode 1234

# 永久分享
python3 scripts/quark_cli.py share /文档/report.pdf --expire permanent

转存他人分享

# 基本转存
python3 scripts/quark_cli.py share-save "https://pan.quark.cn/s/xxxxx"

# 带密码转存
python3 scripts/quark_cli.py share-save "https://pan.quark.cn/s/xxxxx 提取码: 1234"

# 指定保存目录
python3 scripts/quark_cli.py share-save "https://pan.quark.cn/s/xxxxx" --to /我的资源

批量上传功能

基本用法

# 上传整个目录到夸克网盘
python3 scripts/quark_cli.py batch-upload /path/to/local/dir --remote-dir /远程目录

# 使用默认远程目录（/备份/日期）
python3 scripts/quark_cli.py batch-upload /path/to/local/dir

高级选项

# 跳过特定文件模式
python3 scripts/quark_cli.py batch-upload /path/to/dir --skip "__pycache__,.pyc,node_modules"

# 限制上传文件大小（MB）
python3 scripts/quark_cli.py batch-upload /path/to/dir --max-size 5

# 组合使用
python3 scripts/quark_cli.py batch-upload ~/.hermes --remote-dir /Hermes备份 --skip "cache,output,__pycache__" --max-size 20

批量上传特性

• ✅ 自动创建远程目录结构
• ✅ 支持秒传（相同文件自动跳过）
• ✅ 进度显示和统计
• ✅ 可配置跳过模式和文件大小限制
• ✅ 自动处理同名文件（夸克会自动加后缀）

Cookie 配置

方式1：环境变量（推荐）

export QUARK_COOKIE="your_cookie_string_here"

方式2：配置文件

python3 scripts/quark_cli.py config --cookie "your_cookie_string_here"

方式3：扫码登录（推荐）

python3 scripts/quark_cli.py login

错误处理

错误码	说明	解决方案
401	未授权	重新登录
403	禁止访问	检查文件权限
404	文件不存在	检查路径
413	文件过大	分片上传或压缩
500	服务器错误	稍后重试
14001	参数错误	检查文件夹参数名（应为file_name）

上传坑点与解决方案

坑点1：文件夹创建参数错误

问题: 使用 dir_name 而非 file_name 会导致 400 错误

# ✅ 正确
{"pdir_fid": parent_fid, "file_name": folder_name, "dir_init_lock": False, "dir_path": ""}

# ❌ 错误
{"pdir_fid": parent_fid, "dir_name": folder_name, ...}

坑点2：callback 编码错误

问题: callback 是 dict，需要 json.dumps 后再 base64

# ✅ 正确
callback_b64 = base64.b64encode(json.dumps(callback).encode()).decode()

# ❌ 错误
callback_b64 = base64.b64encode(callback.encode()).decode()

坑点3：Cookie 鉴权问题

问题: GET 正常但 POST 返回 401

# ✅ 正确：通过 cookies.set() 设置到域名
client = httpx.Client(headers={"User-Agent": "..."})
for part in cookie.split(";"):
    name, value = part.strip().split("=", 1)
    client.cookies.set(name.strip(), value.strip(), domain=".quark.cn")

# ❌ 错误
headers = {"Cookie": cookie_string, ...}
client = httpx.Client(headers=headers)

坑点4：POST 请求必须带公共查询参数

# ✅ 所有请求URL需附加
params={"pr": "ucpro", "fr": "pc", "uc_param_str": ""}

坑点5：重复文件处理

夸克网盘对同名文件自动加 (1)、(2) 后缀，不会覆盖。重跑上传前需清理。

技术实现

• API 基础 URL: https://drive-pc.quark.cn
• 认证方式: Cookie（__pus）
• 上传方式: 分片上传（支持断点续传）
• 下载方式: 直链下载
• 分享协议: 支持密码/有效期设置