---
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. 分享链接是否仍有效（部分资源可能被屏蔽）