diff --git a/AGENTS.md b/AGENTS.md index 0fa4cac..fbb3087 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ 3. **建项目**:运行 `bin/vh new `,它会建好 `projects/<日期>-/`,复制模板,并把该类型的 prompt 块填进 BRIEF(类型的默认做法,立意定了再取舍);手绘类还会复制引擎、装好依赖。其他引擎的初始化方式见 `engines/README.md`。 4. **先想立意,再看案例和参考**:建完项目,先把材料里只属于它的数字、原话、物件列进 NOTES.md 的素材清单,自己想 5–8 个点子;这时先不看 BRIEF 末尾的 TYPE 块、`styles/`、`recipes/` 和案例,免得点子往看过的东西上靠。然后再看下面这些参考,用它们补强,收敛成 2–3 张立意卡(做法见 `playbook/12-ideation.md`,例子见 `cases/oneshot-five.md`)。人已经给了立意,就记进 BRIEF,不再出卡,最多附一个备选。参考:打开类型文档"可参考的案例"和"社区 skill 参考"两节列出的文件;需要看真实代码时读 `references/repos/` 里的源码。本仓库自己做过的片子在 `showcase/`,各带 BRIEF、STORYBOARD、NOTES 和源码,是最直接的样板。分镜时,镜头怎么动、全片节奏怎么排,先查 `recipes/`:按意图和能量筛(`bin/vh recipes list`),把选中的配方 id 写进 STORYBOARD 的"配方"列,写代码前读配方全文。 5. **停下来给人审**:`standard` 和 `studio` 必过下面三道关卡,`quick` 不设关卡;人点名要亲自拍板的事,按"导演模式"另外停,`quick` 也一样。每次停默认做一页决定优先的审阅页(`bin/vh review` 生成本地 HTML,做法见 `playbook/01-pipeline.md` 的"审阅页"),聊天里只发要人定的事和页面路径;只有一两个纯文字的选择时,直接在聊天里问也行。然后**停下来等人回复**,不要自己往下做: - - ① **立意和大纲**:2–3 张彼此拉得开的立意卡,每张写明由它推出的画面(专属风格,或借 `styles/` 的一个预设)和钩子,配一帧画面(`playbook/12-ideation.md` 第 7 节)。选一张卡,立意、风格方向和钩子就一起定了,人可以在回复里换预设或钩子。再附按推荐立意写的 BRIEF、3–7 段大纲、引擎和费用。不要默认只给一种口味; + - ① **立意和大纲**:2–3 张彼此拉得开的立意卡,每张写明由它推出的画面(专属风格,或参考 `styles/` 的预设,可以几个)和钩子,配一帧画面(`playbook/12-ideation.md` 第 7 节)。选一张卡,立意、风格方向和钩子就一起定了,人可以在回复里换预设或钩子。再附按推荐立意写的 BRIEF、3–7 段大纲、引擎和费用。不要默认只给一种口味; - ② **分镜**:按大纲的段落拆页,每页 3–6 镜的关键帧,没把握的镜头标出来,逐镜默认通过。长片再附一版全长灰盒 animatic; - ③ **初版**:draft 成片加联系表,并写出你自己最不满意的 2–3 处。 @@ -39,7 +39,7 @@ | 适合 | 试方向、草稿、随手发 | 大多数正式视频 | 发布片、旗舰内容、会被反复看的片子 | | 人工关卡 | 0 道,直接出片。选 quick 就等于授权跳过关卡,把这一点记进 REVIEW.md;需求有歧义时最多问 1 个问题;人点名要拍板的事照样停(导演模式) | 3 道 | 3 道;关卡 ① 每张立意卡附一段 10–20 s 草图,关卡 ② 附全长 animatic | | 立意 | 自己想 3 个一句话点子,挑 1 个,写一行理由 | 关卡 ① 给 2–3 张立意卡,每张配一帧画面 | 同左,每张配一段 10–20 s 的草图(look-dev) | -| 风格 | 从立意推出来,可以借 `styles/` 的 1 个预设,写明理由 | 写在每张立意卡的"画面"一行(专属,或借一个预设);选卡就一起定了,人可以在回复里换 | 同左;每张卡的草图就是那种风格的小样,借来的预设人想看时在 E0 补小样 | +| 风格 | 从立意推出来,可以参考 `styles/` 的预设,写明借了什么 | 写在每张立意卡的"画面"一行(专属,或借一个预设);选卡就一起定了,人可以在回复里换 | 同左;每张卡的草图就是那种风格的小样,借来的预设人想看时在 E0 补小样 | | 分镜 | 简表:镜头、时长、reads | 完整 STORYBOARD + 分镜预览图 | 同左 + animatic | | 自查 | 整片一张联系表、一张按目标屏缩的联系表、前 2 s 的 strip,20 条清单速查一遍 | 每个场景:联系表、关键动作 strip、局部 crop;20 条清单 | 同左,再加目标屏尺寸测试、循环接缝、无损帧确定性、静默故障扫描 | | 独立评审(打分层) | 不做 | 1 轮:全新上下文的 reviewer 打 8 项分(含立意),修最差的 3 处 | ≥ 3 轮,8 项都 ≥ 8 才出片;达不到就带着分数进关卡 ③ | @@ -64,7 +64,7 @@ `quick` 省掉的是轮数和审阅,不是这些。 -**底线之外都是默认口味**:`TASTE_CHECKLIST.md` 里没标【底线】的条目、BRIEF 的 Motion defaults、类型文档 Prompt 增量块里的语域和节拍、风格预设和配方,都是没有立意时的稳妥做法。立意需要时可以反着来:在写用到它的场景之前,把改了什么、立意为什么需要写在立意卡或 STYLE.md 上,记进 `DECISIONS.md`;人批过的卡上写了的,算人的决定,reviewer 只查有没有做到;之后才加的由 reviewer 判断站不站得住,判了 FAIL 再补的不算(`playbook/12-ideation.md` 第 6 节)。类型文档"禁止"一节也分两种:管事实、许可、可读和隐私的是底线,管长相的(配色、质感、缓动、图表样式)是默认口味。规则是用来防止犯错的,不是用来规定口味的。 +**底线之外都是默认口味**:`TASTE_CHECKLIST.md` 里没标【底线】的条目、BRIEF 的 Motion defaults、类型文档 Prompt 增量块里的语域和节拍、镜头配方,都是没有立意时的稳妥做法。风格预设只是参考:借了什么在 `DECISIONS.md` 记一行,不借、借一半、几个混着借都行,和它不一样不用解释;借来的东西碰到清单里没标【底线】的条目,照口味覆盖记一行。立意需要时可以反着来:在写用到它的场景之前,把改了什么、立意为什么需要写在立意卡或 STYLE.md 上,记进 `DECISIONS.md`;人批过的卡上写了的,算人的决定,reviewer 只查有没有做到;之后才加的由 reviewer 判断站不站得住,判了 FAIL 再补的不算(`playbook/12-ideation.md` 第 6 节)。类型文档"禁止"一节也分两种:管事实、许可、可读和隐私的是底线,管长相的(配色、质感、缓动、图表样式)是默认口味。规则是用来防止犯错的,不是用来规定口味的。 ## 导演模式:谁来拍板 @@ -85,7 +85,7 @@ effort 管 agent 自己查得多细,导演模式管人拍板哪些事,两个 用户要 `quick` 时,不用把上面各步列的文档都读完,照这张卡做: 1. **读**:路由表对应的类型文档,只读"工作流"和"禁止"两节("Prompt 增量块"会贴在 BRIEF 末尾,挑定立意以后再读);再读 `engines/README.md` 里对应引擎的一节,HyperFrames 先看其中的"最小写法"。 -2. **建项目和立意**:`bin/vh new --effort quick`。先写 3 个一句话立意,挑一个(`playbook/12-ideation.md` 第 7 节最后一条),再读 BRIEF 末尾的 TYPE 块,决定留哪些默认。风格从立意推出来,合适的话借一个预设:`bin/vh style apply `(`bin/vh style list` 挑),它的 `STYLE_PRESET.md` 会带进项目,写代码前读一遍。立意和风格各写一行理由进 `DECISIONS.md`;改了哪些口味默认,交付时一并列出。 +2. **建项目和立意**:`bin/vh new --effort quick`。先写 3 个一句话立意,挑一个(`playbook/12-ideation.md` 第 7 节最后一条),再读 BRIEF 末尾的 TYPE 块,决定留哪些默认。风格从立意推出来;想参考预设就 `bin/vh style apply `(`bin/vh style list` 挑),副本放进项目的 `style-refs/`,写 STYLE.md 前翻一遍;借了什么在 `DECISIONS.md` 记一行,和它不一样不用解释。立意和风格各写一行理由进 `DECISIONS.md`;改了哪些口味默认,交付时一并列出。 3. **写**:补齐 BRIEF;分镜只写简表(镜头、时长、reads);然后写场景代码。HyperFrames 写完一段,用 `npx hyperframes snapshot --at <秒> --describe false` 看几个关键时刻。 4. **出片**:HyperFrames 先 `export HYPERFRAMES_SKIP_SKILLS=1 DO_NOT_TRACK=1`,再 `npx hyperframes render --quality draft --output out/draft.mp4`;手绘类用 `node render.mjs --clip --out=out/draft.mp4`。 5. **自查一遍**:`bin/vh sheet out/draft.mp4` 看整片联系表,对着 `TASTE_CHECKLIST.md` 的 20 条速查;有字就跑 `bin/vh readcheck`。再看两样(命令见 `playbook/02-verification.md` 的"手机测试"):一张按目标屏缩的联系表(BRIEF 的 `Watch on`:phone、feed 缩到 360 px 宽,desktop 缩到 640),必读字读不读得出,读数、标签别贴着下限;前 2 s 的逐帧 strip,开头是不是第 0 帧就在动、有没有让人停下来的东西。`quick` 没有 reviewer,这两样最容易漏(`docs/research/06-concept-first-ab.md`)。 diff --git a/CHANGELOG.md b/CHANGELOG.md index a1de055..4173111 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ ## Unreleased +**Style presets are references, not templates** +- Why: the maintainer would rather the presets be examples the agent learns from and combines freely ("预设样式只是一些模版参考,让 Agents 自由学习组合并参考") than templates it executes. Before, `--style` copied the preset as `STYLE_PRESET.md`, pasted its prompt block into the BRIEF as instructions and opened the project's STYLE.md with "以风格预设为底…只写改动"; in the research note 06 experiment, the workflow agent that borrowed `ink-wash` logged three taste overrides in its project's DECISIONS.md just to depart from it (the author's local project, not in the repo). +- `bin/vh new --style a,b` and `bin/vh style apply a,b ` attach one or several presets as references: copies in `style-refs//`, a `Style refs (repo presets)` line in the BRIEF, a note at the top of STYLE.md ("只是参考…和它们不一样不用解释"), and one `风格参考` line per preset in DECISIONS.md to fill in with what it lends. Nothing is pasted into the BRIEF; attaching a preset again adds nothing. A project made the old way keeps its preset: `STYLE_PRESET.md` and `style.tokens.json` move to `style-refs//` and it is listed first, while the pasted `## Style preset` block and the "为底" pointer go. Preset names must be lower-case slugs of a preset (no paths, no `_swatch`, no empty list); a missing DECISIONS.md is created from the template. CI covers a comma list in one call, side by side without repeats, the migration, and bad names anywhere in a list. +- Docs: presets leave the list of taste defaults that need an override line, though anything borrowed that touches a non-floor checklist item is still logged as an override (CLAUDE.md; playbook 12's 先说结论 and §6, plus the §4 card and the §7 quick bullet); `recipes/README.md`'s precedence chain counts what is borrowed only once it is in the project's STYLE.md; the quick card, playbook 01's stage 2, the concept card's 画面 line, `styles/README.md`'s how-to (references, mixing allowed, the textures caution kept as advice), the template's prompt-block note and both READMEs ("Borrow from one", `--style `) say "reference"; the quick card says to look through `style-refs/` before writing STYLE.md. + **Spec up front: where it is watched sets the text-size floor; 4K is a render setting** - Why: research note 06 left open whether the 44 px floor, written for 1080 wide, should scale for landscape. The maintainer's answer: it depends on where the film is watched, a phone or a computer, and a landscape 4K film on a computer does not need text scaled up in proportion; and the spec (resolution, 4K or 1080p, and so on) should be set at the start, guided or defaulted. - **Where it is watched**: the BRIEF has `Watch on: phone | feed | desktop` (a vertical phone; a landscape film in a phone feed, not rotated; a computer, or a phone turned sideways) and `Resolution: 1080p | 4k`. `bin/vh new` fills both from the type and frame (portrait and square → phone, landscape → desktop, landscape memes → feed, editing → phone; 1080p) and takes `--watch` and `--res` (`4K` and `2160p` are aliases); it refuses `--res 4k` for the hand-drawn engine, which has no 4K output, and targets that contradict the frame (feed for a vertical or square frame, phone for a landscape one). CI covers defaults, flags, the alias and each refusal's message. diff --git a/CLAUDE.md b/CLAUDE.md index df44679..5e98d1b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ 3. **建项目**:运行 `bin/vh new `,它会建好 `projects/<日期>-/`,复制模板,并把该类型的 prompt 块填进 BRIEF(类型的默认做法,立意定了再取舍);手绘类还会复制引擎、装好依赖。其他引擎的初始化方式见 `engines/README.md`。 4. **先想立意,再看案例和参考**:建完项目,先把材料里只属于它的数字、原话、物件列进 NOTES.md 的素材清单,自己想 5–8 个点子;这时先不看 BRIEF 末尾的 TYPE 块、`styles/`、`recipes/` 和案例,免得点子往看过的东西上靠。然后再看下面这些参考,用它们补强,收敛成 2–3 张立意卡(做法见 `playbook/12-ideation.md`,例子见 `cases/oneshot-five.md`)。人已经给了立意,就记进 BRIEF,不再出卡,最多附一个备选。参考:打开类型文档"可参考的案例"和"社区 skill 参考"两节列出的文件;需要看真实代码时读 `references/repos/` 里的源码。本仓库自己做过的片子在 `showcase/`,各带 BRIEF、STORYBOARD、NOTES 和源码,是最直接的样板。分镜时,镜头怎么动、全片节奏怎么排,先查 `recipes/`:按意图和能量筛(`bin/vh recipes list`),把选中的配方 id 写进 STORYBOARD 的"配方"列,写代码前读配方全文。 5. **停下来给人审**:`standard` 和 `studio` 必过下面三道关卡,`quick` 不设关卡;人点名要亲自拍板的事,按"导演模式"另外停,`quick` 也一样。每次停默认做一页决定优先的审阅页(`bin/vh review` 生成本地 HTML,做法见 `playbook/01-pipeline.md` 的"审阅页"),聊天里只发要人定的事和页面路径;只有一两个纯文字的选择时,直接在聊天里问也行。然后**停下来等人回复**,不要自己往下做: - - ① **立意和大纲**:2–3 张彼此拉得开的立意卡,每张写明由它推出的画面(专属风格,或借 `styles/` 的一个预设)和钩子,配一帧画面(`playbook/12-ideation.md` 第 7 节)。选一张卡,立意、风格方向和钩子就一起定了,人可以在回复里换预设或钩子。再附按推荐立意写的 BRIEF、3–7 段大纲、引擎和费用。不要默认只给一种口味; + - ① **立意和大纲**:2–3 张彼此拉得开的立意卡,每张写明由它推出的画面(专属风格,或参考 `styles/` 的预设,可以几个)和钩子,配一帧画面(`playbook/12-ideation.md` 第 7 节)。选一张卡,立意、风格方向和钩子就一起定了,人可以在回复里换预设或钩子。再附按推荐立意写的 BRIEF、3–7 段大纲、引擎和费用。不要默认只给一种口味; - ② **分镜**:按大纲的段落拆页,每页 3–6 镜的关键帧,没把握的镜头标出来,逐镜默认通过。长片再附一版全长灰盒 animatic; - ③ **初版**:draft 成片加联系表,并写出你自己最不满意的 2–3 处。 @@ -36,7 +36,7 @@ | 适合 | 试方向、草稿、随手发 | 大多数正式视频 | 发布片、旗舰内容、会被反复看的片子 | | 人工关卡 | 0 道,直接出片。选 quick 就等于授权跳过关卡,把这一点记进 REVIEW.md;需求有歧义时最多问 1 个问题;人点名要拍板的事照样停(导演模式) | 3 道 | 3 道;关卡 ① 每张立意卡附一段 10–20 s 草图,关卡 ② 附全长 animatic | | 立意 | 自己想 3 个一句话点子,挑 1 个,写一行理由 | 关卡 ① 给 2–3 张立意卡,每张配一帧画面 | 同左,每张配一段 10–20 s 的草图(look-dev) | -| 风格 | 从立意推出来,可以借 `styles/` 的 1 个预设,写明理由 | 写在每张立意卡的"画面"一行(专属,或借一个预设);选卡就一起定了,人可以在回复里换 | 同左;每张卡的草图就是那种风格的小样,借来的预设人想看时在 E0 补小样 | +| 风格 | 从立意推出来,可以参考 `styles/` 的预设,写明借了什么 | 写在每张立意卡的"画面"一行(专属,或借一个预设);选卡就一起定了,人可以在回复里换 | 同左;每张卡的草图就是那种风格的小样,借来的预设人想看时在 E0 补小样 | | 分镜 | 简表:镜头、时长、reads | 完整 STORYBOARD + 分镜预览图 | 同左 + animatic | | 自查 | 整片一张联系表、一张按目标屏缩的联系表、前 2 s 的 strip,20 条清单速查一遍 | 每个场景:联系表、关键动作 strip、局部 crop;20 条清单 | 同左,再加目标屏尺寸测试、循环接缝、无损帧确定性、静默故障扫描 | | 独立评审(打分层) | 不做 | 1 轮:全新上下文的 reviewer 打 8 项分(含立意),修最差的 3 处 | ≥ 3 轮,8 项都 ≥ 8 才出片;达不到就带着分数进关卡 ③ | @@ -61,7 +61,7 @@ `quick` 省掉的是轮数和审阅,不是这些。 -**底线之外都是默认口味**:`TASTE_CHECKLIST.md` 里没标【底线】的条目、BRIEF 的 Motion defaults、类型文档 Prompt 增量块里的语域和节拍、风格预设和配方,都是没有立意时的稳妥做法。立意需要时可以反着来:在写用到它的场景之前,把改了什么、立意为什么需要写在立意卡或 STYLE.md 上,记进 `DECISIONS.md`;人批过的卡上写了的,算人的决定,reviewer 只查有没有做到;之后才加的由 reviewer 判断站不站得住,判了 FAIL 再补的不算(`playbook/12-ideation.md` 第 6 节)。类型文档"禁止"一节也分两种:管事实、许可、可读和隐私的是底线,管长相的(配色、质感、缓动、图表样式)是默认口味。规则是用来防止犯错的,不是用来规定口味的。 +**底线之外都是默认口味**:`TASTE_CHECKLIST.md` 里没标【底线】的条目、BRIEF 的 Motion defaults、类型文档 Prompt 增量块里的语域和节拍、镜头配方,都是没有立意时的稳妥做法。风格预设只是参考:借了什么在 `DECISIONS.md` 记一行,不借、借一半、几个混着借都行,和它不一样不用解释;借来的东西碰到清单里没标【底线】的条目,照口味覆盖记一行。立意需要时可以反着来:在写用到它的场景之前,把改了什么、立意为什么需要写在立意卡或 STYLE.md 上,记进 `DECISIONS.md`;人批过的卡上写了的,算人的决定,reviewer 只查有没有做到;之后才加的由 reviewer 判断站不站得住,判了 FAIL 再补的不算(`playbook/12-ideation.md` 第 6 节)。类型文档"禁止"一节也分两种:管事实、许可、可读和隐私的是底线,管长相的(配色、质感、缓动、图表样式)是默认口味。规则是用来防止犯错的,不是用来规定口味的。 ## 导演模式:谁来拍板 @@ -82,7 +82,7 @@ effort 管 agent 自己查得多细,导演模式管人拍板哪些事,两个 用户要 `quick` 时,不用把上面各步列的文档都读完,照这张卡做: 1. **读**:路由表对应的类型文档,只读"工作流"和"禁止"两节("Prompt 增量块"会贴在 BRIEF 末尾,挑定立意以后再读);再读 `engines/README.md` 里对应引擎的一节,HyperFrames 先看其中的"最小写法"。 -2. **建项目和立意**:`bin/vh new --effort quick`。先写 3 个一句话立意,挑一个(`playbook/12-ideation.md` 第 7 节最后一条),再读 BRIEF 末尾的 TYPE 块,决定留哪些默认。风格从立意推出来,合适的话借一个预设:`bin/vh style apply `(`bin/vh style list` 挑),它的 `STYLE_PRESET.md` 会带进项目,写代码前读一遍。立意和风格各写一行理由进 `DECISIONS.md`;改了哪些口味默认,交付时一并列出。 +2. **建项目和立意**:`bin/vh new --effort quick`。先写 3 个一句话立意,挑一个(`playbook/12-ideation.md` 第 7 节最后一条),再读 BRIEF 末尾的 TYPE 块,决定留哪些默认。风格从立意推出来;想参考预设就 `bin/vh style apply `(`bin/vh style list` 挑),副本放进项目的 `style-refs/`,写 STYLE.md 前翻一遍;借了什么在 `DECISIONS.md` 记一行,和它不一样不用解释。立意和风格各写一行理由进 `DECISIONS.md`;改了哪些口味默认,交付时一并列出。 3. **写**:补齐 BRIEF;分镜只写简表(镜头、时长、reads);然后写场景代码。HyperFrames 写完一段,用 `npx hyperframes snapshot --at <秒> --describe false` 看几个关键时刻。 4. **出片**:HyperFrames 先 `export HYPERFRAMES_SKIP_SKILLS=1 DO_NOT_TRACK=1`,再 `npx hyperframes render --quality draft --output out/draft.mp4`;手绘类用 `node render.mjs --clip --out=out/draft.mp4`。 5. **自查一遍**:`bin/vh sheet out/draft.mp4` 看整片联系表,对着 `TASTE_CHECKLIST.md` 的 20 条速查;有字就跑 `bin/vh readcheck`。再看两样(命令见 `playbook/02-verification.md` 的"手机测试"):一张按目标屏缩的联系表(BRIEF 的 `Watch on`:phone、feed 缩到 360 px 宽,desktop 缩到 640),必读字读不读得出,读数、标签别贴着下限;前 2 s 的逐帧 strip,开头是不是第 0 帧就在动、有没有让人停下来的东西。`quick` 没有 reviewer,这两样最容易漏(`docs/research/06-concept-first-ab.md`)。 diff --git a/README.md b/README.md index 43f7bd2..ad5a3ab 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ The five films below were made by an agent **reading only this repo's docs**. Cl The 29 style samples, all showing the same content
▶ the reel, with sound (42 s) -29 styles, one reel (5-second samples)
The same content in 29 styles learned from famous work.
Start from one:
bin/vh new promo launch-film --style cutout-jazz
bin/vh style list shows all 29; details in styles/README.md
Sound: one score per sample (bin/vh music, mix … profile=swatch) +29 styles, one reel (5-second samples)
The same content in 29 styles learned from famous work.
Borrow from one:
bin/vh new promo launch-film --style cutout-jazz
bin/vh style list shows all 29; details in styles/README.md
Sound: one score per sample (bin/vh music, mix … profile=swatch) @@ -141,7 +141,7 @@ Watch them back to back, each with its own sound, in [`styles/gallery.mp4`](styl ```bash bin/vh style list # see all 29 -bin/vh new promo launch-film --style cutout-jazz # start a project from a style +bin/vh new promo launch-film --style cutout-jazz # attach a style as a reference (several: --style a,b) ``` We learn the *grammar* of these works; we don't copy them. No original characters, logos or shots, and the prompts never say "in the style of" a person. More in [styles/README.md](styles/README.md). @@ -262,7 +262,7 @@ More in [playbook/04-audio.md](playbook/04-audio.md). | Command | What it does | |---|---| | `doctor` / `setup` | Check your setup / install dependencies and fetch references | -| `types` / `new [--style