快速开始 - ZLHad/OpenVideoHarness GitHub Wiki
English · 中文
这一页带你从零做出第一支视频，前提是你已经在用 coding agent（Claude Code 或 Codex）。完整的安装说明见 README。
| 依赖 | 用来做什么 | 必需吗 |
|---|---|---|
| macOS 或 Linux、git | 基础 | 必需 |
| Node.js ≥ 22、Google Chrome（或 Chromium） | 在无头浏览器里渲染 | 必需 |
| FFmpeg | 编码、混音、检查 | 必需 |
| Python 3 + uv | 声音工具（tts、beats、music、sfx、qa、mix … profile=）、联系表和 Manim；依赖第一次用时下载到 uv 的缓存，不装进全局环境 |
做声音和联系表时必需 |
| Apple Silicon | 本地 Qwen3-TTS 配音 | 用本地配音时需要 |
| LaTeX | Manim 里的公式 | 做数学讲解时需要 |
渲染本身不花钱。云端配音、生成式视频按各家的价格收费，见常见问题。
curl -fsSL https://raw.githubusercontent.com/ZLHad/OpenVideoHarness/main/install.sh | bash这条命令会把仓库的最新版本克隆到 ~/OpenVideoHarness（不带历史），装好自带的手绘引擎和风格样片渲染器，拉取 30 个只读参考仓库，把 open-video-harness skill 注册给 Claude Code（~/.claude/skills）和 Codex（~/.agents/skills），生成 LOCAL.md，最后跑一遍 bin/vh doctor。
可选参数：--dir <路径> 装到别处；--no-refs 先不拉参考仓库（以后再运行 references/fetch.sh，或者用 references/fetch.sh <名字> 只拉一个）；--no-skill 不注册 skill；--skill claude|codex|all 指定注册给谁。
手动安装，用完整克隆（下载约 95 MB，占磁盘约 180 MB，带历史；想参与贡献就这样克隆）：
git clone https://github.com/ZLHad/OpenVideoHarness.git && cd OpenVideoHarness
bin/vh setup # 引擎依赖、参考仓库、样片渲染器，再做一次渲染冒烟测试
bin/vh install-skill # 可选：注册 skill注册完 skill 要重启 Claude Code 或 Codex。之后在任何目录说"做个视频"，agent 都会找到这里。
以后更新：用和上次一样的参数再运行一次安装命令（一键安装的参数写在 bash -s -- 后面：curl -fsSL https://raw.githubusercontent.com/ZLHad/OpenVideoHarness/main/install.sh | bash -s -- --no-refs）。安装脚本克隆的仓库只拉最新的一个提交；LOCAL.md 和 projects/ 都不动，要覆盖你改过的文件时会停下来，不会硬改。完整克隆的仓库也可以 git pull，再运行 references/fetch.sh。2026-10-04 之前做的完整克隆不行：那天重写了历史、去掉旧视频，所有提交号都变了。重新克隆一份，把 LOCAL.md 和 projects/ 挪过去；不要对旧克隆做 merge 或 rebase，那会把旧视频带回来（见 CHANGELOG）。
安装本身约占 590 MB 磁盘：仓库约 185 MB（下载约 85 MB；样片的视频在 GitHub Release 里，复现样片时用 tools/fetch_media.sh 下载）、自带手绘引擎和样片渲染器的 Node 依赖约 210 MB、参考仓库约 195 MB。之后第一次用到的东西还会悄悄再下一批。
大小都是约数，在 macOS（Apple Silicon）上量的，你那边 du -sh 会差一点。
| 下载的东西 | 什么时候 | 放在哪里 | 大小 |
|---|---|---|---|
| 本仓库的最新提交（样片的视频在 GitHub Release，不在里面） | 安装时 | ~/OpenVideoHarness |
下载约 85 MB，占磁盘约 185 MB |
| 手绘引擎和风格样片渲染器的 Node 依赖 | 安装时 | 仓库里的 node_modules
|
约 210 MB |
| 30 个只读参考仓库 | 安装时，加 --no-refs 可跳过 |
references/repos/ |
约 195 MB |
HyperFrames 用的 Chrome（chrome-headless-shell） |
第一次 hyperframes render
|
~/.cache/hyperframes |
下载约 100 MB，解压后约 200 MB |
bin/vh beats、music、sfx、qa、sheet 用的 Python 依赖（librosa、numba、scipy 等） |
每个命令第一次运行时 | uv 的缓存 ~/.cache/uv
|
合计约 700 MB |
每个 HyperFrames 项目自己的 node_modules
|
每次 bin/vh new short、promo、data、meme
|
项目目录里 | 每个约 140 MB |
本地 Qwen3-TTS 配音：mlx-audio 和它的依赖，再加模型 |
第一次用默认的本地配音（qwen）跑 bin/vh tts；换别的配音服务就不用 |
~/.cache/uv 和 ~/.cache/huggingface
|
约 750 MB 和 2 GB |
安装脚本自己只写仓库目录；没加 --no-skill 时，还会在 ~/.claude/skills 和 ~/.agents/skills 下各写一个很小的 skill 文件，npm 也照常写它自己的缓存。从 chrome-headless-shell 那一行往下，都是用到才下载，不会问你，输出也很少：bin/vh 调 uv 是静默的；agent 在非交互的 shell 里跑第一次渲染，只看到 "Checking browser…" 转圈，Chrome 就是这时在下。HyperFrames 还会在 ~/.hyperframes 放一份很小的配置和日志。这些都在你的用户目录下，不在仓库里；uv 和 Hugging Face 的缓存和你别的工具共用。网络慢或不通时，看国内网络。
不想拉参考仓库：它们是别人的 skill 和片子源码，浅克隆下来给 agent 阅读，渲染不依赖它们。用 --no-refs 安装；以后哪份工作流文档指向的 references/repos/<名字>/ 你没有，就只拉那一个：references/fetch.sh hyperframes（约 30 MB）。不带参数的 references/fetch.sh 一次拉全部 30 个。
bin/vh doctor 每项一行：✓ 正常，✗ 缺了必需的东西，! 可选项或者值得看一眼的地方。它会检查 Node、FFmpeg、Chrome（真的起一个无头浏览器测 WebGL）、HyperFrames 自己的 Chrome、Python、uv、LaTeX、git、引擎依赖、参考仓库（和 references/fetch.sh 要拉的数量对一下）、Qwen3-TTS 的缓存、LOCAL.md（里面还留着 {…} 占位符时会提醒你），以及 AGENTS.md 和 CLAUDE.md 是否一致；最后列出前几次运行还会再下载什么。仓库内的东西缺了，跑 bin/vh setup 补上。没有 uv 会显示红色的 ✗，因为声音工具和联系表都靠它跑。
LOCAL.md 不进版本库，用来告诉 agent 这台机器的情况：硬件、装了哪些工具和引擎、渲染速度、有哪些 API key（只写变量名，不写值）、论文和素材放在哪、默认的努力程度、导演模式的默认设置和个人偏好。doctor 的输出可以直接贴进去。模板是 LOCAL.example.md。
# 1. 安装（最后会跑 bin/vh doctor）
curl -fsSL https://raw.githubusercontent.com/ZLHad/OpenVideoHarness/main/install.sh | bash
# 2. 在仓库里打开 agent
cd ~/OpenVideoHarness && claude # 或者：codex- 用一句话说你要什么：
做一个 30 秒的竖屏科普：为什么低轨卫星的信号会"变调"。中文配音，中英双语字幕。
说清楚讲什么、给谁看、发在哪就够了。agent 会先替它想几个立意，其余按类型文档的默认值补全，最多问你 3 个真正影响结果的问题。发在哪很要紧：它决定这支片子在哪看（手机、手机信息流还是电脑），进而决定画幅和最小字号。更多提需求的例子见 README。
想在三道关卡之外多定几件事，就直接说哪几件由你来定："钩子、主角和主旋律我来选，其余你定。"这就是导演模式。
也可以先把项目建出来：bin/vh new short my-first-video（类型列表用 bin/vh types 看），再打开 agent 说这支视频讲什么。短视频、发布片、数据和梗这几类可以加 --aspect 16:9|9:16|1:1 指定画幅；另外，--watch phone|feed|desktop 指定在哪看（默认按类型和画幅定）；--res 1080p|4k 指定输出分辨率（4K 照常按 1080p 写，出片时渲成两倍大）；--dir <目录> 把项目建在仓库外面你指定的目录里。任何命令加 -h 都只打印用法，不会真的运行。
每到一关，agent 默认会做一页本地的审阅页（bin/vh review 写到 out/review/ 里，直接从磁盘打开，图、视频、音频都能在页面里看和听），聊天里只发要你定的事和页面路径，然后停下来等你回复。页面最上面是最多三件要你定的事，每件带推荐和一句回复写法，其余内容放在下面。你的原话会逐字记进项目的 REVIEW.md，agent 自己定的事记进 DECISIONS.md。
| 关卡 | 你会拿到 | 你要决定 |
|---|---|---|
| ① 立意和大纲 | 2–3 张彼此拉得开的立意卡：每张是一句话的点子、由它推出的画面（专属风格，或借一个或几个风格预设）和钩子，配一帧画面；再按推荐的那张给出 BRIEF（讲什么、给谁看、多长、什么画幅、在哪看、有没有声音）、3–7 段大纲、用什么引擎和为什么、要付费的 API 或要下载的模型及费用估算；替你定好的规格默认值；最多 3 个问题 | 选一张卡（可以在回复里换它的预设或钩子）；大纲通过、按意见改或推翻重来 |
| ② 分镜 | 按大纲的段落一段一页，每页 3–6 镜：每镜一张关键帧，带它的 reads 和旁白；没把握的镜头标红，还有这一段的 animatic；可以附一张节奏图 | 通过，或者点名要改的镜头（"S04 改：……"） |
| ③ 初版 |
out/draft.mp4 和整片联系表；清单里哪些条目没过、怎么修的；最近一轮的打分；它自己最不满意的两三处，写明时间点和改法；屏幕上每个数字的出处 |
通过（它去出成片），或者给修改意见 |
最有用的意见带时间点和原因，比如"0:12–0:15 字太多，读不完"。说不清哪里不对，就直说"感觉不对"：它会挑一段 10–20 秒做两三个变体（look-dev），你挑一个方向就行。
选 quick 档时没有关卡，直接出片，需求有歧义时最多问 1 个问题（你点名要定的事照样会停）。选 studio 档时，关卡 ① 的每张立意卡各附一段 10–20 秒的草图，关卡 ② 附全长 animatic。详见工作原理。
每支视频是 projects/ 下的一个目录（git 会忽略它），由 bin/vh new <类型> <名字> 建出来：
projects/2026-09-30-leo-doppler/
├── BRIEF.md STYLE.md STORYBOARD.md REVIEW.md DECISIONS.md NOTES.md LESSONS.md TASTE_CHECKLIST.md
├── audio/ 旁白稿、配音、时间表、字幕、配乐、节拍表、音效事件、混音
├── assets/ 图片、字体、图标（记下来源和许可）
├── style-refs/ 借来参考的风格预设副本（有的话）
├── out/review/ 审阅页（gate-1.html …，最新的一页同时是 index.html）
├── out/check/ 联系表、strip、crop、分镜页
└── out/ draft 和成片 mp4
引擎文件也在这个目录里：手绘和 MV 类会复制一份 ClaudeAnimationBase，科普短视频、发布片、数据和梗类会装好 HyperFrames 脚手架，Manim 类由 bin/vh new 打印出初始化用的 uv 命令。加了 --style <预设>（几个：--style a,b），每个预设的副本会放进 style-refs/ 当参考，并记在 BRIEF 的 Style refs 一行；这支片子自己的 STYLE.md 仍从立意写起，借了什么在 DECISIONS.md 记一行。要定到旁白稿、主角或标题封面时，agent 会再复制进 SCRIPT.md、CHARACTER.md、PACKAGING.md（各是一份精简的模板）。REVIEW.md 记你的原话，DECISIONS.md 记谁定了什么、为什么，NOTES.md 记素材清单、事实核对、自评和素材台账。立意和规格（画幅、分辨率、帧率、时长、在哪看）写在 BRIEF.md 开头。
最后你拿到的是：一支 MP4（可以带能开关的中英字幕轨），一个改一行就能重渲的工程，以及全过程的文件。
macOS：仓库是在 Apple Silicon 的 Mac 上做出来、测过的。本地 Qwen3-TTS 需要 Apple Silicon，say 的音色也只有 macOS 有。CI 还会用 Mac 自带的 /bin/bash 3.2 跑一遍 bin/vh。
Linux：CI 在 Ubuntu 上跑；在一台 Ubuntu 24.04 机器上配环境时又修了一批问题。这些修复已经在 main 上，但还没打版本，之前装过的话先 git pull。Chromium 用包管理器装，或者 npx playwright install chromium，也可以用 CHROME_PATH 指定浏览器。没有 GPU 时，bin/vh doctor 会告诉你软件模拟的 WebGL 能不能用；能用就在渲染时加 --soft-gl（bin/vh setup 的冒烟测试也会这样重试）。配音方面，本地 Qwen3-TTS 和 say 都用不了，改用 edge（免费、非官方接口）或云端服务，见声音与配音。
Windows 不在支持范围内：环境要求写的是 macOS 或 Linux。