视频清单 · Video Inventory
把一个目录或整台电脑里的视频文件列成一份可排序、可过滤的清单。核心是一个共享的
增量目录缓存:第一次扫描完整遍历,之后每次只对目录做 stat,未变化的目录直接复
用缓存,所以重复运行的成本接近“目录数 × 一次 stat”,与文件总数无关。
Triggers
Activate when
- “列出这个文件夹里所有的视频文件。”
- “全盘找一下我电脑上有哪些视频,按大小排。”
- “最近一周新增了哪些 mp4 / mov?”
- “哪些视频是 HEVC 编码,哪些是 H.264?”
- “List all video files under this project.”
- “Find every video on my Mac and show the biggest ones.”
Do not activate when
- 找的是“上次 AI 对话里生成的那个文件”,需要会话证据 →
lov-search-file - 要从一个视频里抽帧、挑瞬间或做照片 →
lov-video-moments - 要转码、剪辑、加字幕或压缩视频 →
lov-media-creator/lov-media-preprocessor - 要把相机卡素材完整迁移到 SSD 并校验 →
lov-migrate-camera-media - 只是问某个视频格式或编码的知识,不需要扫描磁盘 → 直接回答
User Profile (cross-session)
Every generated Skill is connected to the shared user-profile/v1 contract in
skill.yaml. Read the shared user, brand, workspace, preferences, and this
Skill's skills.<skill_id> namespace at the start of every run. Keep the source
portable: resolved personal values belong in the shared profile, never here.
When the user directly states a durable preference or brand fact, persist it
through scripts/profile_store.py and report the saved profile path. Put
Skill-specific values under records.<field>; use brand.<field> or
user.<field> for shared values. Do not persist inferred secrets or credentials.
See references/user-profile.md for the complete contract.
本 Skill 读取的长期记录(都可选):
| 记录 | 含义 |
|---|---|
records.default_scope |
不带参数时的默认范围:current(默认)或 global |
records.global_roots |
--global 使用的根目录列表;缺省为主目录加 /Volumes 下的外接卷 |
records.extra_excludes |
追加跳过的目录名或路径后缀 |
records.extra_extensions |
追加识别的视频扩展名 |
records.default_format |
默认输出:table、json、paths、csv |
records.default_sort |
默认排序:mtime、size、path、name、duration |
缓存文件与 Profile 同住:<profile 目录>/lov-list-videos/cache.json,默认即
~/.lovstudio/skills/lov-list-videos/cache.json。LOV_LIST_VIDEOS_CACHE 或
--cache 可以覆盖。缓存是可再生的派生数据,删掉只会让下一次变成全量扫描。
Skill Group Composition
Read references/skill-composition.md before deciding whether to invoke or
extend any adjacent capability. The record distinguishes optional upstream and
downstream handoffs from embedded Kit modules. Do not silently depend on a
sibling Skill that is not shipped with this source.
Workflow (MANDATORY)
You MUST follow these steps in order.
Step 0: Resolve skill root, dependencies, and runtime context
- Use
SKILL_DIRif the environment provides it. - Otherwise infer the installed skill directory from the current skill context.
- 必须确认
scripts/list_videos.py、scripts/profile_store.py、references/cache-design.md、references/skill-composition.md均存在。 - If a required resource is missing, name its expected relative path and stop before producing a partial result.
When running scripts manually:
export SKILL_DIR="/path/to/lov-list-videos"
Resolve context.profile on every invocation. The precedence is current request,
project context, Skill-specific profile records, shared preferences, shared
brand/user profile, then safe defaults. A direct user statement about a durable
preference or brand fact should be saved with scripts/profile_store.py record
using --confirm, followed by a concise saved-path report.
Step 1: Understand the requested outcome
- 定范围。用户点名了目录就扫那个目录;说“全盘”“整台电脑”“所有地方”用
--global;什么都没说时扫当前工作目录,并在结果里写明扫的是哪里。 - 定输出。用户要“看一眼”给表格;要交给下游脚本或再筛选给
--format json; 只要路径列表给--format paths。 - 定过滤。把“最大的”“最近的”“超过 1G 的”“mp4 的”直接映射到
--sort、--since、--min-size、--ext,不要先全量输出再人工筛。 - 只有用户问到时长、分辨率或编码时才加
--probe;它会调用 ffprobe,结果也会缓存。
Step 1.5: Analyze nearby Skills before implementation
- 先读
references/skill-composition.md。本 Skill 只负责“有哪些视频、在哪、 多大、多新”,下游的抽帧、剪辑、迁移各有归属,不要在这里顺手做。 - 用户要的是某次 AI 对话的产物而不是磁盘盘点时,交给
lov-search-file。
Step 2: Execute the workflow
- 运行 CLI。默认扫当前目录,输出按修改时间倒序的表格:
python3 "$SKILL_DIR/scripts/list_videos.py"
- 指定一个或多个目录,或改为全局:
python3 "$SKILL_DIR/scripts/list_videos.py" ~/Movies ~/Downloads
python3 "$SKILL_DIR/scripts/list_videos.py" --global --sort size --limit 30
- 常用过滤与输出:
# 最近 7 天、大于 200M、只看 mp4/mov,输出 JSON 给后续处理
python3 "$SKILL_DIR/scripts/list_videos.py" --global \
--since 7d --min-size 200M --ext mp4 mov --format json
# 补时长/分辨率/编码,按时长排序(自动启用 --probe)
python3 "$SKILL_DIR/scripts/list_videos.py" ~/Movies --sort duration
缓存控制。怀疑缓存过期用
--full强制重新列目录;不想留痕用--no-cache;--clear-cache删除缓存文件。扫描设置(扩展名集合、是否含隐藏目录)改变时 脚本会自动重新列目录,不需要手动清缓存。默认跳过
node_modules、Library/Caches等噪音目录、.app/.photoslibrary等包目录、隐藏目录和外接卷上的._副本文件。用户明确要扫这些位置时加--no-default-excludes或--hidden;只想多跳过某些目录用--exclude。用户说出长期偏好时写回 Profile,例如“以后默认全盘扫”:
python3 "$SKILL_DIR/scripts/profile_store.py" record \
--skill-id lov-list-videos \
--path records.default_scope \
--value '"global"' \
--confirm
Step 3: Validate the deliverable
- 回读 stderr 摘要:视频数、总大小、目录数、
scanned/reused比例、错误数与 缓存路径。第二次运行reused应接近目录总数;不是就说明有大量目录变化或 设置改变,向用户说明。 - 报告时先给结论(多少个、多大、最值得看的几个),再给范围和过滤条件;不把
整份长清单贴进对话,超过二十条时写文件或给
--format json路径。 errors不为零时说明是权限拒绝或读取失败,并指出受影响的根目录;macOS 上~/Library部分子目录需要“完全磁盘访问”权限,这属于用户系统设置,不要绕过。- Validate
skill-card.yaml,cases/cases.json, andpricing-card.yamlas the standard trust bundle for this Skill.
Dependencies
- Python 3.9+(仅标准库)
- ffprobe(FFmpeg),仅
--probe与--sort duration需要 - 无外部 Skill 依赖;相邻 Skill 的交接见
references/skill-composition.md
