/video-setup
将工作台从全新克隆一步设置为 passed N, failed 0。setup.sh 完成实际工作;你的任务是解释它、获得用户同意、运行它,并将每个 FAIL 行转化为对应的修复方案。
首先找到工作台路径(在工作台目录或产品文件夹内均可):
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
使用用户的母语与其沟通。保持简洁:他们需要的是能正常工作的环境,而不是产品介绍。
使用参数 check
运行 bash "$PVS_HOME/setup.sh" --check 并显示结果。此操作不会安装任何内容、不下载任何文件、也不写入任何数据。对于每个 FAIL 行,给出其修复方法(行末尾指明了修复方式)。到此为止。
否则
1. 报告机器状态
首先运行 bash "$PVS_HOME/setup.sh" --check。它会为每个检查项输出一行结果:ok(通过)、warn(警告)或 FAIL(失败),并附上精确的修复方法。
- 如果 Machine(机器)部分下的任何行失败(如 node 22+、python 3.9+、ffmpeg、git),则无法继续安装。将行中给出的修复方法(例如
brew install ffmpeg)告知用户,请他们在自己的终端中运行,然后重新执行检查。安装系统软件包是用户自己的决定,除非用户主动要求,否则不要自行运行brew或apt。 - Claude Code 上的
warn仅仅是提示性信息。 - Toolchain(工具链)部分下的 FAIL 行是安装脚本需要修复的部分。这在首次运行时属于正常现象。
2. 说明将要下载的内容,并征询一次同意
用一条简短的列表告知用户,只列出检查报告中缺失的部分:
| 组件 | 大小 | 安装位置 |
|---|---|---|
| 固定版本的 HyperFrames CLI 及其依赖 | 约 128 MB | node_modules/ |
| HyperFrames 用于渲染的 Chrome 构建 | 约 195 MB(已缓存则跳过) | HyperFrames 缓存目录 |
| 来自同一发布标签的 HyperFrames Agent 技能 | 几 MB | vendor/hyperframes/skills/ |
| Python 包(主要是用于语音转文字的 torch) | 约 339 MB | .venv/ |
QA 使用的 Whisper small.en 语音模型 | 484 MB | ~/.cache/whisper/ |
只问一个封闭性问题:“现在安装这些组件吗?(是 / 否)”。安装应通过首次 /video-setup 一步完成,不要分成多次确认。
3. 执行安装
如果用户回答“是”,则运行 bash "$PVS_HOME/setup.sh" --yes(--yes 是用户已给出的回答)。首次运行需要几分钟时间,所有组件缓存后只需几秒;设置超时时间至少为 10 分钟。该命令是幂等的:重复运行只会重新安装缺失的部分。
4. 处理每个 FAIL
每个 FAIL 都标明了其修复方法。常见情况如下:
| FAIL | 处理方法 |
|---|---|
npm install failed | 网络或注册表问题。显示它引用的日志文件的最后几行,然后重新运行安装脚本 |
hyperframes browser ensure failed | 在工作台目录运行 npx hyperframes browser ensure --force,然后重新运行安装脚本 |
could not clone heygen-com/hyperframes | 网络或 GitHub 访问问题。检查 git ls-remote https://github.com/heygen-com/hyperframes,然后重新运行安装脚本 |
python3 -m venv failed | 在 Debian 或 Ubuntu 上:sudo apt install python3-venv(由用户运行) |
pip install -r requirements.txt failed | 显示日志尾部。比固定版本更新的 Python 可能需要更新的 wheel 包;请报告这一问题,而不是修改固定版本 |
hyperframes doctor: ... | 该行指明了失败的检查项及其修复方法。版本号、Docker 以及可选的本地语音和音乐检查会被故意忽略 |
tests/run.sh: passed N, failed M | 运行 bash "$PVS_HOME/tests/run.sh" 并显示失败的测试及其输出 |
绝对不要通过运行 hyperframes upgrade 或 hyperframes skills update 来“修复”FAIL。工作台固定了单一 HyperFrames 版本,并从同一标签获取技能,因为不同版本 CLI 与技能对合成合约的理解不一致。版本变更需要通过 tests/run.sh 的拉取请求来实现。守卫钩子也会阻止这两个命令。
5. 语音密钥
安装脚本会从 .env.example 创建 .env,并告知你 ElevenLabs 密钥是否已设置,但不会输出密钥本身。如果密钥为空,请告知用户:
- 在自己的编辑器中打开
.env(位于工作台文件夹内),将密钥粘贴到ELEVENLABS_API_KEY=之后。切勿在聊天中操作:聊天内容会被存储到对话记录中。如果用户仍然在此处粘贴了密钥,请告知他们立即轮换密钥。 - 如果没有密钥,产品
product.yaml中的voice.provider: say会使用 MacOS 自带的免费语音,足以用于草稿和测试。
绝对不要自行打开、读取或打印 .env 文件。 设置和守卫钩子会禁止这些操作,脚本会通过 lib/pvs.py 自行加载密钥。
6. 结束确认
确认输出最后几行为 passed N, failed 0 和 Setup done。然后用一行给出下一步操作:/product-new <slug> 来创建产品,或 /video-ask 查看当前状态。