Claude看视频技能 setup.py 设计解析静默预检与幂等安装的优雅平衡【免费下载链接】claude-videoGive Claude the ability to watch any video. /watch downloads, extracts frames, transcribes, hands it all to Claude.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-video本文拆解 claude-video——让 Claude 看视频的开源技能——中 scripts/setup.py 的设计。它用 326 行代码实现了静默预检silent preflight与幂等安装idempotent installer让/watch命令做到零配置启动是 AI 技能工程里少见的优雅范例。一分钟认识这个看视频技能 Claude 本身没有看视频的能力你丢给它一个视频链接它只能靠标题猜。claude-video 技能补上了这块短板——你粘贴一个 URL 或本地路径再问个问题它就用yt-dlp下载、用ffmpeg抽帧、拉取带时间戳的字幕或 Whisper 转录然后让 Claude 逐帧看完再作答。/watch https://youtu.be/xxx 30秒处发生了什么整个技能零配置体验的关键不在下载和抽帧逻辑而在那个不起眼的setup.py它负责在每次运行前确认ffmpeg/ffprobe/yt-dlp就位、Whisper API 密钥可用然后闭嘴走开。问题背景每次调用都要预检但不能啰嗦SKILL.md 规定了/watch的第 0 步每次调用前先跑一次预检——python3 ${CLAUDE_SKILL_DIR}/scripts/setup.py --check这里有个天然矛盾可靠性要求依赖缺失时必须在开跑前拦住否则ffmpeg报错了才解释用户体验很糟体验要求预检每次调用都跑若每次都在终端刷一切就绪就是纯粹的噪音。setup.py的答案是退出码协议一切就绪时exit 0且不输出任何内容出问题时才打印一行可操作的提示。README.md 称这是一个亚 100 毫秒的查找后续运行几乎零感知。一个脚本三种职责 scripts/setup.py 用单一入口承担三种模式靠第一个命令行参数分派见 scripts/setup.py 的main()模式调用方式面向谁行为静默预检setup.py --check机器/脚本就绪则静默退出 0失败打印一行提示并按约定返回退出码结构化状态setup.py --jsonClaude 解析输出{status, first_run, missing_binaries, whisper_backend, ...}JSON安装器setup.py无参数人/Agent自动装依赖、搭.env骨架、写入完成标记--json模式scripts/setup.py输出ready | needs_install | needs_key | needs_install_and_key四种状态外加first_run字段——这让 Claude 能精确判断这是不是用户的第一次运行从而决定要不要走引导式流程。静默预检的退出码约定cmd_check()scripts/setup.py把失败原因编码成退出码退出码含义Claude 该做什么0一切就绪无输出直接进入正题2缺少二进制ffmpeg/ffprobe/yt-dlp运行安装器3缺少 Whisper API 密钥搭好.env后向用户要密钥4两者都缺先装依赖再要密钥退出码本身就是文档SKILL.md里给 Claude 的处置表格与之一一对应无需任何解析逻辑。幂等安装怎么重复跑都安全 ✅幂等idempotent是这个词最该出现的地方——安装器随时可能被 Claude 或用户再次触发绝不能破坏现有配置。setup.py的源码注释scripts/setup.py直接写明设计目标永不覆盖已有密钥只补齐缺失项。三个关键函数的幂等细节1. 配置骨架只创建、不重写。_scaffold_env()scripts/setup.py发现~/.config/watch/.env已存在就直接返回False只在文件缺失时才写入占位模板并立即chmod 0600收紧权限。你手工填好的 API 密钥永远不会被模板冲掉。2. 完成标记只追加一次。_write_setup_complete()scripts/setup.py写入SETUP_COMPLETEtrue前先逐行扫描发现已有该标记就静默返回——重复安装不会产生重复行。3. 首次运行判定是读取不是状态文件。is_first_run()scripts/setup.py通过读取该标记判断安装器是否成功走完过一次后续会话据此跳过向导式提示保持安静。不同平台的安装策略也刻意保守scripts/setup.pymacOS检测到 Homebrew 就自动执行brew install ffmpeg yt-dlp装完还会复查一次是否真装上Linux / Windows只打印精确的安装命令apt/dnf/pipx、winget/pip把决定权留给人。这背后是一条安全底线绝不 sudo也绝不自动把 API 密钥写到磁盘——密钥栏只留占位符由用户自己填或 Claude 询问后代填。藏在细节里的安全设计 ️除了只搭骨架不写密钥还有两处容易被忽略的细节权限体检_check_file_permissions()scripts/setup.py在每次读取.env时检查文件是否对其他用户/组可读若是就向 stderr 警告并给出chmod 600修复命令。密钥文件的权限问题往往是最先被利用的漏洞。会话级双重检查Claude Code 插件的 SessionStart 钩子 hooks/scripts/check-setup.sh 在每次会话开始时独立复查一遍二进制与密钥状态就绪就静默部分配置时只给一行提示——和setup.py的哲学完全一致形成两道防线。setup.py 在整个技能中的位置 看一张精简的调用链完整结构见 README.md 的 Structure 一节入口用户敲/watch url [问题]→ scripts/watch.py 编排全流程预检每次调用前先跑setup.py --check非零退出则触发安装器下游scripts/download.pyyt-dlp 下载→ scripts/frames.pyffmpeg 抽帧→ scripts/transcribe.py scripts/whisper.py字幕或 Whisper 转录会话钩子hooks/hooks.json 注册的 hooks/scripts/check-setup.sh会话开始时一行状态汇报setup.py恰好站在编排层与执行层之间它不碰视频、不碰网络只保证地基是好的——这正是它敢做到极致的原因职责单一失败路径极少。能带走的 5 个设计要点成功即沉默预检类脚本的默认输出应该是无退出码才是主通道退出码当协议用给上游人或 Agent的处置表与退出码一一对应零解析成本幂等是默认值每个写操作前先检查是否已经做过让重跑永远安全用标记而非状态文件SETUP_COMPLETEtrue直接存在.env里少一个文件就少一类不一致保守安装能自动才自动macOS brew否则打印精确命令密钥永不由脚本代填。这套静默预检 幂等安装的组合拳让 claude-video 用户第一次粘贴视频链接就能用之后每次运行都无感。想进一步阅读可对照 SKILL.md 的 Step 0 预检流程与 CHANGELOG.md 中关于 setup 的演进记录如 Windows 下改用winget/pip提示的修复。相关路径速查预检与安装器scripts/setup.py技能契约含 Step 0 预检规则SKILL.md主入口编排scripts/watch.py会话钩子配置hooks/hooks.json会话钩子脚本hooks/scripts/check-setup.sh版本历史CHANGELOG.md许可证LICENSE【免费下载链接】claude-videoGive Claude the ability to watch any video. /watch downloads, extracts frames, transcribes, hands it all to Claude.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-video创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考