# dsh-qbittorrent

[English](README.md) | 中文

DeepSeek Harness (DSH) 插件：把 qBittorrent 的 WebAPI v2 注册成模型可直接调用的工具，
用于列种子、排查卡死的下载，以及执行一小批受闸门保护的写操作。不开浏览器页面，
也不起 MCP 子进程——工具通过 `@deepseek-ai/dsh-tools` 原生注册。

## 安装

```sh
dsh plugin --profile web add @wuzhican/dsh-qbittorrent
```

若 profile 没有启用配置热重载，装完重启 `dsh web`。

## 配置

不配也能跑。所有键都可选，写在 patch 条目的 `config` 里：

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| `url` | `http://127.0.0.1:8080` | qBittorrent WebUI 地址（也读 `QBT_URL` 环境变量） |
| `tokenRef` | `QBT_API_KEY` | 存放 Bearer 令牌的凭据名（也读 `QBT_TOKEN_REF`） |
| `timeoutMs` | `30000` | 单请求超时 |

```yaml
- insert:
    - id: qbittorrent
      name: '@wuzhican/dsh-qbittorrent'
      config:
        url: http://192.168.1.10:8080
        tokenRef: QBT_API_KEY
```

**令牌不写进 patch 文件。** 它按名字走 DSH 凭据服务解析，解析不到再回退到
`process.env`。qBittorrent v5.2.x 只认 `Authorization: Bearer <token>`；
`X-API-Key`、`api-key`、查询参数三种写法一律返回 403。

## 工具

共注册 9 个工具：

| 工具 | 用途 |
| --- | --- |
| `qb_status` | 版本、WebAPI 版本、各状态种子计数、传输概况 |
| `qb_list_torrents` | 按 `filter` / `category` / `tag` / `hashes` / `sort` 列种子，上限 200 条 |
| `qb_torrent_detail` | 单个种子的属性与文件清单 |
| `qb_list_categories` | 全部分类及其存档路径 |
| `qb_find_orphans` | 元数据从未取回、名称仍是裸 infohash、报错或文件缺失的种子 |
| `qb_resume_torrent` | 继续下载——需 `confirm: true` |
| `qb_pause_torrent` | 暂停——需 `confirm: true` |
| `qb_set_category` | 改分类——需 `confirm: true` |
| `qb_delete_torrent` | 移除——需 `confirm: true` 且 `expect` 与哈希个数相等；单次最多 20 个；`deleteFiles: true` 会连带删除盘上数据 |

写操作不带 `confirm: true` 一律拒绝。接口失败以工具结果返回而不是抛异常，
一次调用失败不会终结整轮对话。

## 运行要求

- DSH `>=0.2.0-rc.1`
- Node >= 18（需要全局 `fetch` 与 `AbortSignal.timeout`）
- 开启 WebAPI v2 并配有 API 令牌的 qBittorrent

无运行时依赖。`@deepseek-ai/cordis` 与 `@deepseek-ai/dsh-tools` 是 peer 依赖，
由 harness 本身提供。

## 许可

MIT