Communitygithub.com

josueh04/product-video-skills

确保 HyperFrames 并行渲染工作线程不会丢失、闪烁或抖动元素的动画规则,以及一个静态检查工具(lint_motion.py),在视频模板开始渲染之前找出其中的违规行为。

product-video-skills 是什么?

该技能提供了一套完整的动画安全规则和静态检查工具,专门用于解决 HyperFrames 并行渲染引擎中的帧丢失、闪烁或抖动问题。HyperFrames 的渲染器并非按顺序播放时间线,而是通过三个并行工作线程分别处理每第三帧,并通过“后退 1 毫秒再前进”的方式定位帧。这意味着每一帧必须是一个关于时间的纯函数,任何依赖于之前渲染状态、时钟或随机性的操作都会导致不同工作线程渲染结果不一致,从而产生元素在第 3 帧缺失的 Bug。该技能在 Studio 预览中完全不可见,仅在最终 MP4 渲染中暴露。 核心工具是 `lint_motion.py` 静态检查脚本,它通过读取视频模板的 HTML、TPL 和 JS 文件,识别出 12 类违反安全规则的模式。这些规则涵盖了 GSAP 动画从 `fromTo` 的键值对应、`immediateRender` 的使用、禁止动画 `display/visibility`、禁止使用 `Date/performance.now/Math.random` 等非确定性操作,以及注册单一暂停时间线等关键点。技能还会指出哪些检查是静态检查可以自动发现的,哪些(如时间重叠的补间)需要开发者手动确认。 除了检查,技能还提供了在渲染前重现 Bug 的精确方法:使用 `snapshot` 命令对比同一时间点的两次快照,如果图像不一致则说明该补间存在跨工作线程状态差异。同时引用 `scan_render.py` 的“WORKER PATTERN”报告模式来确认最终的渲染问题。此技能适用于 Cursor、Codex 和 Claude Code 等 AI 辅助开发环境,帮助开发者编写安全的 GSAP 动画代码,避免代价高昂的渲染重试。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/seek-safe-motion

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

安全定位运动(Seek-safe motion)

HyperFrames 并非按顺序播放时间线,而是通过“定位”方式工作:对于每一帧,渲染器将时间线设置到该帧对应的时间点,并捕获页面内容。在 HyperFrames 0.8.x 版本中,这一过程由三个并行工作线程完成,每个线程处理每第三帧,并且每次定位都会先退回 1 毫秒再前进,以确保稳定。因此,每一帧必须是一个关于其时间的纯函数。任何依赖于先前渲染状态、系统时钟或随机性的操作,都会导致不同工作线程渲染出不同的结果,其表现为某些元素在每第三帧缺失。

这个 Bug 在 Studio 预览(按顺序播放)和单张快照中是看不见的。在创建本技能的生产环境中,这是唯一一个能传递到审阅者手中的缺陷:开场标题“连续七秒出现卡顿和闪烁”。

先进行静态检查

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" <video_dir>/video

该脚本会读取 index.html、src/*.tpl 以及它们旁边的 *.js 文件(仅内联脚本),输出 file:line: severity RULE: why 格式的错误信息及修复建议,并在发现任何错误时以退出码 1 终止(使用 --strict 标志可让警告也导致失败,--json 标志则以 JSON 格式输出供工具使用)。每次编辑时间线后以及每次渲染前都应运行它。这是静态检查:它无法识别在运行时计算的变量(将其视为“不可检查”),也无法检测时间上重叠的两个补间。这些情况仍需开发者依靠下面的复现方法来处理。qa.py(渲染质量检查)也会自动运行该检查,并在发现错误时使报告失败。

规则及存在理由

  1. 每个 fromTo 的 fromVars 中的每一个键也必须在 toVars 中出现(SS001,错误)。当工作线程的某一帧恰好落在补间开始时,1 毫秒的回退会将补间恢复到其开始之前的状态,此时仅存在于 fromVars 中的键将永远不会被再次写入。之前的标题补间是 fromTo(sel, {yPercent: 110, opacity: 1}, {yPercent: 0}):opacity: 1 仅存在于 fromVars 中,导致一个工作线程在整个补间期间都将标题的透明度保持在 0。应写为 {yPercent: 110, opacity: 1} 到 {yPercent: 0, opacity: 1},或者使用 tl.set() 后跟 tl.to()。同样的规则也适用于 to() 内部的 startAt(SS002)。
  2. 每个时间点 0 之后的 fromTo 都必须设置 immediateRender: false(SS003,警告)。否则,补间会在时间线创建时立即写入其起始值,覆盖之前补间设置的值,导致定位到时间线中间时从错误的状态开始。
  3. 优先使用 fromTo 而非 from(SS004,警告)。from() 的结束状态取决于元素在构建时的状态;一旦较早的补间修改了该元素,不同工作线程对该结束状态的判断就会不一致。
  4. 绝不动画 display 或 visibility 属性(SS005,错误)。这两个属性无法进行插值;它们会在补间的某个随机点突然翻转。应使用零持续时间的 tl.set() 在明确的时间点更改它们,并使用 opacity 或 autoAlpha 实现淡入淡出效果。
  5. 不使用时钟、随机数或定时器(SS006,错误):对于任何可见元素,禁止使用 Date、performance.now()、Math.random()、setTimeout、setInterval 或 requestAnimationFrame。打字抖动或波形效果应使用种子随机数生成器;屏幕上显示的调用计时器应通过时间线内部的 onUpdate 回调中的 tl.time() 计算得到。
  6. 一个暂停的时间线,注册到全局对象,永不播放(SS007、SS011、SS012)。使用 gsap.timeline({ paused: true }) 创建时间线,完全构建它(当位置依赖文本度量时,应在 document.fonts.ready 内部构建),然后才赋值 window.__timelines["<composition id>"] = tl。在构建完成前注册空时间线会导致空白视频;tl.play() 会与渲染器的定位过程冲突。
  7. 滚动效果应使用 fromTo 并显式指定起始和结束位置,以确保每个工作线程计算出相同的偏移量,并且偏移量应限制在真实内容范围内,避免任何线条或图标在边界处被截断。
  8. 绝不同时存在两个补间操控同一元素的同一属性。 如果某个光标重置操作落入了下一次移动的时间范围内,定位后指针将停留在错误的位置。此规则不通过静态检查检测:需要检查构建时的时序表。
  9. 动画变换属性,而不是布局属性(SS009,警告):使用 x、y、scale、clip-path 替代 left、top、width、margin。布局补间会在每一帧触发回流,并且 hyperframes check 会将其标记为 gsap_non_transform_motion。如果某个真实产品控件(如侧边栏展开)的短暂宽度变化能够准确复现产品行为,则可以接受。
  10. 绝不动画 .clip 元素内的内容(SS010,错误)。HyperFrames 通过 data-start 和 data-duration 属性拥有对 clip 可见性的控制权;应动画该 clip 内部的一个包装元素。
  11. 有限次重复(SS008,警告)。repeat: -1 仅允许在有限的根元素 data-duration 下使用;应通过 Math.max(0, Math.floor(span / period) - 1) 计算重复次数。
  12. 在时间点 0 显式设置每个初始状态。 一个执行 gsap.set(sel, vars) 的辅助函数也应执行 tl.set(sel, vars, 0),这样当定位回 0 时,能恢复第一帧的状态,而不是保留工作线程渲染的最后一帧的状态。

在渲染前复现可疑 Bug

静态检查可以识别模式;快照则能够证明像素级差异。对于从 t0 开始的怀疑有问题的补间:

npx --yes hyperframes@<pinned> snapshot . --at <t0 + 0.3> --no-end --describe false -o a
npx --yes hyperframes@<pinned> snapshot . --at <t0>,<t0 + 0.3> --no-end --describe false -o b

t0 + 0.3 时刻的帧在 a 和 b 中必须完全一样。如果不同,说明通过补间起始点的定位操作改变了状态。要精确重现单个工作线程的行为,可以按顺序对 0, 3, 6, ... 帧执行快照,一直持续到超过补间结束位置。通过不断将时间范围减半进行二分法查找,直到定位出唯一一个问题补间。渲染后,scan_render.py(渲染质量检查)会将同样的 Bug 报告为 WORKER PATTERN 运行:异常帧全部共享同一个帧索引模 3 的余数。

参考资料

  • references/patterns.md:每个规则的前后代码示例、保持模板安全的辅助函数(lineIn、init、打字效果、滚动效果、光点击等),以及静态检查能发现和不能发现的内容。在编写新辅助函数或修复静态检查发现的问题时,请阅读此文件。

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

josueh04/product-video-skills

Write a product video's narration and turn it into voice clips with word timings, pronunciation fixes, sound effects and even loudness. The script becomes a table of moments and then audio/lines.tsv (one clip per sentence, with role and speed columns); tts.py voices it with ElevenLabs or the free macOS say voice, maps brand respellings back to the on-screen spelling, normalizes every clip and writes audio/timings.json for the composer; make_sfx.py builds typing tracks from real keystrokes and places recorded click and pop sounds. Use it whenever a video needs a script, narration, voice-over, lines.tsv, timings.json, TTS, a new take, a voice or casting choice, a pronunciation fix ("it says the name wrong"), a changed sentence, a tone note ("too hype", "sounds cut off"), audio levels, a click at the end of a clip, typing or click sounds, or when the build stage asks for the voice. Also use it for silent loops, which still need a moment table and SFX.

josueh04/product-video-skills

Pin a product's source code (read-only exports in sources/ plus sources.lock), confirm that the pinned commit is what runs in production, and map every screen of a video brief to its route, components, i18n strings and state, written to the video's SOURCES.md. Use it whenever a video needs to know where a screen lives in the code, when sources/ is missing or stale, before ui-spec-from-code or product-truth start on a video, after the product's frontend changed ("what changed", "which videos are affected", "refresh the sources", "is this checkout current", "which commit is in prod"), and when there is no code and you need an inventory of the no-code references (recordings, recovered captures, docs) a screen can be rebuilt from.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Gather pixel references for UI that the code cannot show, or to check a rebuild against the real thing, using frames and timed OCR text from screen recordings, captures recovered from past Claude Code session transcripts, a local instance of the app built like production, and web research for third-party apps, plus side-by-side parity images and contact sheets. Use it whenever someone hands over a screen recording (.mov or .mp4) of the product, when a screen has no usable source code (a stale checkout, another company's UI such as a sign-in page, calendar or CRM, runtime output from a backend not in the repos), when asked "what does it really look like", "match the recording", "how long does that animation take in the app", "compare our render to the real app", or when screenshots from an earlier session might already exist. Never uses the reviewer's personal browser.

josueh04/product-video-skills

Turn a product's real frontend code into 1:1 rebuild specs for a video, one read-only subagent per screen, each returning static HTML, CSS with every variable resolved to its literal value and cited (role/path:line@sha), every state, transitions with exact durations and easings, icons from the code's own icon sets, and the exact i18n strings; plus resolve_tokens.py to write the product's design tokens to kit/tokens.css. Use it whenever a screen of the product has to appear in a video, when writing or fixing video/src/app.css or the template markup, when someone asks for exact sizes, colors, fonts, paddings, animations or icons of a screen, when a rebuilt screen "looks off" next to the real app, and when the design tokens or theme of a product need extracting. Framework adapters cover Angular with PrimeNG (proven), React, Vue, Tailwind and plain HTML (unproven).

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

相关技能