1实现原理 · 为什么它能做到
定位是网关（GATEWAY）：编任何 HyperFrames 动画前先读它——它决定每个接缝发生什么、每个场景如何表演，技法 skill 负责实现；且这些规则优先于通用/上游的运动指导。它要防的失败是「各场景独立创作」——眼睛的动量在每个切点死掉，场景在入场与退场之间原地抖动。
Read this before composing any animation. It decides WHAT happens at every seam and how every scene performs; the technique skills implement it. These rules supersede generic / upstream motion guidance. The failure this prevents: scenes authored in isolation — the eye's momentum dies at every cut, and scenes wobble in place between entry and exit.
路由表把「决策」与「实现」分离：接缝选型/参数/代码 → cut-the-curve §1–5；文字入场级联 → §6；组重定位 → §7；光标动作/场景开场/形变点火 → oversized-cursor；接缝渲染机制/白闪守卫 → seam-craft；产品发布/解说/字幕 → 在上游 skill 之上叠 text-beat-economics / brand-faithful / captions-overlay。
| Cursor-led action / scene kickoff / morph ignition | `oversized-cursor` | | Seam render mechanics / white-flash guard | `seam-craft` |
规定了固定创作顺序：先写向量账本 ledger.json → 用它 STAMP 出主接缝（seam-stamp.mjs --write index.html）→ 按阶段选一条持续运动路线 → 定载体与起因 → 构建 comps → 用 seam-gate.mjs 验证；只有 Tier-A 的形变/匹配切需要手写，盖章出来的接缝按构造即过闸。
Authoring order: **vector ledger (`ledger.json`) → STAMP the master seams from it (`scripts/seam-stamp.mjs --ledger ledger.json --write index.html`) → sustained-motion route per phase → carriers and causes → build comps → VERIFY (`scripts/seam-gate.mjs`).** Hand-author only Tier-A morphs/match-cuts; stamped seams pass the gate by construction.
向量律四条：① 轴不换（x 归 x、y 归 y、Z 归 Z）；② 方向不镜像——Z 轴的方向是缩放变化的**符号**（变大=推进/镜头前移，变小=拉远/镜头后退），「缩短的出场配从小长大的入场」是最常见违例，因为 grow-from-small 正是元素的默认入场；③ 速度匹配；④ 相位——切点两侧都在运动中，切前停稳或切后从静止起步都是死拍。
2. **Direction** — never mirror. On Z, direction = the SIGN of scale change: growing = push (camera forward), shrinking = pull (camera back).
速度匹配的力学被写进律里：入场初速 ≈ 出场末速，用镜像 ease（出场 power4.in + 入场 power4.out，同距离同时长，入场在设想路径 ≥50% 处接上），具体力学在 cut-the-curve。
3. **Speed** — entry initial velocity ≈ exit final velocity, via mirrored eases (exit `power4.in` + entry `power4.out`, same distance and duration; the incoming side picks up ≥50% through the notional path). Mechanics in `cut-the-curve`.
电流（The Current）：每部片只选一个主导方向（房屋默认 LEFT），所有普通接缝都走它；其他向量是被保留的，动用即表态——向上=抬升（结论/揭示升到更高处）、Z 正向=向同一思路更深处推进、Z 反向=抵达（更大的东西落地）、缩放爆发=离开一个世界。禁止连续反向接缝（乒乓读作错误），方向改变必须有可见起因（点击/弹跳/撞击）或章节边界。
Every film picks ONE dominant direction (house default: LEFT). Every ordinary seam uses it. Other vectors are RESERVED — spending one means something:
向量账本（Vector Ledger）必须在动手写主时间线之前落成项目根目录的 ledger.json，每个接缝一行：切点时间、出场与入场向量（轴+带符号方向，Z 行带缩放符号）、选择器、技法；出入口必须匹配，行不匹配要修计划而不是修 easing；验证器先做静态行一致性检查再做运行时采样。
Write it before authoring any master timeline — as **`ledger.json` at the project root** (schema: `references/seam-gate.md`). One row per seam: cut time, exit and entry vectors (axis + signed direction; Z rows carry the scale sign), selectors, technique. Exit and entry must match; if a row mismatches, fix the plan, not the easing.
载体（Carriers）与因果运动（Causal Motion）：眼睛跟着物体而不是抽象；最强的接缝会把一个具体载体以匹配的位置与速度递过切点（路径中的光标、缩进/停靠进下一布局的容器、飞进精确槽位的标记、瀑布切里的词群）；没有天然载体就让场景主角承担；且绝不用 crossfade——它根本没有载体。运动要成链（点击→挤压→释放回弹→飞出→撞击→回弹→揭示），效果必须在起因那一帧开始，反应按隐含质量缩放，力是改变方向的许可证。
The eye follows objects, not abstractions. The strongest seams hand a concrete carrier across the cut at matched position AND velocity: a cursor mid-path, a container that shrinks/docks into the next layout, a mark that flies into its exact slot, the word group of a waterfall cut.
Seam Gate 是构建闸门：先生成（seam-stamp.mjs --ledger ledger.json --write index.html）再验证（seam-gate.mjs verify --ledger ledger.json --project .），「exit 0 或这个接缝不算完成」；检查项包括账本行一致、出场在切点仍在动、入场在半途（绝不从静止起）、实测方向=账本方向、出入场速度匹配（WARN）、零重叠（每帧只有一侧可见——切不是叠化）、Z 符号规则（两侧 d(scale)/dt 同号，并扫描入场场景自身入场是否符号打架）、载体矩形连续性（计入祖先缩放）。
node <SKILL_DIR>/scripts/seam-stamp.mjs --ledger ledger.json --write index.html # generate node <SKILL_DIR>/scripts/seam-gate.mjs verify --ledger ledger.json --project . # verify
脚本查不了的仍归作者：① 任何对场景首/末 ~1s 的改动（含为适配新旁白重新配时）都会作废该边界的审计，必须重跑验证器；② 音频是时钟——场景要按旁白真实词时间戳重新配时，绝不能为塞进槽位而赶读，旁白重生成会重开它的接缝；③ clip 门控陷阱（零重叠 FAIL 的常见死因）——data-start 早于入场 tween 的 clip 会在初始不透明度上被解除隐藏，必须同时设 autoAlpha: 0 且 data-start 恰好等于切点时间。
3. **Clip-gating gotcha** (the usual cause of a zero-overlap FAIL): a clip whose `data-start` precedes its entry tween is un-hidden at its initial opacity — set initial `autoAlpha: 0` AND `data-start` = the cut time, never earlier.
第二部分是「表演」：禁止用空闲正弦循环（breathe/float/drift/glow pulse）充当持续运动——它们读作「视频在等」；入场结束后还剩几秒没人管是规划 bug，应加故事而不是加抖动。入场到退场之间的每个阶段必须由五条路线之一领管并在计划中命名（分阶段揭示 / 有意图的镜头 / 有序列的 UI 生命 / 动画序列 / 光标主导动作）；自检句：任一秒暂停，必须有有意义的东西正在半途。
Idle sine loops (breathe, float, drift, glow pulse) are BANNED as sustained motion — they read as "the video is waiting." A scene that finishes entering with seconds left is a planning bug: add story, not wobble.
高潮前的静止（stillness before climax）与配时意图：主要动作与其结果之间安排 0.3–0.75s 停顿（戏剧逗号），动作直连结果会丢掉它；单元素入场 ≤ ~800ms（更长铺垫要用多元素错峰，而不是一个元素慢慢入场）；出场 ≈ 入场的 75%（例外：cut-the-curve 反过来，入场约为出场的 127%）；总错峰 ≤ 500ms，8+ 元素时收紧单项延迟；禁用 ease bounce.out / elastic.out（入场过冲 back.out(1.4–1.7) 可用）；相似元素共用一个 ease+时长意图，绝不逐元素各配一套。
Schedule a **0.3–0.75s pause** between the major action and its result — the dramatic comma. A scene that jumps straight from action to result loses it.
转场词汇表有预算：每片只用 2–3 个场景间转场并重复使用，默认边界是「沿电流方向的 cut-the-curve」；手写的共享元素形变（intent: morph）不占这个预算。
Use only 2–3 inter-scene transitions per film and repeat them; the default boundary is **cut-the-curve in the current's direction**.
反模式表把上述禁令汇编成 11 条对照（孤立写入场→先写账本；场景间 crossfade→沿电流的 cut-the-curve；出场完成后再换场→两侧中段切；切后从静止入场→在设想路径 ≥50% 处进入；Z 符号打架→按 Seam Gate 7 匹配符号；入场场景自己的 pop-in→保持开场帧已构图或匹配符号；空闲抖动填充时间→指派持续运动路线或加故事；无起因的方向翻转→花掉一个力；把保留向量当变化用→默认走电流；反应晚于起因几帧→同帧点火；动作直连结果→安排高潮前静止）。
| Inverse-zoom exit → grow-from-small entry (or push → oversized retraction) | Match the scale-velocity sign (Seam Gate 7) |
2核心能力
3外部依赖
| 类型 | 依赖 |
|---|---|
| cli | hyperframes CLI（preview 子命令；seam-gate 优先用仓库内 packages/cli/bin/hyperframes.mjs，skill 被复制出仓时才回退 npx --yes hyperframes） |
| package | chrome-headless-shell（经原始 CDP 驱动做帧采样；自动探测 CHROME_PATH → ~/.cache/puppeteer → 系统 Chrome） |
| network | 本地预览服务 HTTP 接口（仅 localhost：/api/projects 与 comp 预览页；非外网） |
| package | 兄弟 skill 依赖（被指名路由）：cut-the-curve、oversized-cursor、seam-craft，以及上游的 text-beat-economics / brand-faithful / captions-overlay |
| package | node ≥ 22（脚本头注明零 npm 依赖，仅用 node 内置模块 + 本机 Chrome） |
4风险提醒 风险提醒：蓝色 · 知晓即可
- 它是网关，不读它的代理不会被拦 — 所有约束（向量律、禁 idle wobble、禁 crossfade、配时意图）都靠「先读这份文档」生效；仓库内没有 lint 强制加载或检查场景级表演（seam-gate 只查接缝）。
- seam-gate 需要本地 Chrome 与可用的预览服务，环境不满足时无降级 — 验证依赖 chrome-headless-shell（CHROME_PATH 或 ~/.cache/puppeteer）与 --project 起服务；缺 Chrome 时脚本失败，闸门形同不存在（SKILL.md 未给无 Chrome 的降级路径）。
- seam-stamp 会改写 index.html — `--write` 直接在用户项目文件上做定点替换；虽被 <seams:auto> 标记限定且可逆，但若项目里手工改过该块，重跑会覆盖手工改动（文档亦声明该块 do not hand-edit）。
- 速度匹配只报警（WARN）不算失败 — references 明确 speed-match 是 WARN；「切点处速度不等」这一最影响观感的项不会让闸门以非零码退出，容易被忽略。
- `--server-cmd` 是可替换的 shell 命令字符串 — 默认值安全（仓库 CLI 或 npx），但该参数允许调用方传入任意命令交给 `sh -c` 执行；若上游有把外部输入拼进该参数的调用点，则构成命令注入（本目录内未见此类调用，故不升档，仅提示）。
- 阈值与平台的隐含前提 — 验证器默认 --fps 30、按 getBoundingClientRect 测速；不同帧率或极端布局下容差（15px/s、12px、5%）可能偏松/偏紧，文档未给按项目调参的指引。
5第二遍独立确认
- [ok] 是否存在被忽略的第三方数据外发（判蓝的关键反证点） — 对两脚本做 https?:// 全扫：seam-gate.mjs 命中 2 处，均为 `http://localhost:...`（注释示例与端口拼接）；seam-stamp.mjs 零命中。fetch 仅 2 处（httpOk 探活、/api/projects 取项目 id），目标都是 localhost。未发现任何远端域名、遥测、上报或 CDN 请求。判蓝成立。
- [ok] 凭证读取面（是否碰 KEY/TOKEN/cookie） — process.env 使用点只有 `process.env.CHROME_PATH`（渲染器路径）与 `const env = { ...process.env }` 后 delete HYPERFRAME_RUNTIME_URL 的整环境传递。全脚本无 GEMINI/OPENAI/AWS/HeyGen 等 key 名，无 keychain/.env 读取。判蓝（而非橙）成立。
- [ok] 写盘范围（是否可能误写用户仓库其他文件） — seam-stamp.mjs 只 writeFileSync(target, html)，target 来自 --write 参数（实践为 index.html），替换范围被 `// <seams:auto>` 标记限定；seam-gate.mjs 只读。无 rm/mkdir/unlink。风险为客户项目内的定点改写。
- [ok] 子进程与清理（是否留下孤儿进程或提权） — 预览服务以 detached: true spawn，并在 process.on('exit') 里 `process.kill(-child.pid, "SIGTERM")` 按进程组回收；SIGINT/SIGTERM 处理器以 exit 130 退出；chrome 子进程同样 detached 并在清理里 SIGKILL 进程组。未见 sudo/提权，未见沙箱或权限模式相关危险开关。
- [ok] SKILL.md 声称的闸门语义是否真由脚本实现（防吹牛） — SKILL.md 列出 8 类被强制的检查；references/seam-gate.md 给出「检查行 ↔ 规则」对照表；seam-gate.mjs 内可见 EPS_XY=15 / EPS_Z=0.04 / SPEED_RATIO=3 / CARRIER_POS_TOL=12 / CARRIER_SIZE_TOL=0.05 等阈值常量，与文档中「12px 中心 / 5% 尺寸容差」「速度比 >3 报警」一致。声称有实现支撑。
- [ok] 「盖章即合规」是否只是宣传语 — seam-stamp.mjs 从 ledger 生成基础态（首个场景 autoAlpha:1，其余 autoAlpha:0 且归零 transform）与逐缝 wrapper tween，并把 Z 入场按 dir 预设 scale（dir=-1 → 1.25 超大抵达；否则 0.78 从小到大），与接缝检查要求的方向/符号一致——生成端确实按构造满足被检查字段。仍有手写项（match-cut/morph 只给可见性集，载体交接手写），与 SKILL.md 自述一致。
- [unlocatable] prompt/内容注入面 — seam-gate 的 `--server-cmd` 允许调用者替换实际执行的 shell 命令（默认值安全）。是否存在其他调用方把外部输入拼进该参数，超出本 skill 目录范围（pin 内其他 skill 的调用点未逐一追查），故不在此断言；仅记录该开关的存在与其默认值。
6结论
9280ac3792a44afd…d2f0bc7f34