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
+320
View File
@@ -0,0 +1,320 @@
"""clean_seed_extras 清理脚本离线单元测试
全部使用 tmp_path 临时目录,不触碰真实下载目录(/mnt/fnOS/123)。
运行: uv run python -m pytest tests/test_clean_seed_extras.py -v
"""
import os
import pytest
import clean_seed_extras as c
MB = 1024 * 1024
def make_file(path, size, header=b""):
"""创建指定体积的文件(稀疏文件,速度快),可选写入文件头"""
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "wb") as fp:
if header:
fp.write(header)
os.truncate(path, size)
return path
def run(root, *extra):
"""以预演/删除模式运行脚本主函数"""
return c.main(["--root", str(root), "--quiet", *extra])
# ---------------------------------------------------------------- 文件头嗅探
def test_looks_like_video_常见容器(tmp_path):
cases = {
"a.mp4": b"\x00\x00\x00\x20ftypisom",
"b.mkv": b"\x1a\x45\xdf\xa3\x01\x00\x00\x00",
"c.avi": b"RIFF\x00\x00\x00\x00AVI LIST",
"d.flv": b"FLV\x01\x05\x00\x00\x00",
"e.wmv": b"\x30\x26\xb2\x75\x8e\x66\xcf\x11",
"f.mpg": b"\x00\x00\x01\xba\x44\x00",
"g.rmvb": b".RMF\x00\x00\x00\x12",
}
for name, header in cases.items():
path = make_file(str(tmp_path / name), 200 * MB, header)
assert c.looks_like_video(path) is True, name
def test_looks_like_video_ts_需要两次同步字节(tmp_path):
ts = make_file(str(tmp_path / "ok.ts"), 200 * MB, b"\x47" + b"\x00" * 187 + b"\x47")
assert c.looks_like_video(ts) is True
fake = make_file(str(tmp_path / "fake.ts"), 200 * MB, b"\x47" + b"\x00" * 511)
assert c.looks_like_video(fake) is False
def test_looks_like_video_非视频(tmp_path):
junk = make_file(str(tmp_path / "junk.bin"), 200 * MB, os.urandom(64))
assert c.looks_like_video(junk) is False
assert c.looks_like_video(str(tmp_path / "not-exist")) is False
# ------------------------------------------------------------------ 保留规则
def test_大视频保留_小视频删除(tmp_path):
big = make_file(str(tmp_path / "x/big.mp4"), 120 * MB)
small = make_file(str(tmp_path / "x/sample.mp4"), 20 * MB)
run(tmp_path, "--apply")
assert os.path.exists(big) is True
assert os.path.exists(small) is False
def test_无扩展名大视频按文件头保留(tmp_path):
video = make_file(str(tmp_path / "noext_video"), 150 * MB, b"\x00\x00\x00\x20ftypisom")
junk = make_file(str(tmp_path / "noext_junk"), 150 * MB, os.urandom(64))
run(tmp_path, "--apply")
assert os.path.exists(video) is True
assert os.path.exists(junk) is False
def test_字幕保留_含old备份(tmp_path):
make_file(str(tmp_path / "x/movie.mp4"), 120 * MB)
subs = [
make_file(str(tmp_path / "x/movie.srt"), 1024),
make_file(str(tmp_path / "x/movie.CN.srt"), 1024),
make_file(str(tmp_path / "x/movie.CN_dual_eye.ass"), 1024),
make_file(str(tmp_path / "x/movie.CN.srt.old-20260918"), 1024),
]
run(tmp_path, "--apply")
assert all(os.path.exists(p) for p in subs)
def test_海报仅保留与视频同名的(tmp_path):
make_file(str(tmp_path / "x/ATID-643 淫魔病棟.mp4"), 120 * MB)
keep = make_file(str(tmp_path / "x/ATID-643 淫魔病棟-poster.jpg"), 4096)
drop_folder = make_file(str(tmp_path / "x/folder.jpg"), 4096)
drop_other = make_file(str(tmp_path / "x/OTHER-999-poster.jpg"), 4096)
run(tmp_path, "--apply", "--no-covers") # --no-covers = 严格模式,只留同名海报
assert os.path.exists(keep) is True
assert os.path.exists(drop_folder) is False
assert os.path.exists(drop_other) is False
def test_通用封面图默认保留(tmp_path):
"""folder.jpg / poster.jpg 等媒体库封面默认保留(同目录有大视频时)"""
make_file(str(tmp_path / "x/movie.mp4"), 120 * MB)
covers = [
make_file(str(tmp_path / "x/folder.jpg"), 4096),
make_file(str(tmp_path / "x/poster.jpg"), 4096),
make_file(str(tmp_path / "x/backdrop.jpg"), 4096),
make_file(str(tmp_path / "x/fanart.png"), 4096),
]
run(tmp_path, "--apply")
assert all(os.path.exists(p) for p in covers)
def test_无视频目录的通用封面不保留(tmp_path):
"""只有 folder.jpg 没有视频的目录属于无主垃圾,封面和目录都应删掉"""
make_file(str(tmp_path / "shell/folder.jpg"), 4096)
run(tmp_path, "--apply")
assert os.path.exists(str(tmp_path / "shell/folder.jpg")) is False
assert os.path.exists(str(tmp_path / "shell")) is False
def test_跨目录不误匹配海报(tmp_path):
"""海报只与同目录的视频匹配,避免 A 目录海报被 B 目录视频保住"""
make_file(str(tmp_path / "a/movie.mp4"), 120 * MB)
other = make_file(str(tmp_path / "b/movie-poster.jpg"), 4096)
run(tmp_path, "--apply")
assert os.path.exists(other) is False
def test_关闭字幕与海报保留(tmp_path):
make_file(str(tmp_path / "x/movie.mp4"), 120 * MB)
sub = make_file(str(tmp_path / "x/movie.srt"), 1024)
poster = make_file(str(tmp_path / "x/movie-poster.jpg"), 4096)
cover = make_file(str(tmp_path / "x/folder.jpg"), 4096)
run(tmp_path, "--apply", "--no-subtitles", "--no-posters")
assert os.path.exists(sub) is False
assert os.path.exists(poster) is False
assert os.path.exists(cover) is False
def test_阈值可调(tmp_path):
small = make_file(str(tmp_path / "x/sample.mp4"), 20 * MB)
run(tmp_path, "--apply", "--min-size-mb", "10")
assert os.path.exists(small) is True
# ------------------------------------------------------------------ 重复视频去重
HEADER = b"\x00\x00\x00\x20ftypisom"
def test_重复大视频只保留一份(tmp_path):
a = make_file(str(tmp_path / "x/hkbisi.com@abc001_1_8k.mp4"), 120 * MB, HEADER)
b = make_file(str(tmp_path / "x/masex.tv@abc001_1_8k.mp4"), 120 * MB, HEADER)
run(tmp_path, "--apply")
assert sum(os.path.exists(p) for p in (a, b)) == 1
def test_体积相同内容不同不去重(tmp_path):
a = make_file(str(tmp_path / "x/a.com@abc001_1.mp4"), 120 * MB, HEADER)
b = make_file(str(tmp_path / "x/b.com@abc001_1.mp4"), 120 * MB, b"\x00\x00\x00\x20ftypmp42")
run(tmp_path, "--apply")
assert os.path.exists(a) is True
assert os.path.exists(b) is True
def test_去重时保留无站点前缀的一份(tmp_path):
plain = make_file(str(tmp_path / "x/abc001_1_8k.mp4"), 120 * MB, HEADER)
prefixed = make_file(str(tmp_path / "x/masex.tv@abc001_1_8k.mp4"), 120 * MB, HEADER)
run(tmp_path, "--apply")
assert os.path.exists(plain) is True
assert os.path.exists(prefixed) is False
def test_prefer_source_优先保留指定站点(tmp_path):
make_file(str(tmp_path / "x/masex.tv@abc001_1_8k.mp4"), 120 * MB, HEADER)
other = make_file(str(tmp_path / "x/hkbisi.com@abc001_1_8k.mp4"), 120 * MB, HEADER)
run(tmp_path, "--apply", "--prefer-source", "hkbisi.com")
assert os.path.exists(other) is True
assert os.path.exists(str(tmp_path / "x/masex.tv@abc001_1_8k.mp4")) is False
def test_不同目录内容相同不去重(tmp_path):
a = make_file(str(tmp_path / "x/abc001_1_8k.mp4"), 120 * MB, HEADER)
b = make_file(str(tmp_path / "y/abc001_1_8k.mp4"), 120 * MB, HEADER)
run(tmp_path, "--apply")
assert os.path.exists(a) is True
assert os.path.exists(b) is True
def test_no_dedupe_关闭去重(tmp_path):
a = make_file(str(tmp_path / "x/a.com@abc001_1.mp4"), 120 * MB, HEADER)
b = make_file(str(tmp_path / "x/b.com@abc001_1.mp4"), 120 * MB, HEADER)
run(tmp_path, "--apply", "--no-dedupe")
assert os.path.exists(a) is True
assert os.path.exists(b) is True
def test_去重后副本的同名海报一并删除(tmp_path):
"""去重必须在海报匹配之前:副本的海报不能留到下一轮才清(要求一次收敛)"""
make_file(str(tmp_path / "x/a.com@abc001_1.mp4"), 120 * MB, HEADER)
make_file(str(tmp_path / "x/b.com@abc001_1.mp4"), 120 * MB, HEADER)
keep_poster = make_file(str(tmp_path / "x/a.com@abc001_1-poster.jpg"), 4096)
dup_poster = make_file(str(tmp_path / "x/b.com@abc001_1-poster.jpg"), 4096)
run(tmp_path, "--apply")
assert os.path.exists(keep_poster) is True
assert os.path.exists(dup_poster) is False
# 再跑一次应当无事可做(一次收敛)
entries, _ = c.collect(str(tmp_path))
c.decide(entries, 100 * MB, True, True)
assert [e.path for e in entries if not e.keep] == []
def test_去重会记录保留的那一份(tmp_path):
a = make_file(str(tmp_path / "x/a.com@abc001_1.mp4"), 120 * MB, HEADER)
make_file(str(tmp_path / "x/b.com@abc001_1.mp4"), 120 * MB, HEADER)
entries, _ = c.collect(str(tmp_path))
c.decide(entries, 100 * MB, True, True)
dups = [e for e in entries if e.dup_of]
assert len(dups) == 1
assert dups[0].reason == "重复视频"
assert os.path.exists(dups[0].dup_of) is True
assert dups[0].dup_of in (a, str(tmp_path / "x/b.com@abc001_1.mp4"))
def test_重复视频单独成段写入清单(tmp_path):
make_file(str(tmp_path / "x/a.com@abc001_1.mp4"), 120 * MB, HEADER)
make_file(str(tmp_path / "x/b.com@abc001_1.mp4"), 120 * MB, HEADER)
manifest = tmp_path / "m.txt"
c.main(["--root", str(tmp_path), "--quiet", "--manifest", str(manifest)])
text = manifest.read_text(encoding="utf-8")
assert "E. 重复大视频" in text
assert "--- 保留:" in text
assert "F. 待删除的空目录" in text
# ------------------------------------------------------------------ 删除行为
def test_预演模式不删除任何文件(tmp_path):
make_file(str(tmp_path / "x/movie.mp4"), 120 * MB)
junk = make_file(str(tmp_path / "x/a.url"), 16)
assert run(tmp_path) == 0
assert os.path.exists(junk) is True
assert os.path.exists(str(tmp_path / "x/movie.mp4")) is True
def test_清理空目录_但保留root(tmp_path):
make_file(str(tmp_path / "x/movie.mp4"), 120 * MB)
make_file(str(tmp_path / "x/movie.trickplay/320 - 10x10/0.jpg"), 1024)
empty = tmp_path / "empty-dir"
empty.mkdir()
run(tmp_path, "--apply")
assert os.path.isdir(str(tmp_path)) is True
assert os.path.exists(str(tmp_path / "x/movie.trickplay")) is False
assert os.path.exists(str(empty)) is False
def test_父目录级联删除到影片级目录(tmp_path):
"""多层子目录被清空后,父目录应逐级向上删除,直到影片级目录"""
make_file(str(tmp_path / "vrkm-1763/a-poster.jpg"), 4096)
make_file(str(tmp_path / "vrkm-1763/sub/b.url"), 16)
make_file(str(tmp_path / "vrkm-1763/sub/deep/deeper/c.jpg"), 1024)
make_file(str(tmp_path / "keepme/x/movie.mp4"), 120 * MB)
run(tmp_path, "--apply")
# 整条空目录链连同影片级目录一起消失
assert os.path.exists(str(tmp_path / "vrkm-1763")) is False
assert os.path.exists(str(tmp_path / "vrkm-1763/sub/deep/deeper")) is False
# 有视频的目录不受影响,root 本身保留
assert os.path.exists(str(tmp_path / "keepme/x/movie.mp4")) is True
assert os.path.isdir(str(tmp_path)) is True
def test_全部删除后root仍保留(tmp_path):
make_file(str(tmp_path / "only/a.url"), 16)
make_file(str(tmp_path / "only/b.jpg"), 1024)
run(tmp_path, "--apply")
assert os.path.isdir(str(tmp_path)) is True
assert os.listdir(str(tmp_path)) == []
def test_keep_empty_dirs(tmp_path):
make_file(str(tmp_path / "x/movie.mp4"), 120 * MB)
make_file(str(tmp_path / "x/movie.trickplay/0.jpg"), 1024)
run(tmp_path, "--apply", "--keep-empty-dirs")
assert os.path.isdir(str(tmp_path / "x/movie.trickplay")) is True
def test_不跟随符号链接目录(tmp_path):
"""符号链接目录内的文件不应被扫描/删除"""
outside = tmp_path / "outside"
victim = make_file(str(outside / "keep-me.jpg"), 1024)
target = tmp_path / "root" / "link"
target.parent.mkdir(parents=True, exist_ok=True)
os.symlink(str(outside), str(target))
run(target.parent, "--apply")
assert os.path.exists(victim) is True
def test_目录不存在返回2(tmp_path):
assert run(tmp_path / "not-exist") == 2
# ------------------------------------------------------------------ 汇总统计
def test_汇总统计(tmp_path):
make_file(str(tmp_path / "x/movie.mp4"), 120 * MB)
make_file(str(tmp_path / "x/movie.srt"), 1024)
make_file(str(tmp_path / "x/junk.url"), 16)
entries, dirs = c.collect(str(tmp_path))
c.decide(entries, 100 * MB, True, True, keep_covers=False)
assert len(entries) == 3
assert sum(1 for e in entries if e.keep) == 2
assert sum(1 for e in entries if not e.keep) == 1
assert [e.reason for e in entries if e.name == "movie.srt"] == ["字幕"]
def test_human_size():
assert c.human_size(0) == "0.0 B"
assert c.human_size(1024) == "1.0 KB"
assert c.human_size(100 * MB) == "100.0 MB"