claude-watch setup.py 的设计美学:静默预检、幂等安装与 0600 密钥守卫
claude-watch setup.py 的设计美学:静默预检、幂等安装与 0600 密钥守卫
claude-watch 是一个让 Claude 拥有"看视频"能力的开源技能:贴一个链接或本地文件,它就能下载视频、抽取关键帧、生成带时间戳的字幕,然后基于"真正看到和听到"的内容回答你的问题。而每次执行 /watch 之前,第一道关卡是 scripts/setup.py——一个用静默预检、幂等安装、0600 密钥守卫把"开箱即用"做到极致的安装脚本。
为什么一个安装脚本值得细读
对大多数用户来说,安装脚本是"跑完就忘"的东西。但 claude-watch 的 setup.py 恰恰相反:它需要在每一次 /watch 调用前被静默执行一次,所以任何一次多余输出、任何一次重复覆盖,都会被成百上千次放大。作者在文件开头的注释里就把三条设计原则写得明明白白(scripts/setup.py):
- 成功时保持安静:预检通过就退出码 0、零输出,避免每一轮都刷"setup is complete";
- 幂等:安装器可以反复重跑,绝不覆盖已有密钥,只补上缺失的部分;
- 永不自动落盘 API Key:只生成占位骨架,密钥由用户亲手填写。
静默预检:成功时保持安静,失败时只说一句
/watch 的完整流程在 SKILL.md 中被定义为"Step 0 预检 → 下载 → 抽帧 → 转录 → 读帧 → 回答"。预检只需要一次不到 100ms 的查找,却要回答三个问题:
- 依赖二进制(
ffmpeg、ffprobe、yt-dlp,见 scripts/setup.py)是否都在 PATH 里? - 配置里有没有 Whisper 密钥(
GROQ_API_KEY或OPENAI_API_KEY)? - 用户是不是第一次运行(
SETUP_COMPLETE标记)?
三种退出码,一眼定位问题
cmd_check()(scripts/setup.py)是整段代码里最"克制"的部分——就绪时 return 0 且什么都不打印;失败时向 stderr 只输出一行可执行的提示,再用退出码区分故障类型:
| 退出码 | 含义 | 终端表现 |
|---|---|---|
0 |
环境就绪 | 完全静默 ✅ |
2 |
缺二进制(ffmpeg / ffprobe / yt-dlp) | 一行 stderr 提示 + 安装器路径 |
3 |
缺 Whisper API Key | 一行 stderr 提示 + 安装器路径 |
4 |
依赖和密钥都缺 | 一行 stderr 提示 + 安装器路径 |
Claude 拿到退出码就知道该不该打扰用户:0 就继续干活,非 0 才开口说"需要补哪一步"。这种"以退出码为协议、以安静为默认"的思路,对任何被高频调用的工具脚本都适用。
用 --json 让状态变成数据
如果调用方需要按细节分支(比如判断"这是不是用户的第一次运行"),可以改用结构化模式(scripts/setup.py),输出 status、first_run、missing_binaries、whisper_backend、has_api_key、config_file、platform 七个字段,其中 status 取值 ready | needs_install | needs_key | needs_install_and_key。同一个脚本,给人看用退出码,给程序读用 JSON——两种受众各得其所。
幂等安装:重复执行永远安全
🔁 幂等(idempotent)的意思是:执行一次和执行十次,结果完全一样。setup.py 的安装模式(scripts/setup.py)在两个地方把它落实到了细节:
只补缺、不覆盖:.env 骨架文件
_scaffold_env()(scripts/setup.py):只有当~/.config/watch/.env不存在时才创建,写入的是一段带详尽注释的模板(GROQ_API_KEY=、OPENAI_API_KEY=占位),已存在的配置文件原封不动;_write_setup_complete()(scripts/setup.py):先逐行扫描,发现已有SETUP_COMPLETE=就直接return,否则才在末尾追加一行SETUP_COMPLETE=true,绝不会重写整个文件。
再配合"永不自动写密钥"的原则,重跑安装器的最坏结果只是"什么都没变"——这对脚本而言是最高的赞美。
永不 sudo:按平台给出最小动作
macOS 上如果检测到 Homebrew,就自动执行 brew install ffmpeg yt-dlp,装完立刻复检、确认才报成功;Linux / Windows 则不自动动手,只打印精确到包名的命令(apt/dnf/pipx、winget)。没有 Homebrew 或平台不支持时,同样退化为"打印该敲什么"。边界全部处理干净,绝不 sudo、绝不猜。
0600 密钥守卫:API Key 的权限保险
🔒 配置文件里存的是真金白银的 API Key。0600 是 Unix 文件权限里"仅属主可读写"(owner read/write,其他人零权限)的八进制写法。setup.py 在两个时点都把它管起来:
- 创建即上锁:
_scaffold_env()和_write_setup_complete()每次写入.env后都会紧跟一次chmod 0o600(scripts/setup.py); - 读取再检查:
_check_file_permissions()(scripts/setup.py)在每次从配置文件读取密钥前,用stat检查文件位——只要"组"或"其他人"有读权限(mode & 0o044),就向 stderr 打一条警告并附上修复命令chmod 600。
不止如此,Claude Code 会话启动时的 SessionStart 钩子 hooks/scripts/check-setup.sh(注册于 hooks/hooks.json)会再用 stat 交叉验证一次权限,不是 600/400 就提醒修复;而一切就绪时它同样选择闭嘴(hooks/scripts/check-setup.sh)。
也就是说,密钥守卫是"双保险":Python 侧写入时上锁、读取时报警,Shell 侧会话级再复核。即便用户手动改坏过权限,系统也会在 5 秒超时的启动钩子里把它揪出来。
快速上手:三条命令体验完整流程
拿到仓库后(例如 git clone https://gitcode.com/gh_mirrors/cla/claude-watch ~/.claude/skills/watch),在 scripts/ 目录下只需三条命令:
python3 setup.py --check # 预检:就绪时静默,退出码 0
python3 setup.py # 首次运行:自动装依赖 + 生成 0600 的 .env 骨架
python3 setup.py --json # 机器可读的状态快照
装完后,把 ~/.config/watch/.env 里的 GROQ_API_KEY(首选,更便宜更快)或 OPENAI_API_KEY 填上你的密钥即可;两个都不填也不会坏,只是没有原生字幕的视频会退化为"只有画面帧、没有转录"。
从 setup.py 学到的三个设计启示
- 安静是默认值,报错才发声——高频调用的脚本,成功路径的零输出就是性能的一部分;
- 把"重跑安全"当作验收标准——先检查是否存在、只追加不重写,幂等性靠约束而不是靠用户自觉;
- 密钥权限最小化——创建即 600、读取即校验、跨进程交叉复核,安全不是一次设置,而是每个触点都守一次。
一个不到 330 行的文件(scripts/setup.py),把预检、安装、密钥管理三件事都收敛成了"可预期、可重放、可审计"的小动作。这大概就是它最值得细读的原因:好设计往往不在功能多,而在每一处边界都被想明白了。