Skip to content

feat(influence): EP1 落地动效工具三轨改造——paths/three 增强簇 + Lottie 管线 + HyperFrames PoC - #1123

Merged
ThreeFish-AI merged 4 commits into
feature/1.x.xfrom
ThreeFish-AI/video-motion-tooling-research
Sep 5, 2026
Merged

feat(influence): EP1 落地动效工具三轨改造——paths/three 增强簇 + Lottie 管线 + HyperFrames PoC#1123
ThreeFish-AI merged 4 commits into
feature/1.x.xfrom
ThreeFish-AI/video-motion-tooling-research

Conversation

@ThreeFish-AI

Copy link
Copy Markdown
Owner

摘要

#1122 调研报告 §8 的三轨推荐,对 claude-code-explained-video(Harness Engineering EP1)做一次落地改造。frozen 运动层六文件与 4 个兄弟集零改动;全部改造点落在 seeded 档与不受门文件,时序语义零变化。

三轨落地

A 轨 · 增强现役 Remotion 栈

  • evolvePath ×2:P3 兜底弧(FourResults)与 P4 回流弧(SlotsLightUp)从手写 pathLength/strokeDasharray/strokeDashoffset 三元组改为 @remotion/paths evolvePath——落实 skills/06 既载未行的「官方正解」,同一进度曲线逐帧视觉等价
  • 3D 层板harness-stack.tsx 新增 PlateSlab3D(ThreeCanvas + 正交相机 + boxGeometry 棱线描边),P0 开场/P6 收尾五层板换 3D 渲染后端;glow/dim/settle 全部复用既有 hooks 数值,落板/呼吸/缩退每一帧时点零改动;文字留 DOM 层(文字永不进 3D);chip 档与 HarnessBadge 一行不动
  • remotion.config.tssetChromiumOpenGlRenderer('angle')(@remotion/three 无头强制)
  • 依赖 8 条全部 4.0.512 同版钉死零升级@remotion/three@4.0.512 的 remotion peer 精确匹配现役 pin);three@0.185.1 无 install 脚本,allowBuilds 不动

C 轨 · 设计师 Lottie 资产管线

  • LottieEmphasis 包装组件:delayRender 加载 + 结构硬断言(无 fonts/chars、无文本层、无表达式)+ getLottieMetadata 现读时长 + 窗口钳制
  • 手写占位资产 plug-pulse.json(脉冲圈 + 对勾描画,单色 mech,24f@30fps,零表达式)替换 4-C「插头咬合」的 2 帧布尔闪;sidecar README 声明占位身份与替换方式(同名覆盖零代码改动)

B 轨 · HyperFrames 平行管线 PoC(poc-hyperframes/,与 video/ 零交集)

P0 开场四句真实口播 + 五层板落板的 HTML+GSAP 复刻,渲染全链路打通

  • lint 0 error(linter 报错即修复指引)→ snapshot 3 帧确定性抽帧 → render 441 帧/17.8s,beginframe 原子捕获
  • 产物 ffprobe = h264/1920×1080/yuv420p/30fps与现役交付硬化规格逐项一致
  • 重定时往返实证:缩退时点改一处(14s→16s)重渲,日志 totalFrames: 441→501 自动重算——audio-first 的 GSAP 时间线等价物成立
  • 系统 ffmpeg 缺失经两行 shim 复用 Remotion 自带二进制解决(复现命令在 FINDINGS.md);audio-first 通道 A(duration-less 音频探测)待 TTS 可达后补测

骨架治理

skeleton.toml 新增 2 条指纹钉住的 [[drift]]video/package.json structured / video/remotion.config.ts frozen),reason 均写明撤销条件(EP2–5 收敛或本集回退)。

验证

  • tsc --noEmit PASS;verify_skeleton.py --strict 退出码 0(3 条登记全数在案)
  • check_series.py FAIL 0 / WARN 0(291 文件,含新增死链执法)
  • 评审面 video/src/dev/retrofit-gallery.tsx 三帧(f14/f40/f130)目检:双弧线、3D 板顶棱/侧棱、层栈落板-缩退编排、Lottie 脉冲+对勾全部正确
  • pnpm-lock.yaml 零 diff;4 兄弟集零 diff;PoC 产物 mp4 已被 gitignore 排除
  • 待办(不在本轮):TTS 可达后全链回归 + qa_frames --compare A/B 对拍;Cavalry/Jitter 真实导出替换占位资产

🤖 Generated with Claude Code

以现役科普视频管线(Remotion 4.0.512 + frozen 运动层 + audio-first 时序 SSOT)为基线,
全网与 GitHub 全景调研动效建模与 Web 可视化搭建工具:54+9 候选长表、四路深评
(HyperFrames / Motion Canvas+Revideo / Cavalry·Jitter→Lottie / @Remotion 增强簇)、
87 条主张双反驳者核验,产出 A/B/C 三轨推荐(增强现栈 / HyperFrames 平行试点 /
设计师 Lottie 资产管线)、四道击穿门评估框架与 POC 验收清单;
同步 research 索引与 knowledge-map,pipeline README 交叉链接(check_series 全绿)。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
…rames PoC;

A 轨(增强现役栈):P3 兜底弧/P4 回流弧改 @remotion/paths evolvePath(零时序改动,
落实 skills/06 既载未行的官方正解);HarnessStackP0/P6 层板 3D 化(@remotion/three
+ R3F,glow/dim/settle 全部复用既有 hooks 数值,chip 档与 HarnessBadge 不动);
remotion.config 加 gl:angle。C 轨(设计师资产管线):LottieEmphasis 包装组件
(fonts/chars/表达式硬断言 + 时长现读钳制)+ 手工占位资产 plug-pulse 替换 4-C
二帧布尔闪。B 轨(平行管线):poc-hyperframes/ 垂直切片实测——lint/snapshot/
render/重定时往返全通过(441→501 帧自动重算实证),ffmpeg 经 shim 复用 Remotion
自带二进制,结论见 FINDINGS.md。

依赖 7+1 条 4.0.512 同版钉死零升级;skeleton.toml 新增 2 条指纹钉住的 [[drift]];
评审面 video/src/dev/retrofit-gallery.tsx 三帧目检过;verify_skeleton --strict /
check_series / tsc --noEmit 全绿;frozen 运动层与 4 兄弟集零改动。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
…D 读色三处实景缺陷;

全链回归:IndexTTS(8766/MPS)启动 + refs.py 按 sha1 台账重建 me-bright.wav →
音频版本库 167/167 句 1.7s 回收(零重合成)→ 总帧数复算 25164 与成片精确一致 →
全片草渲 → 七幕 --check / --beat-heads / 末 6 句全 FAIL 0;A/B 对拍
(基线=2722929e 同 manifest 硬链接)167 帧仅 p6-08 超 5%(3D 层板,目检归因)。

回归中修掉三处实景缺陷:
① HarnessBadge 五 chip 塌陷重叠(P1–P6 六幕)——共用件带 absolute 使 chip 失去
  内容撑宽;PlateText 改返回 Fragment,平面 Plate 恢复改造前逐字等价的 flex 行;
② Lottie 脉冲定位偏移——按 190+218·cos/sin(-20°) 重算锚定节点 1 (347,67);
③ 3D 板读色脱节——emissive 把点亮层烧成实心橙块压掉文字对比;改 meshBasicMaterial
  恒深底(active 仅掺暖意 #241C1E)+ 正面 lineLoop 描边加权。

教训入 ISSUE-177:A/B 低 meanΔ(0.8–1.0%)与 --check FAIL 0 双双放过小面积严重
缺陷;改跨幕常驻元素须抽非改动幕的帧逐帧目检。P2 唯一 WARN 查明为 16×16 均值
哈希假阳性(实测差异 13.83%≈基线 13.72%)。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI

Copy link
Copy Markdown
Owner Author

全链回归完成(2026-09-05)

TTS(自行启用)

  • IndexTTS 服务启动(8766 / MPS / v2.5)+ refs.py rebuild 按 sha1 台账重建 me-bright.wav(指纹 54b699cce97f 精确匹配)
  • 音频版本库 167/167 句 1.7 秒回收(零重合成)——纯语音 12.95 分钟与已交付成片完全一致;总帧数复算 25164 帧精确相等,逐帧对齐前提成立

全量 QA

  • 七幕 --check FAIL 0(唯一 WARN 查明为 16×16 均值哈希假阳性:p2-07/p2-10 实测差异 13.83% ≈ 基线 13.72%,画面未冻)
  • --beat-heads P0/P4/P6 FAIL 0 · 末 6 句 FAIL 0

A/B 对拍(基线 = 2722929 改造前代码,同 manifest 硬链接)

  • 167 帧同帧号对拍:仅 p6-08 一帧 >5%(13%,3D 层板所在,目检归因通过)其余全部 ≤1%

回归揪出并修复三处实景缺陷(这正是对拍的价值)

  1. HarnessBadge 五 chip 塌陷重叠(P1–P6 六幕)——A/B 低差异(0.8–1.0%)与 --check FAIL 0 双双放过了它;根因是共用文字组件带了 absolute 定位使 chip 失去内容撑宽。教训入 ISSUE-177
  2. Lottie 脉冲定位偏移——按环坐标三角函数重算锚点至「工具执行之前」插口节点
  3. 3D 板读色脱节——emissive 自发光把点亮层烧成实心橙块;改 basic 材质恒深底 + 正面描边线环加权

修复后终版渲染全部复验通过(badge/3D/Lottie 实景逐帧目检 + QA 全绿)。

Cavalry 真实导出替换占位资产:等用户安装 Cavalry 并导出后接入(操作指引已在对话中给出)。

🤖 Generated with Claude Code

本机无 Cavalry/Jitter(安装需 Canva 账号登录、原生 GUI 不可自动化),故不走设计工具
导出,改由脚本按 motion/tokens.ts 的权威数值生成——Lottie 的关键帧切线本就是贝塞尔
控制点,M3 三条曲线可逐字写进 i/o 字段,使资产与全片 16 个动效模型**逐帧同源**,
而非事后目测对齐(设计工具导出的曲线是现场手拉的,反需按 tokens 回校)。

三层编排,时长全部落 DUR 令牌:
  外环 26→132% 扩散  f6=21f  decelerate
  内环 f2=3f 错峰起跳、f5=12f 回响  decelerate
  对勾 trim path 描画 f3→f3+f5  standard
       + 收束过冲 109.5% 落回 f4——取 SPRING.snap 的 ζ=0.6 经 overshootPeak
       算得,与 P4「插头咬合」useSpring('snap') 同源同公式(motion.test.ts 钉死)
  整体末 f3 淡出  accelerate(EXIT_FACTOR 出场快于入场)

生成脚本 gen_plug_pulse.py 随资产入库(自锚定路径可就地重跑,sha1 幂等已验),
资产即成为可复算产物而非不可追溯的二进制。sidecar 如实标注「脚本生成、非设计
工具导出」并说明同名覆盖即可替换。

验证:四条断言全过(无 fonts/chars/文本层/表达式)+ 单色 #64C4C0 三层一致 +
96×96/30fps/24f 契约;全片重渲 350s 无 cancelRender;七幕 --check FAIL 0、
P4 beat-heads FAIL 0、末 6 句 FAIL 0;A/B 对拍 167 帧仅 p6-08(3D 层板)超阈值。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI
ThreeFish-AI merged commit 44ee713 into feature/1.x.x Sep 5, 2026
1 check passed
ThreeFish-AI added a commit that referenced this pull request Sep 6, 2026
* fix(influence): 修正 EP1 口播三处官方口径偏差并补录轨 C 官方信源台账;

对照 Anthropic 官方文档原文逐条复核《执行层》全部官方断言(取数 2026-09-06),
修正三处、补齐一个系统性缺口。

内容修正(3 句,字数 3979 → 3989):
- p0-06 第五样勘误:「护栏」→「把这些串起来的循环」。官方 glossary 原文是
  "the loop that chains actions together"。这不是口径偏差——本集整整 14 分钟
  讲的就是那个循环,P0 命名帧却把它从官方定义里漏掉。改对后叙事反而收紧:
  P0 埋下「循环」、P1 第一句直接接上。与 p5-05 的四件套不冲突(两个官方来源,
  交集恰好是「循环」)。
- p4-23 改抗漂移口径:「三十一个」→「三十多个,官方文档还在往上加」。官方
  hooks 事件表实测已从 31 漂移到 33;该数属活数据,踩本集禁用清单第 1、2 条。
  绝对数降入画面角标并带取数日期。
- p6-06 取数日期同步为 2026 年 9 月。

信源台账(根因修复):
Harness Engineering 改造引入的六个官方锚点此前一条都不在 sources.toml 里,
导致「写错了没有事实源能拦、写对了也会随官方更新悄悄陈旧」。现补录
cc-glossary / cc-how-it-works / cc-hooks / cc-permissions / cc-auto-mode /
cc-harness-blog,verify 受检面 12 → 18 条 FAIL 0;source-notes 新增
「轨 C · 官方文档」与 §十 官方断言表(12 条逐条附原文)。
补录前 verify 报「受检 12 · FAIL 0」全绿——门是绿的,只因为出问题的六页
不在受检集里。

分镜同步:0-C 第五辐条、4-F 计数 31→33、4-C/5-D 的 3D 画面描述。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>

* feat(influence): EP1 3D 表意强化——solids-3d 原语层 + 5-D「壳」与 4-C「插座插头」;

3D 能力(PR #1123 引入)此前只用在 P0/P6 的系列身份层板上,全片 39 个 beat 里
37 个没有 3D——能力已具备而未用于表意。本轮挑两处「平面表达不出来」的落点。

新增 video/src/components/solids-3d.tsx(seeded 档,零 motion hook,运动量全部
prop 注入),三条宪法写进文件头:
- 只做直角体不做圆/环/曲面——画面里的「圆」已被 LoopRing 独占,它是「循环始终
  不变」被看见的唯一载体;副产品是元素词表被钉死在已跑通的那一组,零新类型面。
- 读感来自转物体不来自动相机——正交 zoom:1 的等距映射是 domToWorld 存在的前提,
  相机零动画同时白送无头渲染确定性。
- 颜色永不是「光 × 材质」的运行时乘积——零光源、只用 unlit 材质,明暗靠手写
  面色梯度(ISSUE-177 教训二的结构化)。ISSUE-177 教训一写进类型:Stage3D 的
  style 在类型上 Omit 掉定位属性,实体原语一律返回 group 不返回 DOM。

5-D「壳」:p5-17 是全片唯一把整套结构命名为三维实体名词的句子,而原实现只是
一个 3px 边框 div(读作「框」)。框与壳的差别是维度差——观众要读出「终端在壳
里面」,需要看见壳壁的内表面。改为四层实心板嵌套,层序即 z 序(循环最内、插口
最外),终端沉在井底,「挂在外面」成为几何事实。

4-C「插座插头」:插座的定义就是一个凹进去的洞,而原 22×22 方框只是画在墙上的
符号,「插入」这个动作在平面上根本不存在。3D 咬合时插头侧棱被口沿吃掉的遮挡,
是「它真的进去了」的唯一无歧义信号。只做四个插口中的第一个(口播说的是「一张
卡片插入」,四个全做反会把另三个读成空洞)。

PlateSlab3D 收敛到 Slab3D:同帧 PNG md5 逐字节相同;顺带删除对 basic 材质是
空操作的 ambientLight。收敛边界画在「画布之内、group 之内」——刻意不让它改用
Stage3D,因为它的画布带着两个只对它成立的假设(ISSUE-177 教训一会重演)。

时序零改动:四层合拢开在既有 26 帧 shell 进度的子窗口(frozen win())、插头直接
吃既有 useSpring('snap'),无新 hook、无新 @动词、总帧数由 manifest 结构性推导。
Plug3D 内部对 seat 取 min(seat,1):snap 的 ζ=0.6 峰值 1.095,不钳制会穿透井底;
过冲转为棱线提亮不丢手感。

5-B 体积柱评估后不做(决策入注释):试做发现侧板必然遮挡章名标签与 20–28 实测带
——带是仪器、柱是被测物,遮住仪器等于丢掉这幕的判据;且「一根芯贯穿四柱」本身
要否决,四柱是四个版本的独立实测,连续芯等于断言「同一段代码的四次采样」。

P0-C 第五辐条随内容勘误改为「循环」并染 core 色,成为 P1 环诞生的视觉引信;
retrofit-gallery 新增 housing close 三态与 socket seat 四态(含过冲峰 1.095 的
穿底判据)两格。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>

* docs(influence): 沉淀 3D 实现规格与四条缺陷经验,更新 EP1 交付台账;

skills/06 新增「3D 点缀(@remotion/three)」节:此前该文件 three/3D/angle 三个
关键词零命中——3D 已在 EP1 用了一轮却从未沉淀为跨集规格,EP2–5 跟进时无据可依。
现补齐三条宪法、读色契约(含「面要被看见必须与 bg 拉开」「多层嵌套必须关 edges」
两条实景结论)、构造经验(实心板嵌套而非边框拼框、弹簧过冲要钳行程、一 beat 一
画布、z 层级属调用点契约)与验收方式(收敛以逐字节相同为门、3D 是 --check 盲区
必须逐帧目视)。

issue.md 补四条:
- ISSUE-178 口播断言在事实源里没有锚点也能进成片——真实性纪律写在散文里,没有
  任何门在执行。附带教训:「门是绿的」不等于「查过了」,先问它在看什么。
- ISSUE-179 静态口径写死的官方数字会周期性陈旧(31 → 33)。判断是不是活数据,
  不看它此刻是否精确,而看它未来会不会变;结构性表述比枚举计数稳定得多。
- ISSUE-180 3D 化「壳/井」用四条边框拼会读成一堆细线框——面色与 bg 同色时 3D
  只剩棱线。三轮实景抽帧才定位。
- ISSUE-181 两个渲染进程并发写同一 mp4 → 索引损坏、抽帧 seek 全落回第 0 帧,
  伪造出 52 条 WARN。与 ISSUE-177 互补:那条说「低差异不等于无回归」(判据不
  敏感),这条说「高 WARN 也未必是真回归」(输入已损坏);异常 WARN 集中在未改动
  的幕、而改动的幕反而干净,这个分布本身就是产物损坏的信号。

EP1 README 更新交付台账:终渲 13:59.90(25197 帧,较前版 +1.10 秒)· 42.2 MB ·
终渲全分辨率复检 FAIL 0 WARN 0(草渲期唯一的哈希 WARN 在全分辨率下消失,佐证
其为假阳性)· beat-heads 39 镜 ×4 帧 FAIL 0。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>

* fix(influence): 修复 EP1 3D 评审五项——5-D 层序反转、壳画布裁切与三处死契约;

评审对 3D 表意强化提出五条,逐条修复并以实机抽帧自证。

## 1. 5-D 四层壳的层序被渲染反了(成片缺陷)

`depth = SHELL_RIMS.length - 1 - i` 与数组声明的「自内向外」相反,i=0(循环)
拿到 depth=3 ⇒ 尺寸最大、面色最暗、棱线最淡。抽帧 frame 23510 实证:由内向外
是 插口(mech)/闸门(deny)/分发表(mech)/循环(core),与 storyboard、README、组件
文档块三处「循环最内、插口最外」全部相反——口播此刻正说「留了插口的壳」。

根因是「里面」由 z、尺寸、色阶三个量共同表达,而只有 z 被对齐;正交投影下 z 只
体现为极小的遮挡差,真正决定读法的是尺寸。改 `depth = i` 后三项同向自洽。
`dev/retrofit-gallery.tsx` 的 HousingCell 手抄了同一段反转逻辑,故一并修正——
评审面复制被评审的逻辑,就验不出自己复制来的错误。

## 2. 壳画布余量漏算合拢期的 z 后推量

原 `+60` 对称余量既误用 `SHELL_DEPTH`(26) 当外扩量、又完全没计入
`-(1-close)*180` 的后推量。以 `THREE.Euler('XYZ',−12°,8°)` 投影最外层八角实测:
需 W≥1397 / H≥751,实际只有 1394×674 ⇒ 合拢初期最外层底缘被画布下沿在 y=876
直切 635px(frame 23502 实证)。改为 `SHELL_PAD_X=66` / `SHELL_PAD_Y=142`,
并把 `3` 换成 `SHELL_RIMS.length - 1`、`180` 提为 `SHELL_PUSH_IN`。
安全带复核:最外层底缘 close=0 落 915.5、close=1 落 878.4,均 < SAFE_TOP_Y 920。

## 3. `Socket3D` 的 `skin.face` 是空操作

井底恒 `theme.bg`、井壁恒 `SOCKET_WALL`,`face` 从未被读取,但两个调用点都传了
`face: theme.panel`。类型收窄为 `Omit<SolidSkin, 'face'>`,由编译器拦住这类
「看起来在设色、实际没有效果」的调用。4-C 帧 17392 修前后逐像素相同。

## 4. 删除 5-B 那批无消费者的 3D 导出

`Bar3D` / `BAR_SIDE` / `BAR_YAW` / `domToWorld` / `SHELL_INNER` 全仓零调用,而
同一轮已在 `GrowthBars` 注释里明确「本幕评估后不做 3D」。它们带着文件里最长的
规格注释,易被误读为现行口径;相关结论已公共化在 skills/06。原语层 356 → 298 行。

## 5. 4-C 锚点注释是上一版残留

注释写「节点 1(ang=-20°)」而代码是 `i === 0`(ang=-60°),且引用了不存在的
`SocketPlug` 符号。

## 验证

- `tsc --noEmit` 通过;`node --test scripts/motion.test.ts` fail 0
- 全分辨率抽帧 f17392 / f23502 / f23510 / f23525 + retrofit-gallery f40 目视复检
- 数值复检:画布四边(col 258–260 / 1658–1660、row 915–918)零硬切edge
- ⚠️ `out/final.mp4` 的 5-D 段已过期,需重渲后重跑 QA

经验沉淀入 ISSUE-182(判据要落在成片像素上而非某个中间量;评审面不可手抄被评审
的逻辑;3D 画布余量必须按投影算而非按几何尺寸算)。

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant