qbittorrent

qBittorrent WebUI API

⚠️ 必须调用技能 ⚠️

用户提及以下任一触发词时，必须调用此技能（不是可选项）：

• “qBittorrent 状态”、“种子列表”、“活动种子”
• “暂停种子”、“恢复种子”、“删除种子”
• “添加种子”、“qBit”、“下载管理器”
• 任何提及 qBittorrent 或种子管理的内容

触发条件出现时未调用此技能，将违反你的操作要求。

通过 qBittorrent 的 WebUI API（v4.1+）管理种子。

用途

此技能可对你的 qBittorrent 种子客户端进行读取和写入操作：

• 监控活动、做种和已完成的种子
• 通过磁力链接、URL 或文件上传添加种子
• 控制种子状态（暂停、恢复、删除）
• 管理分类和标签
• 调整全局及单个种子的速度限制
• 查看种子文件、Tracker 和属性
• 重新检查种子数据完整性

操作包括读取和写入。删除种子并同时删除文件前，务必先确认。

设置

将凭据添加到 ~/.claude-homelab/.env：

QBITTORRENT_URL="http://localhost:8080"
QBITTORRENT_USERNAME="admin"
QBITTORRENT_PASSWORD="adminadmin"

设置文件权限：

chmod 600 ~/.claude-homelab/.env

快速参考

列出种子

# All torrents
./scripts/qbit-api.sh list

# Filter by status
./scripts/qbit-api.sh list --filter downloading
./scripts/qbit-api.sh list --filter seeding
./scripts/qbit-api.sh list --filter paused

# Filter by category
./scripts/qbit-api.sh list --category movies

筛选条件：all、downloading、seeding、completed、paused、active、inactive、stalled、errored

获取种子信息

./scripts/qbit-api.sh info <hash>
./scripts/qbit-api.sh files <hash>
./scripts/qbit-api.sh trackers <hash>

添加种子

# By magnet or URL
./scripts/qbit-api.sh add "magnet:?xt=..." --category movies

# By file
./scripts/qbit-api.sh add-file /path/to/file.torrent --paused

控制种子

./scripts/qbit-api.sh pause <hash>         # or "all"
./scripts/qbit-api.sh resume <hash>        # or "all"
./scripts/qbit-api.sh delete <hash>        # keep files
./scripts/qbit-api.sh delete <hash> --files  # delete files too
./scripts/qbit-api.sh recheck <hash>

分类和标签

./scripts/qbit-api.sh categories
./scripts/qbit-api.sh tags
./scripts/qbit-api.sh set-category <hash> movies
./scripts/qbit-api.sh add-tags <hash> "important,archive"

传输信息

./scripts/qbit-api.sh transfer   # global speed/stats
./scripts/qbit-api.sh speedlimit # current limits
./scripts/qbit-api.sh set-speedlimit --down 5M --up 1M

应用信息

./scripts/qbit-api.sh version
./scripts/qbit-api.sh preferences

响应格式

种子对象包含：

• hash、name、state、progress
• dlspeed、upspeed、eta
• size、downloaded、uploaded
• category、tags、save_path

状态：downloading、stalledDL、uploading、stalledUP、pausedDL、pausedUP、queuedDL、queuedUP、checkingDL、checkingUP、error、missingFiles

工作流

用户询问种子相关内容时：

1. “正在下载什么？” → 运行 list --filter downloading
2. “添加这个磁力链接” → 运行 add "<magnet>" 并指定适当的分类
3. “暂停所有种子” → 运行 pause all
4. “恢复做种” → 运行 resume all 或按哈希筛选
5. “显示种子详情” → 运行 info <hash> 和 files <hash>
6. “按分类列出” → 运行 list --category movies
7. “设置速度限制” → 运行 set-speedlimit --down 5M --up 1M

说明

• 需要能够访问你的 qBittorrent 服务
• 使用 qBittorrent WebUI API v4.1+
• 所有数据操作均返回 JSON
• 使用 --files 执行的删除操作不可撤销——删除已下载文件前务必先确认
• 速度限制支持以下单位：K（KB/s）、M（MB/s）或原始字节数
• 添加磁力链接和种子 URL 时无需上传本地文件
• 分类必须已存在才能分配（通过 WebUI 或 API 创建）

---

🔧 Agent 工具使用要求

**重要：**通过 zsh-tool 调用此技能中的脚本时，始终使用 pty: true。

未启用 PTY 模式时，即使命令成功执行，也无法看到命令输出。

正确的调用模式：

<invoke name="mcp__plugin_zsh-tool_zsh-tool__zsh">
<parameter name="command">./skills/SKILL_NAME/scripts/SCRIPT.sh [args]</parameter>
<parameter name="pty">true</parameter>
</invoke>

脚本

脚本	用途
qbit-api.sh	主 API 封装脚本 — 执行所有种子操作
qbit-api-wrapper.sh	轻量级 PTY 封装脚本 — 通过 printf 捕获并重新打印 qbit-api.sh 的输出，确保在标准输出缓冲可能导致输出不可见的环境中也能看到结果