- # 夸克网盘 Skill 对接指南
> 本文档记录夸克网盘 Skill 的安装、授权、常用命令及注意事项，供其他智能体快速对接使用。
---
一、Skill 安装
1.1 下载 Skill 包
```bash
从官方链接下载（需替换为最新版本）
curl -L -o /tmp/quarkclouddrive.zip \
-H "User-Agent: Mozilla/5.0" \
"https://pdds.quark.cn/download/stfile/kkqqltosqklokmsmf/quarkclouddrive-1.0.12.zip"
```
1.2 解压到 Skill 目录
```bash
创建技能目录
mkdir -p /root/.hermes/skills/quark-clouddrive
解压
unzip -o /tmp/quarkclouddrive.zip -d /root/.hermes/skills/quark-clouddrive/
```
1.3 运行安装脚本
```bash
cd /root/.hermes/skills/quark-clouddrive
bash scripts/install.sh
```
安装脚本会自动：
- 检测 Node.js >= 16
- 验证 CLI 版本与 SKILL.md 版本一致
- 生成自检验证
---
二、授权登录
2.1 启动登录流程
```bash
cd /root/.hermes/skills/quark-clouddrive
node scripts/quark-drive.cjs login
```
注意： 登录命令会阻塞等待用户完成授权，需在后台运行或交互式环境使用。
2.2 获取授权链接
登录后会返回 NDJSON 格式的输出：
```json
{"code":-106,"msg":"你好像还没完成授权？...","action":"login","type":"result","data":{}}
```
从中提取 `msg` 字段中的授权链接，格式为：
```
https://pan.quark.cn/open/v1/oauth/agent?device_id=xxx&page_code=xxx&...#/agent-oauth
```
2.3 用户完成授权
- 用户用夸克网盘 APP 扫描或点击授权链接
- 在 APP 内确认授权
- 浏览器跳转后，从 URL 中复制 `code` 参数值
2.4 提交授权码
```bash
node scripts/quark-drive.cjs login --token ""
```
返回 `code: 0` 表示授权成功。
---
三、常用命令速查
3.1 查看用户信息
```bash
node scripts/quark-drive.cjs get-user-info
```
返回示例：
```json
{
"code": 0,
"msg": "成功",
"data": {
"vipInfo": {"vipType": "NORMAL", "used": 16749243474, "capacity": 21495808000},
"userInfo": {"nickname": "猪班长"}
}
}
```
- `vipType`: NORMAL(普通) / SVIP(超级会员)
- `used`: 已用空间（字节）
- `capacity`: 总容量（字节）
3.2 搜索文件
```bash
基本搜索
node scripts/quark-drive.cjs search --keyword "关键词"
仅获取FID列表（不展示给用户）
node scripts/quark-drive.cjs search --keyword "关键词" --stdout-only
```
搜索结果包含：
- `total`: 总文件数
- `file_list`: 文件列表（最多5条预览）
- `check_all_link`: 查看全部结果的链接
- `browse_hint`: 浏览提示文案
完整结果写入 JSONL 文件，路径在 `artifact` 行中：
```json
{"code":0,"msg":"成功","data":{"file_path":"/root/.hermes/skills/quark-clouddrive/hermes/search/.../search-xxx.jsonl","count":10,"format":"jsonl"}}
```
3.3 创建文件夹
```bash
node scripts/quark-drive.cjs create-folder --dir-path "文件夹名称"
```
返回：
```json
{"code":0,"msg":"成功","data":{"fid":"xxx","full_path":"夸克网盘/来自：xxx"}}
```
3.4 移动文件/文件夹
```bash
移动到根目录
node scripts/quark-drive.cjs move "" --target-fid "0"
移动到指定目录
node scripts/quark-drive.cjs move "" --target-fid ""
```
3.5 上传文件
```bash
上传单个文件
node scripts/quark-drive.cjs upload "/本地文件路径.txt"
上传到指定目录
node scripts/quark-drive.cjs upload "/本地文件路径.txt" --parent-fid ""
查看上传任务列表
node scripts/quark-drive.cjs upload list
```
3.6 下载文件
```bash
下载到当前目录
node scripts/quark-drive.cjs download --fid ""
指定下载目录
node scripts/quark-drive.cjs download --fid "" --output-dir "./downloads"
覆盖同名文件
node scripts/quark-drive.cjs download --fid "" --overwrite
查看下载任务列表
node scripts/quark-drive.cjs download list
```
3.7 分享文件
```bash
创建分享链接
node scripts/quark-drive.cjs share "" "" --title "分享标题"
获取分享详情
node scripts/quark-drive.cjs share-detail ""
```
注意： 分享需要手机号实名绑定，否则返回错误：
```json
{"code":32011,"msg":"当前夸克网盘账号未绑定手机号/实名认证，无法为您进行操作..."}
```
3.8 AI 助手功能
```bash
总结文件内容
node scripts/quark-drive.cjs summary \
--fid-list "," \
--query "总结这个文件的内容"
基于文件问答
node scripts/quark-drive.cjs qa \
--fid-list "," \
--query "这个问题怎么解决？"
```
3.9 相册整理
```bash
AI自动整理照片/视频
node scripts/quark-drive.cjs organize --query "把去年日本旅行的照片按东京大阪京都整理一下"
确认整理方式（复制）
node scripts/quark-drive.cjs organize-copy --fid-list ""
确认整理方式（移动）
node scripts/quark-drive.cjs organize-move --fid-list ""
```
3.10 转存分享链接
```bash
转存整个分享
node scripts/quark-drive.cjs saveas --url ""
转存指定文件
node scripts/quark-drive.cjs saveas --fid "" --to-pdir-fid ""
```
---
四、公共参数说明
所有命令都支持以下参数：
| 参数 | 说明 | 是否必填 |
|------|------|----------|
| `--session-input` | 用户原始提问文本，用于服务质量追踪 | 建议传 |
| `--session-id` | 会话唯一标识，格式 `{timestamp}-{random}`，同一对话复用 | 建议传 |
| `--verbose` | 启用详细日志输出 | 可选 |
session-id 生成示例：
```bash
python3 -c "import time,random; print(f'{int(time.time())}-{random.randint(100000,999999)}')"
输出: 1786966079-599889
```
---
五、错误处理
5.1 未授权错误
```json
{"code":-103,"msg":"未登录，请先执行 login 命令完成登录授权"}
```
处理：调用 `login` 命令重新授权。
5.2 非零错误码
当返回 `code` 为非零负数且 `msg` 包含"未授权"、"认证"等关键词时，表示授权失效，需重新登录。
5.3 分享限制
```json
{"code":32011,"msg":"当前夸克网盘账号未绑定手机号/实名认证..."}
```
处理：引导用户到夸克网盘 APP 完成手机号绑定。
---
六、最佳实践
6.1 调用顺序
```bash
1. 先检查授权状态
node scripts/quark-drive.cjs get-user-info
2. 搜索获取文件FID
node scripts/quark-drive.cjs search --keyword "xxx" --stdout-only
3. 执行具体操作（上传/下载/分享等）
node scripts/quark-drive.cjs download --fid ""
```
6.2 大文件处理
- 上传/下载支持断点续传
- 可查看任务列表：`upload list` / `download list`
- 恢复中断任务：`upload resume` / `download resume`
6.3 权限边界
- 只能操作当前授权账号的网盘
- 无法访问其他用户的共享文件夹（除非被分享给当前账号）
- 分享链接有效期由用户设置（永久/7天/30天）
---
七、卸载
```bash
撤销授权并清除配置
node scripts/quark-drive.cjs logout
删除 skill 目录
rm -rf /root/.hermes/skills/quark-clouddrive
```
---
## 八、参考资料
- 官方文档：`/root/.hermes/skills/quark-clouddrive/SKILL.md`
- 授权管理：`/root/.hermes/skills/quark-clouddrive/references/auth.md`
- 文件操作：`/root/.hermes/skills/quark-clouddrive/references/file-ops.md`
- 分享管理：`/root/.hermes/skills/quark-clouddrive/references/file-share.md`