---

name: lov-list-videos description: > 用增量缓存扫描指定目录或全局（主目录与外接卷），秒级列出全部视频文件及大小、 修改时间，可选 ffprobe 补时长、分辨率与编码。Use when 用户说“列出所有视频” “找视频文件”“哪些视频最大”或 “list all video files”。 license: MIT compatibility: "Portable Agent Skills format. Requires Python 3.9+; macOS/Linux filesystem. ffprobe (FFmpeg) only for --probe. Standard library only." metadata: author: contributors version: "0.1.0" card_standard: lovstudio/skill-card/v1 content_class: deterministic-output tags: - video - file-search - incremental-cache - local-first - macos

视频清单 · 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_DIR if 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

1. 运行 CLI。默认扫当前目录，输出按修改时间倒序的表格：

python3 "$SKILL_DIR/scripts/list_videos.py"

2. 指定一个或多个目录，或改为全局：

python3 "$SKILL_DIR/scripts/list_videos.py" ~/Movies ~/Downloads
python3 "$SKILL_DIR/scripts/list_videos.py" --global --sort size --limit 30

3. 常用过滤与输出：

# 最近 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

4. 缓存控制。怀疑缓存过期用 --full 强制重新列目录；不想留痕用 --no-cache； --clear-cache 删除缓存文件。扫描设置（扩展名集合、是否含隐藏目录）改变时 脚本会自动重新列目录，不需要手动清缓存。

5. 默认跳过 node_modules、Library/Caches 等噪音目录、.app/.photoslibrary 等包目录、隐藏目录和外接卷上的 ._ 副本文件。用户明确要扫这些位置时加 --no-default-excludes 或 --hidden；只想多跳过某些目录用 --exclude。

6. 用户说出长期偏好时写回 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, and pricing-card.yaml as the standard trust bundle for this Skill.

Dependencies

• Python 3.9+（仅标准库）
• ffprobe（FFmpeg），仅 --probe 与 --sort duration 需要
• 无外部 Skill 依赖；相邻 Skill 的交接见 references/skill-composition.md