| name | video-cleaner |
| description | 视频目录清理。扫描并清理非视频文件夹（func1）和无用文件（func2）。当用户提到"清理"、"clean"、"删除无用文件"、"整理目录"时触发。 |
视频目录清理 Skill
负责清理视频目录中的无用内容。
功能说明
func1：清理非视频文件夹
扫描指定目录，将不含任何有效视频文件的文件夹移至 .delete 目录。
有效视频定义：
- 扩展名在配置的
video.extensions 列表中
- 文件大小 >= 配置的
video.min_size_mb
func2：清理无用文件
在视频文件夹内，将与视频无关的文件移至 .delete 目录。
保留规则：
- 视频文件：全部保留
- 图片文件：
- 文件名包含配置的
image.valid_keywords（如 poster, cover）→ 保留
- 文件名前 N 个字符与某个视频文件名匹配 → 保留
- 其他 → 删除
- NFO 文件：
- 文件名前 N 个字符与某个视频文件名匹配 → 保留
- 其他 → 删除
- 字幕文件（.srt/.ass/.ssa/.vtt/.sub）：
- 只要前缀名（第一个
. 之前）与某个视频文件的前缀相同 → 保留
- 不因语言后缀（如
.zh、.ja）而删除
- 其他 → 删除
- 其他文件：全部删除
操作模式
支持三种模式，由用户指令决定：
模式 1：仅计划
生成 JSON 计划文件，不执行。
调用方式：
.venv/bin/python .opencode/skills/video-cleaner/scripts/plan_clean_folders.py \
--root "/path/to/videos" \
--extensions ".mp4,.mkv,.avi,.wmv,.mov,.flv,.rmvb,.rm,.3gp,.m4v,.m2ts,.ts,.mpg" \
--min-size 300 \
--delete-dir ".delete" \
--output "plans/"
.venv/bin/python .opencode/skills/video-cleaner/scripts/plan_clean_files.py \
--root "/path/to/videos" \
--video-extensions ".mp4,.mkv,.avi,.wmv,.mov,.flv,.rmvb,.rm,.3gp,.m4v,.m2ts,.ts,.mpg" \
--image-extensions ".jpg,.jpeg,.png,.gif,.bmp,.webp,.tiff" \
--valid-keywords "poster,movie,folder,cover,fanart,banner,clearart,thumb,landscape,logo,clearlogo,disc,discart,backdrop,keyart" \
--nfo-match-length 5 \
--temp-tail-globs "*.115chrome_*,*.115chrome_*.cfg" \
--subtitle-extensions ".srt,.ass,.ssa,.vtt,.sub" \
--delete-dir ".delete" \
--output "plans/"
输出：
- 文件路径：
plans/clean_folders_20260220_150000.json
- 格式：见下方 JSON 规范
模式 2：仅执行
读取已有 JSON 计划文件，执行操作。
调用方式：
.venv/bin/python .opencode/skills/video-cleaner/scripts/execute_plan.py \
--plan "plans/clean_folders_20260220_150000.json"
模式 3：联动执行
先计划，agent 向用户展示摘要，用户确认后执行。JSON 保留作为事后核查记录。
参数来源
Agent 从 config.toml 读取配置，理解后作为命令行参数传入：
| 参数 | 配置来源 |
|---|
--extensions / --video-extensions | [video] extensions |
--min-size | [video] min_size_mb |
--image-extensions | [image] extensions |
--valid-keywords | [image] valid_keywords |
--nfo-match-length | [nfo] match_length |
--subtitle-extensions | [subtitle] extensions |
--temp-tail-globs | [cleanup] temp_tail_globs |
--delete-dir | [cleanup] delete_dir_name |
--root 参数：
- 优先从
memory/paths.md 中读取 last_clean_path
- 若无记忆，询问用户
计划 JSON 格式
[
{
"func": "clean_folders",
"action": "MOVE",
"source": "/path/to/videos/non-video-folder",
"destination": "/path/to/videos/.delete/non-video-folder",
"size_mb": 12.5,
"created_at": "2026-02-20T15:00:00"
},
{
"func": "clean_files",
"action": "MOVE",
"source": "/path/to/videos/some-movie/useless.txt",
"destination": "/path/to/videos/.delete/some-movie/useless.txt",
"size_mb": 0.01,
"created_at": "2026-02-20T15:00:05"
}
]
日志
脚本运行日志输出到 logs/ 目录。
文件命名：{func}_{timestamp}.log
脚本职责
plan_clean_folders.py
- 遍历目录树
- 判断文件夹是否包含有效视频
- 生成 MOVE 操作列表
- 写入 JSON 文件
plan_clean_files.py
- 遍历视频文件夹
- 判断每个文件是否有用
- 生成 MOVE 操作列表
- 写入 JSON 文件
execute_plan.py
- 读取 JSON 文件
- 逐条执行 MOVE 操作
- 记录成功/失败日志
execute_plan.py（执行前强制步骤）
在调用执行脚本前，先清理 plans/ 中超过 10 天的旧计划文件：
- 只处理
plans/ 下普通文件（不递归目录）
- 按文件修改时间判断，
mtime > 10 天 才删除
- 禁止使用
rm，统一使用 Python（pathlib / os）删除
- 清理后输出摘要：
删除数量 + 剩余数量，再继续执行 execute_plan.py
注意事项
- 脚本自包含所有所需逻辑，不依赖外部 helper 模块。
- 文件遍历、视频判断、图片/NFO 判断、文件大小计算等全部在脚本内实现。
- 使用 Python 标准库 +
pathlib。
- 生成的计划路径，不能放在skill的目录中，要放在agent运行的目录中，保持skill目录清洁
