feat: 新增种子目录清理脚本与配套 skill

主程序只能把 magnet 交给 Transmission,无法挑选文件,种子内的广告
(*.url、宣传页、样片/预告)会一并下载,同一部作品还会被多个发布站各下一份。
新增离线清理脚本处理下载完成后的目录。

clean_seed_extras.py:
- 保留:>=100MB 的视频(40+ 扩展名;无扩展名时读文件头嗅探)、字幕
  (含 .srt.old-<日期> 备份)、与同目录视频同名的海报、folder.jpg 等通用封面
- 删除:其余文件;同目录内内容相同的大视频只保留一份,校验方式为
  sha256(体积 + 头 4MB + 尾 4MB),体积相同但内容不同的不会误删
- 删除后自底向上级联清理空目录(可删到影片级目录,但不删 --root 本身)
- 默认预演,需 --apply 才真正删除;--manifest 导出待删清单供逐段复核
- 其他开关:--no-subtitles/--no-posters/--no-covers/--no-dedupe/--min-size-mb/
  --prefer-source/--keep-empty-dirs/--skip-recent-min

.agents/skills/torrent-download-cleanup:
- 记录完整流程(预演 -> 出清单 -> 用户确认 -> 执行 -> 复核)、保留/删除规则、
  去重策略、代码维护注意(decide() 必须是 视频 -> 去重 -> 海报匹配 的顺序)
- 附只读盘点脚本 find_missing_torrents.py:找出 Transmission 中数据已不在磁盘
  的任务(自包含,只用 requests)

tests/test_clean_seed_extras.py: 30 个离线用例(tmp_path 临时目录)
tests/README.md: 补充脚本用法与测试说明
This commit is contained in:
2026-10-18 00:54:08 +08:00
parent 01827224d6
commit 827bbb6b6a
6 changed files with 1372 additions and 13 deletions
@@ -0,0 +1,146 @@
---
name: torrent-download-cleanup
description: 用 clean_seed_extras.py 清理 LookingWeb 的种子下载目录(默认 /mnt/fnOS/123):保留大体积视频、字幕、同名海报与通用封面,删除广告/样片/重复视频并级联清理空目录。当用户要求"清理/整理下载目录、删除重复视频、看看有哪些垃圾可以删、下载完成了清一下",或需要继续上一次的清理流程与 Transmission 收尾时使用。
---
# 种子下载目录清理(LookingWeb)
主程序 `LookingWebMain.py` 只能把 magnet 交给 Transmission,**无法挑选文件**,所以种子里的广告
(`*.url`、宣传页、样片、预告)会和正片一起下载;同一部作品还会被多个发布站各下一份。
本 skill 负责下载完成后的离线清理,与主程序互不依赖。
## 硬性流程(必须遵守)
1. **先预演**:`--quiet` 看汇总,`--manifest` 导出完整清单。绝不直接 `--apply`。
2. **把清单给用户看**:报数量、体积、分段行号,并把"可能误伤"的类别单独列出来
(小体积视频、通用封面、会被整体清空的影片级目录)。
3. **拿到明确确认后才执行** `--apply`。删除不可逆,这是硬边界。
4. **执行后复核**:文件数是否等于预演的"保留"数、垃圾是否清零、再跑一次预演是否 0 删除。
5. **不要用 `df` 宣称"释放了空间"**(原因见下文"磁盘空间")。
## 脚本
`clean_seed_extras.py`(仓库根目录,仅依赖 loguru)。
```bash
cd <repo> # 例如 ~/Documents/myProject/lookingWeb
.venv/bin/python clean_seed_extras.py --quiet --manifest clean_manifest.txt # 预演 + 导出清单
.venv/bin/python clean_seed_extras.py --apply --quiet # 确认后执行
```
| 参数 | 作用 |
|---|---|
| `--root PATH` | 目标目录,默认 `/mnt/fnOS/123/` |
| `--min-size-mb N` | "大视频"阈值,默认 100 |
| `--apply` | 真正删除;不加则只预演 |
| `--manifest PATH` | 导出待删清单(文件 + 空目录) |
| `--list-all` / `--list-limit N` | 预演时是否列出全部待删项 |
| `--no-subtitles` | 连字幕一起删 |
| `--no-posters` | 不保留任何图片 |
| `--no-covers` | 不保留 `folder.jpg` 等通用封面(只留同名海报) |
| `--no-dedupe` | 关闭重复视频去重 |
| `--dup-check-bytes N` | 重复校验头/尾各读多少字节,默认 4MB |
| `--prefer-source a,b` | 优先保留的站点前缀 |
| `--keep-empty-dirs` | 不删空目录 |
| `--skip-recent-min N` | 跳过最近 N 分钟内改动过的文件(防误删在下的) |
| `--quiet` | 只输出统计,不逐条列文件 |
## 保留 / 删除规则
保留(命中任一):
1. **视频**:扩展名在 `VIDEO_EXTS` 内(mp4/mkv/avi/wmv/ts/m2ts/rmvb/iso…共 40+ 种)
且体积 `>= --min-size-mb`;扩展名未知或无扩展名时读**文件头**嗅探
(ftyp / EBML / RIFF-AVI / FLV / ASF / MPEG-PS / TS 双同步字节 / RMF)。
2. **字幕**:文件名含 `.srt/.ass/.ssa/.vtt/.sub/.idx/.sup/.smi` 等,
含 `xxx.CN.srt.old-<日期>` 这类备份。
3. **海报**:图片扩展名,且文件名包含**同目录**下某个已保留视频的文件名主干。
4. **通用封面**:`folder.jpg` / `poster.jpg` / `cover.jpg` / `backdrop.jpg` / `fanart.jpg`
等媒体库约定名(Jellyfin/Emby/Kodi 当封面用),且同目录下确实还有保留的视频
(目录里没视频时封面算无主垃圾,一并删)。
删除:其余全部;外加**同目录内内容相同的大视频只保留一份**。
删除完成后**自底向上级联清空目录**:子目录先删,父目录变空后继续向上删,
可一路删到影片级目录,但**不删 `--root` 本身**。
不跟随符号链接目录;删符号链接只删链接本身。
## 重复视频去重
同一部作品被多个发布站各下一份时,文件名只差站点前缀,例如:
```
masex.tv@vrkm01874_1_8k.mp4 ← 保留
hkbisi.com@vrkm01874_1_8k.mp4 ← 删除(体积与头尾指纹完全一致)
```
- 先按「同目录 + 同体积」分组(几乎不耗 IO),再对每组算
`sha256(体积 + 头 4MB + 尾 4MB)` 确认内容一致。**体积相同但内容不同的不会误删。**
- 不做全量哈希:740 个视频约 3.5TB,读全量不现实。
- 保留哪一份依次比较:**无站点前缀** > `--prefer-source` 指定站点 >
同目录内该前缀出现次数更多(保持目录内命名一致)> 文件名短 > 字典序。
- 实测站点前缀:`masex.tv@`、`4k2.com@`、`4k2.me@`、`hkbisi.com@`、`twojav.com@`、`489155.com@`。
## 代码维护注意(改 `decide()` 时)
处理顺序**必须是**:① 标记达阈值视频 → ② 去重 → ③ 字幕/海报/封面匹配。
去重必须排在海报匹配之前:否则"被删副本的同名海报"要等到下一轮才被清掉,脚本就不是一次收敛
(历史上踩过这个坑,测试 `test_去重后副本的同名海报一并删除` 会断言"再跑一次无事可做")。
另外第 ③ 轮的入口是 `if entry.keep or entry.reason: continue`——`reason` 非空表示已定案
(保留或已判为重复视频),不能被覆盖成"待删除"。
改完必须同步:`tests/test_clean_seed_extras.py`(离线用例)与 `tests/README.md`。
```bash
.venv/bin/python -m pytest tests/test_clean_seed_extras.py -v
```
## 执行后的复核清单
```bash
cd /mnt/fnOS/123
find . -type f | wc -l # 应等于预演的"保留"数
find . -type f -size +100M -name '*.mp4' -printf '%h\t%s\n' | sort | uniq -d | wc -l # 应为 0 组
find . -name '*.url' | wc -l # 应为 0
find . -type d -name '.pad' | wc -l # 应为 0
find . -type d -name '*.trickplay' | wc -l # 应为 0
.venv/bin/python <repo>/clean_seed_extras.py --quiet # 再跑一次应为"删除: 0"(幂等)
```
## Transmission 收尾(每次清理后都要看一眼)
清理会让 Transmission 里的任务缺文件:被清掉的样片/预告 → 部分缺失;
被去重删掉的那一侧副本 → 该任务**数据全部不在磁盘上**。
先用只读脚本盘点(`scripts/find_missing_torrents.py`,自包含,只用 requests,不修改任何东西):
```bash
.venv/bin/python .agents/skills/torrent-download-cleanup/scripts/find_missing_torrents.py
.venv/bin/python .../find_missing_torrents.py --json # 机器可读输出
.venv/bin/python .../find_missing_torrents.py --host 192.168.123.199 --port 9095
```
输出里标 `!` 的任务仍在活动状态(会空转/报错),最值得处理。
注意:Transmission 的 `downloadDir` 是 **NAS 侧路径**(实测为 `/downloads`),
在客户端命名空间里不存在,所以**不能**用 `os.path.join(downloadDir, f["name"])` 判断存在性——
那样会把所有任务误报为"全部缺失"。必须按**文件名 basename** 与本机目录比对。
要把这些任务从 Transmission 移除时(`torrent-remove`,只删任务记录不删数据),
**必须先列出清单(id / 名称 / 状态 / 缺失文件数)给用户确认**,不要自行决定。
## 磁盘空间:不要用 df 下结论
`/mnt/fnOS/123` 是 CIFS 挂载(`//192.168.123.199/123`),它报告的容量是**缓存的**:
实测写入 256MB 并 `sync` 后 `df` 读数**一位都没变**,间隔 20 秒的两次读数也完全相同。
所以 `df` 既不能证明"空间已释放",也不能证明"没释放"。
释放空间请让用户到 **fnOS 存储空间页面**确认;若那边也没降,考虑快照或回收站占用。
## 背景数据(2026-10-18 首次完整清理)
- 清理前 4540 个文件 → 清理后 **3021 个**(视频 701 / 字幕 1658 / 海报 624 / 通用封面 38),目录 276。
- 累计删除 1519 个文件 ≈ 226.7 GB:1441 个垃圾(2.9GB)+ 39 个重复大视频(223.8GB)
+ 39 个孤儿海报(26.8MB);另删除 751 个空目录。
- 站点常见垃圾:`*.url`(广告)、`twojav.com@*` 等前缀的样片/预告、
`.pad/`(BT BEP47 填充文件,全 0 字节)、`*.trickplay/`(Jellyfin 缩略图)。
- 预告片特征:同一支 19.3MB 的 `三 上 悠 亚 想 要 跟 你 决 胜 负.mp4` 在 80+ 个目录重复。
@@ -0,0 +1,180 @@
#!/usr/bin/env python3
"""
只读盘点:Transmission 里哪些任务的数据文件已经不在本机下载目录上。
用途:`clean_seed_extras.py` 清理后,被删掉的样片/预告会让对应任务"部分缺失",
被去重删掉的那一侧副本会让对应任务"数据全部不在磁盘上"。这个脚本只查询、不修改,
输出清单供人工确认后,再决定是否用 torrent-remove 移除这些任务。
自包含:只用 requests 直连 Transmission RPC,不依赖仓库里其他模块。
用法:
.venv/bin/python .agents/skills/torrent-download-cleanup/scripts/find_missing_torrents.py
.venv/bin/python .../find_missing_torrents.py --root /mnt/fnOS/123 --json
.venv/bin/python .../find_missing_torrents.py --host 192.168.123.199 --port 9095
要点:Transmission 返回的 downloadDir 是 **NAS 侧路径**(实测为 /downloads),
在客户端命名空间里并不存在,所以不能拿它拼路径判断文件是否存在;
必须按文件名的 basename 与本机目录里的文件比对,否则会把所有任务误报为"全部缺失"。
"""
import argparse
import json
import os
import sys
import requests
DEFAULT_HOST = "192.168.123.199"
DEFAULT_PORT = 9095
DEFAULT_RPC_PATH = "/transmission/rpc"
DEFAULT_USER = "admin"
DEFAULT_PASSWORD = "GUOxy.5157"
DEFAULT_ROOT = "/mnt/fnOS/123"
REQUEST_TIMEOUT = (5, 30)
STATUS_TEXT = {
0: "stopped",
1: "check-wait",
2: "checking",
3: "download-wait",
4: "downloading",
5: "seed-wait",
6: "seeding",
}
# 仍在活动的状态:这些任务缺文件会一直空转/报错,最值得处理
ACTIVE_STATUS = {1, 2, 3, 4, 5, 6}
TORRENT_FIELDS = ["id", "name", "status", "error", "errorString", "downloadDir", "files"]
class TransmissionRpc:
"""最小可用的 Transmission RPC 客户端(处理 409 会话握手 + Basic 认证)"""
def __init__(self, host, port, rpc_path, username, password):
self.url = f"http://{host}:{port}{rpc_path}"
self.session = requests.Session()
if username and password:
self.session.auth = (username, password)
self.session_id = None
def call(self, method, arguments=None):
"""发一次 RPC;409 时取 session id 重发一次。返回解析后的 JSON 或 None"""
payload = {"method": method}
if arguments:
payload["arguments"] = arguments
for attempt in range(2):
headers = {}
if self.session_id:
headers["X-Transmission-Session-Id"] = self.session_id
try:
response = self.session.post(self.url, json=payload, headers=headers,
timeout=REQUEST_TIMEOUT)
except Exception as err:
print(f"RPC 请求异常({method}): {err}", file=sys.stderr)
return None
if response.status_code == 409 and attempt == 0:
new_id = response.headers.get("X-Transmission-Session-Id")
if new_id:
self.session_id = new_id
continue
print("Transmission 会话握手失败(409 且无 session id)", file=sys.stderr)
return None
if response.status_code == 401:
print("Transmission 认证失败(401),检查用户名/密码", file=sys.stderr)
return None
if response.status_code != 200:
print(f"Transmission 返回非 200: {response.status_code}", file=sys.stderr)
return None
try:
body = response.json()
except ValueError:
print("Transmission 响应不是合法 JSON", file=sys.stderr)
return None
if body.get("result") != "success":
print(f"Transmission 业务失败: result={body.get('result')!r}", file=sys.stderr)
return None
return body.get("arguments") or {}
return None
def build_parser():
parser = argparse.ArgumentParser(description="只读盘点 Transmission 中缺数据的任务")
parser.add_argument("--root", default=DEFAULT_ROOT, help=f"本机下载目录(默认 {DEFAULT_ROOT})")
parser.add_argument("--host", default=DEFAULT_HOST)
parser.add_argument("--port", type=int, default=DEFAULT_PORT)
parser.add_argument("--rpc-path", default=DEFAULT_RPC_PATH)
parser.add_argument("--user", default=DEFAULT_USER)
parser.add_argument("--password", default=DEFAULT_PASSWORD)
parser.add_argument("--json", action="store_true", help="以 JSON 输出")
return parser
def main(argv=None):
args = build_parser().parse_args(argv)
if not os.path.isdir(args.root):
print(f"下载目录不存在: {args.root}", file=sys.stderr)
return 2
on_disk = {name.casefold() for _, _, files in os.walk(args.root) for name in files}
rpc = TransmissionRpc(args.host, args.port, args.rpc_path, args.user, args.password)
arguments = rpc.call("torrent-get", {"fields": TORRENT_FIELDS})
if arguments is None:
return 1
torrents = arguments.get("torrents", [])
gone, partial = [], []
for torrent in torrents:
files = torrent.get("files") or []
if not files:
continue
present = sum(1 for f in files if os.path.basename(f["name"]).casefold() in on_disk)
if present == 0:
gone.append(torrent)
elif present < len(files):
partial.append((present, len(files), torrent))
if args.json:
print(json.dumps({
"root": args.root,
"total_torrents": len(torrents),
"all_missing": [{"id": t["id"], "name": t["name"],
"status": STATUS_TEXT.get(t["status"], t["status"]),
"error": t["error"], "files": len(t.get("files") or []),
"active": t["status"] in ACTIVE_STATUS} for t in gone],
"partially_missing": [{"id": t["id"], "name": t["name"],
"present": present, "files": total,
"status": STATUS_TEXT.get(t["status"], t["status"]),
"active": t["status"] in ACTIVE_STATUS}
for present, total, t in partial],
}, ensure_ascii=False, indent=2))
return 0
active_gone = sum(1 for t in gone if t["status"] in ACTIVE_STATUS)
print(f"下载目录: {args.root}")
print(f"Transmission 任务总数: {len(torrents)}")
print(f"数据文件已全部不在磁盘上的任务: {len(gone)} 个(其中仍在活动状态: {active_gone} 个)")
for t in gone:
mark = "!" if t["status"] in ACTIVE_STATUS else " "
print(f" {mark} id={t['id']:<5} {STATUS_TEXT.get(t['status'], t['status']):<13} "
f"error={t['error']:<2} 文件数={len(t.get('files') or []):<3} {t['name'][:56]}")
print(f"\n部分文件缺失的任务: {len(partial)} 个")
for present, total, t in sorted(partial, key=lambda r: r[0] / r[1]):
mark = "!" if t["status"] in ACTIVE_STATUS else " "
print(f" {mark} id={t['id']:<5} 缺 {total - present}/{total} "
f"{STATUS_TEXT.get(t['status'], t['status']):<13} error={t['error']:<2} {t['name'][:56]}")
print("\n标记 ! 的任务仍在活动状态(会空转/报错),最值得处理。")
print("要移除请先让用户确认,再执行 torrent-remove(只删任务记录,不删数据)。")
return 0
if __name__ == "__main__":
sys.exit(main())