参与贡献 - ZLHad/OpenVideoHarness GitHub Wiki

English · 中文

谢谢你愿意帮忙。规则以 CONTRIBUTING.md 为准，这一页是简版。人和 coding agent 守同一套规矩，agent 另外多几条。

• 用这套工作台做视频。你的项目都在 projects/ 里，不进版本库。可以回馈的有：做好的片子放进 showcase/，拉片拆解写进 cases/，镜头配方放进 recipes/，通用的经验补进 playbook/ 或类型文档的自查重点。
• 改这套工作台本身：bin/vh、tools/、引擎、文档、风格库。这些都走 PR。

1. 开分支：一件事一个分支、一个 PR。人用 <名字>/<主题>，agent 用 claude/<主题> 或 codex/<主题>。谁都不能直接推 main，维护者也一样，由规则集 main-via-pr 强制执行。
2. 推送前自查：tools/ci.sh --committed 会在一份干净的检出上检查你已提交的 HEAD，结果和 CI 看到的一致。在 Mac 上，还可以用 VH_BASH=/bin/bash tools/ci.sh 在系统自带的 bash 3.2 下跑一遍。
3. 开草稿 PR：写清改了什么、为什么改、怎么验证的。修 bug 要先复现，再给出修复前后的对比。
4. 合并：有人看过之后，草稿转成正式 PR，等两项 CI 检查（Linux、macOS）都通过、分支已同步到最新的 main、评审里的对话都已解决，再用 squash 合并。可以打开 auto-merge，不用守着 CI。
5. 不改写已推送的历史：推送过的分支不 rebase、不 amend、不 force push；main 往前走了，就把 main 合进你的分支。

另外几件事：

• 用户能感知到的改动，在 CHANGELOG.md 的 Unreleased 下记一笔。
• 改了 CLAUDE.md，运行 bin/vh sync-agents 重新生成 AGENTS.md，CI 会检查两者是否一致。
• 不要提交 API key、LOCAL.md、projects/ 和渲染产物。测试时如果重渲了受版本管理的样片（styles/<slug>/media/），推送前还原。

agent 还要多守几条：只推自己的分支，不动 tag，PR 一律开成草稿，只有人在对话里明确要求时才合并。

按 styles/README.md"加一个新风格"一节的六步来：用 playbook/07 拆解 1–3 部作品；照 _TEMPLATE.md 写 STYLE.md，再写 tokens.json；从 demo 复制 swatch.js（风格要路径追踪的光和真实景深时，改写成 Blender 场景 swatch.py，样板是 tabletop-miniature），要声音就加 score.json；用 bin/vh style <slug> --draft --hud 反复改，再用 bin/vh style <slug> 出正式样片；跑 bin/vh style check <slug>；用 bin/vh style gallery --mp4 重建总览，在表里加一行。守住风格库的规矩：学语法、不抄作品，文化题材要准确，只用本机字体。预设要写成立意可以借用的参考，不要写成模板。import bpy 的 .py 文件要带 GPL-3.0-or-later 的 SPDX 文件头；CI 会检查这个文件头，并对每个 Blender 场景跑一遍渲染器在启动 Blender 之前做的那次静态扫描。给社区投稿准备的更轻量的模板和评审流程，计划在 v0.3 推出（见路线图）。

配方写的是一个镜头或一个接缝怎么动：分几段、每段多少帧，参数表里标出命门，哪里容易翻车，做完看哪一帧，再附一段能被风格 tokens 换皮的 canvas 草图。复制 recipes/_TEMPLATE.md 填好，在 recipes/README.md 的索引里加一行，再跑 bin/vh recipes check，CI 也会跑它。状态要如实标：只有本仓库做过的片子里用过、并且有人看过、给了判定，才能标 battle-tested。改编别人的配方，要写明来源、改了什么，并保留对方的许可声明（Apache-2.0 的那些列在 recipes/NOTICE.md 里）。

按 playbook/07-reverse-engineer.md 拉片：拿到帧，逐层拆，反推 BRIEF，再按现有案例的格式写出来（做了什么、怎么做的、为什么有效、能借用什么）。文件放进 cases/，并在 cases/README.md 的表里加一行。取帧时注意平台条款和版权：拆解只用于学习，不要重新发布原片的画面。记下原作的许可证。

在 showcase/ 下按现有目录的命名方式新建一个目录，放进 BRIEF.md、STORYBOARD.md、NOTES.md、LESSONS.md、源码，以及一份和其他目录格式一致的 README。视频不进 git，放进 Release media：用 gh release upload media <文件> 上传，再在 tools/media.txt 登记路径和 sha256（见 CONTRIBUTING.md）。

这些还没有开成 issue；动手前先开一个说一声，免得重复。

• 用实验性的第 09 类剪一支真的口播片，把成片导进剪辑软件看看，告诉我们它的阈值和规则哪里不对：它目前只在合成材料上标定过。
• 把 engines/blender.md "首次冒烟"里还没做的几项跑一遍，把结果写回去：EEVEE 命令行渲 300 帧的内存曲线，Metal 上 Cycles 的确定性（-f N 对 -a，自适应采样开、关），OIDN 在静止区域的闪烁，刚体缓存乱序渲染是否一致，HyperFrames 的 <video> 是否保留 alpha，以及指南里的命令在 5.2 上的实际行为。其余几项已经用 Blender 5.2.2 跑过。
• 用你自己的 key，对真实接口跑一遍 dashscope 或 elevenlabs 配音，报告哪里出问题。
• 在你用的 Linux 发行版上装一遍，报告或修掉不顺手的地方。
• 把一份工作流文档（某个类型文档或 playbook 的一篇）翻译成英文。
• 为一支公开的、用代码做的片子写案例拆解。
• 从 playbook/04 的"已知局限"里挑一条，提出修法。

问题、bug 和建议，都请开 issue。