视频压缩与归档
使用用户自己的本地 AI 环境完成视频压缩。先检查环境，再分析素材，询问目标，推荐参数，提供小样；收到用户对具体小样和批量范围的确认后再批量执行，并指导归档。不要将“自动校验通过”描述为用户已经接受画质。
配套脚本只依赖 Python 3.9+ 标准库、FFmpeg 和 ffprobe。首版主要面向 macOS；执行依赖 POSIX 文件锁。普通聊天工具若无法读写本地文件和执行命令，只能提供指导，不能宣称已经处理视频。脚本不需要模型 API Key，不上传素材。
入口与任务目录
- 找到本 Skill 的绝对路径。下文
<脚本>指scripts/workflow.py的绝对路径；<任务>是用户机器上新建的独立任务目录。不能把结果写回已安装的 Skill 包。 - 在用户原始素材目录之外创建任务目录；每批任务独立保存清单、计划、样品、确认和状态。新增或变更素材另建任务，已启动批次保持原计划。
- 用户明确的指令和已给出的授权优先于本 Skill 的默认建议。不要重复询问已经确定的目标、路径或选择。用户要求超出脚本支持范围时，说明限制并准备单独方案，不悄悄改脚本或降级处理。
1. 环境检查与安装指导
先确认终端能找到 Python，再运行 python3 "<脚本>" doctor。检查 Python 版本、FFmpeg、ffprobe、libx265/libx264 和必要选项。缺失时读取 environment.md，说明缺什么、安装方式及影响。用户已经要求安装则按该范围执行；否则先提供具体命令让用户选择执行方式。不得把缺失工具误报成“无视频”。安装后复查到可用才继续。
2. 只读分析素材
确认源目录和输出目录，运行 init、scan，命令见 operations.md。扫描只读媒体元数据，不启动编码。向用户报告数量、体积、时长、分辨率/帧率、色深、色彩标记、音轨与主要 Profile，并单列无法读取和需要复核的文件。
BT.709 标签不能证明拍摄模式，也不能排除 Log；结合用户提供的拍摄信息判断。首版执行器仅自动处理 BT.709 标签完整的 H.264/HEVC、4:2:0、8/10-bit 素材；HLG/PQ/HDR、字幕、多主视频流和不明色彩单独列为 REVIEW，不自动转成 SDR。已知 Log 素材先单独处理，不给用户保证色彩正确。
3. 询问使用目标
先解释扫描发现，再只问尚不明确且会改变方案的问题：主要用途（家庭观看/长期保存/继续剪辑/分享）、画质与容量的优先级、可接受的处理时间、播放设备或文件大小限制。一般合并成一轮简短问题；不要让用户填写无关参数表。
归档同时说明两种选择：原片保留原位；或成功并复验后移到原父目录的指定子目录。默认 keep，移动需要用户明确选择；不提供删除原片功能。先确定该选择，再生成样品配置。
4. 推荐可比较的方案
按 quality.md 将用户目标与实际素材联系起来。说明编码器、preset、2–3 个候选 CRF、保留的参数、预期取舍和不确定性。不要把 CRF22、某相机或某目录作为所有用户的固定规则。
创建任务内 plan.json，格式见 operations.md。保存用户目标与推荐理由；仅选择本次有明确处理意图的 Profile，每个选中 Profile 至少有一个小样。挑选运动、纹理、暗部等代表片段；元数据无法识别场景时说明，并请用户指定重点片段或协助观看。素材类型很多时分批缩小范围。
默认保持分辨率、帧率、宽高比、方向、色深、已知色彩元数据并复制全部音轨。脚本只复制主视频及音轨，辅助数据轨/封面不会进入压缩副本，要在方案中说明。缩放、调色、HDR 转换、音频重编码、硬件编码、严格目标体积和剪辑中间格式不在首版自动执行范围。
5. 小样与人工观看
运行 sample，展示 sample-report.md、reference 和各候选的本地路径。所有候选从同一参考片段编码。解释容量与耗时，并指导对照观看细节、运动、暗部、渐变、音画同步及实际播放设备；关键帧裁切可能使时长略有偏移。
在用户明确接受某候选前不运行 approve、run 或 start。用户不满意则调整计划、重新小样，再收集结论；不猜测“符合要求”。脚本的 PASS 是结构检查，不是逐帧质量证明。
6. 确认后批量执行
展示 plan --crf N 的范围与输出映射、选中 CRF、归档策略和预计时间/容量的样本依据。用户确认可用并同意这批执行后，用 approve 记录真实用户回复；已经涵盖这些事项的回复无需再问一遍。确认记录可恢复上下文，但不等于脚本能证明回复来自真人。
调用 start 后用 status 和日志确认实际运行。批量单个 FFmpeg 顺序处理；当前文件完成编码、验证、归档后才能安全暂停。使用 pause；不通过杀进程正常暂停。resume 清除暂停请求，控制器退出后再 start；已有控制器运行时不再启动。不要为长任务保持 AI 高频轮询。用户要求以后通知时，才使用其 AI 系统提供的通知/调度能力。
参数、路径、范围或样品变化会使旧确认失效；已启动的任务按原方案恢复，变更另建任务。失败与待复核项目单独报告。断点恢复以文件为单位，未完成视频从头编码。
7. 校验与归档交付
按 archival.md 解释压缩版本、原片和任务记录的对应关系。汇总已完成/跳过/待复核、压缩副本的容量差、原片现址和恢复方式。报告中的压缩率不等于实际释放空间：原片仍保留，当前流程的磁盘占用通常增加。
不覆盖原片或既有输出；未验证的临时文件不作为成品交付。自动核验基于 ffprobe、size/mtime，不是内容哈希或全片解码检测。用户需要更严格验证或备份时再设计相应步骤；移动目录不是备份。保留任务目录，使用户或另一 AI 能恢复和解释结果。