cli-anything-quietshrink为 AI Agent 打造的原生屏幕录制压缩 CLI【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything本篇技术指南以cli-anything-quietshrink为核心介绍如何在 macOS Apple Silicon 上通过硬件 HEVC 编码器对屏幕录制视频进行近乎无损的压缩典型体积缩减 70%–90%并重点剖析其面向 AI Agent 设计的四大子命令、结构化 JSON 输出、质量预设体系与可测试的命令接线方式。读完本文你将掌握这套 Agent 原生 harness 的安装、使用、参数语义、JSON 数据契约与底层实现原理可直接将其接入 Claude Code、Cursor 等 Agent 工作流。一、背景与定位什么是 cli-anything-quietshrinkquietshrink是一款面向 macOS 屏幕录制场景的视频压缩工具其核心卖点是零 CPU 压力借助 Apple SiliconM1/M2/M3/M4内置的 Media Engine 硬件 HEVC 编码器hevc_videotoolbox编码过程几乎不占用 CPU电脑在压缩期间保持安静与流畅同时实现 70%–90% 的体积缩减且画质视觉无损。cli-anything-quietshrink则是 CLI-Anything 生态中为该工具封装的Agent-native harness——一个基于 Python Click 的薄封装层将独立的quietshrinkbash CLI 包装为带有结构化 JSON 输出、稳定退出码、面向 Agent 的命令接口。其完整说明见 QUIETSHRINK.md模块内的快速参考见 README.md。之所以说它“Agent-native”是因为屏幕录制压缩是 Agent 的高频任务compress this screencast before sharing、make this file smaller、convert recording.mov for email。Agent 需要的是确定性、可预测的行为而这套 harness 从设计上保证了三点硬件编码→ 压缩过程不超预算电脑保持可响应智能帧去重→ 利用屏幕内容的高度静态特性丢弃重复帧长 GOP 自适应量化→ 以硬件速度达到接近软件编码器的体积SSIM 验证过的质量预设→ Agent 可以根据用户目标分享 vs 归档直接选择合适的预设。二、安装与环境依赖2.1 安装 harness方式一git 子目录安装通过 pip 以 subdirectory 方式从仓库安装quietshrink/agent-harness子目录。方式二本地安装进入仓库内的 quietshrink/agent-harness 目录后执行pip install -e .从 setup.py 可以看到该包名为cli-anything-quietshrink版本 1.0.0运行时仅依赖click8.0.0Python 要求3.10开发依赖pytest7.0.0并通过console_scripts注册了cli-anything-quietshrink命令入口entry_points{ console_scripts: [ cli-anything-quietshrinkcli_anything.quietshrink.quietshrink_cli:cli, ], },2.2 安装上游 bash CLIharness 是围绕独立quietshrinkbash CLI 的薄封装因此要求quietshrink命令存在于$PATH中。安装方式为运行上游 quietshrink 项目提供的install.sh安装脚本。quietshrink_cli.py 中的find_bash_cli()通过shutil.which(quietshrink)定位该二进制若找不到会抛出ClickException并给出安装提示exit 非零这正是 Agent 可捕获的确定性错误信号def find_bash_cli() - Path: in_path shutil.which(quietshrink) if in_path: return Path(in_path) raise click.ClickException( quietshrink bash CLI not found on $PATH. Install it with:\n curl -fsSL .../install.sh | bash\n )2.3 硬件与 ffmpeg 要求根据 TEST.md 的说明compress压缩功能要求macOS Apple SiliconM1/M2/M3/M4使用硬件 HEVC 编码器ffmpeg 6 且启用hevc_videotoolbox通过brew install ffmpeg安装。Intel Mac 与 Linux 并非不支持只是缺少硬件加速时会回退到libx265软件编码doctor会对此给出平台检查结果输出仍然正确但失去“安静压缩”的核心体验。probe、presets、doctor等命令则无硬件要求。三、快速参考四个子命令一览从 README.md 的 Quick reference 与 SKILL.md 的命令清单出发完整命令形态如下# 压缩视频默认 transparent 质量 cli-anything-quietshrink compress input [output] # 指定质量预设压缩 cli-anything-quietshrink compress -q tiny input # 最小体积 cli-anything-quietshrink compress -q transparent input # 默认视觉无损 cli-anything-quietshrink compress -q pristine input # 接近源质量 # 压缩前检查文件编解码器 / 分辨率 / 时长 / 大小 cli-anything-quietshrink probe input # 列出可用质量预设及经验数据 cli-anything-quietshrink presets # 校验环境是否就绪ffmpeg、hevc_videotoolbox、bash CLI、平台 cli-anything-quietshrink doctor所有命令均接受--json选项输出机器可读的 JSON并以正确的退出码结束。这是 Agent 工作流的基础契约——test_cli.py 中的TestVersionAndHelp验证了--version、--help与无参数时展示帮助的行为四个子命令均被断言存在于帮助输出中。四、质量预设体系Presets质量预设是这套工具最核心的设计。四个预设由两个维度定义q量化值数字越小压缩越激进与经验测得的SSIM结构相似度越接近 1 越无损预设q典型缩减SSIM适用场景tiny50~90%~0.95聊天 / 邮件发送允许轻微瑕疵balanced55~88%~0.99文档 / 分享高质量transparent默认60~87%~0.99重要内容视觉无损pristine70~84%~0.997归档 / 剪辑接近源质量在源码中quietshrink_cli.py 的presets命令将这四组数据定义为结构化字典并原样输出而compress命令则通过 Click 的click.Choice严格限定--quality可选值tiny/balanced/transparent/pristine默认值为transparent——非法预设会被 Click 参数校验直接拒绝这也呼应了上游 bash CLI 测试中invalid quality preset correctly errors的行为click.option( --quality, -q, typeclick.Choice([tiny, balanced, transparent, pristine]), defaulttransparent, helpQuality preset, )4.1 进阶压缩参数除-q外compress还暴露两个可调参数默认值来自 quietshrink_cli.py--gop / -gGOP 大小默认600。长 GOP 是屏幕录制压缩的关键——屏幕内容静态帧多更大的 GOP 让编码器更充分地利用帧间冗余--audio / -a音频码率默认96k。屏幕录制的音频旁白、系统音对码率不敏感96k 已是质量与体积的良好平衡。因此完整的压缩命令可以写成cli-anything-quietshrink compress rec.mov rec_compressed.mov \ -q balanced -g 600 -a 96k --json4.2 预设选择决策流面向 AgentSKILL.md 给出了一条明确的决策流Agent 可按此为用户自动选择用户想分享录制视频 ├─ 在 Apple Silicon Mac 上 → 使用 quietshrink │ ├─ 聊天/邮件/快速分享 → -q tiny │ ├─ 文档/重要分享 → -q transparent默认 │ └─ 归档/剪辑 → -q pristine └─ 不在 Mac 上 → 回退软件编码效率较低处理前先运行doctor验证环境对陌生文件先运行probe了解分辨率 / 编码 / 时长。五、compress压缩命令的完整链路5.1 参数与调用链compress的完整签名见 quietshrink_cli.pycli-anything-quietshrink compress input_path [output_path] \ [--quality/-q PRESET] [--gop/-g N] [--audio/-a BITRATE] [--replace] [--json]input_path必填click.Path(existsTrue, dir_okayFalse)校验文件必须存在[output_path]可选不指定时由 bash CLI 决定输出位置--replace以压缩版本替换原文件flag 型开关。底层调用链非常清晰find_bash_cli()定位二进制 → 构造[quietshrink, --quality, ..., --gop, ..., --audio, ..., --json, (--replace), input, (output)]参数列表 →subprocess.run(..., checkTrue)调用 bash CLI 并捕获 stdout →json.loads解析结果后原样透传。测试 test_cli.py 的test_compress_passes_quality_flag通过 mocksubprocess.run断言了--quality tiny参数确实被透传给了 bash CLI。5.2 输出契约JSON Schemacompress --json返回的字段契约来自 SKILL.md 的 JSON output schema 示例{ input: /path/to/input.mov, output: /path/to/output.mov, input_size: 105952129, output_size: 12345678, saved_bytes: 93606451, saved_percent: 88.3, duration_seconds: 193.3, elapsed_seconds: 87, encoding_speed: 2.2x, quality_preset: transparent, q_value: 60, gop: 600 }字段说明字段含义input/output输入 / 输出文件路径input_size/output_size压缩前后字节数saved_bytes/saved_percent节省的字节数与百分比duration_seconds视频时长秒elapsed_seconds/encoding_speed编码耗时与实际速度倍率quality_preset/q_value/gop实际使用的预设、量化值、GOP 大小5.3 错误处理compress的失败路径同样是结构化的bash CLI 非零退出 → 输出{error: compression_failed, stderr: stderr}并以退出码1结束bash CLI 输出不是合法 JSON → 输出{error: invalid_output, raw: ..., detail: ...}并以退出码 1 结束。对应测试test_compress_handles_bash_failuremock 了CalledProcessError断言error compression_failed且 stderr 内容被携带。这保证了 Agent 总能拿到可解析的错误而不是裸的异常栈。六、probe压缩前体检probe用于在压缩前检查文件返回编解码器、分辨率、帧率、时长与体积见 quietshrink_cli.py。其内部调用ffprobeffprobe -v error \ -show_entries streamcodec_name,width,height,r_frame_rate \ -show_entries formatduration,bit_rate,size \ -of json input随后代码会从 streams 中剔除aac/mp3音频流取首个视频流信息并叠加文件真实大小与时长输出如下 JSON{ path: /path/to/rec.mov, size_bytes: 105952129, size_mb: 101.04, codec: h264, width: 1920, height: 1080, framerate: 60/1, duration_seconds: 12.5 }值得注意的实现细节若系统中没有ffprobe命令会输出{error: ffprobe not found, hint: brew install ffmpeg}并以退出码2结束——这是唯一使用退出码 2 的命令。测试 test_cli.py 的TestProbe覆盖了 ffprobe 缺失、元数据提取mock ffprobe 输出后断言 codec/width/height/duration/size 字段与文件不存在三种场景。七、doctor环境自检doctor是 Agent 在任何压缩任务前的“安全检查门”。它逐项验证quietshrink_cli.pyffmpeg 已安装shutil.which(ffmpeg)hevc_videotoolbox可用运行ffmpeg -hide_banner -encoders并检查输出是否包含hevc_videotoolboxbash CLI 存在调用find_bash_cli()捕获ClickException判定缺失平台为 Apple Silicon Macplatform.system() Darwin and platform.machine() arm64。输出格式--json{ checks: [ {check: ffmpeg installed, ok: true, path: /usr/local/bin/ffmpeg}, {check: hevc_videotoolbox available, ok: true}, {check: quietshrink bash CLI, ok: true}, {check: Apple Silicon Mac, ok: true} ], ready: true }文本模式则输出✓ / ✗标记并汇总Ready或Setup incomplete。退出码语义全部通过为 0任一检查失败为 1——Agent 可以直接用退出码做分支判断。对应测试TestDoctor断言了 JSON 结构中checks数组与ready布尔字段并验证了 ffmpeg 缺失时ready false。八、Agent 决策流与最佳实践结合 SKILL.md一个完整的 Agent 压缩工作流建议如下先doctor --json确认ready: true再继续否则先引导用户修复环境再probe --json了解编码、分辨率、时长——若输入是 h264 且分辨率极高的 120fps 录屏压缩收益会非常明显按目标选预设聊天分享用-q tiny重要分享用默认transparent归档剪辑用-q pristinecompress --json解析saved_percent与output路径反馈给用户失败恢复compression_failed时检查输入文件是否损坏或尝试更保守的预设。适用范围提醒该工具针对屏幕内容优化存在大量重复帧可供去重。SKILL.md 明确建议不要用于相机拍摄、vlog 等非屏幕内容——因为没有重复帧可丢弃压缩收益会大幅缩水。九、错误处理速查错误/异常出现条件处理建议ffmpeg not found环境缺 ffmpegbrew install ffmpeghevc_videotoolbox not availableffmpeg 未编译硬件编码器brew reinstall ffmpegcompression_failedbash CLI 压缩失败检查输入文件是否损坏用--verbose模式查看 ffmpeg 详细报错invalid_outputbash CLI 输出非 JSON属于异常情况可携带raw字段诊断probe_failedffprobe 执行失败确认文件未损坏所有错误均通过结构化 JSON 输出且退出码非零Agent 无需解析人类可读文本即可完成异常处理。十、测试与验证10.1 单元测试harness 自带 15 个冒烟/单元测试位于 test_cli.py。它们不调用 ffmpeg 或 bash CLI全部 mock仅验证 harness 层的行为。运行方式见 TEST.mdpip install -e .[dev] pytest cli_anything/quietshrink/tests/ -v测试分组与覆盖点测试类覆盖内容TestVersionAndHelp--version、--help、无参数行为TestPresets文本 JSON 输出、schema 完整性、4 个预设齐全且q_value为整数TestFindBashCli$PATH解析、缺失时的报错信息TestDoctor环境检查项、ready布尔、ffmpeg 缺失场景TestProbeffprobe 接线、缺失文件、元数据提取TestCompressquality 参数透传、JSON 输出、bash 失败处理上游 bash CLI 本身另有 6 个冒烟测试--help、--version、缺失输入文件报错、非法预设报错等在 macos-latest CI 上全部通过——编码逻辑的正确性由上游保障本仓库的测试则守护 Agent 交互层的契约。10.2 手动端到端验证安装 harness 与 bash CLI 后可按 TEST.md 的顺序手工验证# 1. 环境自检预期 ready: true cli-anything-quietshrink doctor --json # 2. 探测真实视频预期输出 codec/尺寸/时长/大小 cli-anything-quietshrink probe ~/Desktop/recording.mov --json # 3. 压缩预期输出 input_size/output_size/saved_percent/encoding_speed cli-anything-quietshrink compress input.mov output.mov --json10.3 硬件要求小结compress需要 macOS Apple Silicon ffmpeg 6含hevc_videotoolbox其余命令probe/presets/doctor无平台限制Intel Mac / Linux 可运行但回退到libx265软件编码性能与安静体验打折。十一、与 CLI-Anything 生态的集成作为 CLI-Anything 生态的一份子cli-anything-quietshrink还随包携带了面向 Agent 的 Skill 文件 skills/SKILL.md通过 setup.py 的package_data打入安装包。该文件以 front-matter 形式声明了技能名称与描述Compress macOS screen recordings with zero CPU stress using Apple Silicons hardware HEVC encoder正文则包含完整命令清单、预设表、JSON schema、决策流与错误恢复指引——这正是 Agent 可自动加载并理解工具能力边界的标准载体让compress this screencast before sharing这类自然语言指令能被 Agent 拆解为确定性的 CLI 调用序列。如果你正在构建自动化视频处理工作流这套bash 工具 Python harness JSON 契约 Skill 元数据的组合模式本身就是一份可以直接复用的 Agent 原生工具封装范本。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 cli-anything-quietshrink：为 AI Agent 打造的原生屏幕录制压缩 CLI
cli-anything-quietshrink为 AI Agent 打造的原生屏幕录制压缩 CLI【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything本篇技术指南以cli-anything-quietshrink为核心介绍如何在 macOS Apple Silicon 上通过硬件 HEVC 编码器对屏幕录制视频进行近乎无损的压缩典型体积缩减 70%–90%并重点剖析其面向 AI Agent 设计的四大子命令、结构化 JSON 输出、质量预设体系与可测试的命令接线方式。读完本文你将掌握这套 Agent 原生 harness 的安装、使用、参数语义、JSON 数据契约与底层实现原理可直接将其接入 Claude Code、Cursor 等 Agent 工作流。一、背景与定位什么是 cli-anything-quietshrinkquietshrink是一款面向 macOS 屏幕录制场景的视频压缩工具其核心卖点是零 CPU 压力借助 Apple SiliconM1/M2/M3/M4内置的 Media Engine 硬件 HEVC 编码器hevc_videotoolbox编码过程几乎不占用 CPU电脑在压缩期间保持安静与流畅同时实现 70%–90% 的体积缩减且画质视觉无损。cli-anything-quietshrink则是 CLI-Anything 生态中为该工具封装的Agent-native harness——一个基于 Python Click 的薄封装层将独立的quietshrinkbash CLI 包装为带有结构化 JSON 输出、稳定退出码、面向 Agent 的命令接口。其完整说明见 QUIETSHRINK.md模块内的快速参考见 README.md。之所以说它“Agent-native”是因为屏幕录制压缩是 Agent 的高频任务compress this screencast before sharing、make this file smaller、convert recording.mov for email。Agent 需要的是确定性、可预测的行为而这套 harness 从设计上保证了三点硬件编码→ 压缩过程不超预算电脑保持可响应智能帧去重→ 利用屏幕内容的高度静态特性丢弃重复帧长 GOP 自适应量化→ 以硬件速度达到接近软件编码器的体积SSIM 验证过的质量预设→ Agent 可以根据用户目标分享 vs 归档直接选择合适的预设。二、安装与环境依赖2.1 安装 harness方式一git 子目录安装通过 pip 以 subdirectory 方式从仓库安装quietshrink/agent-harness子目录。方式二本地安装进入仓库内的 quietshrink/agent-harness 目录后执行pip install -e .从 setup.py 可以看到该包名为cli-anything-quietshrink版本 1.0.0运行时仅依赖click8.0.0Python 要求3.10开发依赖pytest7.0.0并通过console_scripts注册了cli-anything-quietshrink命令入口entry_points{ console_scripts: [ cli-anything-quietshrinkcli_anything.quietshrink.quietshrink_cli:cli, ], },2.2 安装上游 bash CLIharness 是围绕独立quietshrinkbash CLI 的薄封装因此要求quietshrink命令存在于$PATH中。安装方式为运行上游 quietshrink 项目提供的install.sh安装脚本。quietshrink_cli.py 中的find_bash_cli()通过shutil.which(quietshrink)定位该二进制若找不到会抛出ClickException并给出安装提示exit 非零这正是 Agent 可捕获的确定性错误信号def find_bash_cli() - Path: in_path shutil.which(quietshrink) if in_path: return Path(in_path) raise click.ClickException( quietshrink bash CLI not found on $PATH. Install it with:\n curl -fsSL .../install.sh | bash\n )2.3 硬件与 ffmpeg 要求根据 TEST.md 的说明compress压缩功能要求macOS Apple SiliconM1/M2/M3/M4使用硬件 HEVC 编码器ffmpeg 6 且启用hevc_videotoolbox通过brew install ffmpeg安装。Intel Mac 与 Linux 并非不支持只是缺少硬件加速时会回退到libx265软件编码doctor会对此给出平台检查结果输出仍然正确但失去“安静压缩”的核心体验。probe、presets、doctor等命令则无硬件要求。三、快速参考四个子命令一览从 README.md 的 Quick reference 与 SKILL.md 的命令清单出发完整命令形态如下# 压缩视频默认 transparent 质量 cli-anything-quietshrink compress input [output] # 指定质量预设压缩 cli-anything-quietshrink compress -q tiny input # 最小体积 cli-anything-quietshrink compress -q transparent input # 默认视觉无损 cli-anything-quietshrink compress -q pristine input # 接近源质量 # 压缩前检查文件编解码器 / 分辨率 / 时长 / 大小 cli-anything-quietshrink probe input # 列出可用质量预设及经验数据 cli-anything-quietshrink presets # 校验环境是否就绪ffmpeg、hevc_videotoolbox、bash CLI、平台 cli-anything-quietshrink doctor所有命令均接受--json选项输出机器可读的 JSON并以正确的退出码结束。这是 Agent 工作流的基础契约——test_cli.py 中的TestVersionAndHelp验证了--version、--help与无参数时展示帮助的行为四个子命令均被断言存在于帮助输出中。四、质量预设体系Presets质量预设是这套工具最核心的设计。四个预设由两个维度定义q量化值数字越小压缩越激进与经验测得的SSIM结构相似度越接近 1 越无损预设q典型缩减SSIM适用场景tiny50~90%~0.95聊天 / 邮件发送允许轻微瑕疵balanced55~88%~0.99文档 / 分享高质量transparent默认60~87%~0.99重要内容视觉无损pristine70~84%~0.997归档 / 剪辑接近源质量在源码中quietshrink_cli.py 的presets命令将这四组数据定义为结构化字典并原样输出而compress命令则通过 Click 的click.Choice严格限定--quality可选值tiny/balanced/transparent/pristine默认值为transparent——非法预设会被 Click 参数校验直接拒绝这也呼应了上游 bash CLI 测试中invalid quality preset correctly errors的行为click.option( --quality, -q, typeclick.Choice([tiny, balanced, transparent, pristine]), defaulttransparent, helpQuality preset, )4.1 进阶压缩参数除-q外compress还暴露两个可调参数默认值来自 quietshrink_cli.py--gop / -gGOP 大小默认600。长 GOP 是屏幕录制压缩的关键——屏幕内容静态帧多更大的 GOP 让编码器更充分地利用帧间冗余--audio / -a音频码率默认96k。屏幕录制的音频旁白、系统音对码率不敏感96k 已是质量与体积的良好平衡。因此完整的压缩命令可以写成cli-anything-quietshrink compress rec.mov rec_compressed.mov \ -q balanced -g 600 -a 96k --json4.2 预设选择决策流面向 AgentSKILL.md 给出了一条明确的决策流Agent 可按此为用户自动选择用户想分享录制视频 ├─ 在 Apple Silicon Mac 上 → 使用 quietshrink │ ├─ 聊天/邮件/快速分享 → -q tiny │ ├─ 文档/重要分享 → -q transparent默认 │ └─ 归档/剪辑 → -q pristine └─ 不在 Mac 上 → 回退软件编码效率较低处理前先运行doctor验证环境对陌生文件先运行probe了解分辨率 / 编码 / 时长。五、compress压缩命令的完整链路5.1 参数与调用链compress的完整签名见 quietshrink_cli.pycli-anything-quietshrink compress input_path [output_path] \ [--quality/-q PRESET] [--gop/-g N] [--audio/-a BITRATE] [--replace] [--json]input_path必填click.Path(existsTrue, dir_okayFalse)校验文件必须存在[output_path]可选不指定时由 bash CLI 决定输出位置--replace以压缩版本替换原文件flag 型开关。底层调用链非常清晰find_bash_cli()定位二进制 → 构造[quietshrink, --quality, ..., --gop, ..., --audio, ..., --json, (--replace), input, (output)]参数列表 →subprocess.run(..., checkTrue)调用 bash CLI 并捕获 stdout →json.loads解析结果后原样透传。测试 test_cli.py 的test_compress_passes_quality_flag通过 mocksubprocess.run断言了--quality tiny参数确实被透传给了 bash CLI。5.2 输出契约JSON Schemacompress --json返回的字段契约来自 SKILL.md 的 JSON output schema 示例{ input: /path/to/input.mov, output: /path/to/output.mov, input_size: 105952129, output_size: 12345678, saved_bytes: 93606451, saved_percent: 88.3, duration_seconds: 193.3, elapsed_seconds: 87, encoding_speed: 2.2x, quality_preset: transparent, q_value: 60, gop: 600 }字段说明字段含义input/output输入 / 输出文件路径input_size/output_size压缩前后字节数saved_bytes/saved_percent节省的字节数与百分比duration_seconds视频时长秒elapsed_seconds/encoding_speed编码耗时与实际速度倍率quality_preset/q_value/gop实际使用的预设、量化值、GOP 大小5.3 错误处理compress的失败路径同样是结构化的bash CLI 非零退出 → 输出{error: compression_failed, stderr: stderr}并以退出码1结束bash CLI 输出不是合法 JSON → 输出{error: invalid_output, raw: ..., detail: ...}并以退出码 1 结束。对应测试test_compress_handles_bash_failuremock 了CalledProcessError断言error compression_failed且 stderr 内容被携带。这保证了 Agent 总能拿到可解析的错误而不是裸的异常栈。六、probe压缩前体检probe用于在压缩前检查文件返回编解码器、分辨率、帧率、时长与体积见 quietshrink_cli.py。其内部调用ffprobeffprobe -v error \ -show_entries streamcodec_name,width,height,r_frame_rate \ -show_entries formatduration,bit_rate,size \ -of json input随后代码会从 streams 中剔除aac/mp3音频流取首个视频流信息并叠加文件真实大小与时长输出如下 JSON{ path: /path/to/rec.mov, size_bytes: 105952129, size_mb: 101.04, codec: h264, width: 1920, height: 1080, framerate: 60/1, duration_seconds: 12.5 }值得注意的实现细节若系统中没有ffprobe命令会输出{error: ffprobe not found, hint: brew install ffmpeg}并以退出码2结束——这是唯一使用退出码 2 的命令。测试 test_cli.py 的TestProbe覆盖了 ffprobe 缺失、元数据提取mock ffprobe 输出后断言 codec/width/height/duration/size 字段与文件不存在三种场景。七、doctor环境自检doctor是 Agent 在任何压缩任务前的“安全检查门”。它逐项验证quietshrink_cli.pyffmpeg 已安装shutil.which(ffmpeg)hevc_videotoolbox可用运行ffmpeg -hide_banner -encoders并检查输出是否包含hevc_videotoolboxbash CLI 存在调用find_bash_cli()捕获ClickException判定缺失平台为 Apple Silicon Macplatform.system() Darwin and platform.machine() arm64。输出格式--json{ checks: [ {check: ffmpeg installed, ok: true, path: /usr/local/bin/ffmpeg}, {check: hevc_videotoolbox available, ok: true}, {check: quietshrink bash CLI, ok: true}, {check: Apple Silicon Mac, ok: true} ], ready: true }文本模式则输出✓ / ✗标记并汇总Ready或Setup incomplete。退出码语义全部通过为 0任一检查失败为 1——Agent 可以直接用退出码做分支判断。对应测试TestDoctor断言了 JSON 结构中checks数组与ready布尔字段并验证了 ffmpeg 缺失时ready false。八、Agent 决策流与最佳实践结合 SKILL.md一个完整的 Agent 压缩工作流建议如下先doctor --json确认ready: true再继续否则先引导用户修复环境再probe --json了解编码、分辨率、时长——若输入是 h264 且分辨率极高的 120fps 录屏压缩收益会非常明显按目标选预设聊天分享用-q tiny重要分享用默认transparent归档剪辑用-q pristinecompress --json解析saved_percent与output路径反馈给用户失败恢复compression_failed时检查输入文件是否损坏或尝试更保守的预设。适用范围提醒该工具针对屏幕内容优化存在大量重复帧可供去重。SKILL.md 明确建议不要用于相机拍摄、vlog 等非屏幕内容——因为没有重复帧可丢弃压缩收益会大幅缩水。九、错误处理速查错误/异常出现条件处理建议ffmpeg not found环境缺 ffmpegbrew install ffmpeghevc_videotoolbox not availableffmpeg 未编译硬件编码器brew reinstall ffmpegcompression_failedbash CLI 压缩失败检查输入文件是否损坏用--verbose模式查看 ffmpeg 详细报错invalid_outputbash CLI 输出非 JSON属于异常情况可携带raw字段诊断probe_failedffprobe 执行失败确认文件未损坏所有错误均通过结构化 JSON 输出且退出码非零Agent 无需解析人类可读文本即可完成异常处理。十、测试与验证10.1 单元测试harness 自带 15 个冒烟/单元测试位于 test_cli.py。它们不调用 ffmpeg 或 bash CLI全部 mock仅验证 harness 层的行为。运行方式见 TEST.mdpip install -e .[dev] pytest cli_anything/quietshrink/tests/ -v测试分组与覆盖点测试类覆盖内容TestVersionAndHelp--version、--help、无参数行为TestPresets文本 JSON 输出、schema 完整性、4 个预设齐全且q_value为整数TestFindBashCli$PATH解析、缺失时的报错信息TestDoctor环境检查项、ready布尔、ffmpeg 缺失场景TestProbeffprobe 接线、缺失文件、元数据提取TestCompressquality 参数透传、JSON 输出、bash 失败处理上游 bash CLI 本身另有 6 个冒烟测试--help、--version、缺失输入文件报错、非法预设报错等在 macos-latest CI 上全部通过——编码逻辑的正确性由上游保障本仓库的测试则守护 Agent 交互层的契约。10.2 手动端到端验证安装 harness 与 bash CLI 后可按 TEST.md 的顺序手工验证# 1. 环境自检预期 ready: true cli-anything-quietshrink doctor --json # 2. 探测真实视频预期输出 codec/尺寸/时长/大小 cli-anything-quietshrink probe ~/Desktop/recording.mov --json # 3. 压缩预期输出 input_size/output_size/saved_percent/encoding_speed cli-anything-quietshrink compress input.mov output.mov --json10.3 硬件要求小结compress需要 macOS Apple Silicon ffmpeg 6含hevc_videotoolbox其余命令probe/presets/doctor无平台限制Intel Mac / Linux 可运行但回退到libx265软件编码性能与安静体验打折。十一、与 CLI-Anything 生态的集成作为 CLI-Anything 生态的一份子cli-anything-quietshrink还随包携带了面向 Agent 的 Skill 文件 skills/SKILL.md通过 setup.py 的package_data打入安装包。该文件以 front-matter 形式声明了技能名称与描述Compress macOS screen recordings with zero CPU stress using Apple Silicons hardware HEVC encoder正文则包含完整命令清单、预设表、JSON schema、决策流与错误恢复指引——这正是 Agent 可自动加载并理解工具能力边界的标准载体让compress this screencast before sharing这类自然语言指令能被 Agent 拆解为确定性的 CLI 调用序列。如果你正在构建自动化视频处理工作流这套bash 工具 Python harness JSON 契约 Skill 元数据的组合模式本身就是一份可以直接复用的 Agent 原生工具封装范本。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考