sutong
5d296ee38b
- storage/quark/v1/usage.md: 新增重命名操作
- ref/quark-netdisk-helper/SKILL.md: 新增重命名操作
- ref/resource-pipeline/quark-api.md: 端点表新增重命名
POST /1/clouddrive/file/rename {"fid":"...","file_name":"..."}
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
222 lines
5.8 KiB
Markdown
222 lines
5.8 KiB
Markdown
---
|
||
name: quark-netdisk-helper
|
||
description: 夸克网盘 MCP 操作指南（基于 @ptbsare/netdisk-mcp-server）。涵盖配置、浏览、转存、搜索以及缺失功能的 API 补全方案（创建文件夹/移动/删除）。
|
||
---
|
||
|
||
# 夸克网盘 MCP 操作指南
|
||
|
||
## 安装与配置
|
||
|
||
### 1. 安装 MCP Server
|
||
|
||
```bash
|
||
# 全局安装
|
||
npm i -g @ptbsare/netdisk-mcp-server
|
||
```
|
||
|
||
### 2. 配置到 mcporter
|
||
|
||
需要夸克网盘的 Cookie（浏览器登录 pan.quark.cn → F12 → Network → 复制任意请求的 Cookie）：
|
||
|
||
```bash
|
||
mcporter config add netdisk \
|
||
--stdio "npx -y @ptbsare/netdisk-mcp-server" \
|
||
--env "NETDISK_QUARK_COOKIE=你的Cookie"
|
||
```
|
||
|
||
### 3. 验证
|
||
|
||
```bash
|
||
# 健康检查
|
||
mcporter call netdisk.health
|
||
|
||
# 期望输出: ✅ Quark: Quark cookie is valid
|
||
```
|
||
|
||
---
|
||
|
||
## 工具列表与调用方式
|
||
|
||
### 可用工具
|
||
|
||
| 工具 | 功能 |
|
||
|------|------|
|
||
| `netdisk.list` | 浏览目录 |
|
||
| `netdisk.view` | 查看分享链接 |
|
||
| `netdisk.transfer` | 转存文件 |
|
||
| `netdisk.search` | 跨平台搜索资源 |
|
||
| `netdisk.offline_download` | 115 离线下载 |
|
||
| `netdisk.health` | 健康检查 |
|
||
|
||
### 调用语法
|
||
|
||
**必须使用函数式语法**，`key=value` 形式有 bug：
|
||
|
||
```bash
|
||
# ✅ 正确
|
||
mcporter call 'netdisk.list(cloud: "quark", path: "/")'
|
||
|
||
# ✅ 正确 - 查看分享链接
|
||
mcporter call 'netdisk.view(share_link: "https://pan.quark.cn/s/xxx")'
|
||
|
||
# ✅ 正确 - 转存
|
||
mcporter call 'netdisk.transfer(share_link: "https://pan.quark.cn/s/xxx", source_pattern: "/*", target_path: "/目标目录")'
|
||
|
||
# ❌ 错误 - 不要用 key=value 格式
|
||
mcporter call netdisk.list cloud=quark path=/ # 会报路径错误
|
||
```
|
||
|
||
---
|
||
|
||
## 缺失功能与 API 补全
|
||
|
||
`netdisk-mcp-server` 缺少：**创建文件夹、移动文件、删除文件、重命名**。这些操作通过直接调用夸克 API 实现。
|
||
|
||
### 前置准备
|
||
|
||
```bash
|
||
COOKIE="你的夸克Cookie"
|
||
```
|
||
|
||
### 创建文件夹
|
||
|
||
```bash
|
||
curl -s -X POST "https://drive-h.quark.cn/1/clouddrive/file?pr=ucpro&fr=pc" \
|
||
-H "cookie: $COOKIE" \
|
||
-H "content-type: application/json" \
|
||
-H "origin: https://pan.quark.cn" \
|
||
-H "referer: https://pan.quark.cn/" \
|
||
-d '{"pdir_fid":"<父文件夹FID>","file_name":"<新文件夹名>","file_type":0,"dir_init":true}'
|
||
```
|
||
|
||
- `pdir_fid`: 父文件夹的 FID（根目录为 `0`）
|
||
- `file_name`: 新文件夹名称
|
||
- 返回中的 `data.fid` 是新文件夹的 FID
|
||
|
||
### 获取文件夹 FID
|
||
|
||
通过递归查询路径获取：
|
||
|
||
```bash
|
||
# 查根目录
|
||
curl -s "https://drive-h.quark.cn/1/clouddrive/file/sort?pr=ucpro&fr=pc&pdir_fid=0" \
|
||
-H "cookie: $COOKIE" | python -X utf8 -m json.tool
|
||
```
|
||
|
||
需要逐层查找：根 → 子目录1 → 子目录2 → ... → 目标目录 FID
|
||
|
||
或者直接用 MCP 工具列出目录后从输出中提取 `(ID: xxx)`。
|
||
|
||
### 移动文件
|
||
|
||
```bash
|
||
curl -s -X POST "https://drive-h.quark.cn/1/clouddrive/file/move?pr=ucpro&fr=pc" \
|
||
-H "cookie: $COOKIE" \
|
||
-H "content-type: application/json" \
|
||
-H "origin: https://pan.quark.cn" \
|
||
-H "referer: https://pan.quark.cn/" \
|
||
-d '{"action_type":1,"filelist":["<文件FID1>","<文件FID2>"],"to_pdir_fid":"<目标文件夹FID>"}'
|
||
```
|
||
|
||
- `filelist`: 要移动的文件 FID 数组
|
||
- `to_pdir_fid`: 目标文件夹 FID
|
||
- `action_type: 1` 表示移动
|
||
|
||
### 重命名文件
|
||
|
||
```bash
|
||
curl -s -X POST "https://drive-h.quark.cn/1/clouddrive/file/rename?pr=ucpro&fr=pc&__t=$(date +%s)000" \
|
||
-H "cookie: $COOKIE" \
|
||
-H "content-type: application/json" \
|
||
-H "origin: https://pan.quark.cn" \
|
||
-H "referer: https://pan.quark.cn/" \
|
||
-d '{"fid":"<文件FID>","file_name":"<新文件名>"}'
|
||
```
|
||
|
||
### 删除文件
|
||
|
||
```bash
|
||
curl -s -X POST "https://drive-h.quark.cn/1/clouddrive/file/delete?pr=ucpro&fr=pc" \
|
||
-H "cookie: $COOKIE" \
|
||
-H "content-type: application/json" \
|
||
-H "origin: https://pan.quark.cn" \
|
||
-H "referer: https://pan.quark.cn/" \
|
||
-d '{"action_type":2,"filelist":["<文件FID1>","<文件FID2>"]}'
|
||
```
|
||
|
||
---
|
||
|
||
## 转存文件的注意事项
|
||
|
||
### 1. 目标路径必须已存在
|
||
|
||
`netdisk.transfer` 的 `target_path` 必须指向一个**已存在的目录**，不会自动创建。如果目标目录不存在，需要用上面的 API 先创建。
|
||
|
||
### 2. Glob 匹配可能不准
|
||
|
||
`source_pattern` 的 glob 是**跨所有文件夹**匹配的，不是只在指定文件夹下匹配：
|
||
|
||
```bash
|
||
# 例：分享链接中有以下文件
|
||
# [Z-遮-T] 150.mp4, 151.mp4, 152.mp4
|
||
# [1-43 1080P] Z HD 1080P 15.mp4, Z HD 1080P 16.mp4
|
||
|
||
# source_pattern: "/Z-遮-T/15*"
|
||
# 实际会匹配到：150.mp4 + Z HD 1080P 15.mp4（其他文件夹的也匹配到了！）
|
||
# 因为 filePattern = "15*" 会全局匹配所有文件名以15开头的文件
|
||
```
|
||
|
||
**解决方案**：转存后手动清理杂文件（用删除 API）。
|
||
|
||
### 3. 批量操作建议
|
||
|
||
一次传输的文件数不宜过多，建议分批（20-30 个文件一批）。
|
||
|
||
---
|
||
|
||
## 典型工作流
|
||
|
||
### 从腾讯文档读取资源链接 → 转存到夸克
|
||
|
||
```
|
||
1. tx-doc-large-reader 技能读取大文档 → 找到分享链接
|
||
2. netdisk.view() 查看分享内容
|
||
3. netdisk.transfer() 转存到已有目录
|
||
- 若目标目录不存在，先用 Quark API 创建
|
||
4. 验证转存结果
|
||
5. 如有杂文件，用 Quark API 删除
|
||
```
|
||
|
||
### 文件整理
|
||
|
||
```
|
||
1. netdisk.list() 列出目录 → 获取文件 FID
|
||
2. Quark API 创建分段文件夹
|
||
3. Quark API 移动文件到对应文件夹
|
||
4. 验证最终结构
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### 函数式语法报错
|
||
|
||
```
|
||
Error: Folder not found in Quark: "D:" (path: D:/work/environment/Git/)
|
||
```
|
||
|
||
**原因**：使用了 `key=value` 语法，参数被错误解析。
|
||
**解决**：改用函数式语法 `'netdisk.list(cloud: "quark", path: "/")'`。
|
||
|
||
### Cookie 过期
|
||
|
||
健康检查返回 `401/403`，需要重新登录夸克网盘获取新 Cookie。
|
||
|
||
### 转存失败
|
||
|
||
检查：
|
||
1. Cookie 是否有效
|
||
2. 目标路径是否存在
|
||
3. 分享链接是否仍有效（部分资源可能被屏蔽）
|