Skip to content

An AI editor that watches its own cut: talking-head / AI-avatar video → auto-edited short video. 网感口播精剪:数字人/真人口播 → AI 自动精剪成网感动效短视频 → 可选剪映分层草稿

Initial release

yehuiyufbd867621747
diff --git "a/.github/ISSUE_TEMPLATE/\351\227\256\351\242\230\345\217\215\351\246\210.md" "b/.github/ISSUE_TEMPLATE/\351\227\256\351\242\230\345\217\215\351\246\210.md"
new file mode 100644
index 0000000..3ddcaed
--- /dev/null
+++ "b/.github/ISSUE_TEMPLATE/\351\227\256\351\242\230\345\217\215\351\246\210.md"
@@ -0,0 +1,11 @@
+---
+name: 问题反馈
+about: 环境装不上 / 跑不通 / 效果不理想
+---
+**卡在哪一步**(打勾):[ ] 环境/preflight [ ] 数字人 [ ] 精剪(素材理解/证据/构建/质检) [ ] 剪映草稿 [ ] 音效 [ ] 效果不满意
+
+**你的环境**:系统与芯片(如 macOS 15 / M3)、agent(Claude Code / Codex / …)、`zsh skill/seecut/scripts/preflight.sh` 的完整输出
+
+**素材类型**:真人半身 / 数字人 / 录屏+角落头像 / 其它;时长多少秒
+
+**报错或现象**:贴日志,或工程目录里 runlog 的"skill 问题"一节。效果问题请附成片截图
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..91cd05d
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,11 @@
+*.mp4
+*.mov
+*.MOV
+*.wav
+*.m4a
+node_modules/
+__pycache__/
+.DS_Store
+.env
+**/build/frames/
+**/build/person/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..7941f28
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,137 @@
+SeeCut(网感口播精剪)
+
+Required Notice: Copyright (c) 2026 YeJe-cpu (https://github.com/YeJe-cpu)
+
+---
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose. However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
diff --git a/NOTICE b/NOTICE
new file mode 100644
index 0000000..39606f8
--- /dev/null
+++ b/NOTICE
@@ -0,0 +1,16 @@
+SeeCut — third-party notices
+
+- skill/seecut/assets/hf-hw/hf-hw.js, hf-hw.css: helpers extracted from HyperFrames registry
+ components (hw-callout-circle / hw-underline / hw-arrow), https://github.com/heygen-com/hyperframes,
+ Copyright HeyGen, licensed under the Apache License 2.0. Modified: self-preview code removed.
+- skill/seecut/assets/hf-hw/fonts/Caveat-700-latin.woff2: Caveat font, SIL Open Font License 1.1.
+
+Not distributed here (install yourself under their own licenses):
+- HyperFrames CLI / runtime (Apache-2.0), GSAP (GreenSock standard license), playwright-core (Apache-2.0),
+ faster-whisper (MIT), ffmpeg.
+- jianying-headless (https://github.com/mcncarl/jianying-headless) — personal learning / non-commercial license.
+- HeyGen, Google Antigravity / Gemini: third-party services under their own terms; bring your own account.
+
+Acknowledgements (see README): video-talkcraft (SHOTBOOK / design language),
+hypit (breaking a video into a structural blueprint), hyperframes-student-kit (design-token structure,
+card library), rachel-digital-human-production (AI-avatar workflow: HeyGen avatar + separate voice track).
diff --git a/README.en.md b/README.en.md
new file mode 100644
index 0000000..7f0231d
--- /dev/null
+++ b/README.en.md
@@ -0,0 +1,99 @@
+<div align="center">
+
+# SeeCut
+
+**An AI editor that watches its own cut — see, cut, loop.**
+
+[中文](README.md) · English · [日本語](README.ja.md)
+
+</div>
+
+**Talking-head video (real person or AI avatar) → an automatically edited, high-energy short video with motion graphics → optionally pushed into a layered JianYing (CapCut China) draft for fine-tuning.**
+SeeCut is a skill for coding agents such as Claude Code. The agent understands your footage, finds real on-screen evidence, plans and renders every shot, then **watches its own output with a video-native AI to review and improve it**, and finally hands it to you for the last look.
+
+| Raw AI-avatar footage (HeyGen AV5 + Doubao TTS voice) | After SeeCut |
+|:---:|:---:|
+| https://github.com/user-attachments/assets/6c5c821a-bb8b-48f0-bead-5509425835ce | https://github.com/user-attachments/assets/4702dc92-8bb3-4199-acc0-31fd3d98ae96 |
+
+Both videos have sound; click to play. Everything on the right was produced by the agent (real screenshots as evidence, cards, hand-drawn callouts, the speaker moving between full screen and picture-in-picture); only the volume was adjusted afterwards in JianYing. Original files: [Releases · demo-v1](https://github.com/YeJe-cpu/SeeCut/releases/tag/demo-v1). The demo is in Chinese.
+
+The skill's own docs (under `skill/`, `digital-human/`, `jianying/`) are written in Chinese. Your agent reads them fine; ask it to explain anything you need.
+
+---
+
+## Highlights
+1. **See: the AI actually watches the video.** Models like Claude and GPT usually have to look at a few frames extracted from a video, which can't show motion or pacing. SeeCut uses Gemini (through the Antigravity CLI) to watch video directly, both to understand the footage and to review its own cuts.
+2. **Seeing accurately: a calibrated judge.** Change the prompt and the same AI will call one video "polished" or "tacky". We tested the judge on videos with known answers: absolute scores were unreliable, while "which of these two is better" was reliable. So every review is a pairwise comparison, run twice with the order swapped, and a version only wins if it wins both times.
+3. **Loop: it edits and chooses by itself.** Each version must pass hard checks, then beat the previous version head-to-head before it is adopted. At most 3 versions, each with a visible improvement. With an accurate eye, the loop gets better instead of drifting.
+4. **Real evidence, not fake UI.** Whatever the speaker mentions, the agent captures the real web page, product screen or example as visual evidence. Mock interfaces used to "fill the frame" are forbidden. You get a rich video even without extra B-roll.
+5. **A method, not a pile of effects.** A structured style system: design tokens → component library → an editing decision table ("what is this sentence doing → how should the frame handle it") → a shot-by-shot build sheet.
+6. **A real, reproducible AI-avatar recipe.** HeyGen AV5 digital twin for the picture; for the voice, **not HeyGen's built-in voices (they sound artificial) but Doubao (ByteDance) TTS**. That is how the demo was made. Scripts and steps are in [digital-human/](digital-human/).
+7. **Editable in JianYing.** Besides the rendered video you get a layered project package; with the optional draft engine installed it becomes a JianYing draft with separate tracks you can adjust, including auto-placed sound effects.
+
+## Quick start
+1. Make a folder with **a 20–30 s vertical, half-body talking-head clip** (a phone recording is fine) plus, optionally, 3–6 screenshots of things you mention.
+2. Install the "Core" items below and run `zsh skill/seecut/scripts/preflight.sh` until all required checks pass.
+3. Copy `skill/seecut` into `~/.claude/skills/` (or your agent's skills folder), open a new conversation and run:
+ ```
+ /seecut 素材:<your folder>
+ ```
+ (`素材` means "footage".)
+4. You get: the rendered video (in `~/Downloads`), a layered project package, and a delivery report (what changed in each version and the review results).
+
+**Sample first, then the full video.** For longer footage, run the first 20–30 seconds, confirm the style and direction, then run the whole thing (the skill will ask you first when the footage is longer than 60 s). One loop produces 2–3 versions, each rendered and reviewed by the AI, so a 25-second sample currently takes about an hour, and longer videos take longer.
+
+## Three-step pipeline
+| Step | What it does | Notes |
+|---|---|---|
+| [1 · AI avatar](digital-human/) | Script → voice → avatar → vertical talking-head A-roll | What we use: Doubao TTS + HeyGen; the tools are swappable. Skip if you record yourself |
+| [2 · SeeCut edit](skill/seecut/) | Understand footage → find real evidence → plan → render with HyperFrames → AI review loop → deliver | **Core** |
+| [3 · JianYing draft](jianying/) | Layered package → a draft you can open and adjust track by track in JianYing | Optional |
+
+## Before you start
+Tested on macOS only so far. Clone the repo and hand it to your agent; it can install things following this section and `preflight.sh`.
+
+**Core: required for editing** (checked by `preflight.sh`)
+| Item | Notes |
+|---|---|
+| A coding agent | Claude Code is tested; Codex, WorkBuddy and other skill-capable agents should work in principle. The self-review loop makes many calls, so make sure you have enough quota |
+| **Antigravity CLI (`agy`)** | The AI's eyes. **Without it there is no self-review and no loop.** A Google account is enough: free accounts get a weekly quota; Google AI Pro gets a higher quota that refreshes every 5 hours (one video needs many calls, so the free quota may not last a full run; see the [official plans page](https://antigravity.google/docs/plans/)). Gotchas: the Google account's **country setting** must be a supported region (the account setting, not your IP); headless calls need `--dangerously-skip-permissions` |
+| HyperFrames CLI | Free and open source, runs via `npx -y hyperframes@latest`. Behind a proxy, set the **uppercase** `HTTPS_PROXY` |
+| ffmpeg, Node 22+ (required by HyperFrames), Python 3, `pip install faster-whisper`, `npm i playwright-core` in the project folder | All free; used for rendering, transcription and capturing evidence |
+
+**AI avatar: needed when you generate avatar footage** (the tools are swappable; these are what we use)
+| Item | Notes |
+|---|---|
+| Voice: Volcengine · Doubao Speech | Sounds more natural than avatar platforms' built-in voices. New apps get a free quota (about 20,000 characters as shown in the console when we signed up); check the [Volcengine console](https://console.volcengine.com/speech/service/10035) and the latest official docs |
+| Avatar: HeyGen account + API wallet | AV4 from a photo ≈ $0.04/s; AV5 digital twin ≈ $0.12/s |
+
+**Optional extras**
+| Item | Used for |
+|---|---|
+| jianying-headless (third party, non-commercial license) | Building layered JianYing drafts |
+| Your own sound-effect library | `scripts/sfx_ledger.py` indexes it, then effects are placed automatically |
+| An image generator | Fills gaps when footage is missing; any image model works, we happen to use Grok CLI |
+
+## Known issues
+- `agy` says "not eligible": the Google account's country setting is not supported (change the account setting; a VPN won't help).
+- `npx hyperframes` times out: the proxy isn't set as uppercase `HTTPS_PROXY`.
+- `CERTIFICATE_VERIFY_FAILED`: a local proxy is intercepting HTTPS; add its CA for Python/Node, or use curl.
+- AI avatar: AV5 requires creating the digital twin manually on the HeyGen website; AV4 only needs one photo and is good enough when the speaker is shown small.
+- JianYing: the third-party engine needs to be set up on your machine; without it you still get the video and the layered assets.
+- Screen recording + corner webcam footage has not been tested much in this version. Feedback welcome.
+- One video takes from tens of minutes to an hour; try the direction on a 20–30 s sample first.
+
+Please open an issue (there is a template) with your preflight output and the "skill issues" section of the delivery report.
+
+## Acknowledgements
+This pipeline stands on the shoulders of:
+- [HyperFrames](https://github.com/heygen-com/hyperframes): the rendering engine and official component library behind much of the motion on screen.
+- [video-talkcraft](https://github.com/Vincentwei1021/video-talkcraft): the overall editing-pipeline structure (Design Reference → component library → SHOTBOOK).
+- [hypit](https://github.com/hypit-ai/hypit): its approach to breaking down viral videos helped us understand what makes footage feel native to the feed.
+- [hyperframes-student-kit](https://github.com/nateherkai/hyperframes-student-kit): the Vox Explainer-style design tokens and card styling.
+- [jianying-headless](https://github.com/mcncarl/jianying-headless): the JianYing draft engine.
+- [rachel-digital-human-production](https://github.com/Jingyi-Wu-Richael/rachel-digital-human-production): the starting point of our AI-avatar workflow; on top of it we tested and improved the AV5 digital twin, the Doubao voice and vertical cropping.
+
+Thanks to the authors of these projects. Third-party components and fonts included in this repository, and their licenses, are listed in [NOTICE](NOTICE).
+
+## License
+[PolyForm Noncommercial 1.0.0](LICENSE)
diff --git a/README.ja.md b/README.ja.md
new file mode 100644
index 0000000..d7e2d3f
--- /dev/null
+++ b/README.ja.md
@@ -0,0 +1,99 @@
+<div align="center">
+
+# SeeCut
+
+**An AI editor that watches its own cut — see, cut, loop.**
+
+[中文](README.md) · [English](README.en.md) · 日本語
+
+</div>
+
+**トーキングヘッド動画(本人出演または AI アバター)→ モーショングラフィックス入りの見応えあるショート動画に自動で仕上げる → 必要なら剪映(JianYing)のレイヤー付きドラフトに書き出して微調整。**
+SeeCut は Claude Code などのコーディングエージェント向けのスキルです。エージェントが素材を理解し、画面に出す「本物の証拠」を探し、ショットを組み立ててレンダリングし、さらに**動画をそのまま見られる AI で自分の編集結果を見直して改善**します。最後の確認はあなたの目で行います。
+
+| AI アバターの元動画(HeyGen AV5 + Doubao 音声合成) | SeeCut で自動編集した結果 |
+|:---:|:---:|
+| https://github.com/user-attachments/assets/6c5c821a-bb8b-48f0-bead-5509425835ce | https://github.com/user-attachments/assets/4702dc92-8bb3-4199-acc0-31fd3d98ae96 |
+
+どちらも音声付きで、クリックすると再生できます。右側の映像はすべてエージェントが作成しました(証拠としての実際のスクリーンショット、カード、手描き風の囲み、話し手の全画面/小窓の切り替え)。後から剪映で音量だけ調整しています。元ファイルは [Releases · demo-v1](https://github.com/YeJe-cpu/SeeCut/releases/tag/demo-v1) にあります。デモは中国語です。
+
+スキル本体のドキュメント(`skill/`、`digital-human/`、`jianying/`)は中国語で書かれています。エージェントはそのまま読めますので、わからない点はエージェントに説明させてください。
+
+---
+
+## 特長
+1. **See:AI が動画を本当に「見る」。** Claude や GPT のようなモデルは、通常は動画から抜き出した数枚の静止画を見るしかなく、動きやテンポは分かりません。SeeCut は Gemini(Antigravity CLI 経由)で動画を直接見て、素材の理解と自己レビューの両方に使います。
+2. **正しく見る:較正済みの審査。** 同じ動画でもプロンプト次第で AI は「洗練」とも「ダサい」とも言います。答えの分かっている動画で審査役を試したところ、絶対評価の点数は当てにならず、「2 本のうちどちらが良いか」の比較は当てになりました。そのため審査はすべて一対比較で、左右を入れ替えて 2 回とも勝った場合だけ採用します。
+3. **Loop:自分で直し、自分で選ぶ。** 各バージョンはまず致命的なミスのチェックを通り、次に前のバージョンとの一対比較で勝ったときだけ採用されます。最大 3 バージョン、毎回目で見て分かる改善が必須です。目が正確だからこそ、ループは良い方向に進みます。
+4. **偽の画面ではなく本物の証拠。** 話に出てきた Web ページや製品画面、事例を実際にキャプチャして映像の証拠にします。画面を埋めるための偽 UI は禁止。追加の B ロールがなくても中身のある映像になります。
+5. **エフェクトの寄せ集めではなく方法論。** 体系立ったスタイル規範:デザイントークン → コンポーネントライブラリ → 編集判断表(「この一文の役割は何か → 画面でどう扱うか」)→ ショットごとの施工指示書。
+6. **AI アバターの作り方も実際の手順どおりに公開。** 映像は HeyGen AV5 のデジタルツイン、音声は **HeyGen 内蔵の声(不自然に聞こえる)ではなく Doubao(ByteDance)の音声合成**。デモもこの方法で作りました。スクリプトと手順は [digital-human/](digital-human/) にあります。
+7. **剪映で微調整できる。** 完成動画に加えてレイヤー分けしたプロジェクト素材を出力します。任意のドラフトエンジンを入れれば、トラックごとに調整できる剪映ドラフトになり、効果音も自動で配置されます。
+
+## クイックスタート
+1. フォルダを用意し、**20〜30 秒の縦長・上半身のトーキングヘッド動画**(スマホ撮影で十分)と、任意で話に出てくるもののスクリーンショットを 3〜6 枚入れます。
+2. 下の「コア」項目を入れ、`zsh skill/seecut/scripts/preflight.sh` の必須チェックがすべて通るまで整えます。
+3. `skill/seecut` を `~/.claude/skills/`(またはお使いのエージェントの skills フォルダ)にコピーし、新しい会話で実行します:
+ ```
+ /seecut 素材:<あなたのフォルダ>
+ ```
+ (`素材` は「素材・フッテージ」の意味です。)
+4. 受け取るもの:レンダリング済み動画(`~/Downloads`)、レイヤー分けしたプロジェクト素材、納品レポート(各バージョンの変更点とレビュー結果)。
+
+**まずサンプル、それから全編。** 長い素材はまず冒頭 20〜30 秒で試し、スタイルと方向性を確認してから全編を回してください(素材が 60 秒を超えるとスキルが先に確認します)。1 回のループで 2〜3 バージョンを作り、それぞれレンダリングと AI レビューを行うため、25 秒のサンプルで現状約 1 時間かかり、長い動画ほど時間が延びます。
+
+## 3 ステップの流れ
+| ステップ | 内容 | 備考 |
+|---|---|---|
+| [1 · AI アバター](digital-human/) | 原稿 → 音声 → アバター → 縦長トーキングヘッド A ロール | 私たちの方法:Doubao 音声合成 + HeyGen。ツールは差し替え可能。自分で撮るなら不要 |
+| [2 · SeeCut 編集](skill/seecut/) | 素材理解 → 証拠集め → 構成 → HyperFrames でレンダリング → AI レビューループ → 納品 | **中核** |
+| [3 · 剪映ドラフト](jianying/) | レイヤー素材 → 剪映で開いてトラックごとに調整できるドラフト | 任意 |
+
+## 始める前に
+現時点で動作確認は macOS のみです。リポジトリをクローンしてエージェントに渡せば、この節と `preflight.sh` に沿ってセットアップを手伝ってくれます。
+
+**コア:編集に必須**(`preflight.sh` が 1 つずつ確認します)
+| 項目 | 説明 |
+|---|---|
+| コーディングエージェント | Claude Code で動作確認済み。Codex、WorkBuddy などスキルを動かせるエージェントも理論上は使えます。自己レビューのループで何度も呼び出すため、利用枠に余裕を持たせてください |
+| **Antigravity CLI(`agy`)** | AI の「目」。**これがないと自己レビューもループもできません。** Google アカウントがあれば使え、無料アカウントには週ごとの利用枠があります。Google AI Pro は枠が大きく 5 時間ごとに回復します(1 本の動画で何度も呼び出すため、無料枠では足りない場合があります。[公式のプラン説明](https://antigravity.google/docs/plans/)を参照)。注意:Google アカウントの**国/地域の設定**が対応地域である必要があります(IP ではなくアカウント設定)。ヘッドレス実行には `--dangerously-skip-permissions` が必要です |
+| HyperFrames CLI | 無料のオープンソース。`npx -y hyperframes@latest` で使えます。プロキシ環境では**大文字**の `HTTPS_PROXY` を設定してください |
+| ffmpeg、Node 22 以上(HyperFrames の要件)、Python 3、`pip install faster-whisper`、プロジェクトフォルダで `npm i playwright-core` | すべて無料。レンダリング、文字起こし、証拠キャプチャに使います |
+
+**AI アバター:アバター動画を作るときに必要**(ツールは差し替え可能。以下は私たちが実際に使っているもの)
+| 項目 | 説明 |
+|---|---|
+| 音声:Volcengine・Doubao 音声 | アバターサービス内蔵の声より自然です。新規アプリには無料枠があります(登録時のコンソール表示で約 2 万文字)。[Volcengine コンソール](https://console.volcengine.com/speech/service/10035)と最新の公式ドキュメントで確認してください |
+| アバター:HeyGen アカウント+ API ウォレット | AV4(写真から)約 $0.04/秒、AV5(デジタルツイン)約 $0.12/秒 |
+
+**任意の拡張**
+| 項目 | 用途 |
+|---|---|
+| jianying-headless(サードパーティ、非商用ライセンス) | 剪映のレイヤー付きドラフト生成 |
+| 手持ちの効果音ライブラリ | `scripts/sfx_ledger.py` で台帳を作ると効果音を自動配置 |
+| 画像生成ツール | 素材が足りないときに自動で画像を補う。どの画像生成モデルでもよく、私たちは手元の Grok CLI を使っています |
+
+## 既知の問題
+- `agy` が "not eligible" と出る:Google アカウントの国/地域設定が対象外です(VPN ではなくアカウント設定を変更)。
+- `npx hyperframes` がタイムアウトする:プロキシが大文字の `HTTPS_PROXY` で設定されていません。
+- `CERTIFICATE_VERIFY_FAILED`:ローカルのプロキシが HTTPS を中継しています。Python / Node にそのプロキシの CA を設定するか、curl を使ってください。
+- AI アバター:AV5 は HeyGen の Web サイトで手動でデジタルツインを作る必要があります。AV4 は写真 1 枚で作れ、話し手を小さく表示するなら十分です。
+- 剪映:サードパーティのエンジンは各自の環境に合わせた設定が必要です。なくても完成動画とレイヤー素材は受け取れます。
+- 画面録画+隅のワイプ顔出しの素材は、現バージョンでは十分にテストしていません。フィードバック歓迎です。
+- 1 本に数十分〜1 時間かかります。まず 20〜30 秒のサンプルで方向性を確かめてください。
+
+問題があれば issue を立ててください(テンプレートあり)。preflight の出力と、納品レポートの「skill の問題」の節を添えてください。
+
+## 謝辞
+このパイプラインは次のプロジェクトに支えられています:
+- [HyperFrames](https://github.com/heygen-com/hyperframes):レンダリングエンジンと公式コンポーネントライブラリ。画面の動きの多くを支えています。
+- [video-talkcraft](https://github.com/Vincentwei1021/video-talkcraft):編集パイプライン全体の組み立て方(Design Reference → コンポーネントライブラリ → SHOTBOOK)。
+- [hypit](https://github.com/hypit-ai/hypit):ヒット動画を分解する考え方が、「ネットらしさ」と素材を理解する助けになりました。
+- [hyperframes-student-kit](https://github.com/nateherkai/hyperframes-student-kit):Vox Explainer スタイルのデザイントークンとカードのスタイル。
+- [jianying-headless](https://github.com/mcncarl/jianying-headless):剪映ドラフトエンジン。
+- [rachel-digital-human-production](https://github.com/Jingyi-Wu-Richael/rachel-digital-human-production):AI アバター手順の出発点。その上で AV5 デジタルツイン、Doubao 音声、縦長クロップを検証・改良しました。
+
+これらのプロジェクトの作者に感謝します。本リポジトリに含まれるサードパーティのコンポーネントとフォント、およびそのライセンスは [NOTICE](NOTICE) を参照してください。
+
+## ライセンス
+[PolyForm Noncommercial 1.0.0](LICENSE)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e4bb682
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+<div align="center">
+
+# SeeCut · 网感口播精剪
+
+**An AI editor that watches its own cut — see, cut, loop.**
+
+中文 · [English](README.en.md) · [日本語](README.ja.md)
+
+</div>
+
+**数字人 / 真人口播 → AI 自动精剪成"网感"动效短视频 → 可选推成剪映分层草稿微调。**
+一个给 coding agent(Claude Code 等)用的 skill:它自己理解素材、自己去找真证据、自己编排和渲染,再**用 AI 看视频给自己质检、自己迭代**,最后交你肉眼终审。
+
+| 数字人原片(HeyGen AV5 + 豆包配音) | SeeCut 自动精剪后 |
+|:---:|:---:|
+| https://github.com/user-attachments/assets/6c5c821a-bb8b-48f0-bead-5509425835ce | https://github.com/user-attachments/assets/4702dc92-8bb3-4199-acc0-31fd3d98ae96 |
+
+两条都有声音,点开即可播放。右边的画面由 agent 全程自动完成(真证据截图、卡片、手绘圈注、人像在全屏和小窗之间调度),最后只在剪映里调了音量。原始文件在 [Releases · demo-v1](https://github.com/YeJe-cpu/SeeCut/releases/tag/demo-v1)。
+
+"精剪"不是去气口的粗剪;"口播"是有真人或数字人出镜;"网感"是画面有料、动效跟着每句话走。
+
+---
+
+## 亮点
+1. **See:让 AI 真正"看"视频。** Claude、GPT 这类模型通常要先把视频抽成几张图片再看,看不出动效和节奏。SeeCut 接入 Gemini(通过 Antigravity CLI)直接看视频,素材理解和质检都靠它。
+2. **看得准:评委是校准过的。** 同一条视频换个提示词,AI 能从"标准"说成"土味"。我们用答案已知的片子测评委,发现"打绝对分"不可靠、"两条比哪条好"才可靠,所以质检用两两对比,交换位置各跑一次都赢才算。
+3. **Loop:自己改、自己挑。** 每版先过硬伤检查,再和上一版两两对比,赢了才采纳;最多 3 版,每版必须有肉眼可见的进步。眼睛准了,循环才会越改越好,而不是越改越偏。
+4. **找真证据。** 口播提到什么,就去截真的网页、界面、案例当画面证据,禁止用假界面凑满画面。没有额外 B-roll 也能做得有料。
+5. **有章法,不是堆特效。** 一套成体系的风格规范:设计令牌 → 组件库 → 编排决策表("这句话是什么功能 → 画面怎么处理")→ 逐镜施工单,层层有据。
+6. **数字人也给了实打实的做法。** HeyGen AV5 数字分身出人像,**配音不用 HeyGen 内置音色(偏假),改用豆包语音合成**,demo 里的声音就是这么来的。脚本和步骤都在 [digital-human/](digital-human/)。
+7. **能在剪映里微调。** 交成片的同时交分层工程包;装了剪映草稿引擎还能直接推成剪映里分轨可改的草稿,音效也能自动配。
+
+## 最快跑通
+1. 准备一个文件夹:**一段 20-30 秒竖屏半身口播**(自己拍的就行)+ 3-6 张口播里提到的东西的截图(可选)。
+2. 装好下面"核心"部分的环境,运行 `zsh skill/seecut/scripts/preflight.sh`,直到必需项全绿。
+3. 把 `skill/seecut` 放进 `~/.claude/skills/`(或你的 agent 的 skills 目录),新开对话:
+ ```
+ /seecut 素材:<你的文件夹>
+ ```
+4. 拿到:渲染成片(`~/Downloads`)+ 分层工程包 + 交付报告(每版改了什么、质检结论)。
+
+**先样片、后全片。** 长视频请先拿开头 20-30 秒跑一遍,确认风格和方向没问题再跑全片(素材超过 60 秒时 skill 也会先问你)。一次循环会出 2-3 版,每版都要渲染和 AI 看片对比,一条 25 秒样片目前约 1 小时,片子越长越久。
+
+## 三步流水线
+| 步骤 | 做什么 | 说明 |
+|---|---|---|
+| [第 1 步 · 数字人](digital-human/) | 口播文案 → 配音 → 数字人 → 竖屏口播 A-roll | 我们的做法:豆包配音 + HeyGen 数字人;工具可以换。有真人口播就跳过 |
+| [第 2 步 · 网感口播精剪](skill/seecut/) | 素材理解 → 找真证据 → 编排 → HyperFrames 渲染 → AI 质检自迭代 → 交付 | **核心** |
+| [第 3 步 · 剪映草稿](jianying/) | 分层工程包 → 剪映里能打开、分轨微调的草稿 | 可选 |
+
+## 开始之前:你需要准备
+目前只在 macOS 上实测过。克隆下来交给你的 agent,它会按这里和 `preflight.sh` 帮你装。
+
+**核心:精剪必需**(`preflight.sh` 会逐项检查)
+| 内容 | 说明 |
+|---|---|
+| 一个 coding agent | Claude Code 已实测;Codex、WorkBuddy 等能跑 skill 的 agent 理论上通用。要跑多轮自迭代,额度要充足 |
+| **Antigravity CLI(`agy`)** | AI"看视频"的眼睛,**没有它就没有自检和自迭代**。用 Google 账号登录即可,免费账号有按周刷新的额度;Google AI Pro 会员额度更高、每 5 小时刷新(一条片子要调很多次,免费额度可能不够跑完,以[官方说明](https://antigravity.google/docs/plans/)为准)。坑:Google 账号**底层地区**要是支持地区(看账号设置,不看 IP);国内要代理;无头调用要加 `--dangerously-skip-permissions` |
+| HyperFrames CLI | 免费开源,`npx -y hyperframes@latest` 即用;代理要设成**大写** `HTTPS_PROXY` |
+| ffmpeg、Node 22+(HyperFrames 要求)、Python 3、`pip install faster-whisper`、工程目录里 `npm i playwright-core` | 均免费,用于渲染、转写、截证据 |
+
+**数字人:要出数字人口播时需要**(工具可以换,下面是我们实际用的)
+| 内容 | 说明 |
+|---|---|
+| 配音:火山引擎·豆包语音 | 比数字人平台的内置音色自然。新应用有免费额度(我们开通时控制台显示约 2 万字符),以[火山引擎控制台](https://console.volcengine.com/speech/service/10035)和官方最新文档为准 |
+| 数字人:HeyGen 账号 + API 钱包 | AV4 照片驱动约 $0.04/秒,AV5 数字分身约 $0.12/秒 |
+
+**可选增强**
+| 内容 | 用途 |
+|---|---|
+| jianying-headless(第三方,非商业协议) | 生成剪映分层草稿 |
+| 你自己的音效库 | `scripts/sfx_ledger.py` 一键建台账后自动配音效 |
+| 一个生图工具 | 缺素材时自动生图补画面;任何生图模型都行,我们手边用的是 Grok CLI |
+
+## 已知卡点
+- agy 报 not eligible:Google 账号底层地区不对(改账号设置,不是换 IP)。
+- `npx hyperframes` 下载超时:代理没设成大写 `HTTPS_PROXY`。
+- 证书报错(CERTIFICATE_VERIFY_FAILED):本机有代理做了 HTTPS 中间人,给 Python / Node 配上代理的 CA,或改用 curl。
+- 数字人:AV5 需要在 HeyGen 网页人工建分身;AV4 只要一张照片,缩成小窗时足够用。
+- 剪映:第三方引擎要自己适配;没有它也能拿到成片 + 分层素材。
+- 录屏 + 角落头像类型的素材在当前版本没有充分测试,欢迎反馈。
+- 一条片子要跑几十分钟到一小时,先用 20-30 秒样片试方向。
+
+遇到问题请开 issue(有模板),附上 preflight 输出和交付报告里的"skill 问题"一节。
+
+## 致谢
+这套管线站在这些项目的肩膀上:
+- [HyperFrames](https://github.com/heygen-com/hyperframes):渲染引擎和官方组件库,画面里的大量动效靠它撑起来。
+- [video-talkcraft](https://github.com/Vincentwei1021/video-talkcraft):剪辑管线的整体编排思路(Design Reference → 组件库 → SHOTBOOK)。
+- [hypit](https://github.com/hypit-ai/hypit):爆款拆解的思路,帮助我们理解网感和素材。
+- [hyperframes-student-kit](https://github.com/nateherkai/hyperframes-student-kit):Vox Explainer 风格的设计令牌和卡片样式。
+- [jianying-headless](https://github.com/mcncarl/jianying-headless):剪映草稿引擎。
+- [rachel-digital-human-production](https://github.com/Jingyi-Wu-Richael/rachel-digital-human-production):数字人流程的起点;在它的基础上,我们又实测改进了 AV5 数字分身、豆包配音和竖屏裁切。
+
+感谢这些项目的作者。本仓库包含的第三方组件与字体及其许可见 [NOTICE](NOTICE)。
+
+## 协议
+[PolyForm Noncommercial 1.0.0](LICENSE)
diff --git a/digital-human/README.md b/digital-human/README.md
new file mode 100644
index 0000000..685f184
--- /dev/null
+++ b/digital-human/README.md
@@ -0,0 +1,60 @@
+# 第 1 步(可选)· 数字人口播 A-roll
+
+流程:口播文案 →(豆包)配音 mp3 →(HeyGen)数字人竖屏口播 mp4 → 交给第 2 步精剪。用别的数字人工具也行,只要最后是一条竖屏半身口播 mp4。
+
+**有自己拍的口播就跳过这步**,直接进第 2 步。想先跑通最小闭环的,也建议先拿一段自己拍的 20-60 秒竖屏半身口播试。
+
+## 两种方案
+| | 基础:AV4(照片驱动) | 进阶:AV5(数字分身) |
+|---|---|---|
+| 你要准备 | 一张清晰正脸半身照(自己的或生成的) | 在 HeyGen 网页建好数字分身:上传 15-600 秒真人训练视频 + 摄像头现录授权(consent) |
+| 像不像 | 脸忠实原图,动起来五官会漂、动作少 | 高,口型和微表情从你的视频学来 |
+| 价格(参考) | 约 $0.04/秒 | 约 $0.12/秒 |
+| 够不够用 | **够**:精剪里人像大多缩成小窗、不常全屏,AV4 的瑕疵大都看不出来 | 更真,做系列内容推荐 |
+
+## 准备
+1. HeyGen 账号 → Settings → API 拿 key,`export HEYGEN_API_KEY=...`(**别写进任何文件或仓库**)。
+2. API 钱包充值(最低 $5)。**不需要**网页的月度订阅。**余额不足也会照扣钱,而且任务不能取消** → 提交前先 `python3 heygen_avatar.py balance`,一次只交一个任务。
+3. 口播音频:推荐先用豆包语音合成配好音(见下面"配音"一节),也可以用自己的录音或别的 TTS。HeyGen 内置音色听起来偏假,分身自带的克隆声往往不稳,我们都没用。
+4. AV5 另外:网页 `Avatars → Clone a Real Person` → 上传训练视频 → 现录 consent → 等训练完成。训练视频要求:竖版、单人正对镜头连续说话、光线均匀,**手和麦克风别挡嘴**(否则生成时口型穿帮)。
+
+## 配音(豆包语音合成)
+demo 里的声音不是 HeyGen 的,是先用豆包 TTS 配好音,再拿这段音频驱动数字人。
+
+**开通**(一次性)
+1. [火山引擎控制台 →「豆包语音」](https://console.volcengine.com/speech/service/10035) → 新建应用,开通"豆包语音合成模型"的试用包。
+2. 同一页的"服务接口认证信息"里拿 **AppID** 和 **Access Token**。
+3. 坑:开了试用包后,音色列表可能还是空的,要再点"开通服务试用"把音色激活,否则调不通。
+4. 额度:新应用有免费额度,我们开通时控制台显示约 2 万字符,具体以控制台和火山引擎官方最新文档为准。一条 20 秒口播约 100 字,够试很多条。
+
+**生成**
+```bash
+export VOLC_APPID=... VOLC_ACCESS_TOKEN=... # 别写进任何文件或仓库
+python3 doubao_tts.py --file 文案.txt --out 口播.mp3 # 一行一句,逐句合成后拼接
+```
+- 默认音色 `zh_male_liufei_uranus_bigtts`(男声),语速 1.1,就是 demo 用的。换音色用 `--voice`,音色 id 在控制台音色列表里查。
+- 逐句合成更稳:一次塞太长的文案容易超字数,连发太快会被瞬时限流(报错就等几秒重跑)。
+- 合成完建议听一遍,或用 whisper 转写核对有没有漏句。
+
+## 出片
+```bash
+python3 heygen_avatar.py balance
+python3 heygen_avatar.py av4 --photo 我.png --audio 口播.mp3 --out a_roll.mp4 # 基础
+python3 heygen_avatar.py looks --avatar-group <分身组 id> # 进阶:先找 look id
+python3 heygen_avatar.py av5 --look <LOOK_ID> --audio 口播.mp3 --out a_roll.mp4 # 进阶
+```
+输出统一是竖屏 mp4(AV5 目前默认出横屏、人像在中间,脚本会自动裁回竖屏),直接当第 2 步的素材。
+
+## 常见坑
+- 手一抬就崩手指(AV4):脚本已用 `motion_prompt` 压手势 + `expressiveness: low`;还崩就剪辑时缩小人像或裁掉手。
+- `dimension` 字段会被接口拒:别加,竖屏靠脚本后处理。
+- 上传音频必须用 multipart 的 `file` 字段(脚本已处理)。
+- 更多参数和最新接口以 HeyGen 官方文档为准(https://docs.heygen.com),让你的 agent 去查即可。
+
+## 我们实际是怎么做的(上面 demo 的那条数字人)
+- **训练片**:自己的口播原片前 45 秒,竖版 1080×1920,单人正对镜头连续说话,手和麦克风不挡嘴(第一版 30 秒训练片手持麦在嘴边,生成的口型穿帮,换掉后正常)。
+- **建分身**:HeyGen 网页 `Clone a Real Person` → 上传训练片 → 摄像头现录 consent → 训练完成后得到竖版 720×1280 的 look。
+- **配音**:没用 HeyGen 内置音色和分身克隆声,另用豆包语音合成(`zh_male_liufei_uranus_bigtts`,语速 1.1)把 110 字文案配成 17.9 秒 mp3:`python3 doubao_tts.py --file 文案.txt --out 口播.mp3`。
+- **出片**:`heygen_avatar.py av5 --look <你的 look> --audio 口播.mp3`(引擎 avatar_v)。接口默认出 1280×720 横屏、人像在中间,脚本自动裁回竖屏。
+- **花费**:这一条约 $2(从钱包余额差推算)。
+- 然后把这条竖屏 mp4 当素材交给第 2 步精剪,就是上面的 demo。
diff --git a/digital-human/doubao_tts.py b/digital-human/doubao_tts.py
new file mode 100644
index 0000000..d13147b
--- /dev/null
+++ b/digital-human/doubao_tts.py
@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""口播配音(豆包语音合成):文案 → mp3,再交给 heygen_avatar.py 驱动数字人。
+我们不用 HeyGen 内置音色(听起来假),也不用分身克隆声(不稳),而是先用豆包 TTS 配好音再喂给数字人。
+需要:环境变量 VOLC_APPID、VOLC_ACCESS_TOKEN(火山引擎控制台 → 豆包语音),ffmpeg/ffprobe。
+
+ python3 doubao_tts.py --text "你的口播文案" --out 口播.mp3
+ python3 doubao_tts.py --file 文案.txt --out 口播.mp3 --speed 1.1 --voice zh_male_liufei_uranus_bigtts
+文案按行分句逐句合成,句间留 0.16 秒气口再拼接(长文案一次合成容易超字数、语气也平)。
+"""
+import argparse, base64, json, os, subprocess, sys, tempfile, uuid
+
+API = 'https://openspeech.bytedance.com/api/v1/tts'
+GAP = 0.16
+
+
+def tts(text, out, voice, speed):
+ appid, token = os.environ.get('VOLC_APPID'), os.environ.get('VOLC_ACCESS_TOKEN')
+ if not appid or not token: sys.exit('先 export VOLC_APPID=... VOLC_ACCESS_TOKEN=...(别写进任何文件或仓库)')
+ body = {'app': {'appid': appid, 'token': token, 'cluster': 'volcano_tts'},
+ 'user': {'uid': 'seecut'},
+ 'audio': {'voice_type': voice, 'encoding': 'mp3', 'speed_ratio': speed, 'rate': 24000},
+ 'request': {'reqid': str(uuid.uuid4()), 'text': text, 'operation': 'query', 'text_type': 'plain'}}
+ r = subprocess.run(['curl', '-sS', '--max-time', '60', '-X', 'POST', API, '-H', f'Authorization: Bearer;{token}',
+ '-H', 'Content-Type: application/json', '-d', json.dumps(body, ensure_ascii=False)],
+ capture_output=True, text=True)
+ try: d = json.loads(r.stdout)
+ except Exception: sys.exit(f'豆包返回异常:{r.stdout[:300]} {r.stderr[:300]}')
+ if not d.get('data'): sys.exit(f'合成失败:{json.dumps(d, ensure_ascii=False)[:300]}')
+ open(out, 'wb').write(base64.b64decode(d['data']))
+
+
+def main():
+ p = argparse.ArgumentParser()
+ g = p.add_mutually_exclusive_group(required=True)
+ g.add_argument('--text'); g.add_argument('--file')
+ p.add_argument('--out', required=True)
+ p.add_argument('--voice', default='zh_male_liufei_uranus_bigtts', help='音色 id,控制台音色列表里挑')
+ p.add_argument('--speed', type=float, default=1.1)
+ a = p.parse_args()
+ lines = [a.text] if a.text else [l.strip() for l in open(a.file, encoding='utf-8') if l.strip()]
+ tmp = tempfile.mkdtemp()
+ gap = os.path.join(tmp, 'gap.mp3')
+ subprocess.run(['ffmpeg', '-v', 'error', '-y', '-f', 'lavfi', '-i', 'anullsrc=r=24000:cl=mono', '-t', str(GAP), '-q:a', '9', gap], check=True)
+ parts = []
+ for i, t in enumerate(lines):
+ seg = os.path.join(tmp, f'seg_{i:03d}.mp3'); tts(t, seg, a.voice, a.speed)
+ parts += [seg] + ([gap] if i < len(lines) - 1 else [])
+ print(f' {i + 1}/{len(lines)} {t[:20]}')
+ lst = os.path.join(tmp, 'list.txt')
+ open(lst, 'w').write(''.join(f"file '{x}'\n" for x in parts))
+ subprocess.run(['ffmpeg', '-v', 'error', '-y', '-f', 'concat', '-safe', '0', '-i', lst, '-c:a', 'libmp3lame', '-b:a', '128k', a.out], check=True)
+ d = subprocess.check_output(['ffprobe', '-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', a.out]).decode().strip()
+ print(f'完成 → {a.out}({float(d):.1f} 秒)')
+
+
+if __name__ == '__main__':
+ main()
diff --git a/digital-human/heygen_avatar.py b/digital-human/heygen_avatar.py
new file mode 100644
index 0000000..9c4e712
--- /dev/null
+++ b/digital-human/heygen_avatar.py
@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""数字人口播 A-roll(HeyGen):生成一条竖屏口播 mp4,作为 skill 的输入素材。
+需要:环境变量 HEYGEN_API_KEY;curl、ffmpeg/ffprobe。国内网络需要代理(curl 会读 https_proxy)。
+
+ python3 heygen_avatar.py balance # 查钱包余额(提交前先查:余额不足也会照扣钱,且不能取消)
+ python3 heygen_avatar.py looks --avatar-group <网页里建好的分身组 id> # 列出 look,并显示每个 look 支持的引擎
+ # 基础方案 AV4:一张照片 + 一段口播音频
+ python3 heygen_avatar.py av4 --photo 我.png --audio 口播.mp3 --out a_roll.mp4
+ # 进阶方案 AV5:网页建好的数字分身 look + 口播音频(或文字 + 音色)
+ python3 heygen_avatar.py av5 --look <LOOK_ID> --audio 口播.mp3 --out a_roll.mp4
+ python3 heygen_avatar.py av5 --look <LOOK_ID> --script "文案" --voice <VOICE_ID> --out a_roll.mp4
+音频建议先用 doubao_tts.py 配好(HeyGen 内置音色偏假、分身克隆声往往不稳)。输出统一为竖屏:AV5 目前默认出横屏(人像居中两边灰边),脚本会自动裁回竖屏。
+"""
+import argparse, json, os, subprocess, sys, time
+
+API = 'https://api.heygen.com'
+
+
+def key():
+ k = os.environ.get('HEYGEN_API_KEY')
+ if not k: sys.exit('先 export HEYGEN_API_KEY=...(HeyGen 网页 → Settings → API)')
+ return k
+
+
+def curl(method, path, body=None, form=None):
+ cmd = ['curl', '-sS', '-X', method, API + path, '-H', f'X-Api-Key: {key()}']
+ if body is not None: cmd += ['-H', 'Content-Type: application/json', '-d', json.dumps(body, ensure_ascii=False)]
+ if form: cmd += ['-F', form]
+ out = subprocess.run(cmd, capture_output=True, text=True)
+ try: return json.loads(out.stdout)
+ except Exception: sys.exit(f'HeyGen 返回异常:{out.stdout[:300]} {out.stderr[:300]}')
+
+
+def upload(path):
+ mime = {'.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.m4a': 'audio/mp4'}
+ ext = os.path.splitext(path)[1].lower()
+ r = curl('POST', '/v3/assets', form=f'file=@{path};type={mime.get(ext, "application/octet-stream")}') # 必须 multipart 的 file 字段
+ d = r.get('data') or {}
+ if not d.get('asset_id'): sys.exit(f'上传失败:{r}')
+ return d
+
+
+def balance():
+ r = curl('GET', '/v3/users/me')
+ return ((r.get('data') or {}).get('wallet') or {}).get('remaining_balance')
+
+
+def submit_and_wait(body, out):
+ b = balance(); print(f'钱包余额:{b}(AV4 约 $0.04/秒,AV5 约 $0.12/秒)')
+ r = curl('POST', '/v3/videos', body)
+ vid = (r.get('data') or {}).get('video_id')
+ if not vid: sys.exit(f'提交失败:{r}')
+ print('已提交', vid, ',渲染中(通常几分钟)…')
+ for _ in range(180):
+ time.sleep(10)
+ s = (curl('GET', f'/v1/video_status.get?video_id={vid}').get('data') or {})
+ st = s.get('status')
+ if st == 'completed':
+ raw = out + '.raw.mp4'
+ subprocess.check_call(['curl', '-sSL', s['video_url'], '-o', raw]); to_vertical(raw, out); os.remove(raw)
+ print('完成 →', out); return
+ if st == 'failed': sys.exit(f'渲染失败:{s.get("error")}')
+ sys.exit(f'30 分钟还没完成,稍后用 video_id={vid} 自己查')
+
+
+def to_vertical(src, out):
+ w, h = map(int, subprocess.check_output(['ffprobe', '-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=width,height', '-of', 'csv=p=0', src]).decode().strip().split(','))
+ if h >= w:
+ os.replace(src, out); return
+ cw = int(h * 9 / 16) // 2 * 2 # 横屏里居中那条竖版人像
+ subprocess.check_call(['ffmpeg', '-v', 'error', '-y', '-i', src, '-vf', f'crop={cw}:{h}:{(w - cw) // 2}:0,scale=-2:1280',
+ '-c:v', 'libx264', '-crf', '18', '-c:a', 'copy', out])
+
+
+def speech(a):
+ if a.audio: return {'audio_asset_id': upload(a.audio)['asset_id']}
+ if a.script and a.voice: return {'script': a.script, 'voice_id': a.voice}
+ sys.exit('要么 --audio 口播音频,要么 --script 文案 + --voice 音色 id')
+
+
+ap = argparse.ArgumentParser(); sub = ap.add_subparsers(dest='cmd', required=True)
+sub.add_parser('balance')
+l = sub.add_parser('looks'); l.add_argument('--avatar-group', required=True)
+for name in ('av4', 'av5'):
+ p = sub.add_parser(name); p.add_argument('--out', required=True); p.add_argument('--audio'); p.add_argument('--script'); p.add_argument('--voice')
+ if name == 'av4': p.add_argument('--photo', required=True)
+ else: p.add_argument('--look', required=True)
+a = ap.parse_args()
+if a.cmd == 'balance':
+ print(balance())
+elif a.cmd == 'looks':
+ looks = (curl('GET', f'/v2/avatar_group/{a.avatar_group}/avatars').get('data') or {}).get('avatar_list', [])
+ for lk in looks:
+ lid = lk.get('id') or lk.get('avatar_id') # 接口里不同 look 用的字段名不一样
+ info = curl('GET', f"/v3/avatars/looks/{lid}").get('data') or {}
+ print(lid, lk.get('name') or info.get('name', ''), info.get('avatar_type', ''), info.get('supported_api_engines', ''))
+elif a.cmd == 'av4':
+ body = {'type': 'image', 'image': {'type': 'asset_id', 'asset_id': upload(a.photo)['asset_id']}, **speech(a),
+ 'motion_prompt': '自然亲和的口播,双手基本放在身前,几乎不抬手,保持冷静从容,微微点头', # 压手势,避免崩手指
+ 'expressiveness': 'low', 'aspect_ratio': '9:16', 'resolution': '1080p'}
+ submit_and_wait(body, a.out)
+else:
+ submit_and_wait({'type': 'avatar', 'avatar_id': a.look, **speech(a), 'engine': {'type': 'avatar_v'}}, a.out)
diff --git a/jianying/README.md b/jianying/README.md
new file mode 100644
index 0000000..001cf09
--- /dev/null
+++ b/jianying/README.md
@@ -0,0 +1,15 @@
+# 第 3 步(可选)· 推成剪映分层草稿,在剪映里微调
+
+第 2 步每次都会产出一份**分层工程包**(`<工程>/jianying/`):纸底 PNG、人像按状态切好的视频、信息层逐元素透明 PNG、原声、音效计划,以及一份剪映草稿计划 `plan.json`。
+
+把它变成剪映首页里能打开的草稿,需要第三方的草稿引擎 **jianying-headless**:https://github.com/mcncarl/jianying-headless
+- 它的协议是**个人学习、非商业使用**,本仓不附带它的任何代码,请按它的协议自行安装。
+- 它原生适配 Apple 芯片 Mac;我们在 Intel Mac + 剪映 11.5.0 上跑通过,但需要自己改一些地方(编译架构、固定哈希等)。建议让你的 agent 读它的 README 自己适配。
+- 装好后:`export JIANYING_HEADLESS_ROOT=<它的目录>`,skill 的 preflight 会检测到,交付时自动 build → verify → 登记到剪映首页。
+- 登记前**剪映主程序要完全退出**(托盘助手不影响),并备份剪映的 `root_meta_info.json`。
+
+## 草稿里有什么
+主轨纸底 → 证据底 → 人像(多段,带位置/缩放关键帧)→ 卡片 / 卡内图 / 荧光 / 标题 / 手绘各自成轨 → 原声 → 音效轨。
+动效会比渲染成片"素"一些:剪映引擎不收带透明通道的视频,信息层只能是透明图片 + 淡入淡出。所以我们同时交渲染成片。
+
+没有装引擎也没关系:你会拿到成片(音效已混进去)和分层工程包,素材都在,可以手动拖进任何剪辑软件。
diff --git a/skill/seecut/CHANGELOG.md b/skill/seecut/CHANGELOG.md
new file mode 100644
index 0000000..866c117
--- /dev/null
+++ b/skill/seecut/CHANGELOG.md
@@ -0,0 +1,76 @@
+# CHANGELOG
+
+## v3.2.1-beta(2026-09-25)· 开源同步前整理(维护者)
+- SKILL 第 0 步新增"先样片后全片":素材超过 60 秒先截 20-30 秒出样片,用户确认后再跑全片(作者定)。
+- README:agy 改为"Google 账号即可,免费有按周额度,AI Pro 额度更高"(依据 Antigravity 官方套餐页);修正交付描述(成片只带原声、音效进剪映草稿,没剪映引擎才混进成片,与 v3.0.1 一致)。
+- SKILL 第 6 步找方向:金锚集没有参考片时,改拿 03 决策表 + 05 质量地板对照找差距(开源版用户默认没有参考片)。
+- preflight:检查 node 版本 ≥ 22(HyperFrames 0.8.x engines 要求,npm view 实证)。
+- sfx.py:没有音效台账时给出建台账提示再退出(从开源版回灌)。
+- 开源仓改名 SeeCut,公开版由同步脚本(本地 seecut-sync/sync.py)从本地生成,不再手工改。
+
+## v3.2-beta(2026-09-24)· 剪映/数字人改为"指向不打包" + 音效接口开放
+- 剪映引擎改为**可选依赖**(只指向上游仓库,不分发):始终产出编辑器无关的**分层工程包**;装了引擎才登记剪映草稿。
+- **没装剪映引擎 → 音效直接混进渲染成片**(音效在推剪映之前就算好,不依赖剪映)。
+- 新增 `scripts/sfx_ledger.py`:用户自己的本地音效库一键建台账(起音点/第一下长度/共几下实测 + 文件名猜类别 + 可选 Gemini 试听);`sfx.py plan` 支持 `--ledger` `--sfx-dir`。实测与既有台账的起音点、段数一致。
+- 数字人:不在本仓,README 指向"用数字人服务生成口播 mp4 当素材"。
+- 定位名:网感口播精剪。
+
+## v3.1.1-beta(2026-09-23 晚)
+- 总纲第7条打码口径(作者定):来源标识默认打码;被讨论的产品名先保留,交付时问用户。
+
+## v3.1-beta(2026-09-23 21:0x)· 最终测试(Round2-4.2,2-2 素材)回灌
+依据:作者本地过程记录(未收录) 的 10 条 skill 问题(维护者逐条核,7 条修、3 条写进规范)。
+- 剪映:人像中途隐藏不再被当成过渡(隐藏段不出人像 + 淡出/淡入);30fps 时长按帧时刻换算、不超过媒体实测时长。两个工程回归 + 引擎 build/verify 通过。
+- 几何检查新增"被人像盖住"(拿 Round2-4.2 v2 快照验证:抓到 3.9s 两张字卡被挡)。
+- sfx.py:choices 支持单条 `gain_db`;`--fps` 必填(30fps 片子不再按 25 取整);已降 3dB 的重击不再报压字。
+- render.mjs:project.json `output_scale` 定终版分辨率(720 构图 → 1080 源片 = 1.5)。
+- grab_evidence 在工程根目录也能跑(会去 build/ 找依赖)。
+- 规范:图片素材执行窗自己读、视频走 agy;采纳对手 = 当前采纳版,输了但核心改动没被批评可在失败版上修;参考片全胜读不出方向时改问"参考片用了哪些手法";hw-write-title 不支持中文。
+
+## v3.0.1-beta(2026-09-23 19:45)· 作者微调
+- 渲染成片**不混音效**(像 v5b 那样直接出画面+原声);音效只放剪映草稿的音效轨。
+- **截图一律打码**(品牌/logo/人名/账号默认全模糊),用户说不用打再不打。
+- `render.mjs` 支持 `RENDER_SCALE=0.5`:迭代中间版半分辨率(实测 60 帧 23s→11s),终版全分辨率;长素材两两对比可挑改动最大的片段比。
+
+## v3.0-beta(2026-09-23 晚)· 交付剪映分层草稿 + 自动音效 + 迭代提效
+依据:2-4.1 首测全程(v1-v5、剪映草稿 A/B、音效试配)+ 作者验收("剪映能微调就算成功""有音效总比没有好""v2-v5 看不出区别""太慢")。详见作者本地决策记录(未收录) §十-§十五。
+- **两份交付**(总纲第16条):渲染成片(带音效)+ 剪映分层草稿(带音效轨)。
+- **剪映分层**:新增 `scripts/jianying_layers.mjs`(按 `data-layer` 打标自动拆:纸底 PNG / 人像按状态切视频 / 信息层逐元素透明 PNG / 原声 / 音效候选事件)+ `scripts/jianying_plan.py`(生成 jy14 plan、证据底在人像下、淡入提前 1 帧、可选 ffmpeg 预览)+ `references/10-剪映分层工程.md`。由 2-4.1 手工脚本通用化;在 2-4.1 工程上回归:38 段 / 3 个人像状态 / 18 轨,与手工版一致,并修了"证据底压在人像上"的层级问题。
+- **音效**:新增 `scripts/sfx.py`(plan:起音点裁剪/只取第一下/偏移+取整到帧/按人声峰值定音量/检查开头抓耳、密度、低频压字、慎用、重复;mix:混进成片)+ `references/09-音效规范.md` + `references/sfx/音效库台账`(39 个,起音点按峰值 10%)。作者要求:开头 0.5 秒内必须有抓耳音效。
+- **迭代提效**:版本上限 5→3;每版必须改一处"对照参考片的大差距",硬伤小修补合并进同一版;每 15 分钟写一行进度。
+- **总纲第7条**:负面语境不点名第三方品牌/课程/个人(截图打码)。
+- preflight 增加剪映引擎、音效库检查。
+
+## v2.1-beta(2026-09-23 晚)· 首测(2-4.1 / Round2-5)回灌
+依据:作者本地过程记录(未收录) 交付报告 + runlog"skill 问题"10 条(维护者逐条复核)。
+- 🔴 **评委隔离**:`agy_judge.py` 临时目录从调用处 cwd 改到系统 tmp,prompt 追加"不要读其它文件"(首测实证:评委读到了 master.html/runlog,评判被源码污染)。
+- **指纹核**:比对源 = 源码文字 + 同目录 `fp-manifest.txt`(证据图里的字,读图核敏感字时顺手记)+ `--fp-extra`(首测:agy 照抄截图字被误判编造,v2 vs v1 因此无效)。
+- **退出码/授权**:0 通过、1 有 FAIL、2 无结果(不再写出"看着像结果"的空 json)、3 agy 授权过期→停下找用户。
+- **官方组件库升为硬规则**(总纲第11条、`04` 选卡列):必须写 registry 组件名或"库里没有:原因";preflight 用 `npx -y hyperframes@latest` 探测、失败=预检不过;自动补大写 `HTTPS_PROXY`(CLI 只认大写)。
+- 新增 `assets/hf-hw/`:首测抽好的 HF 手绘三件(hw-callout-circle / hw-underline / hw-arrow,Apache-2.0)+ 接线说明(墨色覆盖、callout label 慢 1.4s、hw-arrow 太小)。
+- 新增 `scripts/agy_read.sh`(素材理解用 agy:隔离 + 超时 + 禁 OCR 子任务)。
+- **评审提速**(根因实证:首测 21 次 agy 调用 9 次败于接口断连/超时,每次白等 2-9 分钟,占掉近 1 小时):超时 540s→240s;接口报错/超时判为瞬时错误立即重试(最多 3 次,不算内容无效);pair 两序并行;直接读 agy 的 `structured_output`。实测同一组 v4 vs v3:29 分钟 → 110 秒,结论不变。
+- `render.mjs` 时长护栏区分"动画比视频长(尾部溢出,不影响)"与"比视频短"。
+
+## v2.0-beta(2026-09-23)· 顶层重构:生产与质检统一到"复刻参考风格"
+依据:作者本地记录(未收录) + 校准实验 `agy验收留档/08、09`。
+
+**为什么改**
+- v1 的 agy "像参考片几成"分数与用户肉眼反向(2-3.1:干净 v3 35% / 假满屏 v7.3 68%;用户判 v3 好),同片两次打分差 20 分,修真 bug 分数不动 → 无法当迭代信号。
+- 生产端(设计令牌 §3"默认干净")跟着素人尺走,质检端(agy spec"满屏镜像/死磕95")跟着参考片尺走 → 两把尺分家。
+- 素人 prompt 给参考原片 62/45 分、给干净仿制品 90 分:它量的是"清爽克制",不是参考片。
+- 当年判丑的"满屏"是**假证据满屏**;错的是"假",不是"满"。
+
+**改了什么**
+- 新增 `references/00-总纲.md`:15 条最高规则 + 信源优先级(原片 > 逐拍拆解 > 决策表/方法论 > 设计令牌)。
+- 背景规则(`02` §3):有据段铺真证据(满屏是正常做法)/ 无据段半身或干净底 / **禁假证据**;撤销"默认干净、真素材执行窗不主动够"。
+- 新增"找真证据"环节(SKILL 第3步、`04` 证据计划列、`scripts/grab_evidence.mjs`、敏感字读图核)。
+- 素材分类(`02` §6.5):按"有没有完整口播人像 A-roll"分,数字人完整半身归①。
+- 质检:`06-agy自闭环质检spec` → `06-质检闭环spec`。硬门 H1 几何 + H2 硬伤清单;采纳用两两对比(交换位置两次一致才算);参考片只找差距不打分;停止条件 = 连续 2 次不胜或到 v5;删除百分比阈值、"死磕95"、"维护者"熔断。
+- 评委:删 `prompt/放开挑刺.md`、`prompt/素人评测.md`;新增 `prompt/对比评委.txt`、`prompt/硬伤清单.txt` + JSON schema。
+- 脚本:删 `capv3`/旧 `render`/旧 `geom-check`/`run_agy_safe.sh`(路径写死);新增 `_common.mjs`、`render.mjs`、`geom-check.mjs`(读 `project.json`,无写死路径)、`agy_judge.py`(`--new-project` + schema + 指纹核 + 时长核 + 交换位置共识)、`preflight.sh`。几何自检把"无弹簧"从提示升为 FAIL。
+- 金锚集:用途改为"学手法 + 找差距";新增锚9(样本04 半身分屏定调);按"功能 + 有据/无据 + 人像形态"挑锚。
+
+
+## v1.0(2026-09-22)
+首版封装(2-4 冒烟测试所用)。
diff --git a/skill/seecut/README.md b/skill/seecut/README.md
new file mode 100644
index 0000000..1ff45a0
--- /dev/null
+++ b/skill/seecut/README.md
@@ -0,0 +1,48 @@
+# SeeCut skill(网感口播精剪)
+
+把口播视频(真人或数字人出镜 + 截图/录屏/B-roll)自动剪成网感动效短视频:口播打底,把画面让给高密度信息层(**真实证据** + chip/卡/大字 + 手绘/撕纸/像素手作 + 弹簧动效),人像按"对你说露、给你看藏"调度。
+
+自循环:预检 → 素材理解 → 找真证据 → 编排 → HyperFrames 构建 → 硬门 + 两两对比自迭代(≤3 版)→ 配音效 → 交付 → 你肉眼终审。
+交付:**渲染成片 + 分层工程包**;装了剪映引擎再出**剪映分层草稿**(音效放草稿音效轨,成片只带原声),没装则音效混进成片。
+
+## 用法
+把本目录放进 `~/.claude/skills/seecut/`,新开对话:
+```
+/seecut 素材:<你的素材文件夹>
+```
+素材超过 60 秒时,skill 会先剪开头 20-30 秒样片给你确认,再跑全片。字幕、BGM 请在剪映等编辑器里自己补。
+
+## 依赖
+见仓库根目录 README 的"开始之前";`scripts/preflight.sh` 会逐项检查。
+
+## 结构
+```
+SKILL.md 入口:自循环步骤
+CHANGELOG.md 规则变更记录
+references/
+ 00-总纲.md ★最高规则 + 信源优先级(冲突以它为准)
+ 01-方法论 / 03-编排层决策表 风格拆解结论("这句话是什么功能 → 画面怎么处理")
+ 02-设计令牌 色/字/动效/背景选底规则/人像/素材类型
+ 04-SHOTBOOK施工规格 逐镜编排(含有据/无据 + 证据计划)
+ 05-视觉质量地板 / 08-避坑SOP 护栏与渲染铁律
+ 06-质检闭环spec 硬门 H1/H2 + 两两对比 + 停止条件(含校准实证)
+ 07-几何规则自检spec 几何规则 + project.json 配置契约
+ 09-音效规范 落点/映射/对齐/密度音量(配 sfx.py)
+ 10-剪映分层工程 打标契约/流程/能力边界(配 jianying_layers + jianying_plan)
+ prompt/ 对比评委.txt / 硬伤清单.txt
+ 金锚集/ 可选:你自备的参考片
+ sfx/ 你的音效台账放这里(sfx_ledger.py 生成)
+assets/hf-hw/ HyperFrames 官方手绘组件(圈注/下划线/箭头)可嵌入版
+scripts/
+ preflight.sh 开工预检
+ render.mjs 逐帧渲染
+ geom-check.mjs 几何自检(硬门 H1)
+ agy_judge.py AI 评委:check 硬伤清单 / pair 两两对比(交换位置求共识)
+ agy_read.sh 素材理解:agy 读单个文件
+ grab_evidence.mjs 截真网页当证据
+ sfx.py / sfx_ledger.py 音效:建台账、对齐、检查、混音
+ jianying_layers.mjs / jianying_plan.py 分层工程包 → 剪映草稿 plan
+ schemas/ 评委 JSON schema
+```
+
+说明:文档里的"参考片"指作者拆解时用的同风格样片(不随仓分发);"作者/维护者"指本仓作者;文中提到的 Round2-x 等是作者本地的测试轮次记录,未收录。
diff --git a/skill/seecut/SKILL.md b/skill/seecut/SKILL.md
new file mode 100644
index 0000000..0c03c08
--- /dev/null
+++ b/skill/seecut/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: seecut
+description: 网感口播精剪(v3.2):口播视频加动效,自动剪成"网感口播精剪风格"竖版/横版样片,交付渲染成片+分层工程包(装了剪映引擎则再出剪映分层草稿,音效放草稿;没装则音效混进成片)。当用户给了口播粗剪(+B-roll/截图/录屏)并想要"口播动效/加卡片弹字/剪成短视频/做动效样片/网感口播精剪"时用。自循环:预检→素材理解→找真证据→编排→HyperFrames构建→硬门+两两对比自迭代(≤3版)→配音效→交付→用户终审。不做:纯字幕/纯配音/纯生图/BGM。
+---
+
+# SeeCut v3.2 · 网感口播精剪(口播动效自动剪辑)
+
+把口播粗剪 + 素材,剪成"网感口播精剪风格"动效样片:数字人/真人口播打底,把画面让给高密度信息层(**真实证据** + chip/卡/大字 + 手作质感 + 弹簧动效),人像按"对你说露、给你看藏"调度。**你(执行窗)自己跑完整循环,交两份东西给用户终审:渲染成片(原声,不混音效)+ 剪映分层草稿(带音效轨)。长任务每 15 分钟往 runlog 写一行进度。**
+
+## 0 · 开工前(必做)
+1. **读** `references/00-总纲.md`(16 条,全 skill 最高规则;其它文件与它冲突时以它为准并在报告里指出)+ `references/08-避坑SOP.md`(渲染铁律)。
+2. **预检**:`export JIANJI_PROXY=http://127.0.0.1:1087` 后 `zsh scripts/preflight.sh` —— 必需项缺失就先装或报告用户,别跑到一半才发现。hyperframes CLI 走 npx,是必需项(官方组件库靠它)。
+3. 建工程目录(素材、`build/`、`qc/`、文档都放这里),`cd build && npm i playwright-core`(别 sudo)。
+4. **先样片后全片**:素材超过 60 秒时,先截开头 20-30 秒跑完整循环出样片,交用户确认风格和方向后再跑全片(一次循环会出 2-3 版,全片耗时随时长和版本数一起涨,方向错了代价很大)。用户明确说直接出全片则跳过。
+
+## 1 · 素材理解 → `素材台账.md`
+- **视频素材**用 agy 读:`zsh scripts/agy_read.sh <文件> "<问题>"`(已含新项目隔离、超时、禁 OCR 子任务;长视频先切 ≤25s 段、降 540p),别只抽帧。**图片素材**执行窗自己读图(更准,也顺便逐张核敏感字、记 fp-manifest)。
+- 判人像素材类型(`02` §6.5):①半身口播(真人或数字人完整半身 A-roll)/ ②角落圆 PIP / ③点缀型数字人。
+- 若 `references/金锚集/` 里有你自备的参考片,按功能挑 1-2 条看一遍;没有就跳过。
+
+## 2 · 转写 → 词级时间轴
+faster_whisper(small) 词级转写 → `seg_words.json`,转一次就沉淀。动效锚关键词被说出的那一帧(非句首)。
+
+## 3 · 找真证据(v2 新增,参考片密度的来源)
+- 逐句标"有据/无据":提到真实产品/网页/文档/数据/操作 = 有据。
+- 有据句按顺序拿证据:用户素材 → `node scripts/grab_evidence.mjs <素材目录> <url>...` 截真网页(在 build/ 下或工程根目录跑都行)→ 自己录屏;3D 比喻/场景图可 Grok 生成(不能当"真界面"用)。
+- **每张截图入片前读图核敏感字**(总纲第 7 条),同时把图里看得清的字逐行记进 `build/fp-manifest.txt`(评委指纹核要用);拿不到的列进"证据缺口清单"(`04` 第3步),按 `02` §3 第4条退回无据打法。
+- **禁假证据**:不许用占位窗口/伪代码网格/假 Mac/假 App 界面冒充或"填满"(总纲第 5 条)。
+
+## 4 · SHOTBOOK 编排(`references/04-SHOTBOOK施工规格.md`)
+逐镜填:功能(`03` 决策表)→ 有据/无据 + 证据计划 → 人像层/信息层 → 选卡(**必须写 registry 组件名或"库里没有:原因"**,`npx -y hyperframes@latest catalog`;手绘件用 `assets/hf-hw/`)→ 背景底(`02` §3:有据铺真证据、无据半身或干净底)→ 镜内变化 → 动效 → 衔接。
+
+## 5 · 构建(HyperFrames HTML/GSAP,守 08 避坑SOP)
+- 人像 ffmpeg 预抽逐帧 JPG + `<img>` 换 src(禁 video scrub);GSAP 主时间轴暴露为 `window.__timelines.master`;某刻才出现的元素 CSS `opacity:0` + `.set`/`.to`(禁 `.from`)。
+- 给元素打标 `data-check="box|bg"` / `data-anchor` / `data-word`+`data-t`(几何自检用),**以及 `data-layer`/`data-layer-cat`(剪映分层用,契约见 `10`)**;写 `build/project.json`(契约见 `07` §配置契约,另加 `"source": 口播源片路径`)。
+- 渲染:`node scripts/render.mjs build probe`(抽帧看)→ `full` → ffmpeg 合成源音轨。**迭代中间版用 `RENDER_SCALE=0.5`**(实测快一倍);**终版分辨率 = 源片分辨率**:构图按 720 宽写、源片 1080 宽时,在 project.json 写 `"output_scale": 1.5`,终版不设 RENDER_SCALE 就按它出。
+
+## 6 · 质检闭环(`references/06-质检闭环spec.md`)
+每版 vN:
+1. **硬门 H1**:`node scripts/geom-check.mjs build`(撞位/压人像/圈锚/无脸/抢拍/弹簧)→ 有 FAIL 先改。
+2. **硬门 H2**:`python3 scripts/agy_judge.py check --video vN.mp4 --html build/master.html --out qc/vN-check.json`(假证据/版面/人像乱跳/读不完/敏感字/空拍)→ 有 FAIL 先改;agy 报的 FAIL 先抽帧核实。
+3. **采纳判定**:`python3 scripts/agy_judge.py pair --a vN.mp4 --b vN-1.mp4 --html-a ... --out qc/vN-vs-prev.json` → consensus=A 采纳;B 回退;tie 平手。
+4. **找方向**:`pair --a vN.mp4 --b <同类参考片>`,只读各维度差距证据当下一版改动清单。`金锚集/` 里没有参考片时,改为拿 `03` 决策表 + `05` 质量地板逐条对照 vN,列出差距最大的 1-2 处当改动清单。
+5. **停**:硬门全过 且(对比不胜上一版 或 到 **v3** 或 只剩肉眼看不出的小修补)→ 进入交付。每一版必须至少改一处第4步找出的大差距,小修补合并进同一版。**不追任何百分比,不自判"够了",也不无限死磕**;卡住就带证据报告用户。
+**agy(Antigravity)是必需项**:AI 看视频做质检和自迭代是本管线的核心,不提供无 agy 的降级模式;preflight 里 agy 不通就先修好再开工。
+(代理:`export JIANJI_PROXY=http://127.0.0.1:1087` 或按本机 VPN 端口。agy_judge 退出码 2=无结果、3=agy 要重新登录→停下找用户。)
+
+## 7 · 音效(`references/09-音效规范.md`)
+1. 从 `jianying/layers/manifest.json` 的 `events`(先跑第 8 步的 `jianying_layers.mjs`)+ SHOTBOOK 语义挑落点,写 `sfx_choices.json`(开头 0.5 秒内必须有一个 `hook`)。
+2. `python3 scripts/sfx.py plan --choices sfx_choices.json --voice jianying/layers/原声.m4a --words seg_words.json --fps <帧率> --duration <秒> --out sfx_plan.json` → 有 ⚠ 就改 choices 重跑(压字可在 choices 里给该条写 `"gain_db": -3`)。
+3. 有剪映引擎:音效只进剪映草稿(第 8 步 `--sfx`),成片只带原声。**没有剪映引擎:`python3 scripts/sfx.py mix --plan sfx_plan.json --video 成片.mp4 --out 成片_带音效.mp4`**,交带音效的成片。
+- 用户自己的音效库:`python3 scripts/sfx_ledger.py <音效文件夹> --out 台账.json [--listen]` 生成台账,之后 `sfx.py plan` 加 `--ledger 台账.json --sfx-dir <音效文件夹>`。
+
+## 8 · 分层工程包 → 剪映分层草稿(`references/10-剪映分层工程.md`;剪映引擎可选,没装就交分层工程包 + plan,跳过第 3 步)
+1. `node scripts/jianying_layers.mjs build` → 纸底 / 人像分状态视频 / 信息层透明 PNG / 原声 / 候选事件。
+2. `python3 scripts/jianying_plan.py jianying/layers/manifest.json --name "<片名>_分层工程" --out jianying/plan.json --sfx sfx_plan.json --preview jianying/preview.mp4` → 预览和成片同时间点抽帧对比。
+3. jianying-draft 引擎 build → verify-build → publish(剪映主程序须退出;先备份 root_meta_info.json;publish 后核对首页 +1、原有条目未变)。
+
+## 9 · 交付
+- `~/Downloads/<片名>_vN.mp4`(渲染成片,全分辨率;有剪映引擎时只带原声,没有时带音效)+ 分层工程包(`jianying/`)+(有剪映引擎时)剪映首页「<片名>_分层工程」草稿(带音效轨)。ffmpeg 预览若也放出来,文件名注明"非剪映原生导出"。
+- 报告(`06` §六):每版硬门与对比结论 + 改了什么;证据拿到/没拿到 + 敏感字核查 + 截图打码核查;音效清单与 ⚠ 处理;剪映草稿轨道说明;agy 误报清单;需要用户定的主观项。**用户肉眼终审为准。**
+
+## 依赖
+见 `README.md`。改规则请改 `references/00-总纲.md` 或对应文件并记 `CHANGELOG.md`。
diff --git a/skill/seecut/assets/hf-hw/README.md b/skill/seecut/assets/hf-hw/README.md
new file mode 100644
index 0000000..af40d24
--- /dev/null
+++ b/skill/seecut/assets/hf-hw/README.md
@@ -0,0 +1,19 @@
+# hf-hw · HF 官方手绘组件的可直接嵌入版
+
+来源:HyperFrames 官方 registry(github.com/heygen-com/hyperframes,Apache-2.0)的 `hw-callout-circle` / `hw-underline` / `hw-arrow` 组件 helper,**原样抽出、去掉了 self-preview**(2-4.1 实测可用,手作感明显好于手写 SVG)。字体 Caveat(OFL)。
+
+## 为什么需要这层
+registry 组件是独立 composition 形态(自带预览、自己注册 `__timelines`),不能直接塞进我们的单文件 master。这里已经抽好,拷进工程即可。
+
+## 用法
+1. `cp -r <skill>/assets/hf-hw <build>/lib/`
+2. master.html:`<link rel="stylesheet" href="lib/hf-hw/hf-hw.css">`,GSAP 之后 `<script src="lib/hf-hw/hf-hw.js"></script>`。
+3. 结构和调用照抄 `npx -y hyperframes@latest add hw-callout-circle` 生成的示例 HTML;时间轴里 `tl.set(sel,{opacity:0},0); tl.set(sel,{opacity:1},t); hwCalloutOn(tl, sel, t);`
+4. **必须覆盖墨色**(默认 #f4f2ec 是给深色底的,米白底上看不见):
+ `.hw-callout{--hw-co-ink:var(--red);--hw-co-accent:var(--amber);} .hw-arrow{--hw-arrow-color:var(--red);}` 标记线用 `--hw-mark-color`。
+5. **callout 的 label 很慢**:外圈→涂鸦→连线画完才弹 label(约 1.4s)。≤2s 的镜头要关掉 scribble、提前起笔,或者不用 label。
+6. `hw-arrow` 在 720 宽竖版里默认尺寸偏小,像红点——至少 150px 宽,或换 `hw-underline`。
+7. `hw-write-title` 只有 Caveat 拉丁字形,**中文手写做不了**;中文手写气泡目前手搭(在 SHOTBOOK 写明原因)。
+
+## 其它 registry 组件
+`npx -y hyperframes@latest catalog` 查全表(需大写 `HTTPS_PROXY`);装上后若是带自预览的 composition,照本目录的办法抽 helper,并把抽好的版本也补进本目录,下次直接用。
diff --git a/skill/seecut/assets/hf-hw/fonts/Caveat-700-latin.woff2 b/skill/seecut/assets/hf-hw/fonts/Caveat-700-latin.woff2
new file mode 100644
index 0000000..5a34234
Binary files /dev/null and b/skill/seecut/assets/hf-hw/fonts/Caveat-700-latin.woff2 differ
diff --git a/skill/seecut/assets/hf-hw/hf-hw.css b/skill/seecut/assets/hf-hw/hf-hw.css
new file mode 100644
index 0000000..68f36ac
--- /dev/null
+++ b/skill/seecut/assets/hf-hw/hf-hw.css
@@ -0,0 +1,126 @@
+@font-face{font-family:"Caveat";src:url("fonts/Caveat-700-latin.woff2") format("woff2");font-weight:700;}
+/* ==== hw-callout-circle ==== */
+
+
+
+
+ /* ---- hw-callout-circle ----------------------------------------------
+ The full callout anatomy: wobbled ellipse outline draws around a
+ target, optional scribble fill sketches in, a curved connector leads
+ to a handwritten label that POPS in with momentum — the drawn shapes
+ absorb the arrival with a volume-preserving contact squash (g21).
+ Ships the full family runtime it needs (hw-boil + boil poses +
+ stroke matrix + springEase) — copy the helpers once per host.
+ WRAPPER RULES: boil owns x/y/rotation of .hw-co-boil; the squash
+ deforms .hw-co-deform (outline + scribble only); the label rides
+ the uniform-scale .hw-co-pop OUTSIDE the deform — non-uniform
+ scale never reaches glyphs. One timeline has ONE onUpdate
+ (everything registers through hwOnUpdate). */
+ .hw-callout {
+ position: absolute;
+ pointer-events: none;
+ }
+ .hw-callout .hw-co-boil,
+ .hw-callout .hw-co-deform,
+ .hw-callout .hw-co-conn-layer,
+ .hw-callout .hw-co-pop {
+ position: absolute;
+ inset: 0;
+ }
+ .hw-callout .hw-co-pop {
+ opacity: 0;
+ }
+ .hw-callout svg {
+ width: 100%;
+ height: 100%;
+ overflow: visible;
+ }
+ .hw-callout path {
+ fill: none;
+ stroke-linecap: round;
+ stroke-linejoin: round;
+ }
+ .hw-callout .hw-co-outline {
+ stroke: var(--hw-co-ink, var(--hw-ink, #f4f2ec));
+ stroke-width: var(--hw-co-w, 6);
+ }
+ .hw-callout .hw-co-scribble {
+ /* Warm marker accent to match hw-frame / hw-title / hw-underline; the
+ previous blue read as a default UI colour. Lighter weight and alpha
+ so the hatch sits behind the labelled subject instead of over it. */
+ stroke: var(--hw-co-accent, var(--hw-accent, #ffb020));
+ stroke-width: 3;
+ opacity: 0.42;
+ }
+ .hw-callout .hw-co-connector {
+ stroke: var(--hw-co-ink, var(--hw-ink, #f4f2ec));
+ stroke-width: 4;
+ }
+ .hw-callout .hw-co-label {
+ position: absolute;
+ font-family: var(--hw-font-print, "Caveat", cursive);
+ font-weight: 700;
+ font-size: 54px;
+ color: var(--hw-co-ink, var(--hw-ink, #f4f2ec));
+ white-space: nowrap;
+ text-shadow: 0 2px 14px rgba(0, 0, 0, 0.45);
+ }
+
+/* ==== hw-underline ==== */
+
+
+
+
+ /* ---- hw-underline ------------------------------------------------
+ Squiggle underline / strikethrough / bracket marks that draw on.
+ Size the wrapper over the text they annotate. Requires the hw-boil
+ helpers in the host. */
+ .hw-mark {
+ position: absolute;
+ pointer-events: none;
+ }
+ .hw-mark svg {
+ width: 100%;
+ height: 100%;
+ overflow: visible;
+ }
+ .hw-mark path {
+ fill: none;
+ stroke: var(--hw-mark-color, var(--hw-accent-warm, #ffb020));
+ stroke-width: var(--hw-mark-w, 7);
+ stroke-linecap: round;
+ stroke-linejoin: round;
+ }
+
+/* ==== hw-arrow ==== */
+
+
+
+
+ /* ---- hw-arrow ------------------------------------------------------
+ Hand-wobbled draw-on arrow, boiling, with a travel-aligned
+ arrival stretch on the head. Position the wrapper, build with a
+ CONFIG (arrowStyle / strokeType / boil), wire with a position
+ only: hwArrowBuild + hwArrowOn / hwArrowOff. Requires the hw
+ family helpers below (hwOnUpdate / hwHash / hwBoil / hwBoilPose /
+ springEase / hwStrokeApply / hwDrawOn) in the host script. */
+ .hw-arrow {
+ position: absolute;
+ pointer-events: none;
+ }
+ .hw-arrow svg {
+ width: 100%;
+ height: 100%;
+ overflow: visible;
+ }
+ .hw-arrow path {
+ fill: none;
+ stroke: var(--hw-arrow-color, var(--hw-ink, #f4f2ec));
+ stroke-width: var(--hw-arrow-w, 6);
+ stroke-linecap: round;
+ stroke-linejoin: round;
+ }
+ .hw-arrow.hw-soft path {
+ filter: blur(0.6px);
+ }
+
\ No newline at end of file
diff --git a/skill/seecut/assets/hf-hw/hf-hw.js b/skill/seecut/assets/hf-hw/hf-hw.js
new file mode 100644
index 0000000..b0a07d6
--- /dev/null
+++ b/skill/seecut/assets/hf-hw/hf-hw.js
@@ -0,0 +1,1077 @@
+/* ==== from HF registry: hw-callout-circle (helpers verbatim, self-preview removed) ==== */
+(function(){
+ window.hwOnUpdate = function (tl, fn) {
+ if (!tl.__hwRenders) {
+ tl.__hwRenders = [];
+ tl.eventCallback("onUpdate", function () {
+ for (var i = 0; i < tl.__hwRenders.length; i++) tl.__hwRenders[i]();
+ });
+ }
+ tl.__hwRenders.push(fn);
+ fn();
+ };
+ window.hwHash = function (n, seed) {
+ var x = Math.sin(n * 127.1 + (seed || 1) * 311.7) * 43758.5453;
+ return (x - Math.floor(x)) * 2 - 1;
+ };
+ window.hwBoil = function (tl, target, opts) {
+ opts = opts || {};
+ var amp = opts.amp !== undefined ? opts.amp : 1.6;
+ var rot = opts.rot !== undefined ? opts.rot : 0.5;
+ var fps = opts.fps || 30;
+ var drop = opts.frameDrop || 3;
+ var seed = opts.seed || 1;
+ var els = gsap.utils.toArray(target);
+ window.hwOnUpdate(tl, function () {
+ var step = Math.floor((tl.time() * fps) / drop);
+ for (var i = 0; i < els.length; i++) {
+ gsap.set(els[i], {
+ x: window.hwHash(step * 3 + i * 97, seed) * amp,
+ y: window.hwHash(step * 3 + 1 + i * 97, seed) * amp,
+ rotation: (opts.baseRot || 0) + window.hwHash(step * 3 + 2 + i * 97, seed) * rot,
+ });
+ }
+ });
+ };
+ // boil control: authored poses over the family-locked frameDrop.
+ // Unknown pose → default + console error (bounded-controls law).
+ window.hwBoilPose = function (tl, target, pose, opts) {
+ opts = opts || {};
+ var poses = { calm: { amp: 1.6, rot: 0.5 }, lively: { amp: 2.6, rot: 0.9 } };
+ if (pose === "off") return;
+ var p = poses[pose];
+ if (!p) {
+ console.error('hw: unknown boil pose "' + pose + '" — falling back to "calm"');
+ p = poses.calm;
+ }
+ window.hwBoil(tl, target, { amp: p.amp, rot: p.rot, frameDrop: 3, seed: opts.seed || 1 });
+ };
+ /* ---- spring library (spring-lab, validated 2026-08-04 — verbatim) ---- */
+ var LN1000 = Math.log(1000);
+ var FEELS = {
+ snappy: { zeta: 0.9, response: 0.22 },
+ "heavy-settle": { zeta: 1.0, response: 0.8 },
+ bouncy: { zeta: 0.5, response: 0.4 },
+ wobbly: { zeta: 0.28, response: 0.5 },
+ };
+ window.springEase = function (opts) {
+ var f = opts.feel ? FEELS[opts.feel] : opts;
+ var zeta = f.zeta,
+ response = f.response;
+ var w0 = (2 * Math.PI) / response;
+ var T = LN1000 / (zeta * w0);
+ var x;
+ if (zeta < 1) {
+ var wd = w0 * Math.sqrt(1 - zeta * zeta);
+ x = function (t) {
+ return (
+ 1 -
+ Math.exp(-zeta * w0 * t) *
+ (Math.cos(wd * t) + ((zeta * w0) / wd) * Math.sin(wd * t))
+ );
+ };
+ } else {
+ x = function (t) {
+ return 1 - Math.exp(-w0 * t) * (1 + w0 * t);
+ };
+ }
+ var xT = x(T);
+ return {
+ ease: function (p) {
+ return p >= 1 ? 1 : x(p * T) / xT;
+ },
+ duration: T,
+ zeta: zeta,
+ response: response,
+ };
+ };
+ window.hwWobbleEllipse = function (cx, cy, rx, ry, seed, wobblePct) {
+ wobblePct = wobblePct === undefined ? 3 : wobblePct;
+ var N = 14,
+ pts = [];
+ for (var i = 0; i < N; i++) {
+ var a = (i / N) * Math.PI * 2;
+ var wr = 1 + window.hwHash(i * 13 + 5, seed) * (wobblePct / 100);
+ pts.push([cx + Math.cos(a) * rx * wr, cy + Math.sin(a) * ry * wr]);
+ }
+ var mx = (pts[0][0] + pts[N - 1][0]) / 2,
+ my = (pts[0][1] + pts[N - 1][1]) / 2;
+ var d = "M" + mx.toFixed(1) + " " + my.toFixed(1);
+ for (var j = 0; j < N; j++) {
+ var p = pts[j],
+ q = pts[(j + 1) % N];
+ d +=
+ " Q" +
+ p[0].toFixed(1) +
+ " " +
+ p[1].toFixed(1) +
+ " " +
+ ((p[0] + q[0]) / 2).toFixed(1) +
+ " " +
+ ((p[1] + q[1]) / 2).toFixed(1);
+ }
+ return d;
+ };
+
+ /* ---- stroke matrix (family runtime): plain | soft | sharp | spray ----
+ strokeType is a g09 variant control. Authored constants per type;
+ unknown value → default ("plain") + console error (bounded-controls
+ law). sharp = micro stroke-dasharray gaps (dry marker) — draw-on
+ must therefore ride a MASK clone (the visible dasharray never
+ animates). spray = index-seeded deterministic dots along the path
+ via hwHash: position a pure function of path parameter + seed; NO
+ feTurbulence anywhere.
+ Returns { draw: pathToDashAnimate, group: maskedGroupOrNull } */
+ window.hwStrokeTypes = {
+ plain: {},
+ soft: { blur: 0.6 },
+ sharp: { dash: [3.0, 1.55] }, // × stroke-width
+ spray: {
+ coreOpacity: 0.5,
+ coreBlur: 0.4,
+ density: 0.16,
+ scatter: 2.6,
+ rMin: 1.1,
+ rMax: 2.6,
+ },
+ };
+ window.hwStrokeApply = function (pathEl, type, opts) {
+ opts = opts || {};
+ var cfg = window.hwStrokeTypes[type];
+ if (!cfg) {
+ console.error('hw: unknown strokeType "' + type + '" — falling back to "plain"');
+ type = "plain";
+ cfg = window.hwStrokeTypes.plain;
+ }
+ var svg = pathEl.ownerSVGElement;
+ var ns = "http://www.w3.org/2000/svg";
+ var w = parseFloat(getComputedStyle(pathEl).strokeWidth) || 6;
+ if (type === "plain") return { draw: pathEl, group: null, type: type };
+ if (type === "soft") {
+ pathEl.style.filter = "blur(" + cfg.blur + "px)";
+ return { draw: pathEl, group: null, type: type };
+ }
+ // sharp + spray: wrap in a masked group, draw-on animates the mask clone
+ var id =
+ opts.id ||
+ "hwsm-" + Math.abs(Math.round(window.hwHash((opts.seed || 1) * 13.7, 5) * 1e6));
+ var defs = svg.querySelector("defs");
+ if (!defs) {
+ defs = document.createElementNS(ns, "defs");
+ svg.insertBefore(defs, svg.firstChild);
+ }
+ var mask = document.createElementNS(ns, "mask");
+ mask.setAttribute("id", id);
+ mask.setAttribute("maskUnits", "userSpaceOnUse");
+ var clone = document.createElementNS(ns, "path");
+ clone.setAttribute("d", pathEl.getAttribute("d"));
+ clone.setAttribute("fill", "none");
+ clone.setAttribute("stroke", "#fff");
+ clone.setAttribute(
+ "stroke-width",
+ w * (type === "spray" ? 2 + (cfg.scatter * 2) / w : 1.7),
+ );
+ clone.setAttribute("stroke-linecap", "round");
+ clone.setAttribute("stroke-linejoin", "round");
+ mask.appendChild(clone);
+ defs.appendChild(mask);
+ var group = document.createElementNS(ns, "g");
+ group.setAttribute("mask", "url(#" + id + ")");
+ pathEl.parentNode.insertBefore(group, pathEl);
+ group.appendChild(pathEl);
+ if (type === "sharp") {
+ pathEl.setAttribute(
+ "stroke-dasharray",
+ (cfg.dash[0] * w).toFixed(1) + " " + (cfg.dash[1] * w).toFixed(1),
+ );
+ } else {
+ // spray: faint core + seeded dots
+ pathEl.setAttribute("stroke-opacity", cfg.coreOpacity);
+ pathEl.style.filter = "blur(" + cfg.coreBlur + "px)";
+ var len = pathEl.getTotalLength();
+ var n = Math.round(len * cfg.density * (opts.densityScale || 1));
+ var seed = opts.seed || 1;
+ var dots = document.createElementNS(ns, "g");
+ for (var i = 0; i < n; i++) {
+ var t = Math.min(
+ 1,
+ Math.max(0, (i + 0.5) / n + (window.hwHash(i * 7, seed) * 0.35) / n),
+ );
+ var pt = pathEl.getPointAtLength(t * len);
+ var pt2 = pathEl.getPointAtLength(Math.min(len, t * len + 0.5));
+ var tx = pt2.x - pt.x,
+ ty = pt2.y - pt.y;
+ var tl2 = Math.hypot(tx, ty) || 1;
+ var nx = -ty / tl2,
+ nyv = tx / tl2;
+ var off = window.hwHash(i * 7 + 1, seed) * (cfg.scatter + w * 0.55);
+ var r = cfg.rMin + Math.abs(window.hwHash(i * 7 + 2, seed)) * (cfg.rMax - cfg.rMin);
+ var c = document.createElementNS(ns, "circle");
+ c.setAttribute("cx", (pt.x + nx * off).toFixed(1));
+ c.setAttribute("cy", (pt.y + nyv * off).toFixed(1));
+ c.setAttribute("r", r.toFixed(2));
+ c.setAttribute("fill", getComputedStyle(pathEl).stroke);
+ dots.appendChild(c);
+ }
+ group.appendChild(dots);
+ }
+ return { draw: clone, group: group, type: type };
+ };
+
+ /* Draw-on across the stroke matrix: dash-animate whatever hwStrokeApply
+ says. (The pen-velocity ease variant rides the write-on item, not
+ this one.) */
+ window.hwDrawOn = function (tl, applied, at, dur, opts) {
+ opts = opts || {};
+ var p = applied.draw;
+ var len = p.getTotalLength();
+ // the draw target is always solid (plain/soft: the path itself; sharp/spray:
+ // the mask clone — the visible path keeps its texture dasharray untouched)
+ p.setAttribute("stroke-dasharray", len + " " + len);
+ p.setAttribute("stroke-dashoffset", len);
+ gsap.set(p, { opacity: 0 }); // kill the round-cap start nub pre-draw
+ var ease = opts.ease || "power2.inOut";
+ tl.set(p, { opacity: 1 }, at);
+ tl.to(
+ p,
+ { strokeDashoffset: 0, duration: dur === undefined ? 0.7 : dur, ease: ease },
+ at,
+ );
+ };
+
+ // ---- hw-callout helpers (copy these too) ----
+ // Builds outline + scribble + connector + label inside the wrapper and
+ // stores the draw records + control poses hwCalloutOn consumes.
+ // opts — content (uncounted): scribble (bool), seed, label, connector (bool)
+ // controls (g09 — see the CONFIG block, the published-parameter
+ // list): labelAt, strokeType, boil
+ window.hwCalloutBuild = function (target, opts) {
+ opts = opts || {};
+ var seed = opts.seed || 1;
+ var el = document.querySelector(target);
+ var svg = el.querySelector("svg");
+ var vb = svg.getAttribute("viewBox").split(" ");
+ var W = parseFloat(vb[2]),
+ H = parseFloat(vb[3]);
+ var cx = W / 2,
+ cy = H / 2,
+ rx = W * 0.42,
+ ry = H * 0.36;
+
+ var outline = el.querySelector(".hw-co-outline");
+ outline.setAttribute("d", window.hwWobbleEllipse(cx, cy, rx, ry, seed, 4));
+
+ var scr = el.querySelector(".hw-co-scribble");
+ if (opts.scribble === false) {
+ scr.style.display = "none";
+ } else {
+ /* Denser rows so the zigzag reads as a scribbled hatch. At 6 rows
+ the near-horizontal runs dominate and it renders as stacked bars. */
+ var d = "",
+ rows = 11;
+ for (var i = 0; i < rows; i++) {
+ var t = (i + 0.5) / rows;
+ var yy = cy - ry + t * ry * 2;
+ var half = Math.sqrt(Math.max(0.05, 1 - Math.pow((yy - cy) / ry, 2)));
+ var xw = rx * half * 0.86;
+ var xa = cx - xw + window.hwHash(i * 7 + 2, seed) * 8;
+ var xb = cx + xw + window.hwHash(i * 7 + 3, seed) * 8;
+ d += (i === 0 ? "M " : " L ") + (i % 2 ? xa : xb).toFixed(1) + " " + yy.toFixed(1);
+ d +=
+ " L " +
+ (i % 2 ? xb : xa).toFixed(1) +
+ " " +
+ (yy + window.hwHash(i * 7 + 4, seed) * 4).toFixed(1);
+ }
+ scr.setAttribute("d", d);
+ }
+
+ var conn = el.querySelector(".hw-co-connector");
+ var label = el.querySelector(".hw-co-label");
+ // labelAt is a declared variant control — bounded: unknown value
+ // falls back to the default WITH a console error. Validated BEFORE
+ // the connector branch so a malformed value always logs, even when
+ // connector: false leaves the control inert.
+ var at = opts.labelAt || "right";
+ if (at !== "left" && at !== "right" && at !== "below") {
+ console.error('hw: unknown labelAt "' + at + '" — falling back to "right"');
+ at = "right";
+ }
+ var ex = null,
+ ey = null;
+ if (opts.connector === false) {
+ conn.style.display = "none";
+ } else {
+ var sx = at === "left" ? cx - rx : at === "below" ? cx : cx + rx;
+ var sy = at === "below" ? cy + ry : cy + ry * 0.35;
+ ex = at === "left" ? sx - 70 : at === "below" ? sx + 40 : sx + 70;
+ ey = sy + 55;
+ conn.setAttribute(
+ "d",
+ "M " +
+ sx.toFixed(1) +
+ " " +
+ sy.toFixed(1) +
+ " Q " +
+ ((sx + ex) / 2 + window.hwHash(21, seed) * 14).toFixed(1) +
+ " " +
+ (sy + 46).toFixed(1) +
+ " " +
+ ex.toFixed(1) +
+ " " +
+ ey.toFixed(1),
+ );
+ label.style.left = (at === "left" ? ex - 180 : ex + 12) + "px";
+ label.style.top = ey - 24 + "px";
+ }
+ label.textContent = opts.label || "";
+
+ // strokeType control: OUTLINE + CONNECTOR take the texture (the
+ // scribble stays plain). Bounding lives inside hwStrokeApply.
+ var strokeType = opts.strokeType || "plain";
+ var idBase = (el.id || "hw-co") + "-sm";
+ el.__hwCo = {
+ rx: rx,
+ seed: seed,
+ boil: opts.boil || "calm",
+ // the label pops out of the connector tip (falls back to center
+ // when the connector anatomy is off)
+ popOrigin: ex === null ? "50% 50%" : ex.toFixed(1) + "px " + ey.toFixed(1) + "px",
+ draw: {
+ outline: window.hwStrokeApply(outline, strokeType, {
+ seed: seed,
+ id: idBase + "-outline",
+ }),
+ scribble:
+ opts.scribble === false ? null : window.hwStrokeApply(scr, "plain", { seed: seed }),
+ connector:
+ opts.connector === false
+ ? null
+ : window.hwStrokeApply(conn, strokeType, {
+ seed: seed,
+ id: idBase + "-connector",
+ }),
+ },
+ };
+ };
+ // Draw sequence: outline -> scribble -> connector -> label pop, with
+ // the g21 contact squash on the shapes group at pop arrival. The boil
+ // pose registers here too — the host wires a position only.
+ window.hwCalloutOn = function (tl, target, at) {
+ var el = document.querySelector(target);
+ var co = el.__hwCo;
+ var t = at;
+ ["outline", "scribble", "connector"].forEach(function (k) {
+ var rec = co.draw[k];
+ if (!rec) return;
+ var dur = k === "scribble" ? 0.55 : k === "connector" ? 0.35 : 0.7;
+ window.hwDrawOn(tl, rec, t, dur);
+ t += dur * 0.85;
+ });
+ // label pop: the pop ARRIVES WITH MOMENTUM (accelerating into
+ // contact) — the squash absorbs it; a settling back.out crosses
+ // scale 1.0 at ~zero speed and the computed squash is invisible
+ // (measured, not hand-picked)
+ var pop = el.querySelector(".hw-co-pop");
+ var popEase = gsap.parseEase("power2.in");
+ gsap.set(pop, { scale: 0.001, opacity: 0, transformOrigin: co.popOrigin });
+ tl.to(pop, { opacity: 1, duration: 0.08, ease: "none" }, t);
+ tl.to(pop, { scale: 1, duration: 0.3, ease: popEase, immediateRender: false }, t);
+ // arrival velocity in px of radial (rx) travel, measured at the
+ // FIRST crossing of 1.0 — a settling ease's end-slope is ~0 and is
+ // NOT the arrival velocity
+ var eps = 1e-4;
+ var pc = 1;
+ for (var k2 = 1; k2 <= 1000; k2++) {
+ if (popEase(k2 / 1000) >= 1) {
+ pc = k2 / 1000;
+ break;
+ }
+ }
+ var vPop =
+ ((popEase(Math.min(pc + eps, 1)) - popEase(pc - eps)) / (2 * eps)) * (co.rx / 0.3);
+ var S = Math.min(0.08 * (Math.abs(vPop) / 2000), 0.25); // 0.08 = light drawn line tier
+ var rec2 = window.springEase({ feel: "snappy" });
+ var st = { s: 0 };
+ var deform = el.querySelector(".hw-co-deform");
+ gsap.set(deform, { transformOrigin: "50% 100%" });
+ // volume-preserving squash on the SHAPES wrapper only — the label
+ // rides the uniform-scale pop OUTSIDE the deform, so non-uniform
+ // scale never reaches glyphs. Read-back assertion enforces the law.
+ window.hwOnUpdate(tl, function () {
+ var along = 1 - st.s;
+ gsap.set(deform, { scaleY: along, scaleX: 1 / along });
+ var ax = parseFloat(gsap.getProperty(deform, "scaleX"));
+ var ay = parseFloat(gsap.getProperty(deform, "scaleY"));
+ if (Math.abs(ax * ay - 1) > 0.01)
+ console.error("hw volume law violated (callout): " + (ax * ay).toFixed(4));
+ });
+ // contact: squash in 2 frames, 1-frame hold, spring home (factory
+ // duration consumed verbatim)
+ tl.to(st, { s: S, duration: 2 / 30, ease: "power3.out" }, t + 0.3);
+ tl.to(st, { s: 0, duration: rec2.duration, ease: rec2.ease }, t + 0.3 + 3 / 30);
+ // boil control (family base) — x/y/rotation on the boil wrapper only
+ window.hwBoilPose(tl, el.querySelector(".hw-co-boil"), co.boil, { seed: co.seed });
+ };
+ window.hwCalloutOff = function (tl, target, at) {
+ tl.to(target, { opacity: 0, duration: 0.35, ease: "power2.in" }, at);
+ };
+
+
+})();
+
+/* ==== from HF registry: hw-underline (helpers verbatim, self-preview removed) ==== */
+(function(){
+ window.hwOnUpdate = function (tl, fn) {
+ if (!tl.__hwRenders) {
+ tl.__hwRenders = [];
+ tl.eventCallback("onUpdate", function () {
+ for (var i = 0; i < tl.__hwRenders.length; i++) tl.__hwRenders[i]();
+ });
+ }
+ tl.__hwRenders.push(fn);
+ fn();
+ };
+ window.hwHash = function (n, seed) {
+ var x = Math.sin(n * 127.1 + (seed || 1) * 311.7) * 43758.5453;
+ return (x - Math.floor(x)) * 2 - 1;
+ };
+ window.hwBoil = function (tl, target, opts) {
+ opts = opts || {};
+ var amp = opts.amp !== undefined ? opts.amp : 1.6;
+ var rot = opts.rot !== undefined ? opts.rot : 0.5;
+ var fps = opts.fps || 30;
+ var drop = opts.frameDrop || 3;
+ var seed = opts.seed || 1;
+ var els = gsap.utils.toArray(target);
+ window.hwOnUpdate(tl, function () {
+ var step = Math.floor((tl.time() * fps) / drop);
+ for (var i = 0; i < els.length; i++) {
+ gsap.set(els[i], {
+ x: window.hwHash(step * 3 + i * 97, seed) * amp,
+ y: window.hwHash(step * 3 + 1 + i * 97, seed) * amp,
+ rotation: (opts.baseRot || 0) + window.hwHash(step * 3 + 2 + i * 97, seed) * rot,
+ });
+ }
+ });
+ };
+
+ // ---- hw-mark helpers (copy these too) ----
+ // style: "underline" (squiggle) | "strike" (double pass) | "bracket"
+ window.hwMarkPath = function (w, h, style, seed) {
+ seed = seed || 1;
+ function wob(n, range) {
+ return window.hwHash(n, seed) * (range === undefined ? 5 : range);
+ }
+ var mid = h / 2;
+ if (style === "bracket") {
+ return (
+ "M " +
+ (w * 0.9 + wob(1, 3)) +
+ " " +
+ (2 + wob(2, 3)) +
+ " Q " +
+ wob(3, 4) +
+ " " +
+ (2 + wob(4)) +
+ " " +
+ (4 + wob(5, 3)) +
+ " " +
+ (h * 0.5 + wob(6)) +
+ " Q " +
+ wob(7, 4) +
+ " " +
+ (h - 2 + wob(8)) +
+ " " +
+ (w * 0.9 + wob(9, 3)) +
+ " " +
+ (h - 2 + wob(10, 3))
+ );
+ }
+ if (style === "strike") {
+ return (
+ "M " +
+ (2 + wob(1, 3)) +
+ " " +
+ (mid + wob(2)) +
+ " L " +
+ (w - 4 + wob(3, 3)) +
+ " " +
+ (mid - 3 + wob(4)) +
+ " M " +
+ (w - 10 + wob(5, 4)) +
+ " " +
+ (mid + 7 + wob(6)) +
+ " L " +
+ (8 + wob(7, 4)) +
+ " " +
+ (mid + 3 + wob(8))
+ );
+ }
+ /* underline squiggle */
+ var segs = Math.max(5, Math.round(w / 95));
+ var d = "M 2 " + (mid + wob(0, 4));
+ for (var i = 1; i <= segs; i++) {
+ var x = (w / segs) * i;
+ d +=
+ " Q " +
+ (x - w / segs / 2 + wob(i * 4 + 1, 9)) +
+ " " +
+ (mid + (i % 2 ? -1 : 1) * (9 + wob(i * 4 + 2, 4))) +
+ " " +
+ x.toFixed(1) +
+ " " +
+ (mid + wob(i * 4 + 3, 4));
+ }
+ return d;
+ };
+ window.hwMarkOn = function (tl, target, at, dur) {
+ var p = document.querySelector(target + " path");
+ var len = p.getTotalLength();
+ gsap.set(p, { strokeDasharray: len, strokeDashoffset: len });
+ tl.to(
+ p,
+ { strokeDashoffset: 0, duration: dur === undefined ? 0.55 : dur, ease: "power2.inOut" },
+ at,
+ );
+ };
+ window.hwMarkOff = function (tl, target, at) {
+ tl.to(target, { opacity: 0, duration: 0.3, ease: "power2.in" }, at);
+ };
+
+
+})();
+
+/* ==== from HF registry: hw-arrow (helpers verbatim, self-preview removed) ==== */
+(function(){
+ window.hwOnUpdate = function (tl, fn) {
+ if (!tl.__hwRenders) {
+ tl.__hwRenders = [];
+ tl.eventCallback("onUpdate", function () {
+ for (var i = 0; i < tl.__hwRenders.length; i++) tl.__hwRenders[i]();
+ });
+ }
+ tl.__hwRenders.push(fn);
+ fn();
+ };
+ window.hwHash = function (n, seed) {
+ var x = Math.sin(n * 127.1 + (seed || 1) * 311.7) * 43758.5453;
+ return (x - Math.floor(x)) * 2 - 1;
+ };
+ window.hwBoil = function (tl, target, opts) {
+ opts = opts || {};
+ var amp = opts.amp !== undefined ? opts.amp : 1.6;
+ var rot = opts.rot !== undefined ? opts.rot : 0.5;
+ var fps = opts.fps || 30;
+ var drop = opts.frameDrop || 3;
+ var seed = opts.seed || 1;
+ var els = gsap.utils.toArray(target);
+ window.hwOnUpdate(tl, function () {
+ var step = Math.floor((tl.time() * fps) / drop);
+ for (var i = 0; i < els.length; i++) {
+ gsap.set(els[i], {
+ x: window.hwHash(step * 3 + i * 97, seed) * amp,
+ y: window.hwHash(step * 3 + 1 + i * 97, seed) * amp,
+ rotation: (opts.baseRot || 0) + window.hwHash(step * 3 + 2 + i * 97, seed) * rot,
+ });
+ }
+ });
+ };
+ // boil control: authored poses over the family-locked frameDrop.
+ // Unknown pose → default + console error (bounded-controls law).
+ window.hwBoilPose = function (tl, target, pose, opts) {
+ opts = opts || {};
+ var poses = { calm: { amp: 1.6, rot: 0.5 }, lively: { amp: 2.6, rot: 0.9 } };
+ if (pose === "off") return;
+ var p = poses[pose];
+ if (!p) {
+ console.error('hw: unknown boil pose "' + pose + '" — falling back to "calm"');
+ p = poses.calm;
+ }
+ window.hwBoil(tl, target, { amp: p.amp, rot: p.rot, frameDrop: 3, seed: opts.seed || 1 });
+ };
+
+ /* ---- spring library (snappy register; factory duration consumed verbatim) ---- */
+ var LN1000 = Math.log(1000);
+ var FEELS = {
+ snappy: { zeta: 0.9, response: 0.22 },
+ };
+ window.springEase = function (opts) {
+ var f = opts.feel ? FEELS[opts.feel] : opts;
+ var zeta = f.zeta,
+ response = f.response;
+ var w0 = (2 * Math.PI) / response;
+ var T = LN1000 / (zeta * w0);
+ var x;
+ if (zeta < 1) {
+ var wd = w0 * Math.sqrt(1 - zeta * zeta);
+ x = function (t) {
+ return (
+ 1 -
+ Math.exp(-zeta * w0 * t) *
+ (Math.cos(wd * t) + ((zeta * w0) / wd) * Math.sin(wd * t))
+ );
+ };
+ } else {
+ x = function (t) {
+ return 1 - Math.exp(-w0 * t) * (1 + w0 * t);
+ };
+ }
+ var xT = x(T);
+ return {
+ ease: function (p) {
+ return p >= 1 ? 1 : x(p * T) / xT;
+ },
+ duration: T,
+ zeta: zeta,
+ response: response,
+ };
+ };
+
+ /* ---- pen-velocity ease: pure function of the path geometry ----
+ Sample 25–75 curvature-adaptive points, speed ∝ 1/(1+k·curvature)
+ floored at 0.22 (a pen slows into curves, never stalls), integrate
+ ds/speed, invert to a normalized time→distance ease. Seek-safe:
+ no per-frame state. */
+ window.hwPenEase = function (pathEl, opts) {
+ opts = opts || {};
+ var kCurve = opts.kCurve !== undefined ? opts.kCurve : 10;
+ var L = pathEl.getTotalLength();
+ if (L <= 0)
+ return {
+ ease: function (t) {
+ return t;
+ },
+ samples: 2,
+ inkTime: 1,
+ len: 0,
+ };
+ var PRE = 48;
+ var pts = [];
+ for (var i = 0; i <= PRE; i++) pts.push(pathEl.getPointAtLength((L * i) / PRE));
+ var curv = [0];
+ for (i = 1; i < PRE; i++) {
+ var ax = pts[i].x - pts[i - 1].x,
+ ay = pts[i].y - pts[i - 1].y;
+ var bx = pts[i + 1].x - pts[i].x,
+ by = pts[i + 1].y - pts[i].y;
+ var la = Math.hypot(ax, ay) || 1e-6,
+ lb = Math.hypot(bx, by) || 1e-6;
+ var dot = Math.max(-1, Math.min(1, (ax * bx + ay * by) / (la * lb)));
+ curv.push(Math.acos(dot) / ((la + lb) / 2));
+ }
+ curv.push(0);
+ var mass = 0;
+ for (i = 0; i < curv.length; i++) mass += curv[i];
+ var N = Math.max(25, Math.min(75, Math.round(25 + mass * 18)));
+ var seg = L / N;
+ var times = [0];
+ var t = 0;
+ for (i = 1; i <= N; i++) {
+ var u = ((i - 0.5) / N) * PRE;
+ var i0 = Math.floor(u),
+ f = u - i0;
+ var c = curv[Math.min(i0, PRE)] * (1 - f) + curv[Math.min(i0 + 1, PRE)] * f;
+ var speed = Math.max(1 / (1 + kCurve * c * 14), 0.22);
+ t += seg / speed;
+ times.push(t);
+ }
+ var total = times[N];
+ for (i = 0; i <= N; i++) times[i] /= total;
+ var easeFn = function (p) {
+ if (p <= 0) return 0;
+ if (p >= 1) return 1;
+ var lo = 0,
+ hi = N;
+ while (hi - lo > 1) {
+ var mid = (lo + hi) >> 1;
+ if (times[mid] <= p) lo = mid;
+ else hi = mid;
+ }
+ var span = times[hi] - times[lo] || 1e-9;
+ return (lo + (p - times[lo]) / span) / N;
+ };
+ return { ease: easeFn, samples: N, inkTime: total, len: L };
+ };
+
+ /* ---- stroke matrix: plain | soft | sharp | spray -------------------
+ strokeType is a g09 variant control. Authored constants per type;
+ unknown value → default ("plain") + console error (bounded-controls
+ law). sharp = micro stroke-dasharray gaps (dry marker) — draw-on
+ therefore rides a MASK clone (the visible dasharray never animates).
+ spray = index-seeded deterministic dots along the path via hwHash;
+ NO feTurbulence anywhere.
+ Returns { draw: pathToDashAnimate, group: maskedGroupOrNull } */
+ window.hwStrokeTypes = {
+ plain: {},
+ soft: { blur: 0.6 },
+ sharp: { dash: [3.0, 1.55] }, // × stroke-width
+ spray: {
+ coreOpacity: 0.5,
+ coreBlur: 0.4,
+ density: 0.16,
+ scatter: 2.6,
+ rMin: 1.1,
+ rMax: 2.6,
+ },
+ };
+ window.hwStrokeApply = function (pathEl, type, opts) {
+ opts = opts || {};
+ var cfg = window.hwStrokeTypes[type];
+ if (!cfg) {
+ console.error('hw: unknown strokeType "' + type + '" — falling back to "plain"');
+ type = "plain";
+ cfg = window.hwStrokeTypes.plain;
+ }
+ var svg = pathEl.ownerSVGElement;
+ var ns = "http://www.w3.org/2000/svg";
+ var w = parseFloat(getComputedStyle(pathEl).strokeWidth) || 6;
+ if (type === "plain") return { draw: pathEl, group: null, type: type };
+ if (type === "soft") {
+ pathEl.style.filter = "blur(" + cfg.blur + "px)";
+ return { draw: pathEl, group: null, type: type };
+ }
+ // sharp + spray: wrap in a masked group, draw-on animates the mask clone
+ var id =
+ opts.id ||
+ "hwsm-" + Math.abs(Math.round(window.hwHash((opts.seed || 1) * 13.7, 5) * 1e6));
+ var defs = svg.querySelector("defs");
+ if (!defs) {
+ defs = document.createElementNS(ns, "defs");
+ svg.insertBefore(defs, svg.firstChild);
+ }
+ var mask = document.createElementNS(ns, "mask");
+ mask.setAttribute("id", id);
+ mask.setAttribute("maskUnits", "userSpaceOnUse");
+ var clone = document.createElementNS(ns, "path");
+ clone.setAttribute("d", pathEl.getAttribute("d"));
+ clone.setAttribute("fill", "none");
+ clone.setAttribute("stroke", "#fff");
+ clone.setAttribute(
+ "stroke-width",
+ w * (type === "spray" ? 2 + (cfg.scatter * 2) / w : 1.7),
+ );
+ clone.setAttribute("stroke-linecap", "round");
+ clone.setAttribute("stroke-linejoin", "round");
+ mask.appendChild(clone);
+ defs.appendChild(mask);
+ var group = document.createElementNS(ns, "g");
+ group.setAttribute("mask", "url(#" + id + ")");
+ pathEl.parentNode.insertBefore(group, pathEl);
+ group.appendChild(pathEl);
+ if (type === "sharp") {
+ pathEl.setAttribute(
+ "stroke-dasharray",
+ (cfg.dash[0] * w).toFixed(1) + " " + (cfg.dash[1] * w).toFixed(1),
+ );
+ } else {
+ // spray: faint core + seeded dots
+ pathEl.setAttribute("stroke-opacity", cfg.coreOpacity);
+ pathEl.style.filter = "blur(" + cfg.coreBlur + "px)";
+ var len = pathEl.getTotalLength();
+ var n = Math.round(len * cfg.density * (opts.densityScale || 1));
+ var seed = opts.seed || 1;
+ var dots = document.createElementNS(ns, "g");
+ for (var i = 0; i < n; i++) {
+ var t = Math.min(
+ 1,
+ Math.max(0, (i + 0.5) / n + (window.hwHash(i * 7, seed) * 0.35) / n),
+ );
+ var pt = pathEl.getPointAtLength(t * len);
+ var pt2 = pathEl.getPointAtLength(Math.min(len, t * len + 0.5));
+ var tx = pt2.x - pt.x,
+ ty = pt2.y - pt.y;
+ var tl2 = Math.hypot(tx, ty) || 1;
+ var nx = -ty / tl2,
+ nyv = tx / tl2;
+ var off = window.hwHash(i * 7 + 1, seed) * (cfg.scatter + w * 0.55);
+ var r = cfg.rMin + Math.abs(window.hwHash(i * 7 + 2, seed)) * (cfg.rMax - cfg.rMin);
+ var c = document.createElementNS(ns, "circle");
+ c.setAttribute("cx", (pt.x + nx * off).toFixed(1));
+ c.setAttribute("cy", (pt.y + nyv * off).toFixed(1));
+ c.setAttribute("r", r.toFixed(2));
+ c.setAttribute("fill", getComputedStyle(pathEl).stroke);
+ dots.appendChild(c);
+ }
+ group.appendChild(dots);
+ }
+ return { draw: clone, group: group, type: type };
+ };
+
+ /* Draw-on across the stroke matrix: dash-animate whatever hwStrokeApply
+ says. The draw target is always solid (plain/soft: the path itself;
+ sharp/spray: the mask clone — the visible path keeps its texture
+ dasharray untouched). Optionally pen-velocity eased (opts.pen). */
+ window.hwDrawOn = function (tl, applied, at, dur, opts) {
+ opts = opts || {};
+ var p = applied.draw;
+ var len = p.getTotalLength();
+ // the draw target is always solid (plain/soft: the path itself; sharp/spray:
+ // the mask clone — the visible path keeps its texture dasharray untouched)
+ p.setAttribute("stroke-dasharray", len + " " + len);
+ p.setAttribute("stroke-dashoffset", len);
+ gsap.set(p, { opacity: 0 }); // kill the round-cap start nub pre-draw
+ var ease = opts.pen ? window.hwPenEase(p, opts).ease : opts.ease || "power2.inOut";
+ tl.set(p, { opacity: 1 }, at);
+ tl.to(
+ p,
+ { strokeDashoffset: 0, duration: dur === undefined ? 0.7 : dur, ease: ease },
+ at,
+ );
+ };
+
+ // ---- hw-arrow helpers (copy these too) ----
+ // Wobbled arrow path in a w x h box, tail at left, head at right.
+ // curve: "straight" | "gentle" | "swoop"
+ window.hwArrowPath = function (w, h, curve, seed) {
+ seed = seed || 1;
+ var bend = curve === "swoop" ? 0.55 : curve === "gentle" ? 0.28 : 0.06;
+ function wob(v, n, range) {
+ return v + window.hwHash(n, seed) * range;
+ }
+ var x0 = wob(4, 1, 3),
+ y0 = wob(h * 0.72, 2, 4),
+ x1 = wob(w - 10, 3, 4),
+ y1 = wob(h * 0.3, 4, 4);
+ var cx1 = wob(w * 0.35, 5, 10),
+ cy1 = wob(h * (0.72 + bend * 0.5), 6, 8);
+ var cx2 = wob(w * 0.7, 7, 10),
+ cy2 = wob(h * (0.3 + bend), 8, 8);
+ var ang = Math.atan2(y1 - cy2, x1 - cx2);
+ function head(da, len) {
+ var a = ang + Math.PI + da;
+ return (
+ "M " +
+ x1.toFixed(1) +
+ " " +
+ y1.toFixed(1) +
+ " l " +
+ (Math.cos(a) * len).toFixed(1) +
+ " " +
+ (Math.sin(a) * len).toFixed(1)
+ );
+ }
+ return (
+ "M " +
+ x0.toFixed(1) +
+ " " +
+ y0.toFixed(1) +
+ " C " +
+ cx1.toFixed(1) +
+ " " +
+ cy1.toFixed(1) +
+ ", " +
+ cx2.toFixed(1) +
+ " " +
+ cy2.toFixed(1) +
+ ", " +
+ x1.toFixed(1) +
+ " " +
+ y1.toFixed(1) +
+ " " +
+ head(0.5, wob(34, 9, 6)) +
+ " " +
+ head(-0.5, wob(34, 10, 6))
+ );
+ };
+
+ // ---- hwArrowBuild: CONFIG-reading component builder (g09) ----
+ // Builds the arrow as TWO paths (curve + head group) inside the
+ // target's svg with the same wobble math and seed slots as
+ // hwArrowPath, applies CONFIG.strokeType to the curve (the head
+ // stays plain — texture on a ~30px head reads as noise), and rigs
+ // the travel-aligned arrival wrapper: an outer g rotated to the
+ // travel direction + an inner g counter-rotated. The pair cancels,
+ // so geometry stays put while scaleX on the outer acts along
+ // travel. NO transform-box styles on these g's — they fight GSAP's
+ // baked SVG origins (the outer's fill-box would derive from its
+ // rotated child and the cancellation breaks).
+ // `seed` is internal — defaults per target from the element id
+ // (a pure hash of the id string: deterministic across page loads);
+ // it is NOT a control. Targets must carry unique ids: id-less
+ // targets fall back to a shared "hw-arrow" slot (identical wobble;
+ // duplicate mask ids cross-wire sharp/spray reveals), so that case
+ // fails loudly (bounded-controls law).
+ window.hwArrowBuild = function (target, CONFIG, seed) {
+ CONFIG = CONFIG || {};
+ var el = typeof target === "string" ? document.querySelector(target) : target;
+ var svg = el.querySelector("svg");
+ if (!el.id)
+ console.error(
+ 'hw: hwArrowBuild target has no id — falling back to the shared "hw-arrow" seed/mask slot; give each built target a unique id',
+ );
+ if (seed === undefined) {
+ var idStr = el.id || "hw-arrow";
+ seed = 0;
+ for (var si = 0; si < idStr.length; si++)
+ seed = (seed * 31 + idStr.charCodeAt(si)) % 997;
+ seed = (seed % 96) + 1;
+ }
+ var style = CONFIG.arrowStyle === undefined ? "gentle" : CONFIG.arrowStyle;
+ if (style !== "straight" && style !== "gentle" && style !== "swoop") {
+ console.error('hw: unknown arrowStyle "' + style + '" — falling back to "gentle"');
+ style = "gentle";
+ }
+ var vb = svg.viewBox.baseVal;
+ var w = vb && vb.width ? vb.width : el.clientWidth;
+ var h = vb && vb.height ? vb.height : el.clientHeight;
+ // same wobble math + hash slots as hwArrowPath (1–8 body, 9/10 head)
+ var bend = style === "swoop" ? 0.55 : style === "gentle" ? 0.28 : 0.06;
+ function wob(v, n, range) {
+ return v + window.hwHash(n, seed) * range;
+ }
+ var x0 = wob(4, 1, 3),
+ y0 = wob(h * 0.72, 2, 4),
+ x1 = wob(w - 10, 3, 4),
+ y1 = wob(h * 0.3, 4, 4);
+ var cx1 = wob(w * 0.35, 5, 10),
+ cy1 = wob(h * (0.72 + bend * 0.5), 6, 8);
+ var cx2 = wob(w * 0.7, 7, 10),
+ cy2 = wob(h * (0.3 + bend), 8, 8);
+ var ang = Math.atan2(y1 - cy2, x1 - cx2);
+ function headSeg(da, len) {
+ var a = ang + Math.PI + da;
+ return (
+ "M " +
+ x1.toFixed(1) +
+ " " +
+ y1.toFixed(1) +
+ " l " +
+ (Math.cos(a) * len).toFixed(1) +
+ " " +
+ (Math.sin(a) * len).toFixed(1)
+ );
+ }
+ var ns = "http://www.w3.org/2000/svg";
+ var curve = document.createElementNS(ns, "path");
+ curve.setAttribute(
+ "d",
+ "M " +
+ x0.toFixed(1) +
+ " " +
+ y0.toFixed(1) +
+ " C " +
+ cx1.toFixed(1) +
+ " " +
+ cy1.toFixed(1) +
+ ", " +
+ cx2.toFixed(1) +
+ " " +
+ cy2.toFixed(1) +
+ ", " +
+ x1.toFixed(1) +
+ " " +
+ y1.toFixed(1),
+ );
+ svg.appendChild(curve);
+ var headG = document.createElementNS(ns, "g");
+ var headInner = document.createElementNS(ns, "g");
+ var head = document.createElementNS(ns, "path");
+ head.setAttribute("d", headSeg(0.5, wob(34, 9, 6)) + " " + headSeg(-0.5, wob(34, 10, 6)));
+ headInner.appendChild(head);
+ headG.appendChild(headInner);
+ svg.appendChild(headG);
+ // curve texture; mask id derived from the element id — deterministic
+ // and collision-free across id-bearing instances (id-less targets
+ // errored above and share the fallback)
+ var applied = window.hwStrokeApply(
+ curve,
+ CONFIG.strokeType === undefined ? "plain" : CONFIG.strokeType,
+ { seed: seed, id: (el.id || "hw-arrow") + "-sm" },
+ );
+ if (applied.group) {
+ // the item CSS (.hw-arrow path) outranks the mask clone's
+ // presentation attributes — pin them as inline styles so the
+ // reveal mask keeps its authored width and white stroke
+ applied.draw.style.stroke = "#fff";
+ applied.draw.style.strokeWidth = applied.draw.getAttribute("stroke-width");
+ }
+ // arrival rig: rotate the WRAPPER to travel, counter-rotate the
+ // content — wrapper scaleX then acts along travel
+ var angDeg = (ang * 180) / Math.PI;
+ gsap.set(headG, { transformOrigin: "50% 50%", rotation: angDeg, opacity: 0 });
+ gsap.set(headInner, { transformOrigin: "50% 50%", rotation: -angDeg });
+ el.__hwArrowBuild = {
+ el: el,
+ applied: applied,
+ headG: headG,
+ headInner: headInner,
+ seed: seed,
+ boil: CONFIG.boil === undefined ? "calm" : CONFIG.boil,
+ boiled: false,
+ };
+ return el.__hwArrowBuild;
+ };
+
+ // Draw-on. Built targets (hwArrowBuild): accelerating draw (causal
+ // arrival), then the head pops with the g21 travel-aligned stretch —
+ // v measured numerically from the draw ease end-slope, S = min(0.06
+ // × v/2000, 0.25), volume preserved (scaleX × scaleY ≈ 1, asserted),
+ // 2-frame apply + snappy spring recovery (factory duration verbatim).
+ // Legacy single-path targets keep the shipped dashoffset behavior.
+ window.hwArrowOn = function (tl, target, at, dur) {
+ var el = typeof target === "string" ? document.querySelector(target) : target;
+ var b = el && el.__hwArrowBuild;
+ if (!b) {
+ var p = document.querySelector(target + " path");
+ var len = p.getTotalLength();
+ gsap.set(p, { strokeDasharray: len, strokeDashoffset: len });
+ tl.to(
+ p,
+ {
+ strokeDashoffset: 0,
+ duration: dur === undefined ? 0.7 : dur,
+ ease: "power2.inOut",
+ },
+ at,
+ );
+ return;
+ }
+ // built targets (g09): durations are item-locked — a
+ // legacy-signature `dur` is ignored + console.error (edit the item
+ // source to change); the legacy branch above keeps honoring it
+ if (dur !== undefined)
+ console.error(
+ "hw: hwArrowOn draw duration is locked for built targets — ignoring dur=" + dur,
+ );
+ dur = 0.7;
+ // the pen ACCELERATES into the head (power2.in) so the measured
+ // arrival velocity is real — a settling ease ends at ~zero slope
+ // and would make the stretch invisible
+ var drawEase = gsap.parseEase("power2.in");
+ window.hwDrawOn(tl, b.applied, at, dur, { ease: drawEase });
+ var dlen = b.applied.draw.getTotalLength();
+ var eps = 1e-4;
+ var v = ((drawEase(1) - drawEase(1 - eps)) / eps) * (dlen / dur);
+ var S = Math.min(0.06 * (v / 2000), 0.25);
+ var rec = window.springEase({ feel: "snappy" });
+ var FPS = 30;
+ var st = { s: 0 };
+ var hg = b.headG;
+ window.hwOnUpdate(tl, function () {
+ // stretch ALONG travel (the wrapper's local x after rotation)
+ var along = 1 + st.s;
+ gsap.set(hg, { scaleX: along, scaleY: 1 / along });
+ var ax = parseFloat(gsap.getProperty(hg, "scaleX"));
+ var ay = parseFloat(gsap.getProperty(hg, "scaleY"));
+ if (Math.abs(ax * ay - 1) > 0.01)
+ console.error("hw volume law violated (arrowhead): " + (ax * ay).toFixed(4));
+ });
+ tl.set(hg, { opacity: 1 }, at + dur);
+ tl.to(st, { s: S, duration: 2 / FPS, ease: "power3.out" }, at + dur);
+ tl.to(st, { s: 0, duration: rec.duration, ease: rec.ease }, at + dur + 3 / FPS);
+ // boil pose (recorded from CONFIG at build; hwBoil needs the
+ // timeline, so it registers on first wiring). Boil owns x/y/rotation
+ // of the WRAPPER element — the arrival stretch lives on the nested
+ // head rig, never on the boiled element.
+ if (!b.boiled) {
+ b.boiled = true;
+ window.hwBoilPose(tl, el, b.boil, { seed: b.seed });
+ }
+ };
+ window.hwArrowOff = function (tl, target, at) {
+ tl.to(target, { opacity: 0, duration: 0.3, ease: "power2.in" }, at);
+ };
+
+
+})();
diff --git "a/skill/seecut/references/00-\346\200\273\347\272\262.md" "b/skill/seecut/references/00-\346\200\273\347\272\262.md"
new file mode 100644
index 0000000..b0e05b6
--- /dev/null
+++ "b/skill/seecut/references/00-\346\200\273\347\272\262.md"
@@ -0,0 +1,29 @@
+# 00 · 总纲(v3,唯一规范源的最高层)
+
+> 本文件 16 条是全 skill 的"宪法"。其它 references 只负责展开细节,**不得与本文件矛盾**;发现矛盾=以本文件为准,并在交付报告里写明"某文件某处与总纲冲突",不自行调和。
+> 改规则只改本文件或对应细节文件,并记入根目录 `CHANGELOG.md`;**禁止在正文里叠"某日某人定"的补丁层**。
+
+## 一 · 目标与信源
+1. **目标 = 网感口播精剪**:口播(真人或数字人出镜)打底,把画面让给高密度信息层(真证据 + 卡片/chip/大字 + 手作质感 + 弹簧动效),人像按"对你说露、给你看藏"调度。风格规范在 `01-03`。参考片可选:用户自备同风格片段放 `金锚集/`。
+2. **信源优先级**:`03-编排层决策表` / `01-方法论` > `02-设计令牌` > 其它文件(用户自备参考片时,参考片 > 以上)。上下冲突时上层赢。
+
+## 二 · 画面怎么剪
+3. **两层模型**:连续音轨是骨架;人像层(半身/卡化小窗/角落/隐去)+ 信息层(证据/chip/卡/大字/手作)叠在上面。人像露不露 = 这句是"对你说"还是"给你看"(`03` 决策表)。
+4. **证据优先**:口播提到真实的产品/网页/文档/数据/操作 → **必须先尝试拿真证据**(用户素材 > 自己截图/录屏 > 实在拿不到才降级)。真证据当信息层主角,**满屏铺是参考片的正常做法**(配证据镜:滚动/放大/圈注/下划线,前景弹出时背景模糊压暗让位)。
+5. **禁假证据**:不得用抽象占位窗口、伪代码网格、假 Mac 窗口/假 App 界面、与话题无关的装饰窗口拼贴去冒充证据或"填满"画面。概念卡/chip/数字卡/清单等设计元素可以用,但不能装成截图。
+6. **无证据时**(纯观点句,或确实拿不到)→ 干净设计底(米白点阵纸)+ 前景元素扛密度,或人像半身露脸(决策表:纯观点则露脸)。**不许空拍**:信息拍前景有效元素 ≥ 2。
+7. **审核与名誉安全**:画面里不得出现可读的敏感字(下载/反爬/扫码/搬运/联系方式/引流站外/价格违规承诺等),每张证据截图入片前必须读图核一遍。**截图打码**:证据截图里的**来源标识**(站名、logo、人名、账号/头像)默认模糊,出处写"实截(已打码)";**被讨论的产品名**(如帖子标题里的 ChatGPT)先保留,**交付报告里列出来问用户**要不要打(自己做样片无所谓,正式发布时由用户定)。
+8. **名词响应 + 不抢拍**:口播每个具体名词/命令/数字约 1 秒内有画面接住;payoff 元素锚在关键词被说出的那一帧(逐词时间戳),绝不早于词。
+9. **内核令牌全片不变**(`02` §0-A):弹簧回弹 + 错峰级联、粗黑无衬线、色族(砖红/青柠/琥珀)、手作质感、人像卡化、三禁(不纯黑白硬碰、不刺眼纯红大字报、不硬切无缓动)。
+10. **人像连贯**:全片人像卡化形态统一,位置/大小变化必须跟着功能走、过渡平滑,**不无故换位置换形状**;无脸连续 ≤ 5 秒。
+11. **组件必须先调官方库(硬规则)**:`npx -y hyperframes@latest catalog` 查 HF registry(394 项,大写 `HTTPS_PROXY`)。SHOTBOOK 每个镜头的"选哪张卡"**必须写出 registry 组件名,或写明库里为什么没有**;交付报告列出用了哪些组件。手绘类优先用 `assets/hf-hw/`(已抽好的 hw-callout-circle / hw-underline / hw-arrow)。库不可用 = 预检不过,先修,不许以此为由手搭。
+
+## 三 · 怎么验
+12. **渲染铁律**见 `08-避坑SOP`(人像 img 逐帧、绝对时间 seek、opacity+set+to、长任务看门狗)。
+13. **质检闭环**(`06-质检闭环spec`):硬门(3A 几何 + 硬伤清单)全过 → **两两对比"新版 vs 上一版"**(交换 A/B 位置各跑一次,两次一致才算数)决定是否采纳新版;对照参考片参考片只用来找差距方向,不打分。**不追任何百分比**。
+ **迭代要有肉眼可见的进步**:每一版至少改一处"对照参考片找出的大差距"(证据、版式、密度、人像调度这类),硬伤小修补合并进同一版,不单独占一版。
+14. **agy 调用纪律**:每次 `--new-project`;JSON schema 结构化输出;评委隔离(视频复制到系统 tmp 再评,不让它读到工程源码);指纹核(agy 照抄的画面文字必须能在本片源码或 fp-manifest.txt 里找到)+ 时长核;agy 陈述的关键事实要抽帧核实再采信。
+
+## 四 · 何时停
+15. **停止条件**:硬门全过,且(新版对比不胜上一版 或 **已做到第 3 版** 或 只剩肉眼看不出的小修补)→ 交付。卡住(环境缺依赖、素材拿不到、规范冲突)= 停下带证据报告用户,不自判"够了",也不无限死磕。长任务**每 15 分钟往 runlog 写一行进度**,用户随时能看到没在空转。
+16. **交付**:①**渲染成片**(HyperFrames 全效果)落 `~/Downloads`;②**分层工程包**(纸底/人像/信息层透明 PNG/原声/音效计划 + 剪映 plan,编辑器无关);③若本机装了剪映引擎(jianying-headless,可选,**不随 skill 分发**)→ 登记成**剪映分层草稿**,音效放草稿的音效轨,成片只带原声;**没装剪映引擎 → 音效直接混进渲染成片**(音效不丢)。音效按 `09-音效规范`(开头 0.5 秒内必须有一个抓耳音效)。字幕、BGM 留给用户在剪映做。
diff --git "a/skill/seecut/references/01-\346\226\271\346\263\225\350\256\272.md" "b/skill/seecut/references/01-\346\226\271\346\263\225\350\256\272.md"
new file mode 100644
index 0000000..293ca18
--- /dev/null
+++ "b/skill/seecut/references/01-\346\226\271\346\263\225\350\256\272.md"
@@ -0,0 +1,123 @@
+# 《参考片剪辑方法论》· Round1 交付(初稿)
+
+> 依据:10 条参考片样本(8完整+2部分)经 agy 逐拍拆解 + 我抽帧核(抽样40%准确)+ 跨样本聚合 80+ 条"情境→打法"。
+> 输出格式学 student-kit `MOTION_PHILOSOPHY.md`;组件层对齐 talkcraft 108卡 / student-kit。
+> 定位:**参考片=高质量数字人口播科普(作者定)**,富设计、丝滑、信息密度极高。目标=让 agent 能剪出这种效果。
+> ⚠️ 标 [核] = 已抽帧或跨样本≥3次证实;标 [观] = agy 观察待再核。
+
+---
+
+## 0 · 一句话定性
+**数字人口播打底,把满屏让给高密度信息层。** 同一条固定数字人素材做多种"再构图"(PIP撕纸框 / 满屏 / 隐去 / 角落头 / 半身),每个名词都有画面响应,语义拍卡点、极致快切少呼吸。信息层=真实截图证据 + 弹字/命令卡 + 手绘注解 + (部分创作者)3D卡通隐喻。
+
+## 0.5 · 战略层:为什么这么剪(从战略到策略)
+> 摸清底层意图,才不会机械抠像。参考片这套之所以成立,是5条战略在支撑,下面每条战略→落到具体策略/组件。
+1. **数字人口播 = 生产可规模化**(战略)→ 一条音轨骨架 + 可再构图人像,不依赖真人拍摄,能批量复制。(策略:两层模型,人像层大部分隐去/缩小)
+2. **信息层高密度 = 制造"干货感"**(战略)→ 每个名词都有画面响应、快切少呼吸,用视觉密度兑现"信息量大、值得看/收藏"的心理预期,拉完播率。(策略:法则3每名词有响应 + 节奏快切)
+3. **人像露/藏 = 情感与信息的节奏调度**(战略)→ 在"亲和信任"和"信息效率"之间动态平衡。(策略:**"对你说vs给你看"总纲** + 人像状态机)
+4. **手作质感 = 差异化人格 + 亲和**(战略)→ 涂鸦/撕纸框/像素图,区别冷PPT与纯AI,立"用心的极客笔记"人设。(策略:设计层手绘描边 + 组件层手绘涂鸦标题/像素卡)
+5. **真实证据优先 = 可信度**(战略)→ 讲什么给什么真实截图/录屏,不mock。(策略:信息层证据镜 + 法则4真图硬规)
+> **一句话战略**:用数字人把生产做轻,用高密度信息层把"干货感"做足,用人像露藏调度信任节奏,用手作质感立人设——低成本、可复制、还显得用心。
+
+## 1 · 核心法则(跨样本归纳)
+1. **一拍一主体,说完让位**:任一时刻视觉重心只有一个(host 或 一张信息卡);新元素只在语义拍边界进场,不一句一元素堆积。[核]
+2. **host 是可变构图的图层,不是主角**:全片 host 在 PIP / 隐去 / 角落头 / 半身 间切换,**多数时间隐去或缩小**,把画面让给信息。构图靠剪辑再构图同一条素材,不是生成不同构图。[核]
+3. **每个名词都有画面响应**:口播提到命令/文件/数字/概念,0.3~0.8s 内必有对应 chip/卡/大字/箭头弹入同步。[核]
+4. **真实证据优先**:讲工具/操作/数据,满屏铺**真实截图/录屏**(不 mock),配证据镜(滚动/放大/圈注/下划线)。[核]
+5. **背景让位**:上层弹信息时,底层截图高斯模糊+压暗,绝不与前景抢注意力。[核]
+6. **快切少呼吸**:平均每拍 ~3-4s,密集处 1-2s;只在章节卡/收尾/真人定调时留短呼吸。[核]
+7. **真人回切建信任**:每逢定调观点 / 纠偏认知 / 转折 / 收尾,硬切回 A-roll 半身正机位、清空浮UI、用眼神锁定。[核]
+8. **手绘感统一质感**:涂鸦标题/箭头/撕纸PIP框/像素插画构成"极客手作笔记"的统一手绘质感,区别于冷 PPT。[核]
+
+## 2 · 设计层 The Reference(视觉系统)
+- **色板逻辑(角色化,非装饰)**:强调红/珊瑚(钩子/关键词/警示数字)· 科技蓝(品牌/命令/技术)· 米白波点纸底(章节/信息卡底,护眼笔记感)· 分类绿(模块命名)· 警示黄橙(高亮/箭头)。**每色承载一个含义**。[核]
+- **字体**:主标题=粗黑体带手绘描边(手作笔记感);命令/代码=等宽 mono;正文卡=现代无衬线粗体。[核]
+- **幕底三态**:信息期=高斯模糊截图/录屏;转场/章节期=复古米白波点像素幕底;共情/定调期=真实工位环境景深。[核]
+- **构图系统(★核心,Round2 直接套)**:host 五态 —
+ - **半身**(真实工位):hook/定调/纠偏/收尾,建信任。
+ - **PIP框内**(撕纸拍立得/圆形):伴随讲解、总述,人退居边缘让位。
+ - **角落头**(底部/角落小圆):列痛点/信息密集时进一步缩小。
+ - **隐去**:深度原理/满屏证据/章节卡时彻底藏。
+ - **满屏**(人极小或无):纯截图/录屏证据。
+ - 画幅混合:样本里有 3:4 竖屏也有 16:9 横屏,方法论构图无关、按渠道定。[核]
+
+## 3 · 组件层(清单 → 工具映射)
+> 每种参考片组件 → talkcraft 108卡 / student-kit 能否直接做 + 素材来源。slug 为 talkcraft `template/cards/`。
+| 参考片组件 | 作用 | talkcraft 对应卡 | student-kit | 素材来源 |
+|---|---|---|---|---|
+| 手绘涂鸦标题徽章 | 开篇/章节爆点词强调 | `scribble-annotation` `behind-text-title` | 手绘风 | 设计/生成 |
+| 章节卡(多样式) | 换幕定音、章节命名 | `chapter-title-card` | hero hold(Law9) | 设计 |
+| 关键词/命令chip(堆叠) | 命令/要点纵向staggered弹入 | `chip-grid-single-select` `flying-words` `alt-block-lines` | word-reveal | 生成 |
+| 数字滚动卡 | 超大数字(95%/70%/180%)冲击 | `number-roll`(组件) `count-badge-title` `countdown-arc-scatter` | type SCALES(Law8) | 生成 |
+| 概念标签卡+手绘箭头 | 概念定义/上下级/静态vs动态 | `callout-line-label` `converging-arrows` `chevron-lower-third` | — | 生成 |
+| 证据镜(滚动/放大/圈注/下划线) | 真截图上找证据 | `evidence-scroll-tour` `highlighter-sweep` `corner-bracket-frame` `magnifier-detail` | — | 用户截图/录屏 |
+| 进度清单列表 | 痛点/步骤/1-N复盘 | `chapter-progress-list` | — | 生成 |
+| 引用气泡 | 痛点举例/模拟AI回复 | `danmu-bubble-praise` `chat-message-flow` | — | 生成 |
+| 对比分栏 | 双方案/收益对比 | `split-60-40-story` `alt-block-lines` | — | 生成 |
+| host PIP(撕纸/圆形框) | 人降级伴随 | `host-shrink-to-chip`(host-footage §5) | — | 用户口播素材 |
+| 底部字幕条 | 逐句跟读 | `Subtitles`(组件) | caption | 转写 ★剪映补 |
+| 像素/线稿示意图 | 章节/机制示意 | `schematic`(G5线稿,仅线稿) | — | 线稿=talkcraft;像素风=需生成 |
+| 3D卡通隐喻插画/短片 | 痛点/机制具象化 | ❌ 无(talkcraft/student-kit都没有) | ❌ | **需AI生成**(缺口,见反模式下方) |
+
+**两个组件缺口**(talkcraft/student-kit 都不直接产):①像素风插画/吉祥物 ②3D卡通隐喻角色/短片。→ Round2 走 AI 生图/生视频补,或降级为线稿(schematic)。
+
+## 4 · 编排层 · "情境→打法"决策树(★心脏,Round2 直接用)
+> ⚠️ **本节已升级**:以独立的 **《编排层-文本驱动决策表.md》**(8样本536拍数据背书、13类功能→打法)为准。核心总纲:**说话人露不露=这句"对你说 vs 给你看"**。下方6类是v1初版聚类,保留参考。
+> 跨 10 样本 80+ 条规律聚类成 6 类。用法:给用户口播每一拍打情境标签 → 查对应打法。
+
+### A|有匹配素材(截图/文档/录屏/实拍)→ 满屏铺 + host降级 + 证据镜
+- 引用文档/热点/源码 → 满屏铺该截图 + host降PIP或隐去 + 涂鸦标题强调爆点词。[核]
+- 论证资源丰富/海量列表 → 全屏截图**纵向匀速滚动**(缓推拉) + host降左下PIP。[核]
+- 演示实操/工作流/点击 → 满屏录屏 + host隐去 + 证据镜(光标/滚动/高亮)。[核]
+- 展示长报告/长文档 → host隐去 + 截图整屏 + 自下而上匀速滚动展全貌。[核]
+- 引用跑分/评测数据 → host缩右上PIP让位 + 截图弹入 + 左右图文对齐。[核]
+- 教命令/快捷键 → 满屏CLI/IDE录屏 + 命令chip弹入视觉中心 + 终端同步高亮。[核]
+
+### B|无素材·纯观点/概念/机制 → host态调整 + 概念可视化
+- 讲概念结构/分类 → host隐去 + 概念标签卡 + 手绘箭头建上下级。[核]
+- 讲抽象底层机制 → **强视觉物理比喻**(打印机吐无限纸卷/施法升维) + host圆形PIP辅助解说。[观]
+- 讲阈值/关键数字 → 保留界面 + 居中巨型数字卡 + 拟人警示标签。[核]
+- 定调观点/主结论 → A-roll半身推近 + 真实工位 + 无贴片干扰。[核]
+- 纠偏认知/反常识("不是A是B") → 瞬间硬切A-roll半身正机位 + 清空界面 + 眼神冲击。[核]
+
+### C|列举/清单/并列 → chip堆叠 或 进度清单 + 背景模糊让位
+- 列举N并列项/命令 → N个chip纵向/水平staggered堆叠弹入 + 背景模糊让位。[核]
+- 列举等价操作(拖拽/按键A/按键B) → 多chip垂直/水平staggered。[核]
+- 列举避坑/误区 → 高对比概念标签卡("3个误区") + 保留界面锚点。[核]
+- 痛点清单 → 进度清单列表纵向堆叠 + host降角落PIP。[核]
+
+### D|情绪/痛点/共情 → 3D卡通隐喻 或 角落头+引用气泡
+- 病理性/情绪痛点 → host隐去 + 3D卡通角色苦恼抓头插画 + 手绘箭头戳痛点。[观](部分创作者路线,需生成素材)
+- 抛痛点/设问 → A-roll角落头 + 头顶引用气泡列举痛点 + 背景静态让位。[核]
+- 模拟反面低效操作 → 趣味3D角色冲突动画(怪兽击倒小人) + 极简让位。[观]
+
+### E|结构性节点(章节/转折/收尾)→ 换幕 / 硬切真人 / 复位
+- 进大章节/新模块 → 整屏切换章节卡(像素/线稿/录屏) + host隐去 + 停1-2s定音 + 左上角换涂鸦徽章。[核]
+- 转折/新话题 → 硬切回真人半身居中 + 剔除浮UI + 眼神锁定。[核]
+- 收尾/复盘 → 1~N进度清单轮播 + 像素背景;结束Slogan → host复位居中PIP + 纯渐变背景。[核]
+
+### F|纯画质/沉浸证明(特定题材:游戏/生图/视频)→ 满屏B-roll
+- 展示画质/场景细节 → 整屏B-roll(游戏录屏/实拍漫游) + host隐去 + 纯画质承接论点。[观]
+- 复刻/1:1还原证明 → 第一人称交互漫游 + 大纵深展示真实性 + 手持微推拉当"物理证据"。[观]
+
+## 5 · 节奏与音频
+- 节奏:平均~3-4s/拍,密集处1-2s;章节卡/收尾/真人定调留短呼吸。前段高频轰炸(2s一次)、中段原理放缓(~5s)、尾段真人回抓。[核]
+- 音效:章节换幕带卡通提示音;数字/chip弹入带轻音效。**BGM/字幕在剪映补,不在本方法论**。[核]
+
+## 6 · 反模式(不要做)
+- ❌ 一句一个新元素堆积(凌乱根源);新元素只在语义拍边界进。
+- ❌ 裸大字/裸章节卡凑数——每拍要有具体视觉承载(对齐 memory 温感手写地板)。
+- ❌ 上层信息不模糊背景 → 前后景文字打架(对齐 memory 画面丰富两规则)。
+- ❌ 四张同色同纹样章节卡("又来了"不是"翻页")——每章一套主题色+相关线稿motif。
+- ❌ 用代码 mock 假 UI 冒充真截图——有真实页面就截真图。
+- ❌ host 长期占据画面主中心抢信息位。
+
+## 7 · Round2 应用指引(拿到用户素材怎么走)
+1. **理解素材**:转写口播 + 盘点用户有哪些截图/录屏/图 + 认 A-roll 构图(数字人可任意再构图)。
+2. **逐拍打情境标签**(A/B/C/D/E/F)→ 查本决策树 → 生成 SHOTBOOK(每拍:情境→打法→组件→素材来源)。
+3. **缺素材处理**(按组件表"素材来源"列):证据类→要用户截图/我方Playwright截;生成类chip/卡→设计生成;3D卡通/像素→AI生图生视频或降级线稿。
+4. **搭建渲染**:talkcraft卡(蒙皮改CONFIG) + student-kit整屏切换 → Remotion渲。
+5. **收尾**:作者剪映补 字幕+BGM。
+
+---
+> 状态:初稿,规律已跨样本聚合。待 作者眼核 / 或交 Gemini 二次精炼。真正验收=Round2 拿新素材跑出样片(作者定的唯一验收关)。
diff --git "a/skill/seecut/references/02-\350\256\276\350\256\241\344\273\244\347\211\214Design-Reference.md" "b/skill/seecut/references/02-\350\256\276\350\256\241\344\273\244\347\211\214Design-Reference.md"
new file mode 100644
index 0000000..5c1cf52
--- /dev/null
+++ "b/skill/seecut/references/02-\350\256\276\350\256\241\344\273\244\347\211\214Design-Reference.md"
@@ -0,0 +1,156 @@
+# 《参考片 Design Reference》· 设计令牌(★施工包缺的那块)
+
+> 定位:这是下游"蒙皮"的**单一真相源**——talkcraft/student-kit 的卡都是中性件,进片**必须蒙上这套令牌**才是参考片质感(round2 丑的根=用了默认皮)。对标 talkcraft `design-language.md` / student-kit `tokens.css`。
+> 来源:agy 实测两条参考原片(13/02)提取设计DNA + 我抽帧核实(色板/像素/点阵/药丸/涂鸦均已核) + Vox Explainer 令牌结构参照。2026-09-19。
+> 风格名:**极客手账风(Geek Craft + Notion Aesthetic)**——极客工位背书 + 手账纸感 + 复古像素 + 弹簧微动效 + 手绘涂鸦。绝不纯黑纯白硬碰撞。
+
+## 0 · 两层结构总纲(★最重要,8条实证修正)
+> 更正:初版拿2条样本把"米白纸底/像素"当成了universal,8条复查后翻车。参考片**没有一张固定皮**,是"**恒定内核 + 按内容自适应**"。下游要学的是这套自适应,不是一张死皮。
+
+**A. 恒定内核(跨8条不变,蒙皮的地基)**:
+- **动效**:弹簧回弹(cubic-bezier(0.34,1.56,0.64,1)) + 音频驱动stagger(80~120ms) —— 6/6样本全符合,这是"丝滑"的真命门。
+- **字体**:无衬线**粗黑体**(800~900),非衬线(区别于Vox的Fraunces)。
+- **强调色族**:青柠/薄荷绿 + 复古砖红 + 琥珀黄(族固定,具体主色可变,见下)。
+- **手作质感**:手绘涂鸦箭头 + 荧光笔划线(多数样本有;纯3D卡通条如s10可无像素但仍有涂鸦)。
+- **人像卡化**:真人=圆角卡/撕纸PIP/圆形PIP,带边框+柔和阴影(§6),绝不怼脸大头。
+- **视觉模块跟功能走**:什么内容配什么模块 = 我们的《编排层决策表》。
+- **三禁**:不纯黑#000/纯白#FFF硬碰撞 · 不刺眼纯红大字报 · 不硬切无缓动。
+
+**B. 按内容可变层(每条/每段落自适应,不是硬规则)**:
+| 可变项 | 取值随什么变 | 实证 |
+|---|---|---|
+| **背景底** | 看这段讲什么 | 讲录屏操作→真录屏底(暗IDE/白UI) · 讲概念→米白纸质点阵/纯色画板 · 引用→满屏真截图。**样本13一条就4种底** |
+| **强调主色** | 每条选一个主色调 | 13砖红主 / 03·10绿主 / 11红黄双主(都在色族内) |
+| **像素 or 3D卡通** | 风格取向(创作者/题材) | 13·04·11像素CRT / 10·02皮克斯风3D卡通 |
+> 🔴 唯一的背景硬规则:**永远不把主讲人虚化铺底当背景**(round2的病)。背景可以是真录屏/纸质/纯色,就是不能是模糊人脸。
+
+---
+> 下面 §1~§7 是**内核令牌的具体值**(可变项已在上表标出,别当死规则)。
+
+## 1 · 色板 tokens(近似HEX,均已抽帧核 —— 底色/主色属§0可变层)
+```
+--paper #F8F5EE 暖米纸底 · 核心大背景/幕底(替代冷硬纯白)
+--paper-2 #F4F6F9 浅冷灰微渐变 · 衬彩色Web界面时用
+--surface #FFFFFF 纯净白 · 信息卡底(配柔和阴影做悬浮)
+--dark #1A1D20 炭墨黑 · 顶部胶囊药丸标签底/代码块底(稳重心)
+--ink #1F2329 油墨深灰 · 正文/主标题字(比纯黑#000耐看)
+--muted #4E5969 石板灰 · 副标题/路径/次要参数
+--red #D9483B 复古砖红 · 核心强调/指令(/init)/像素小人/指示箭头
+--lime #7DC542 荧光青柠绿 · 技术关键词(Claude.md)/动态标签/成功态
+--amber #F59E0B 琥珀荧光黄 · 荧光笔高亮/重点框选边框
+--tint #EDE9FE/#F0F4F8 浅灰蓝/淡紫 · 标签浅底/行内代码药丸底
+```
+铁律:**底色永远暖米/浅灰,字永远油墨深灰,绝不#000/#FFF硬碰撞、绝不刺眼纯红大字报**。
+
+## 2 · 字体 tokens
+```
+--font-display 高字重无衬线大黑体(MiSans/PingFang/阿里普惠 Heavy) 800~900 字面宽扁饱满
+ 处理:①深色圆角胶囊药丸反白包裹 ②痛点/主题用3D气球金箔字【待核·可能略夸张】
+--font-body 人文无衬线(Inter/PingFang Medium/SF Pro) 400~500 字距-1% 行高1.5~1.6 左圆点列表(Notion感)
+--font-mono 等宽编程字(JetBrains Mono/Fira Code) 600~700 关键命令放大提色 + 浅圆角inline底
+--字幕条 圆角淡绿/淡白胶囊衬底 或 纯白黑体+极细黑扩散阴影(复杂画面也清晰)
+```
+⚠️ 与 Vox 的区别:Vox 标题用衬线(Fraunces),**参考片是无衬线粗黑体**,别抄错。
+
+## 3 · 背景/幕底(按这段讲什么选;v2 与 `00-总纲` 第4-7条一致)
+> v2 修订说明(详见 CHANGELOG):v1 的"默认干净、真素材执行窗不主动够"已撤销。当时判丑的"满屏"其实是**假证据满屏**(抽象代码窗/占位网格拼贴),错的是"假",不是"满"。参考片的满屏靠的是**真实、相关、连贯**的证据。
+
+### 选底规则(逐段判,按决策表的"有据/无据")
+1. **有真证据的段(讲产品/网页/文档/数据/操作/引用)→ 真证据底**:真截图/录屏满屏铺,配证据镜(滚动/放大/圈注/下划线);前景卡弹出时底图 20~40px 模糊 + 降对比 + 浅蒙层让位(方法论法则5)。这是参考片的正常做法,**执行窗必须主动去拿证据**(`04` 第2步 + `scripts/grab_evidence.mjs`)。
+2. **纯观点/情绪/自述段 → 半身露脸 或 干净设计底**:半身实景(真人/数字人书房)+ 少量关键词卡;或米白点阵纸底(`--paper #F8F5EE`+方阵点+2~3%微噪点) + 前景元素扛密度。
+3. **章节/转场段 → 章节卡整屏换幕**(像素/线稿/点阵纸底)。
+4. **拿不到证据的"有据段" → 退回第2条**,并在交付报告"证据缺口"里写明缺了什么、为什么没拿到。
+
+### 禁止(总纲第5条)
+- ❌ 抽象占位窗口 / 伪代码横线网格 / 假 Mac 三色点窗口 / 假 App 界面,冒充证据或"填满"画面(2-3.1 v6/v7.3 的死因)。
+- ❌ 与本段话题无关的装饰截图拼贴。
+- ❌ 主讲人虚化铺底当背景。
+
+### 两条底线
+- **审核安全**(总纲第7条):证据截图入片前逐张读图,不得出现可读敏感字(下载/反爬/扫码/搬运/联系方式/加微信/站外引流/违规承诺…);有就裁掉/打码/换一张,拿不准就不用。
+- **不与前景混淆**:底不得被误读成前景卡或字幕。
+
+## 4 · 手作质感元素(5种,破冷感的命门)
+1. **8-bit像素**:低分辨率CRT屏(红蓝绿色块) + 像素橙红小怪兽/机器人。用于前3秒概念定调。
+2. **白粉笔/蜡笔涂鸦箭头**:边缘粗糙带手抖感的白细线+单线箭头(如指人物头`ADHD ➜`)。直接画在实拍/3D人物上。
+3. **荧光笔划线**:半透平头马克笔刷过文本(淡黄/亮绿,两头微透中间实)。说到核心结论时动态刷过。
+4. **粗3D立体箭头**:红绿两色圆润厚实箭头,柔和漫反射,斜插/垂直。逻辑分流(静态vs动态)。
+> 实现:手绘圈/下划线/箭头用 `assets/hf-hw/`(HF 官方组件),**墨色必须覆盖为 `--red`/`--ink` 等本令牌色**(组件默认 #f4f2ec 是给深色底的,米白底上看不见)。
+5. **贴纸+撕纸边**:带小红书/推特微缩图标的贴纸卡;人像/截图边缘不规则纤维毛边(便签随手贴感)。
+
+## 5 · 动效 tokens("高级丝滑"的本质=弹簧物理+音频驱动stagger)
+```
+--ease-spring cubic-bezier(0.34, 1.56, 0.64, 1) 出入场一律弹簧回弹,105~108%overshoot再回100%
+--dur-in 0.25~0.35s
+--stagger 80~120ms(约3~4帧) 元素绝不同步出,按口播语调级联下落
+ 典型序列:黑药丸标题弹出→3D箭头刺入(Y-30→0弹性)→白卡展开→荧光/代码标签随重音最后现
+--camera-breath 真人全屏时极缓推镜 ~1%/秒(增强专注)
+--punch-in 重要转折无缝跳切放大1.15~1.2x(中景→近景,无转场,制造力量感)
+--window-pinch 全屏真人→演示:整窗收缩(pinch),平滑变形+赋圆角阴影,退成角落PIP(逻辑连贯不断层)
+```
+🔴 round2 的病=硬切+无缓动默认件。正确:每个卡/字/箭头都挂 --ease-spring + stagger。
+
+## 6 · 人像卡规范(真人=组件化,不是怼脸大头)
+```
+① 分屏竖向圆角卡(讲解态):靠右占宽35~40%/高75~80%,左侧留白放大卡文本清单
+ 圆角20~24px · 1px极细半透边rgba(0,0,0,0.06) · 多层柔和阴影 box-shadow:0 16px 36px rgba(0,0,0,0.08)
+② 左下圆形PIP(全屏演示态):直径占宽20~25%,左下留边~30px,正圆裁切+3~4px纯白描边(现场引路人)
+③ 撕纸毛边开场卡(概念切入态):手撕纸质白边+微翘曲阴影,居中或下方
+④ 真人实景背书:暖光台灯+双屏暗色IDE+原木书架+高达/机械臂模型+玻璃台面倒影(极客专业感)
+```
+🔴 round2 的病=怼脸大头顶中上部 + 光秃秃小圆。正确:上面三种卡形态之一,带边框/阴影/留白。
+
+## 6.5 · 素材类型 × 露藏基调(开工第一步判定)
+> 先按素材类型定基调,再按句子功能(决策表)微调。关键区分:**有没有完整的口播人像 A-roll**。
+
+| 素材类型 | 人像形态 | 露藏基调 | 关键规则 |
+|---|---|---|---|
+| **①半身口播(真人实拍 或 数字人完整半身 A-roll,如 2-2、2-4 数字人)** | 可半身大露 / 缩卡化小窗 / 藏 | 按"对你说露、给你看藏" | 演示/信息拍缩或藏让信息层唱主角;观点/情绪/收尾放大半身;竖版可用"上信息卡 + 下半身"分屏 |
+| **②角落圆 PIP 素材(如 2-3)** | 角落小圆,露成本低 | 默认多露少藏 + 有调度 | 自述/感叹/总结必露且情绪拍放大;纯演示拍缩小退让;别全程常驻不动 |
+| **③点缀型数字人(没有完整 A-roll,只有几个镜头)** | 只点缀 | 音频为骨架,数字人少露 | 只在 hook/情绪/总结出现;其余按"有素材→信息层 / 无素材→图形组件或大字卡"填 |
+
+- **通用**:自述、感叹、总结/观点句 = 该露;纯给你看的信息/演示 = 可藏让位;无脸连续 ≤5s;人像形态全片统一、位置变化跟着功能走(总纲第10条)。
+
+## 7 · 音效体系
+- **BGM**:Tech-LoFi/Chillhop 95~110BPM,电钢琴琶音+电子鼓;**sidechain侧链闪避**,人声开口BGM下潜-18~-24dB。
+- **微音效**:①bubble-pop木鱼声(卡片/像素/黄块/气球弹出,80~150ms) ②机械键click(命令/终端) ③marker-swipe沙沙(涂鸦/荧光划线) ④whoosh薄纸风(卡片滑入/PIP缩放/跳切) ⑤ping清脆铃(步骤完成/文件生成)。
+- (BGM+字幕在剪映补,音效可在渲染端配)
+
+## 8 · 组件 → 两仓卡 映射(★上游修正:Vox比talkcraft更贴参考片)
+> student-kit `Vox Explainer`(米白纸质/墨水/编辑感)最贴参考片;talkcraft(几何/dev-craft)为辅;引擎按段渲染再拼可混用。
+| 参考片组件 | student-kit Vox 卡(首选) | talkcraft 卡(辅) |
+|---|---|---|
+| 荧光圈注/马克框 | `section-highlight` `section-circle` `section-markerbox` | highlighter-sweep |
+| 撕纸PIP/撕纸条 | `section-tornstrip` `stat-torn` | theme-frame(撕纸式) |
+| 抠图贴纸 | `section-cutout` `section-stamp` `stat-postage` | media-pop-in |
+| 数字大卡/滚动 | `stat-left`(giant) `stat-odo` `stat-multiplier` | number-roll/count-badge |
+| 放大镜证据镜 | `stat-magnifier` | magnifier-detail/evidence-scroll |
+| 进度清单/步骤 | `overview-numlist` `overview-checklist` `overview-stepper` | chapter-progress-list |
+| 概念对比分栏 | `stat-vs` `section-split` `overview-compare` | split-60-40 |
+| 章节卡 | `section-numeral` `overview-toc` | chapter-title-card |
+| 命令/代码chip | `section-classified` `section-indexcard` | chip-grid/claude-code卡 |
+| 引用气泡/贴条 | `section-ticker` `stat-quote` | danmu-bubble/chat-message |
+| 像素/CRT | (参考片特有,需自制或生成) | schematic(线稿降级) |
+> ⚠️ 这些卡是**中性件**,进片必须蒙第1-6节令牌(改CONFIG的颜色/字体/圆角/阴影/缓动),不改运动命门。
+> ✅ 映射已核实(读了5张Vox卡源码):section-highlight=荧光笔刷过关键词 · section-tornstrip=撕纸条对角贴 · stat-magnifier=放大镜悬停数字 · overview-numlist=清单行stagger左入 · stat-left=巨大数字+黄slab。它们的stagger/放大/撕纸正是参考片动效。
+
+## 8.5 · 引擎按段渲染再拼(两仓混用施工说明,补B)
+- **引擎不互斥**:talkcraft卡=Remotion(.tsx),student-kit/Vox卡=HyperFrames(.html)。二选一**只发生在"单个合成文件内"**,最终成片可混。
+- **施工方式=按段/按元素各自原生渲染 → 合成器拼**:
+ 1. 每个信息层卡:用它所属引擎渲成片段(Vox卡→HyperFrames渲;talkcraft卡→Remotion渲),可带透明通道(webm/PNG序列)。
+ 2. 人像层:真人clip按§6卡形态(圆角/撕纸/圆形PIP)裁框。
+ 3. **在合成器(剪映时间线 / ffmpeg overlay)上分层叠**:底(音轨+背景底) + 信息层卡(各引擎渲出的片段) + 人像层PIP + 字幕(剪映)。
+- **对齐**:卡的入场时刻锚口播节拍(用SRT词级时间);音效点对齐弹入帧。
+- **提速**:host降720p、测试段先渲;Remotion渲染本身不慢(段级几分钟),别被4K编码/僵尸进程拖(round2教训)。
+- 结论:不选A/B引擎,**哪张卡贴参考片就用哪个引擎渲那一段,最后拼**。Vox贴参考片→多数信息卡走HyperFrames;talkcraft补talkcraft独有的。
+
+## 8.6 · 版式按源素材/交付定;竖版时按零件重排(2026-09-19起,2026-09-20补)
+> ★前提(作者 2026-09-20):**画幅横/竖按源素材+交付定,不写死竖版**。源/交付是横版→Vox 横卡(1920×1080)可近即插、最省;源/交付是竖版 reel→才需下面的按零件重排。开工第0步先定画幅。
+### (以下为竖版 reel 情形)
+- **问题**:Vox卡原生是 1920×1080 **横版**,reel是 2160×3840 **竖版**,卡verbatim塞竖frame=上下大片空纸(犯质量地板"卡飘空背景")。
+- **正解=按零件重排(不是verbatim复制横卡)**:**复用Vox的真零件**(clip-path撕纸/报纸纹理/GSAP弹入/tokens/CSS类),**只重排布局**成竖版满frame。
+- **铁律①判定(方法论owner定)**:这**在红线内**。铁律①本意=禁"脱离真设计系统、凭空手捏样式冒充",**不是禁改布局**。用真设计系统零件按目标画幅重排=正当;漂移成手绘lookalike冒充才越线。
+- 实证:Round2-2 的 S1 竖版重排(撕纸标题+药丸高亮+点阵纸底+手绘下划线+像素robot+手写旁注)满frame、三禁全过、真参考片质感;横卡当带那版上下大空纸=淘汰。proof: 作者本地过程记录(未收录)。
+
+## 9 · 一句话落地速查
+底色改 `#F8F5EE` + 6%噪点 + 30px点阵;标题 ExtraBold 无衬线字距-1~2%,关键词用砖红/青柠绿或深药丸反白;入场一律弹簧缩放0.25~0.35s + stagger 3~4帧;每个动效点对齐一记 bubble-pop/marker/key/whoosh 音效;真人只走三种卡形态;**永远不模糊人脸当背景、永远不用刺眼纯红大字报、永远不硬切**。
diff --git "a/skill/seecut/references/03-\347\274\226\346\216\222\345\261\202\345\206\263\347\255\226\350\241\250.md" "b/skill/seecut/references/03-\347\274\226\346\216\222\345\261\202\345\206\263\347\255\226\350\241\250.md"
new file mode 100644
index 0000000..523746f
--- /dev/null
+++ "b/skill/seecut/references/03-\347\274\226\346\216\222\345\261\202\345\206\263\347\255\226\350\241\250.md"
@@ -0,0 +1,67 @@
+# 编排层 · 文本驱动决策表(Round1 核心交付 · v2)
+
+> 数据来源:8条参考片样本、**536拍**,经"文案先行"重跑(口播原话↔画面打法)+ 按"这句功能"聚合。这是**可泛化、文本驱动**的编排规则——不是复刻片段,是"给我一句口播,我知道画面该怎么处理"。
+> 配套原料:`beat-sheets-v2/*.v2.md`(每拍=口播原话+功能+人像层+信息层+动效+转场)。
+
+## 0 · 两层模型(先破"A-roll/B-roll"二分)
+参考片不是"A-roll vs B-roll",而是**一条连续音轨 + 两个可叠图层**:
+- **音轨**(数字人/真人配音)= 全片连续骨架,定时间轴。这才是真"A-roll"。
+- **图层① 人像层**:状态可变(半身/PIP撕纸框/角落小圆/隐去),**不必每拍出现**。
+- **图层② 信息层**:截图/录屏/chip/卡/大字/3D,盖在音轨上。
+
+**一句话总纲**:**说话人露不露,取决于这句是"对你说"还是"给你看"。**
+- 对你说(情感/观点/收尾/纠偏/建信任)→ **露**(半身或PIP)。
+- 给你看(演示/信息/证据/列举)→ **藏**(隐去或缩角落),信息层当主角。
+
+## 1 · 核心流程(Round2 直接用)
+1. 转写用户口播 → 逐句。
+2. 给每句打**功能标签**(下表13类之一)。
+3. 查下表 → 定〔人像层状态〕+〔信息层内容〕+〔动效/转场〕。
+4. 出 SHOTBOOK(每拍:口播原话 → 功能 → 人像层 → 信息层 → 素材需求)。
+
+## 2 · 功能 → 打法 决策表(★数据背书,括号=536拍中占比/次数)
+| 口播这句的功能 | 人像层(主导) | 信息层(主导) | 说明 |
+|---|---|---|---|
+| **hook钩子**(开篇留人) | PIP撕纸框(38%) | 满屏热点截图/图 + 手绘涂鸦标题徽章 | 人压底陪衬,标题砸爆点词 |
+| **建立信任·自我暴露** | 半身/PIP(各31%) | 空 或 轻截图 | 露脸建立真人感 |
+| **举例演示**(敲命令/点操作) | **隐去(77%)** ★最强 | **满屏截图/录屏** + 命令chip + 证据镜 | 演示时人必让位 |
+| **讲底层机制/原理** | 隐去(58%) | 截图 + 命令chip + 概念卡+手绘箭头 + 证据镜 | 图解结构 |
+| **引用文档/源码** | **PIP撕纸框(56%)** | 满屏该文档截图 + chip | 人压底"陪看"文档 |
+| **列举并列项/命令** | 隐去/PIP | **命令chip纵向staggered堆叠 / 进度清单列表** | N项→N chip |
+| **给关键数字/阈值** | 灵活 | **数字大卡**(9/17主导) | 数字=大卡冲击(红警示/蓝正向) |
+| **定调观点/下结论** | 灵活(隐去43%/半身/PIP) | 截图+chip支撑 或 空 | 有据则铺证据,纯观点则露脸 |
+| **纠偏认知**(不是A是B) | 隐去/半身 | 概念卡+手绘箭头 + 证据镜(下划线扫过) | 点破根因 |
+| **情绪痛点共情** | 隐去/角落小圆(49%/22%) | **3D卡通隐喻**(11次) / 进度清单(痛点逐条) | 痛点专用3D隐喻具象化 |
+| **转折过渡** | 隐去/半身 | 空 或 章节卡 | 承上启下 |
+| **章节命名**(进新模块) | 隐去(56%)/半身 | **章节卡 + 像素/线稿示意图** | 整屏换幕定音1-2s |
+| **收尾道别/复盘** | **半身(70%)** / 隐去(复盘时) | 空(人说) / 进度清单1~N轮播(复盘) | 收尾露人;复盘走清单 |
+
+## 3 · 人像层状态机(何时露/缩/藏,独立速查)
+- **露半身** = 收尾(70%) · 建立信任 · 纠偏/定调(部分) —— "人正对你说话"的时刻。
+- **PIP撕纸框陪伴** = hook · 引用文档 · 边讲边陪。
+- **角落小圆(角落头)** = 情绪痛点 · 信息密集需进一步让位。
+- **隐去** = 举例演示(77%) · 讲机制(58%) · 满屏证据 —— "信息才是主角"的时刻。
+- 切换动效:露→缩用 PIP缩放;缩→藏用整屏切换/背景模糊让位;藏→露用硬切。
+
+## 4 · 信息层选型(内容特征 → 组件,接组件层)
+- 有真实页面/操作 → 截图/录屏 + 证据镜(滚动/放大/圈注/下划线)
+- 多个并列项/命令 → 命令chip堆叠 / 进度清单
+- 具体数字/阈值 → 数字大卡
+- 概念关系/分类 → 概念卡+手绘箭头
+- 情绪痛点 → 3D卡通隐喻(缺口,需生成/降级角落头+引用气泡)
+- 章节切换 → 章节卡 + 像素/线稿图
+- 纯观点无据 → 信息层留空、只露人
+
+## 5 · 三类用户输入的适配器(人像层原料从哪来)
+| 用户输入 | 人像层原料 | 怎么再构图 |
+|---|---|---|
+| 录屏(左下小脑袋) | 已含小脑袋 | 抠出当PIP/角落;需满屏时盖住 |
+| 真人半身口播 | 一条完整半身 | 按状态机 切半身/缩PIP/隐去 |
+| 数字人(音轨+完整出镜图) | 生成的完整半身 | 同上;大部分隐去,少数露 |
+→ 三者**编排引擎(本表)完全共用**,只差"人像层原料"这一层适配。
+
+## 6 · 诚实边界
+- 表中占比是8样本536拍的统计倾向,**不是硬规则**——同一功能人像层常有多选(如定调可露可藏),最终看这句"对你说 vs 给你看"的成分。
+- "灵活"类(定调/给数字/转折)需结合上下文,不能纯查表。
+- 3类输入里"数字人"样本尚未实测,录屏/半身可先跑验证。
+- 真正验收=Round2 拿真素材出样片(作者定)。
diff --git "a/skill/seecut/references/04-SHOTBOOK\346\226\275\345\267\245\350\247\204\346\240\274.md" "b/skill/seecut/references/04-SHOTBOOK\346\226\275\345\267\245\350\247\204\346\240\274.md"
new file mode 100644
index 0000000..869ca10
--- /dev/null
+++ "b/skill/seecut/references/04-SHOTBOOK\346\226\275\345\267\245\350\247\204\346\240\274.md"
@@ -0,0 +1,95 @@
+# SHOTBOOK 模板与施工规格(管线步骤②③)
+
+> 作用:把《编排层决策表》+《Design Reference》+两仓卡库 串成"每镜可填、可施工"的表。这是步骤②(编排)+③(判断补素材)的落地件。
+> 依赖:`编排层-文本驱动决策表.md`(功能→人像层/信息层) · `参考片-Design-Reference-设计令牌.md`(两层:内核+可变) · `视觉质量地板-审美对齐清单.md`(护栏)。
+
+## 第0步 · 先定全片"可变层"(填镜之前必做)
+参考片是"恒定内核+按内容自适应",所以**开工先给这条片定3个可变项**(Design Reference §0-B):
+1. **强调主色**(色族内选1主色):如砖红主 / 绿主 / 红黄双主。
+2. **像素 or 3D卡通**(风格取向):题材偏工程/极客→像素CRT;偏情绪/生活→皮克斯3D卡通。
+3. **各段落背景策略**:讲操作段→真录屏底;讲概念段→纸质点阵;引用段→满屏真截图;露脸段→真人实景。
+> 内核项(动效弹簧+stagger/粗黑体/手作质感/人像卡化/三禁)全片不变,不用选。
+
+## 第0.2步 · 判素材类型(定露藏基调)
+按 `02-设计令牌` §6.5 判:①半身口播(真人或数字人完整半身 A-roll)/ ②角落圆 PIP / ③点缀型数字人。**关键看有没有完整口播人像 A-roll**,别把"数字人"一律当③。
+
+## 第0.3步 · ★素材台账(素材理解的中间产出,2026-09-20 新增,必产)
+> 作者定:素材理解不能只抽几帧就跳去 SHOTBOOK;要有**可复核的结构化中间产出**,防花样素材翻车。
+- **每个素材(粗剪/录屏/截图/B-roll)跑一遍 agy/Gemini 读视频**(成本 作者已批),别只抽静帧(会漏)。产出一张台账,每行:
+ | 素材 | 类型(实拍口播/录屏/截图/图) | 时长/尺寸/帧率 | 画面内容(agy 读) | 可用片段+时间码 | 能当什么信息层 | 本片用/备档 |
+- **人像素材特判**:是半身还是角落圆球?→ 定第0.2步基调。
+- 台账落 `<工程>/素材台账.md`,是 SHOTBOOK 的原料,也供用户复核"素材理解够不够"。
+
+## 第0.5步 · 填表前先答5个导演问题(融合作者导演编排表精华)
+先理解整篇文案逻辑、拆成语义段落(**不按标点/句长/停顿机械切镜**)。每一镜先答:
+1. 这一段最需要观众理解什么?
+2. 什么画面能让这句话更具体、更好懂?
+3. 画面主体要发生什么变化?
+4. 镜头最后停留在什么结果上?
+5. 它如何承接上一镜、自然进入下一镜?
+**🔴 anti-偷懒铁律**:入场动画、呼吸循环、背景循环、字幕出现**都不算"有效信息变化"**;避免画面长时间没有新内容,也别让动画为了动而动。(呼应质量地板)
+**时间纪律**:镜头起止落在**短语边界**,不跨语义切开;时间戳以转写时间轴为准、不自行估算不改。
+
+## 第1步 · 逐镜 SHOTBOOK(每句口播一行)
+| 镜# | 时间 | 口播原话 | 功能(13类) | 有据/无据 | 证据计划(拿什么真证据/从哪来) | 人像层 | 信息层组件 | 选哪张卡 | 背景底 | 动态变化(镜内第1/2/3变化) | 动效 | 画面衔接 |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|
+
+**每列怎么填**:
+- **功能**:查决策表13类(hook/建信任/举例演示/讲机制/引用文档/列举/给数字/定调/纠偏/情绪痛点/转折/章节命名/收尾)。
+- **有据/无据 + 证据计划(v2 必填)**:这句提到真实产品/网页/文档/数据/操作 = 有据 → 写清要拿哪张真截图/哪段录屏、从哪来(用户素材/自己截/录);纯观点/情绪/自述 = 无据。**有据镜不许空着证据计划**;背景底按 `02` §3 选底规则跟着有据/无据走。
+- **人像层/信息层**:查决策表该功能的主导取值(如举例演示→隐去77%+满屏截图)。
+- **选哪张卡(★组件调库规范,2026-09-21 作者重定:默认查官方库、能拿就拿、禁从头造)**:
+ - **🔴 铁律:原则上"能直接复用 或 微调即用"就直接拿,不要自己从头造**。2-2/2-3/2-3.1 三窗都"看库找灵感再全手搭"→撞位/圈歪/矢量质感,就是违反这条的代价。
+ 1. **HF 官方库 = 默认首选探查**(比 student-kit 丰富太多,~168 组件,github heygen-com/hyperframes + hyperframes-launches,`hyperframes` CLI `add`):正好覆盖参考片所需——`code-snippet-*`(几十种终端/IDE **满屏内容底**)、`reddit-post`/`app-showcase`(真实 UI 底)、`hw-*`(hw-title/hw-scribble/hw-write-title… **真手绘手作**,修矢量圈)、`mk-callout-highlight`/`mk-progress-stat`(荧光圈注/进度)、`apple-money-count`(数字滚动)、`notes-reveal`/`carousel-*`/`flowchart`/`data-chart`/`lt-*`(下三分之一)。**先在这里找。**
+ 2. **student-kit Vox 库(辅)**:`hyperframes-student-kit/style-library/01-vox-explainer/cards`(106 张),官方库没有的对应件再来这。
+ 3. **动效层**:HF `motion-doctrine`(Vector Law/弹簧/连续运镜)+`seam-gate` 自检 + `hw-scribble-transition` 等;不确定 skill 在不在环境则以 Design Reference §5 动效令牌为准。
+ 4. talkcraft 辅;**不用 Remotion**(慢/占算力;HF 够用)。
+ 5. **硬规则(总纲第11条)**:本列必须填 registry 组件名,或"库里没有:原因"。用 `npx -y hyperframes@latest catalog`(需大写 `HTTPS_PROXY`)查。参考片直接可用件:`hw-arrow` `hw-callout-circle` `hw-underline` `marker-highlight` `marker-checklist-card` `spring-pop` `stagger-cascade` `badge-pop` `count-up` `number-pop-in` `comparison-split` `before-after-wipe` `browser-device-stage` `device-frame-stage` `code-snippet-*` `terminal-simulator` `x-post` `reddit-post` `yt-comment-card` `chat-message` `notes-reveal` `vox-annotate` `inline-highlight` `card-resize`。
+ 6. **接线**:registry 组件多是带自预览的独立 composition,要抽 helper 才能塞进单文件 master。手绘三件已抽好在 `assets/hf-hw/`(含墨色覆盖、callout label 慢 1.4s 等坑,见其 README);新抽的组件也补进 `assets/`,下次直接用。
+ - **为什么**:库件的间距/层级/stagger/clip-path/手作质感是设计过的、经战验的——直接拿能少犯撞位/圈歪/矢量感,**别把版式和质感都压给自己手搭 + agy 事后挑**。
+ - **何时才手搭**:三个库都没有的(参考片特有像素 CRT / 特定产品 UI mockup)才从零手搭,且**必须过几何自检**;手搭前先记录"为什么库里没有、为什么必须手搭"(2-3.1 就是没记录、直接手搭)。
+- **★版式(横/竖)按源素材+交付定,不写死**(作者 2026-09-20):
+ - **源素材/交付是横版** → Vox 横卡(1920×1080)**可近即插**、最省(只蒙令牌);成片横版。
+ - **源素材/交付是竖版 reel** → 复用库卡零件(CSS/clip-path/GSAP/tokens)**按竖版重排**(Design Reference §8.6,铁律①内),"抄零件+重排"非只微调。
+ - 开工第 0 步先定这条片的画幅(看素材/交付),再决定"即插 or 重排"。
+- **蒙皮**:这镜用第0步定的背景底+主色;卡按 Design Reference 内核令牌改CONFIG(色/字/圆角/阴影/缓动),不改运动命门。
+- **素材来源**:见第2步。
+- **动态变化(镜内)**:按旁白顺序写这一镜内第1/2/3次变化(主体出现/重点放大/两方案对比/步骤展开/信息从乱到清/结论落定);长镜头必须有内部变化,没必要别凑数。**入场/呼吸/字幕不算变化**(见0.5)。
+- **动效**:内核=弹簧回弹(back.out/overshoot)+stagger入场,禁匀速线性;转场=运动承接(缩窗pinch)/章节卡换幕,禁硬切。
+- **画面衔接**:写清与前后镜如何通过主体/动作/方向/位置/颜色/意义自然接续,**不许只写"淡入淡出"**(呼应motion-doctrine的Vector Law:出场决定入场、同轴同向匹配)。
+
+## 第2步 · 素材需求判断(步骤③,以参考片密度为基准)
+每镜信息层的素材,归入5类之一,缺的进"未采集清单"问用户/生成:
+| 素材类型 | 判断 | 从哪来 |
+|---|---|---|
+| 用户已有 | 用户提供的截图/录屏/图 | 直接用(必要时裁满/去黑边/装饰框) |
+| 需现截图 | 讲到真实页面/产品/文档但用户没给 | `node scripts/grab_evidence.mjs <素材目录> <url>...` 截真图(禁mock假UI);**逐张读图核敏感字**后登记进素材台账 |
+| 需生成图 | 概念图/场景图/海报 | AI生图(Grok/生图skill) |
+| 需生成像素/3D卡通 | hook像素CRT / 情绪痛点3D卡通(组件缺口) | AI生成 或 降级线稿(schematic) |
+| 纯卡库动效 | chip/大字/数字卡/概念卡/进度清单/章节卡 | 两仓卡库直接搭,无需外部素材 |
+> **🟢 Grok 自主生图能力(打包进管线,作者定)**:用户不会每次给全素材。缺"图/像素/3D/场景"类素材时,执行窗**自主调 Grok image_gen 生成补足**(需自装 Grok CLI;没有就跳过,降级线稿或问用户要)。**约束只到技术层:透明底/无残边/抠图干净;不锁颜色和设计**(留创作空间)。生不出满意的再降级线稿(schematic)或问用户要。未来可扩到用Grok/视频模型**生视频片段**。
+> **以参考片为基准的密度底线**(质量地板):每个信息拍≥2分层元素、无大黑边、无空拍、有手作质感——达不到就是round2那种"一个小卡飘空背景"。
+
+## 第3步 · 证据缺口清单(步骤③产物)
+把"有据镜"里拿不到真证据的逐条列出(镜#/口播原话/想要的证据/没拿到的原因)。能问用户就问;用户不在就按 `02` §3 第4条退回无据打法先做,并在交付报告里列出这张清单。
+
+---
+## 对照示例:round2 "引用Reddit神帖"这一镜,错 vs 对
+| | round2(错) | 参考片式(对) |
+|---|---|---|
+| 背景 | Reddit横截图留巨大上下黑边 | 截图**裁满/竖构图重排**,或纸质点阵底上放截图卡 |
+| 人像 | 光秃秃小圆头 | 撕纸毛边/圆角PIP,带白描边+柔和阴影 |
+| 信息层 | 就一张静态截图 | 截图 + **荧光圈注"147"**(Vox section-highlight) + 手绘箭头 + 字幕条(千层饼) |
+| 动效 | 硬切静止 | 截图弹簧入场 + 圈注stagger刷过 + marker音效 |
+| 卡 | 无(裸贴) | Vox `section-highlight`/`stat-magnifier` 蒙参考片token |
+> round2 的病=每列都取了"最省"的默认值;参考片式=每列都达质量地板。**决策表给"放什么",Design Reference给"做成什么样",质量地板兜"不许偷懒到什么程度"。**
+
+## 第4步 · 全片检查(SHOTBOOK填完、动工前过一遍)
+1. 画面是否真正帮助理解文案(不是为丰富而切)。
+2. 有没有连续重复、节奏单一。
+3. 有没有镜头变化太少 或 信息过载。
+4. 有没有用未提供/无法核实的素材(不编造)。
+5. 重要信息是否得到足够视觉强调。
+6. 前后镜是否连贯(Vector Law:出场决定入场)。
+7. 哪些镜头需要补素材 或 需你/用户做选择。
+**最后单独列三张表**:①需补充的素材(未采集清单)②需确认的视觉方向 ③制作难度较高的镜头。
diff --git "a/skill/seecut/references/05-\350\247\206\350\247\211\350\264\250\351\207\217\345\234\260\346\235\277.md" "b/skill/seecut/references/05-\350\247\206\350\247\211\350\264\250\351\207\217\345\234\260\346\235\277.md"
new file mode 100644
index 0000000..ca744b2
--- /dev/null
+++ "b/skill/seecut/references/05-\350\247\206\350\247\211\350\264\250\351\207\217\345\234\260\346\235\277.md"
@@ -0,0 +1,48 @@
+# 参考片 · 视觉质量地板 / 审美对齐清单(Round2执行窗必达)
+
+> 来源:agy 实测对比 A(round2样片) vs B(参考原片13) + 我抽帧核实 + student-kit卡库排查。2026-09-19。
+> 定位:这是**硬地板**——达不到就是"营销号模板拼凑感"(round2 v1 的病)。方法论§3组件层/§4编排层的补充。
+> 一句话病根:**round2 = 剪辑软件默认件拼凑;参考片 = 完整平面设计规范(Design System) + 细腻动态设计(Motion Design)。**
+
+## 🔴 三条最致命(改完立刻质变)
+1. **禁止"人脸高斯模糊循环当背景"**(round2 最掉价的病,14-22s全犯)。
+ - 正确:人隐去时,背景 = **真实截图/录屏** 或 **米白/浅暖灰微噪点纸质 / 点阵网格(Dot Grid)画板**(像Notion/杂志)。**永远不要把主讲人虚化铺底。**
+2. **禁止刺眼纯红大字报**(round2 用 #FF0000 级红底白字,像街头促销)。
+ - 正确配色:**米白/象牙底 + 深炭黑字(不用死黑) + 克制强调色(科技蓝/牛油果绿/复古砖红)**;文字框一律圆角+四周留padding,不撑满边缘。
+3. **禁止硬切/瞬移/默认几何件**。
+ - 正确:所有卡片/箭头**缓入缓出(ease-out)+错落出场(stagger)+缩放遮罩过渡(scale+mask)**,配清脆pop/按键音;装饰用**手绘涂鸦/荧光笔/像素/撕纸/贴纸**,不是直角纯色块+默认红箭头。
+
+## 信息层"千层饼"密度(每个信息拍必达)
+参考片每个信息拍是**分层叠加**,不是"一个小卡飘在空背景上":
+```
+底层:低对比真实文档/录屏 或 纸质/点阵画板
+ 中层:优雅浮现的卡片/chip(跟口播节拍一拍一落、stagger)
+ 下层:圆角柔和阴影的真人小窗(讲解员位)
+ 底部:字音同步字幕条 + 手绘/像素点睛
+```
+- **禁**:空拍(只有大头在说)、裸大头特写顶画面、满屏截图留大黑边、一屏只飘一个小卡。
+- 每个信息拍 ≥ 2 个分层元素;讲重点可整屏换成像素插画让大脑换挡。
+
+## 人像层"卡片化"(不是顶画面的大头)
+- 讲干货概念 → 真人退成**白色圆角边框+柔和阴影的小卡**,置中下方(讲解员位),给信息腾舞台。
+- 讲金句/定调 → 丝滑放大到**中景半身**(带顶空、与前景模型/后景书架融合),不是怼脸大头特写。
+- 引用截图 → 人可缩PIP,但PIP要**有装饰边框**(撕纸/圆角+阴影),不是光秃秃小圆。
+- **禁**:全程大头特写顶中上部、怼镜头太近、发箍小蜜蜂裸出镜。
+
+## 组件来源=两仓混用(★上游修正,别只用talkcraft)
+- **talkcraft(108卡)**:偏 dev-craft/几何。
+- **student-kit(406卡)**:`Vox Explainer`106 + `Kallaway`300,**编辑感/丝滑感更接近参考片**——有 `section.tornstrip`(撕纸)、`cutout`(抠图)、`highlight`(荧光圈注)、`stamp`(邮戳)、`collage`(拼贴)、`stat.giant-left`(大数字)、`stat.odometer`(数字滚)、Kallaway的丝滑motion。**参考片的手作/编辑感这些卡才有。**
+- **引擎可混**:Remotion(.tsx)与HyperFrames(.html)只在单个合成文件内二选一,**最终成片各渲片段→ffmpeg/剪映拼**即可混用(参考片肉眼就是混的)。别再"选A/B"。
+
+## 背景/纸质规范
+- 信息期底:米白/浅暖灰 + 微噪点纸质 或 极客点阵网格;文字深炭黑。
+- 实拍期底:布光的极客书房(整齐书架/暖光台灯/双屏冷蓝光/高达模型作前景锚点),大光圈景深虚化——**冷暖对比、色温统一**。round2 的杂乱客厅+歪挂画+乱电线是反例。
+
+## 自检(渲染前逐条过,任一 FAIL 不算达标)
+- [ ] 没有任何一拍是"模糊人脸当背景"
+- [ ] 没有刺眼纯红大字报;配色=米白+炭黑+克制强调
+- [ ] 没有硬切;卡片/箭头都有缓动+stagger
+- [ ] 每个信息拍≥2分层元素、无大黑边、无空拍
+- [ ] 有手作质感件(涂鸦/荧光笔/像素/撕纸),不是默认几何
+- [ ] 真人是圆角卡片/中景半身,不是怼脸大头
+- [ ] 组件真的用到了 student-kit(不只talkcraft)
diff --git "a/skill/seecut/references/06-\350\264\250\346\243\200\351\227\255\347\216\257spec.md" "b/skill/seecut/references/06-\350\264\250\346\243\200\351\227\255\347\216\257spec.md"
new file mode 100644
index 0000000..fa7330d
--- /dev/null
+++ "b/skill/seecut/references/06-\350\264\250\346\243\200\351\227\255\347\216\257spec.md"
@@ -0,0 +1,71 @@
+# 06 · 质检闭环 spec(v2)
+
+> 上位:`00-总纲` 第 13-15 条。本文件取代 v1 的"agy 自闭环质检组件 spec"(满屏镜像 / 死磕 95 / 像几成百分比 / 维护者熔断,全部作废)。
+> 依据:2026-09-23 评委校准实验(绝对打分 vs 两两对比,正样本=参考原片、负样本=判丑的假满屏版)。结论见本文末"为什么这样设计"。
+
+## 一 · 闭环总流程
+```
+出一版 vN
+ ① 硬门 H1:3A 几何自检(scripts/geom-check.mjs,秒级免费) → 有 FAIL 先改,不进下一步
+ ② 硬门 H2:硬伤清单(agy check 模式) → 有 FAIL 先改
+ ③ 采纳判定:两两对比 vN vs vN-1(agy pair 模式,交换位置跑两次)
+ 对手 = **当前采纳版**(不一定是上一版)。两次都判 vN 胜 → 采纳 vN;两次都输 → 不采纳,看输的理由:
+ 若只是新引入的附带问题、核心改动没被批评,可以在 vN 上修掉附带问题出 vN+1,再和当前采纳版比(Round2-4.2 这样做成功了);否则回到采纳版再改。结论不一致 → 算平手
+ ④ 找方向:两两对比 vN vs 同类参考片参考片(agy pair 模式,跑一次即可)
+ 不看胜负,只读各维度的"差在哪 + 秒数证据" → 作为下一版改动清单
+ ⚠ 若参考片是短片段、功能不同,评委可能判我方全胜、读不出方向(Round2-4.2 实测 6 次全胜)→ 改用
+ `agy_read.sh 参考片 "逐条列出这段用了哪些剪辑手法(入场、证据呈现、人像调度、手作元素、节奏)"`,拿手法清单对照自己的片子找差距
+ ⑤ 停止:硬门全过 且(对比不胜上一版 或 已到 v3 或 只剩小修补)→ 交付(成片 + 剪映草稿)
+```
+- v1 没有上一版:跑 ①②④,按④的差距清单出 v2,再从 v2 起走完整闭环。
+- **每版改动要肉眼可见**(首测教训:v3-v5 只修 agy 挑的小毛病——印章早退 1s、标签挪几十 px——作者看不出区别,却各占一整轮评审):每一版必须包含至少一项④找出的大差距;①②的硬伤小修补合并进同一版。
+- **长素材**:评审用的视频本来就会降到 540p;渲染迭代版用 `RENDER_SCALE=0.5`。素材超过 1 分钟时,两两对比可以挑改动最大的 30-60 秒片段来比,不必每次整片。
+- **时间预算**(首测 2.5h 太慢):v1 约 30 分钟;之后每版"构建渲染 3-7 分钟 + 评审约 2-4 分钟"。check 和 pair 可以同时跑;等评审时去准备下一版的改动清单,别干等。
+- 每一步的原始输出存 `<工程>/qc/vN-*.json`,交付报告引用。
+
+## 二 · 硬门 H1:3A 几何自检
+见 `07-几何规则自检spec`:撞位 / 压人像 / 圈锚偏移 / 无脸 ≤5s / 逐词 timing 不抢拍 / 弹簧 overshoot / 空拍。能用数据算的一律数据说话;agy 说"没弹簧""压脸"等,以几何数据为准。
+
+## 三 · 硬门 H2:硬伤清单(agy check 模式)
+`python3 scripts/agy_judge.py check --video vN.mp4 --html <master.html>`,逐条过/不过 + 秒数证据:
+| 条 | 内容 | 不过的样子 |
+|---|---|---|
+| C1 假证据 | 有没有用抽象占位窗口、伪代码网格、假 Mac/假 App 界面、无关装饰窗口冒充证据或填满画面 | 总纲第 5 条 |
+| C2 证据缺口 | 口播提到真实产品/网页/数据时,画面是否给了真证据(没有=列出是哪句) | 不是 FAIL,是待补清单,交给"找证据"环节 |
+| C3 版面 | 元素撞位、遮挡关键信息、上一拍残留、无意义漂浮元素、穿帮 | — |
+| C4 人像连贯 | 人像形态无故切换(方↔圆)、位置无故乱跳 | 总纲第 10 条 |
+| C5 看不懂/读不完 | 文字闪现读不完、信息看不懂 | — |
+| C6 敏感字 | 画面出现可读敏感字 | 总纲第 7 条 |
+| C7 空拍 | 连续 ≥2 秒画面几乎无信息、只有一行字 | 总纲第 6 条 |
+- C2 只产出清单不判 FAIL;其余任一 FAIL 即不过门。
+- **agy 报的 FAIL 必须核实**:脚本会把 FAIL 证据里的时间点自动抽帧到 `<out>_failframes/`,执行窗读这些帧 + 对照 H1 几何数据判真假。agy 有稳定的"串场"毛病(把相邻两拍当成同屏,2-4 v2 上两次误报 14-15s"残留撞位",抽帧核实两拍是整屏切换、从未同屏)。核实为假的写进报告"agy 误报",不改片。
+
+## 四 · 两两对比(agy pair 模式)
+`python3 scripts/agy_judge.py pair --a vN.mp4 --b vN-1.mp4 [--html-a ... --html-b ...]`
+- 脚本自动交换位置跑两次,输出 `consensus`:`A` / `B` / `tie`。
+- 维度:证据真实性、名词响应、人像露藏与卡化、动效物理、手作质感、视觉系统一致、版面干净、节奏与画面变化、整体观感。
+- 找方向时 `--b` 换成 `金锚集/` 里同功能、同"有据/无据"的参考片(选法见 `金锚集/README.md`);此时只读 dimensions 的证据,不看 winner。
+
+## 五 · agy 调用纪律(脚本已内置,手动调用也必须守)
+1. 每次 `--new-project`(agy 有按项目的持久记忆,旧项目会被别的片子污染,喂啥都串成那条片)。
+2. `--output-format json --json-schema <schema>`;解析取最后一个含目标字段的 JSON 对象(agy 回复里会夹思考文本/噪声)。
+3. **指纹核**:prompt 要求照抄画面文字;脚本检查这些文字是否出现在本片 `master.html` 源码文字 **或 同目录 `fp-manifest.txt`**(≥2 条命中才有效)。`fp-manifest.txt` = 执行窗读证据图核敏感字时,顺手把图里看得清的字逐行记下(agy 常照抄截图里的字,源码里没有);也可 `--fp-extra` 另给清单。时长核:agy 报的时长与 ffprobe 实测差 ≤3 秒。不过=判 confab,重跑 1 次,再不过=标"agy 无效",不当有结果继续。
+4. 视频压到短边 540p 再喂;prompt 里写"禁止启动后台 OCR/转录/采样子任务"。
+5. **评委隔离**:脚本把视频复制到系统 tmp 的独立目录再调 agy,并声明"不要读取其它文件"——2-4.1 实证:临时目录建在工程里时,agy 读到了 master.html 和 runlog,评判被源码污染。手动调用 agy 也必须这样隔离(素材理解用 `scripts/agy_read.sh`)。
+6. **退出码**:0=通过/有共识;1=check 有 FAIL;2=无效(agy 两次都没给出可信结果——**不是通过也不是不通过**,报告里写"无结果");3=agy 授权过期,停下请用户重新登录。
+7. **快速失败**:单次调用超时 240s;接口断连/超时立即重试(不算内容无效),指纹/时长不过才算内容无效、最多重跑 1 次。pair 两序并行。
+8. agy 判定有波动:同一版两次 check 的 FAIL 集合可能不同。单次 FAIL 先抽帧核;核实为真的才改。
+9. 代理与账号地区见 README 依赖段。
+
+## 六 · 交付报告(给用户)
+- 成片路径 + 每版一行:硬门结果、对比结论(vs 上一版)、这一版改了什么。
+- 找证据环节:拿到了哪些真证据、哪些没拿到(原因)、敏感字核查结果。
+- agy 误报清单(抽帧核实为假的)。
+- 已知未解决项 + 需要用户决定的主观项。
+
+## 七 · 为什么这样设计(校准实证,2026-09-23)
+- **绝对打分不可用**:11 条款各 0-2 分求和,判丑的假满屏版 v6 = 18 分,与参考原片最高分同分;干净版 v3 与 v6 同分。只有"证据真实性"一条能把原片和我们的片分开。→ 绝对分只保留成硬伤清单,不求和、不当迭代信号。
+- **两两对比可用**:原片 vs 我们的片,交换位置两次都判原片胜;同一工程 v1 vs v2,两次都判 v2 胜(与人工复核一致)。
+- **两两对比的盲区**:干净 v3 vs 假满屏 v6,两次都判 v6 胜——抽帧核实 v6 前景确实更好(名词接得住、人像撕纸框),但背景是假占位网格,用户肉眼判它更差。→ 假证据必须由硬门 C1 + 生产端总纲第 5 条直接禁掉,不能指望对比评委扣分。
+- **"像参考片几成"百分比作废**:同片同 prompt 两次 88-90% vs 68-70%;修真 bug 分数不动;把分数往上推的唯一路径曾是"铺假满屏",与用户肉眼方向相反。
+- **素人视角 prompt 作废为评委**:它给参考原片 62 / 45 分、给我们的干净版 90 分,衡量的是"清爽克制"而非网感口播精剪风格;其有用的部分(看不懂/读不完/空拍)已并入硬伤清单 C5/C7。
diff --git "a/skill/seecut/references/07-\345\207\240\344\275\225\350\247\204\345\210\231\350\207\252\346\243\200spec.md" "b/skill/seecut/references/07-\345\207\240\344\275\225\350\247\204\345\210\231\350\207\252\346\243\200spec.md"
new file mode 100644
index 0000000..e948e96
--- /dev/null
+++ "b/skill/seecut/references/07-\345\207\240\344\275\225\350\247\204\345\210\231\350\207\252\346\243\200spec.md"
@@ -0,0 +1,35 @@
+# 几何规则自检 · spec(管线新增护栏,2026-09-20 作者拍板)
+
+> 定位:位置歪/圈错位/撞位/露脸空档/同词重复这类 = **几何问题**,agy 单帧/540p 看不出、我抽帧也易漏(2-3 v3.1 栽此)。用**确定性几何检查**兜住,别老靠 作者肉眼。是质检闭环硬门 H1 的实现(`06-质检闭环spec` §二)。
+> 怎么跑:由 `scripts/geom-check.mjs` 用 playwright `page.evaluate(()=>el.getBoundingClientRect())` 在**每个信息拍的稳态帧**读元素 bbox,跑下面规则,FAIL 当场报警+定位到秒/元素。渲染前几秒级、免费。
+> 🔴 **实现铁律(2-3.1 静默卡死 25min 的教训)**:**整套 scrub+读 bbox 塞进浏览器内一次 `page.evaluate` 跑完**(2.7s),**绝不每帧一次 Node↔浏览器往返**(942 次往返延迟堆叠≈挂死)。且必须套超时看门狗+进度打印(见避坑SOP §三.5),别让自检本身静默空转。
+
+## 检查项(逐条,输出 过/FAIL + 秒 + 元素)
+1. **元素不重叠/不撞位**:给需要判定的元素打 `data-check="box"`(标签/卡片/chip/胶带/窗口/大字)。两两 bbox 重叠面积 > 各自 15% → FAIL(标签压卡、胶带盖角标、卡叠卡)。允许"背景托板"用 `data-check="bg"` 豁免(它本就该被叠在上层)。
+ - **★框-人像重叠检测(2026-09-21,2-3.1 回灌)**:把 `#person` PIP 也纳入重叠检测——任何 `data-check="box"` 与人像 PIP 的 bbox 重叠 > 0(或留 <5% 安全边) → FAIL("清单/卡骑脸")。**agy 跨 v5/v6 持续幻觉"清单骑脸人像",此几何数据(实测 0 重叠)可凭数据 dismiss**——是"用几何驳 agy 假警报"的又一实例。
+2. **圈/下划线/箭头锚准关键词**:给手绘标记打 `data-anchor="<目标元素id>"`。标记中心与目标元素 bbox 中心距离 > 目标高度的 40%,或标记未覆盖目标 60% 宽度 → FAIL(圈歪/圈偏/圈到空白/圈错行)。2-3 末尾红圈圈到空白 = 这条能抓。
+3. **同词重复上限**:扫可见文本节点,同一关键词(如"豆包")在同一拍/相邻拍出现 > N 次(默认 2) → 警告(同质轰炸)。
+4. **无脸空档**:按人像层 `#person` 的显隐时间轴,统计最长连续无脸时长 > 5s → FAIL;并交叉口播功能(自述/感叹/总结句必须有脸) → 这些句子所在帧无脸 → FAIL。
+5. **信息密度**:每个信息拍稳态帧,`data-check="box"` 元素数 < 2 或最大空白连通区 > 画面 45% → 警告(空拍/飘空卡)。
+6. **timing 词级**:每个 payoff 元素 `data-word="<关键词>"`,其揭示帧的时间 < seg_words.json 里该词起始时间 → FAIL(抢拍)。
+
+7. **信息拍不空拍(2026-09-21 修订,撤回"背景须满屏")**:⚠️ 原"背景空白<35%=FAIL"**已废**——它逼出了 v6/v73 满屏 busy 底(素人最丑),方向错了(干净底 v3 反而素人 90)。**改为只抓真空拍**:某信息拍稳态帧**前景有效元素(卡/chip/大字/PIP/手作) < 2 个 且 大片空白 > 画面 55%** → 才 FAIL(v3 早期"空纸飘一张小卡"的病)。**干净透气的底不算问题、别再逼满屏内容**。背景清爽度归 作者肉眼+素人,几何只兜"前景太空"。
+8. **★弹簧 overshoot 检测(驳 agy"无弹簧"假警报,2026-09-21 新增)**:给带弹簧入场的元素在其入场窗口内**采几帧量 scale 曲线**,确认存在"冲过 100%(如 106%)再回落"的 overshoot(back.out)。**有 overshoot=达标、直接驳回 agy"无弹簧/匀速"的误报**(agy 540p 单遍看不出);无 overshoot=真软塌、改。→ 客观数据说话,不跟 agy 辩。
+
+## 用法与边界
+- **打标成本**:要执行窗在 composition 里给元素加 `data-check/data-anchor/data-word` 属性。一次加、复用。
+- **与 agy 分工**:几何自检抓"能算的"(位置/距离/时长/时间/弹簧);agy 硬伤清单(H2)与两两对比抓"要看的"。agy 说法与几何数据冲突时以数据为准。
+- **回灌**:用户肉眼发现的新几何类问题 → 加成新规则并记 CHANGELOG(如"箭头方向错"→加方向检查)。
+- 现状(v3.1):`scripts/geom-check.mjs` 已实现第 1/2/4/6/8 条为 FAIL、第 5 条为 WARN(第 3 条同词计数未实现,靠 H2 兜);**新增"被人像盖住"**:每个 box 取 5 个采样点,≥3 个点最上层是人像 → FAIL(不管人像多大;Round2-4.2 v2 的字卡被盖 1.5s,旧检查和 agy 都漏了,新检查抓到)。
+
+## 配置契约(v2,脚本不再写死路径)
+工程目录(build)里放 `project.json`,渲染与几何自检都读它:
+```json
+{"html":"master.html","fps":25,"width":720,"height":1280,"duration":17.88,
+ "timeline":"master","person_dir":"person","person_img_id":"person","person_wrap_id":"personWrap",
+ "steady":[4.65,6.7,9.0],
+ "spring":[["#s1_cut",4.28],["#s3_vs",8.5]]}
+```
+- `steady`:每个信息拍的稳态秒(撞位/圈锚/空拍在这些时刻检);`spring`:[选择器, 入场秒],检入场 0.6s 内 scale 峰值 >1.02。
+- composition 必须暴露 `window.__timelines[timeline]`(GSAP 主时间轴);人像 `<img id=person_img_id>` 放在 `#person_wrap_id` 外框里。
+- 跑法:`node scripts/geom-check.mjs <build>`(退出码 0=全绿);`node scripts/render.mjs <build> probe|full`。工程目录先 `npm i playwright-core`(别 sudo)。
diff --git "a/skill/seecut/references/08-\351\201\277\345\235\221SOP.md" "b/skill/seecut/references/08-\351\201\277\345\235\221SOP.md"
new file mode 100644
index 0000000..51c3961
--- /dev/null
+++ "b/skill/seecut/references/08-\351\201\277\345\235\221SOP.md"
@@ -0,0 +1,71 @@
+# ★ 口播动效渲染 · 避坑 SOP(一步到位版)
+
+> 定位:**下一个做"口播 + HTML/GSAP 动效 + 逐帧渲染"的窗口/agent,动手前先读这份。** 把 Round2-2 踩过的坑全部前置,照做即可一次到位,别重新踩。
+> 适用管线:Vox 卡蒙参考片令牌 → 竖版 HTML/GSAP composition → **无头 Chrome 逐帧捕获** → ffmpeg 合成 + 口播音轨。
+> 完整原理见 作者本地过程记录(未收录)(§1-10);可复现脚本见 作者本地过程记录(未收录)。
+
+---
+
+## 一、端到端正确管线(每步带⚠️坑)
+
+### 0. 素材与转写
+- 口播源转写**一次就沉淀**(SRT+逐词JSON),别每版重转。
+- ⚠️ 粗剪时间轴 ≠ 全片 main.MOV 时间轴,别套错 SRT。用 ChatCut `preview_timeline` transcript / `find_transcript` 现扒粗剪的精确帧。
+
+### 1. 人像层(A-roll)——★判过一次"卡顿"的坑
+- **不要**在 HTML 里用 `<video>` + 每帧 `currentTime` scrub(无头 Chrome 密集 seek 解码器跟不上 → 人像半数帧冻结 = judder)。
+- ✅ 正确:`ffmpeg -vf fps=30` 把人像**预抽成逐帧 JPG 序列**,HTML 里用 `<img>`,捕获脚本**每帧换 img.src**。0 冻结、还更快。
+- 人像源先规范到 CFR 30fps(`-vf fps=30 -vsync cfr`)。
+
+### 2. 设计层蒙皮(参考片质感)
+- 真复制 Vox 卡(student-kit `01-vox-explainer/cards`)+ 覆盖 tokens:**思源黑体 Heavy**(替 Vox 衬线 Fraunces)、砖红/琥珀/青柠色族、点阵纸底。clip-path撕纸/报纸纹/GSAP弹入**原样复用**(守铁律①禁手写神似)。
+- ⚠️ Vox 卡是横版 1920×1080,reel 竖版 2160×3840:**复用卡的 CSS/tokens/GSAP 按竖版重排布局**(owner 已判在铁律①内),别硬塞横卡当带(会犯"卡飘空背景")。
+- ⚠️ 荧光笔 wipe:父元素若是 inline,`transform:scaleX` **不生效** → 父元素设 `display:inline-block`;GSAP **不插值 clip-path 的%**,用 scaleX+fromTo。
+
+### 3. 动效对齐(★作者发现的系统性坑,最容易翻车)
+- ⚠️**别照句子级时间段的"句首"敲动效时间**。关键词常在句中后段才说出口(整句"海外AI大神从**147**次失败中",147 在句中),句首锚点=系统性早 1~2 秒。
+- ✅ 用 `find_transcript includeWordTimestamps` 拿**逐词精确帧**。把 payoff 元素(数字/高亮/名字/徽章)锚到**词被说出的那一帧**落下(词上或词后 0.1~0.2s,**绝不抢词前**=没揭示感)。背景/铺垫可略早,**句首→关键词的空档 = 揭示前悬念**(先"它有个名字,叫…"吊着,说到"Layer"才砸)。
+
+### 4. 逐帧捕获(★"时间轴漂移"的隐蔽坑)
+- ⚠️ 捕获脚本**必须按绝对时间 seek**:`timeline.time(i/fps)`,**不要**用 `progress(i/(N-1))`。
+- 原因:GSAP 里任何循环动画(如 grain 噪点 repeat:60)会把时间轴总时长撑长(实测 30.5s ≠ 预期 29.7s);progress×总时长 ≠ 音频时钟 → 动画比音频快、越后越偏(结尾差 0.8s)。`.time()` 与总时长无关,恒等音频。
+- ⚠️ **GSAP `.from`/`.fromTo` 在 seek(非播放)渲染下 immediateRender 会提前揭示元素**(尤其父层做了 autoAlpha 动画时)。要"某时刻才出现"的元素:CSS 默认 `opacity:0`(回落态=隐藏) + `.set` 初始态 + `.to` 揭示(`.to` 无 immediateRender)。
+- ✅ **护栏(早发现)**:渲染前自动比对"GSAP 动画钟总长 vs 视频时长",差 >0.15s 报警(提示循环动效 repeat 设太长/内容超时)。capv3.mjs 已内置。根治靠 `.time()` 绝对 seek,护栏是双保险。
+
+### 5. 合成 + 音轨
+- `ffmpeg -framerate 30 -i frames/f%04d.png -i person_cfr.mp4 -map 0:v -map 1:a -shortest out.mp4`。
+- 试拼走 1080p 快迭代;字幕/BGM/音效**留 作者剪映**(音效我方无法试听音色、剪映有库可听可换)。
+
+---
+
+## 二、避坑速查表(贴墙版)
+| 坑 | 症状 | 正解 |
+|---|---|---|
+| video 逐帧 scrub | 人像卡顿/冻结 | 预抽 JPG 序列 + img 换 src |
+| progress 取帧 | 动效整体偏早、越后越偏 | `.time(i/fps)` 绝对时间 seek |
+| 句首锚点 | 动效抢在文案前 | 逐词时间戳锚关键词那帧 |
+| `.from` seek 提前显 | 元素早于该出现的时刻 | CSS opacity:0 + `.set` + `.to` |
+| inline 父元素 | scaleX/wipe 不动 | 父 `display:inline-block` |
+| clip-path % | GSAP 不插值、瞬现 | 用 scaleX + fromTo |
+| 横卡塞竖屏 | 卡飘空背景 | 复用零件按竖版重排 |
+
+## 三、验收方法(★别被骗)
+- 🔴 **时间维度问题(卡顿/对齐)别信 md5/freezedetect/agy/整帧比对**——画面有逐帧抖动的 grain 噪点会让整帧永远"不同",骗过所有整帧检测(我早前就被骗、误判修好)。
+- ✅ **卡顿**:裁人像区、量连续帧"近冻结帧数"(应=0)。
+- ✅ **对齐**:抽"关键词前 0.2s / 词后 0.3s"两帧,确认元素**词前无、词到落**。
+- ✅ 终判交**肉眼看播放**(作者)。
+
+## 三.5、★长任务兜底(管线级硬约束,2026-09-20 institutionalize;作者睡觉时被静默空转烧过时间)
+> 血泪:geom-check 首版**静默卡死 25 分钟**(每帧 Node↔浏览器往返延迟堆叠);此前还有渲染僵尸进程、agy 后台子任务卡死。**静默空转在无人值守时(作者睡觉)浪费极大**。凡 playwright/agy/ffmpeg/渲染类长任务,一律套下面三条硬约束:
+1. **超时看门狗**:每个长任务带超时 + "N 秒无进展即强制退出并触发失败通知"(自杀式看门狗)。别让任何步骤能无限挂着。
+2. **进度可见**:长任务定期打印进度(如全渲每 150 帧打一行;agy 起止打时间戳),能一眼看出"在动还是挂了"。
+3. **失败/超时主动冒泡到人**:任务失败或超时要显式报错/发通知,禁"发起后不管"的静默后台;后台任务必须有完成/失败回执。
+- **几何自检实现铁律**(这次的具体坑):**整个逐帧 scrub 塞进浏览器内一次 `page.evaluate` 跑完**(2.7s),**别每帧一次 Node↔浏览器往返**(942 次往返≈挂死)。呼应 spec"渲染前秒级"。
+- 关联记忆 `feedback_long_task_watchdog`。
+
+## 四、关联文件
+- 人话版原理复盘:作者本地过程记录(未收录)
+- 过程轨(每版迭代):作者本地过程记录(未收录)
+- 可复现脚本:skill 内 `scripts/render.mjs`(逐帧渲染)+ `scripts/geom-check.mjs`(几何自检),配置契约见 `07` §配置契约。
+- 决策表/设计令牌/质量地板:本目录 `references/01`-`05`
+- 记忆:`reference_headless_video_scrub_judder`、`reference_motion_word_alignment`
diff --git "a/skill/seecut/references/09-\351\237\263\346\225\210\350\247\204\350\214\203.md" "b/skill/seecut/references/09-\351\237\263\346\225\210\350\247\204\350\214\203.md"
new file mode 100644
index 0000000..bb5f14a
--- /dev/null
+++ "b/skill/seecut/references/09-\351\237\263\346\225\210\350\247\204\350\214\203.md"
@@ -0,0 +1,45 @@
+# 09 · 音效规范(v1,skill v3)
+
+> 来源:2-4.1 执行窗《音效规范 v0》一线实配(AV5 数字人,12 个落点,作者试听认可"整体还好、总比没有强")+ 维护者《音效库台账》+ 作者要求"开头 0.5 秒给一个醒目音效"。
+> 音效库:`$JIANJI_SFX_DIR`(默认 `~/Downloads/音效`,39 个)。台账:`references/sfx/音效库台账.md`(人读,含★首选清单)/ `.json`(脚本读)。
+
+## 一 · 流程(4 步,工具全自动算,执行窗只负责"挑点 + 挑声音")
+1. **列候选事件**:`jianying_layers.mjs` 输出的 `layers/manifest.json` 里有 `events`(每个信息层元素出现/换状态、人像过渡的时刻)。
+2. **挑落点**(执行窗判断,写 `sfx_choices.json`):对照 SHOTBOOK 每镜的功能和文案语义,只挑"有意义的拍点":换幕、证据落地、结论/盖章、翻车、设问、列举编号。**不逢动必响**。每个落点写 `t`(画面事件时刻)、`kind`、`sfx`(台账文件名)、`why`。
+3. **算与查**:`python3 scripts/sfx.py plan --choices sfx_choices.json --voice <原声> --words seg_words.json --duration <秒> --out sfx_plan.json`
+ - 自动算:起点偏移 + 取整到帧、跳过开头空白、只取第一下、按人声峰值定音量。
+ - 自动查:开头抓耳、密度、低频重击压字、慎用音效、同一音效用太多次。**有 ⚠ 就改 choices 重跑,直到没有 ⚠,或者在报告里写清为什么保留。**
+4. **落地**:有剪映引擎 → `jianying_plan.py --sfx` 进剪映草稿的音效轨,成片只带原声;**没有剪映引擎 → `sfx.py mix` 混进渲染成片**。音效是在推剪映之前就算好的,不依赖剪映。
+5. **用户自己的音效库**:`sfx_ledger.py <文件夹> --out 台账.json [--listen]` → 自动实测起音点/第一下长度/共几下,按文件名猜类别,`--listen` 让 Gemini 补听感;`sfx.py plan --ledger 台账.json --sfx-dir <文件夹>`。skill 自带的台账只描述作者本机音效库(版权原因不随仓分发音效文件)。
+
+## 二 · 映射(按类别挑;下表文件名是作者本机音效库里的例子,换成你库里同类的声音即可)
+| kind | 画面事件 | 首选 | 备选 |
+|---|---|---|---|
+| hook | **开头 0-0.5s 抓耳(必须有)** | 叮当声(dingdongSound) | 叮叮_ / 重磅出场 |
+| whoosh | 滑入 / 换幕 / 人像缩窗 | 转场-唰 | another转场(同一片里 2 次以上就换着用) |
+| pop | 卡片 / chip / 像素弹出 | 字幕出现 | 叮叮_ |
+| impact | 印章砸下 / 大字砸入 / 结论落定 | 咚-重击 | 咚一声another |
+| ding | 要点出现 / 编号 / 步骤完成 | 叮一声 | 叮叮_ / 叮当声 |
+| page | 翻页 / 换图 / 清单轮播 | 翻页( | 快速翻页声(连续翻多张) |
+| click | 按键 / 点选 / 光标 | 金属咔嚓 切换页面 | 鼠标点击 |
+| error | 红叉 / 翻车 / 错误示范 | 错误提示 | 玻璃碎(很严重的翻车) |
+| correct | 对勾 / 达成 | 答题正确 | — |
+| money | 价格 / 到账(语义真是钱) | 支付宝到账金币掉落 | 收银机 |
+- 手绘圈 / 下划线 / 荧光笔:**不配**(库里没有笔刷声,已记缺口)。
+- 设问卡:用 ding,不用"疑问"(卡通滑笛,agy 评出戏)。
+- 梗音效(圣光/咩咩咩/火车/着火/彩票/妈妈牛来):一条片最多 1 次,语义必须特别贴。
+
+## 三 · 对齐(sfx.py 已内置)
+- **起音点**:台账 `trim_start` = 能量包络首次到峰值 10% 的时刻(不是 -45dB 静音检测,那样弱起音会偏小 100-180ms)。剪映里 `source_start_us = trim_start`。
+- **一个文件里有几下的**(咚一声 3 下、鼠标点击 6 下、疑问 5 下…):只取第一下(`first_hit_len`)。
+- **偏移**:pop/ding/page 等 = 元素出现帧;impact = 出现帧 **+0.12s**(弹簧落地那帧);whoosh = 切换帧 **−0.08s**(让"唰"跨过切点)。**向上取整到帧**(声音不能早于画面)。
+- **画面配合**:剪映草稿里信息层淡入提前 1 帧起、2 帧淡满(`jianying_plan.py` 已内置),否则音效响时元素还是透明的。
+- **质检**:带音效版音轨减无音效版 = 纯音效轨,测起点,偏差 ≤50ms(约 1 帧)算过;落点前后各抽一帧,确认画面事件已可见。
+
+## 四 · 密度与音量(sfx.py 自动查)
+- **任意 3 秒最多 2 个;全片平均 ≤0.7 个/秒**(开头 hook 不计)。同类连续元素(两枚 ✓chip)只配第一个。
+- **音量**:按人声峰值算,音效峰值落在人声峰值下方 −16 ~ −11 dB(pop/ding −16、whoosh −15、error/page −14、impact/hook −12)。剪映 volume 一般 0.05-0.25。
+- **关键词避让**:低频重击(impact)不要压在口播关键词中间,会吃字 → 挪到词说完那一帧(sfx.py 会给出建议时刻),或降 3dB。
+
+## 五 · agy 听评怎么用
+- `agy_read.sh 带音效成片.mp4 "音效是否贴合画面和语义?有没有太密、太吵、抢人声?"`:**只信整体判断**(密度、风格割裂、刺耳、抢人声)。它说"第几秒是哪个声音"常常说错(2-4.1:报 13 个实为 12 个,把"咚"说成蜂鸣)。最终以用户人耳为准。
diff --git "a/skill/seecut/references/10-\345\211\252\346\230\240\345\210\206\345\261\202\345\267\245\347\250\213.md" "b/skill/seecut/references/10-\345\211\252\346\230\240\345\210\206\345\261\202\345\267\245\347\250\213.md"
new file mode 100644
index 0000000..efde943
--- /dev/null
+++ "b/skill/seecut/references/10-\345\211\252\346\230\240\345\210\206\345\261\202\345\267\245\347\250\213.md"
@@ -0,0 +1,38 @@
+# 10 · 剪映分层工程(skill v3 交付物之一)
+
+> 目标(作者定):把成片**分图层**推进剪映草稿,用户能在剪映 UI 里微调。**不许把合成好的整片放主轨。** 2-4.1 实测作者验收:"能推到剪映里还能微调,到这一步已经不错"。
+> 依赖(**可选**):剪映草稿引擎 jianying-headless(上游 github.com/mcncarl/jianying-headless,个人学习非商业协议,**不随本 skill 分发**,用户按其协议自行安装;作者本机是 Intel 适配版 + 剪映 11.5.0)。没装也能跑:本管线始终产出**编辑器无关的分层工程包**(`jianying/layers/` + `plan.json`),装了引擎就能一步导入剪映。
+
+## 一 · 打标契约(写 master.html 时就打好)
+- **信息层每个元素**加 `data-layer="显示名"`,可选 `data-layer-cat`:
+ `evbg`(满屏证据底,在人像下面)/ `card`(证据卡、章节卡)/ `cardimg`(卡里的图、标签)/ `hl`(荧光)/ `title`(标题、chip、印章、手写字)/ `hand`(手绘圈/线)。默认 `card`。轨道从下到上:evbg → 人像 → card → cardimg → hl → title → hand。
+- **嵌套**:父元素里的 `data-layer` 子元素会单独成段,截父元素时自动隐藏。粒度按"用户可能想单独挪/删的东西"来定。
+- **人像**:`#personWrap`(外框,带卡化白边/圆角)里放 `<img id="person">`;外框的位置/大小变化就是人像状态(全屏/分屏/小窗…)。
+- 纸底、噪点这类背景不打标。
+
+## 二 · 流程
+```bash
+node scripts/jianying_layers.mjs build # → jianying/layers/:纸底.png、png/*.png(信息层)、人像_状态N.mp4、原声.m4a、manifest.json(含音效候选 events)
+python3 scripts/jianying_plan.py jianying/layers/manifest.json --name "<片名>_分层工程" --out jianying/plan.json \
+ [--sfx sfx_plan.json] --preview jianying/preview.mp4
+cd "$JIANYING_HEADLESS_ROOT" # 你自己装好的 jianying-headless 目录
+python3 engine/jy14_headless.py build --plan <abs>/jianying/plan.json --out <abs>/jianying/work/build
+python3 engine/jy14_headless.py verify-build --build <abs>/jianying/work/build
+# publish 前:剪映主程序必须退出(托盘助手 TrayHelper 在跑不影响,已实证);先备份 root_meta_info.json
+python3 engine/jy14_headless.py publish --build <abs>/jianying/work/build --audit <abs>/jianying/work/publish
+```
+- `project.json` 要写 `source`(口播源片路径),用于抽原声。
+- **核对**:publish 后首页索引条数 +1、原有条目逐条未变;把预览和成片同时间点抽帧对比(稳态画面应一致)。
+
+## 三 · 能力边界(2-4.1 实证)
+- ✅ 多轨分层、线性关键帧(位置/缩放/不透明度)、透明 PNG、音效轨。
+- ❌ **剪映引擎不收带 alpha 的视频** → 信息层只能是透明 PNG(入场动画变成淡入;手绘"画出来"、弹簧回弹在草稿里是静态图 + 淡入)。
+- ❌ **关键帧要求素材从头开始(source_start=0)** → 人像按状态切成独立视频。
+- ❌ **Intel 上代码原生导出跑不通**(引擎写死 arm64 + 中文路径 + 上游 writer 问题)→ 用户在剪映 UI 里手动导出;`--preview` 出的是 ffmpeg 合成预览,文件名必须注明"非剪映原生导出"。
+- ⚠️ 坐标约定:scale=1 = 适应画布,x/y 以半画布为 1、y 向上为正(2-4.1 推算,作者 UI 验收未报偏差)。
+- ⚠️ 蒙版单位文档没写 → 人像卡的白边/圆角直接烤进人像视频,不用蒙版。
+- ✅ 人像中途隐藏再出现:脚本自动识别,隐藏段不出人像,前后加 3 帧不透明度淡出/淡入(v3.1 修,Round2-4.2 回归通过)。
+- ✅ 30fps 等不能整除的帧率:时长按帧时刻换算并不超过媒体实测时长(v3.1 修,避免 build 报 Source trim exceeds)。
+
+## 四 · 所以要两份交付
+剪映草稿里动画会"素"一些,所以同时交**渲染成片**(HyperFrames 全效果、原声)给用户直接用;草稿(带音效轨)给用户微调。
diff --git "a/skill/seecut/references/prompt/\345\257\271\346\257\224\350\257\204\345\247\224.txt" "b/skill/seecut/references/prompt/\345\257\271\346\257\224\350\257\204\345\247\224.txt"
new file mode 100644
index 0000000..a011b69
--- /dev/null
+++ "b/skill/seecut/references/prompt/\345\257\271\346\257\224\350\257\204\345\247\224.txt"
@@ -0,0 +1,6 @@
+你是资深短视频剪辑审片师,专门评"网感口播精剪风格"口播动效视频。网感口播精剪风格的定义:数字人口播打底,把画面让给高密度信息层;口播提到的每个名词都有画面接住;优先铺与内容相关的真实截图/录屏当证据;人像按"对你说就露、给你看就藏"调度;元素弹簧回弹、错峰弹出;手绘涂鸦/荧光笔/撕纸/像素等手作质感。这种风格本来就信息密度高,密度高本身不扣分。
+
+这里有两条视频 @X.mp4 和 @Y.mp4(可能题材不同、时长不同;结尾突然截断是截取造成,不扣分)。完整看完两条,判断:哪一条是"做得更好的网感口播精剪风格成片"——既更像这种风格,又做得更成熟、更让人愿意看完。
+逐维度比较(每维给出 X / Y / 平手,并写具体秒数证据):证据真实性、名词响应、人像露藏与卡化、动效物理、手作质感、视觉系统一致、版面干净、节奏与画面变化、整体观感。
+最后给 winner(X 或 Y)和 confidence(1-5)。fingerprint 里分别照抄 X 和 Y 画面中各 3 处具体文字,并写出两条各自的时长(秒)。
+直接凭观看作答,禁止启动任何后台 OCR/转录/采样子任务。只输出符合 schema 的 JSON。
diff --git "a/skill/seecut/references/prompt/\347\241\254\344\274\244\346\270\205\345\215\225.txt" "b/skill/seecut/references/prompt/\347\241\254\344\274\244\346\270\205\345\215\225.txt"
new file mode 100644
index 0000000..48f1e2f
--- /dev/null
+++ "b/skill/seecut/references/prompt/\347\241\254\344\274\244\346\270\205\345\215\225.txt"
@@ -0,0 +1,11 @@
+你是极挑剔的短视频审片师,负责给一条"网感口播精剪风格"口播动效视频做硬伤检查(只查硬伤,不评风格好坏;这种风格信息密度本来就高,密度高不算问题)。
+完整看完 @A.mp4(结尾突然截断是截取造成,不算问题),逐条判断 pass(true/false),每条写具体秒数和元素作为证据:
+C1 假证据:有没有用抽象占位窗口、伪代码横线网格、假 Mac 三色点窗口/假 App 界面、与话题无关的装饰窗口,去冒充真实截图或填满画面。有=false。
+C3 版面:有没有元素撞位、遮挡关键信息、上一拍元素没退场残留、无意义漂浮元素、穿帮。有=false。
+C4 人像连贯:说话人人像是否无故在方形/圆形等不同形态间切换,或位置无故乱跳(跟内容功能无关的换位)。有=false。
+C5 看不懂/读不完:有没有文字闪现快到读不完,或画面信息让人看不懂在表达什么。有=false。
+C6 敏感字:画面里有没有可读的"下载/反爬/扫码/搬运/联系方式/加微信/站外引流/违规承诺"等敏感字。有=false。
+C7 空拍:有没有连续 2 秒以上画面几乎没有信息(比如只有一行字或大片空白)。有=false。
+另外 evidence_gaps:列出口播里提到真实产品/网页/文档/数据/操作、但画面没有给出真实截图或录屏证据的地方(秒数 + 口播原话 + 建议用什么真证据)。
+fingerprint:照抄画面中 3 处具体文字,并写出视频时长(秒)。
+直接凭观看作答,禁止启动任何后台 OCR/转录/采样子任务。只输出符合 schema 的 JSON。
diff --git "a/skill/seecut/references/\351\207\221\351\224\232\351\233\206/README.md" "b/skill/seecut/references/\351\207\221\351\224\232\351\233\206/README.md"
new file mode 100644
index 0000000..bf07194
--- /dev/null
+++ "b/skill/seecut/references/\351\207\221\351\224\232\351\233\206/README.md"
@@ -0,0 +1,5 @@
+# 金锚集 · 参考片(可选,用户自备)
+
+本仓**不附带任何参考原片**(版权)。风格规范已经写在 `references/01-03`,没有参考片也能跑:质检闭环找方向时改拿决策表(`03`)和质量地板(`05`)对照,其余不变。
+
+想要更贴近某位博主的剪法:把他公开视频里的 8-15 秒片段(一个功能段,如开场钩子 / 讲机制 / 列举 / 定调观点 / 收尾)放在这里,文件名写清 `功能+有据或无据+人像形态`,质检闭环第④步会拿它找差距方向。仅限个人学习使用,不要把别人的视频提交到任何公开仓库。
diff --git a/skill/seecut/scripts/_common.mjs b/skill/seecut/scripts/_common.mjs
new file mode 100644
index 0000000..37da741
--- /dev/null
+++ b/skill/seecut/scripts/_common.mjs
@@ -0,0 +1,25 @@
+// 共用:读工程配置 project.json、定位 playwright-core 与无头 Chrome。
+import fs from 'fs'; import path from 'path'; import os from 'os'; import { createRequire } from 'module';
+export function loadProject(buildDir){
+ const B=path.resolve(buildDir); const f=path.join(B,'project.json');
+ if(!fs.existsSync(f)) throw new Error(`缺 ${f}(见 references/07 §配置契约)`);
+ const c=JSON.parse(fs.readFileSync(f,'utf8'));
+ const d={html:'master.html',timeline:'master',person_dir:'person',person_img_id:'person',person_wrap_id:'personWrap',steady:[],spring:[]};
+ const P={...d,...c,B}; for(const k of ['fps','width','height','duration']) if(!P[k]) throw new Error(`project.json 缺 ${k}`);
+ P.N=Math.round(P.fps*P.duration); return P;
+}
+export function chromium(buildDir){
+ for(const base of [path.resolve(buildDir), path.resolve(buildDir,'build'), path.dirname(new URL(import.meta.url).pathname)]){
+ try{ return createRequire(path.join(base,'package.json'))('playwright-core').chromium; }catch(e){}
+ }
+ throw new Error(`找不到 playwright-core:在工程目录执行 npm i playwright-core(别用 sudo)`);
+}
+export function chromePath(){
+ if(process.env.JIANJI_CHROME) return process.env.JIANJI_CHROME;
+ const root=path.join(os.homedir(),'Library/Caches/ms-playwright');
+ if(fs.existsSync(root)) for(const d of fs.readdirSync(root).filter(x=>x.startsWith('chromium_headless_shell')).sort().reverse()){
+ for(const sub of fs.readdirSync(path.join(root,d))){ const p=path.join(root,d,sub,'chrome-headless-shell'); if(fs.existsSync(p)) return p; }
+ }
+ return undefined; // 交给 playwright 默认
+}
+export function watchdog(ms,label){ const t=setTimeout(()=>{console.error(`⏰ WATCHDOG: ${label} 超 ${ms/1000}s,强退`);process.exit(3);},ms); t.unref&&t.unref(); return t; }
diff --git a/skill/seecut/scripts/agy_judge.py b/skill/seecut/scripts/agy_judge.py
new file mode 100644
index 0000000..35eed2b
--- /dev/null
+++ b/skill/seecut/scripts/agy_judge.py
@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""agy 评委(v2):硬伤清单 check / 两两对比 pair。
+
+用法:
+ python3 agy_judge.py check --video v2.mp4 [--html master.html] [--out qc/v2-check.json]
+ python3 agy_judge.py pair --a v2.mp4 --b v1.mp4 [--html-a a.html] [--html-b b.html] [--out qc/v2-vs-v1.json]
+
+内置纪律(见 references/06-质检闭环spec.md §五):
+ 每次 --new-project;JSON schema 输出;指纹核(照抄文字须在 html 源码里命中 ≥2 条,无 html 则跳过);
+ 时长核(与 ffprobe 差 ≤3s);无效重跑 1 次,仍无效则标 invalid;pair 自动交换位置跑两次求共识。
+代理:继承当前环境的 https_proxy/http_proxy/all_proxy;若设了 JIANJI_PROXY=http://127.0.0.1:1087 则自动套用。
+"""
+import argparse, json, os, re, shutil, subprocess, sys, tempfile, time
+
+SKILL = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+PROMPTS = {'check': 'references/prompt/硬伤清单.txt', 'pair': 'references/prompt/对比评委.txt'}
+SCHEMAS = {'check': 'scripts/schemas/check.json', 'pair': 'scripts/schemas/pair.json'}
+AGY = os.environ.get('AGY_BIN') or shutil.which('agy') or os.path.expanduser('~/.local/bin/agy')
+
+
+def log(*a):
+ print(time.strftime('%H:%M:%S'), *a, flush=True)
+
+
+def duration(path):
+ out = subprocess.check_output(['ffprobe', '-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', path])
+ return float(out.decode().strip())
+
+
+def to540(src, dst):
+ sc = "scale='if(gt(iw,ih),-2,540)':'if(gt(iw,ih),540,-2)'"
+ subprocess.check_call(['ffmpeg', '-v', 'error', '-y', '-i', src, '-vf', sc, '-c:v', 'libx264', '-crf', '26',
+ '-c:a', 'aac', '-b:a', '96k', dst])
+
+
+def norm(s):
+ return re.sub(r'[\s\W_]+', '', s or '').lower()
+
+
+def fp_source(html_path, extra=None):
+ """指纹比对源 = 成片源码文字(去标签)+ 证据截图里的字(fp-manifest.txt:执行窗读图核敏感字时顺手转录)"""
+ if not html_path:
+ return None
+ html = open(html_path, encoding='utf-8', errors='ignore').read()
+ parts = [re.sub(r'<[^>]+>', '', html)] # 去标签:页面文字常被 <span>/<br> 拆开
+ auto = os.path.join(os.path.dirname(os.path.abspath(html_path)), 'fp-manifest.txt')
+ for f in [auto] + list(extra or []):
+ if f and os.path.exists(f):
+ parts.append(open(f, encoding='utf-8', errors='ignore').read())
+ return norm(' '.join(parts))
+
+
+def fp_hits(texts, html_path, extra=None):
+ src = fp_source(html_path, extra)
+ if src is None:
+ return None
+ hits = 0
+ for t in texts:
+ n = norm(t)
+ if len(n) >= 2 and (n in src or (len(n) >= 6 and n[:6] in src)):
+ hits += 1
+ return hits
+
+
+def last_json(text, key):
+ dec, found, i = json.JSONDecoder(), None, 0
+ while True:
+ i = text.find('{', i)
+ if i < 0:
+ return found
+ try:
+ obj, end = dec.raw_decode(text, i)
+ if isinstance(obj, dict) and key in obj:
+ found = obj
+ i = end
+ except ValueError:
+ i += 1
+
+
+RAW_DIR = None # 设了就把每次 agy 原始输出留档到这里
+
+
+class AuthError(Exception):
+ pass
+
+
+class Transient(Exception):
+ """接口断连/超时:与内容无关,立即重试(2-4.1 实测:21 次调用 9 次败于 EOF/超时,每次白等 2-9 分钟)"""
+
+
+def run_agy(mode, workdir, timeout):
+ env = dict(os.environ)
+ px = env.get('JIANJI_PROXY')
+ if px:
+ env.update(https_proxy=px, http_proxy=px, HTTPS_PROXY=px, HTTP_PROXY=px, no_proxy='localhost,127.0.0.1')
+ prompt = open(os.path.join(SKILL, PROMPTS[mode]), encoding='utf-8').read() + '\n只根据本目录里的视频文件作答,不要读取、列出或搜索任何其他文件。'
+ cmd = [AGY, '-p', prompt, '--new-project', '--add-dir', '.', '--model', 'gemini-3.8-flash-high',
+ '--json-schema', os.path.join(SKILL, SCHEMAS[mode]), '--output-format', 'json',
+ '--dangerously-skip-permissions', '--print-timeout', f'{timeout}s']
+ try:
+ p = subprocess.run(cmd, cwd=workdir, env=env, capture_output=True, text=True, timeout=timeout + 30)
+ raw = p.stdout + p.stderr
+ except subprocess.TimeoutExpired:
+ raise Transient(f'agy 超过 {timeout}s 未返回')
+ if RAW_DIR:
+ os.makedirs(RAW_DIR, exist_ok=True)
+ open(os.path.join(RAW_DIR, f'{mode}-{time.strftime("%H%M%S")}-{os.path.basename(workdir)}.raw'), 'w', encoding='utf-8').write(raw)
+ try:
+ outer = json.loads(p.stdout)
+ if outer.get('status') == 'ERROR':
+ raise Transient('agy 接口报错: ' + str(outer.get('error', ''))[:120])
+ so = outer.get('structured_output')
+ if isinstance(so, dict) and ('checks' in so or 'dimensions' in so):
+ return so
+ resp = outer.get('response', '')
+ except Transient:
+ raise
+ except Exception:
+ resp = raw
+ # 只在没拿到正常 JSON 时才判授权问题,避免视频内容里恰好有这些词被误判
+ if re.search(r'Authentication required|not logged in|please (re-?)?log ?in', raw, re.I):
+ raise AuthError('agy 授权过期/未登录:请人工在终端裸跑一次 agy 重新登录后再试')
+ if re.search(r'time(d)? ?out|deadline', raw, re.I):
+ raise Transient('agy 自身 print-timeout 超时')
+ return last_json(resp, 'checks' if mode == 'check' else 'dimensions')
+
+
+def judge_once(mode, files, htmls, timeout, extra=None):
+ """files: {'A': path} 或 {'X': path, 'Y': path};返回 (result, problems)"""
+ wd = tempfile.mkdtemp(prefix='jianji_agy_') # 系统 tmp:评委只能看到这两个 mp4,读不到工程源码/runlog(2-4.1 实证污染)
+ try:
+ real = {}
+ for k, f in files.items():
+ to540(f, os.path.join(wd, f'{k}.mp4'))
+ real[k] = duration(f)
+ r = run_agy(mode, wd, timeout)
+ finally:
+ shutil.rmtree(wd, ignore_errors=True)
+ if not r:
+ return None, ['无有效 JSON']
+ probs = []
+ fp = r.get('fingerprint', {})
+ if mode == 'check':
+ pairs = [('A', fp.get('texts', []), fp.get('duration_sec', 0))]
+ else:
+ pairs = [('X', fp.get('X_texts', []), fp.get('X_duration_sec', 0)),
+ ('Y', fp.get('Y_texts', []), fp.get('Y_duration_sec', 0))]
+ for k, texts, d in pairs:
+ if abs((d or 0) - real[k]) > 3:
+ probs.append(f'{k} 时长不符 agy={d} 实测={real[k]:.1f}')
+ h = fp_hits(texts, htmls.get(k), extra)
+ if h is not None and h < 2:
+ probs.append(f'{k} 指纹命中 {h}/≥2(疑似 confab): {texts}')
+ return r, probs
+
+
+def judge(mode, files, htmls, timeout, extra=None):
+ content_tries, probs, r = 0, [], None
+ for attempt in range(1, 5):
+ try:
+ r, probs = judge_once(mode, files, htmls, timeout, extra)
+ except Transient as e:
+ log(f'第{attempt}次接口失败({e}),立即重试')
+ probs, r = [str(e)], None
+ continue
+ if r and not probs:
+ return {'valid': True, 'result': r}
+ content_tries += 1
+ log(f'第{attempt}次结果无效:', '; '.join(probs))
+ if content_tries >= 2:
+ break
+ return {'valid': False, 'problems': probs, 'result': r}
+
+
+def secs(txt):
+ """从证据文字里抽第一段时间:00:14-00:15 / 14.8s / 00:14 → [起, 止]"""
+ m = re.findall(r'(\d{1,2}):(\d{2}(?:\.\d+)?)', txt or '')
+ ts = [int(a) * 60 + float(b) for a, b in m[:2]]
+ if not ts:
+ ts = [float(x) for x in re.findall(r'(\d+(?:\.\d+)?)\s*s', txt or '')[:2]]
+ return ts
+
+
+def grab_fail_frames(video, fails, outdir):
+ """agy 报的 FAIL 自动抽帧,交执行窗读图核实(agy 会串相邻两拍,历史上多次误报穿模/残留)"""
+ os.makedirs(outdir, exist_ok=True)
+ made = []
+ for c in fails:
+ ts = secs(c.get('evidence', ''))
+ if not ts:
+ continue
+ a, b = ts[0], (ts[1] if len(ts) > 1 else ts[0] + 1)
+ for t in sorted({a, (a + b) / 2, b}):
+ f = os.path.join(outdir, f"{c['id']}_{t:.1f}s.jpg")
+ subprocess.call(['ffmpeg', '-v', 'error', '-y', '-ss', str(t), '-i', video, '-frames:v', '1',
+ '-vf', 'scale=360:-2', f])
+ made.append(f)
+ return made
+
+
+def main():
+ ap = argparse.ArgumentParser()
+ ap.add_argument('mode', choices=['check', 'pair'])
+ ap.add_argument('--video'); ap.add_argument('--html')
+ ap.add_argument('--a'); ap.add_argument('--b'); ap.add_argument('--html-a'); ap.add_argument('--html-b')
+ ap.add_argument('--out'); ap.add_argument('--timeout', type=int, default=240) # 成功调用多在 60-240s;超时即判断连断重试
+ ap.add_argument('--fp-extra', action='append', default=[],
+ help='额外指纹文字清单(证据截图里的字),可多次;html 同目录的 fp-manifest.txt 会自动读')
+ a = ap.parse_args()
+ global RAW_DIR
+ if a.out:
+ RAW_DIR = os.path.splitext(os.path.abspath(a.out))[0] + '_raw'
+
+ if a.mode == 'check':
+ log('check', a.video)
+ res = judge('check', {'A': a.video}, {'A': a.html}, a.timeout, a.fp_extra)
+ if res['valid']:
+ fails = [c for c in res['result']['checks'] if not c['pass']]
+ res['summary'] = {'valid': True, 'gate_pass': not fails, 'fails': [c['id'] for c in fails],
+ 'evidence_gaps': len(res['result'].get('evidence_gaps', []))}
+ if fails and a.out:
+ fr = grab_fail_frames(a.video, fails, os.path.splitext(os.path.abspath(a.out))[0] + '_failframes')
+ res['summary']['verify_frames'] = fr
+ log(f'⚠ {len(fails)} 条 FAIL 待核:读这些帧确认是否 agy 误报(串场)→', os.path.dirname(fr[0]) if fr else '无时间码')
+ else:
+ res['summary'] = {'valid': False, 'gate_pass': None,
+ 'note': 'agy 两次都无效,本次没有检查结果,不能当作通过/不通过'}
+ else:
+ log('pair 两序并行:X=a/Y=b 与 X=b/Y=a')
+ from concurrent.futures import ThreadPoolExecutor
+ with ThreadPoolExecutor(2) as ex:
+ f1 = ex.submit(judge, 'pair', {'X': a.a, 'Y': a.b}, {'X': a.html_a, 'Y': a.html_b}, a.timeout, a.fp_extra)
+ f2 = ex.submit(judge, 'pair', {'X': a.b, 'Y': a.a}, {'X': a.html_b, 'Y': a.html_a}, a.timeout, a.fp_extra)
+ r1, r2 = f1.result(), f2.result()
+ w1 = ('A' if r1['result']['winner'] == 'X' else 'B') if r1['valid'] else None
+ w2 = ('B' if r2['result']['winner'] == 'X' else 'A') if r2['valid'] else None
+ consensus = w1 if (w1 and w1 == w2) else ('invalid' if not (w1 and w2) else 'tie')
+ res = {'a': a.a, 'b': a.b, 'order1': r1, 'order2': r2, 'winners': [w1, w2], 'consensus': consensus}
+ out = json.dumps(res, ensure_ascii=False, indent=1)
+ if a.out:
+ os.makedirs(os.path.dirname(os.path.abspath(a.out)), exist_ok=True)
+ open(a.out, 'w', encoding='utf-8').write(out)
+ s = res.get('summary') or {'consensus': res.get('consensus'), 'winners': res.get('winners')}
+ log('结果:', json.dumps(s, ensure_ascii=False), '→', a.out or '(stdout 未存)')
+ if not a.out:
+ print(out)
+ # 退出码:0=通过/有共识 1=check 有 FAIL 2=无效(没结果) 3=授权过期
+ if a.mode == 'check':
+ sys.exit(2 if not res['summary']['valid'] else (0 if res['summary']['gate_pass'] else 1))
+ sys.exit(2 if consensus == 'invalid' else 0)
+
+
+if __name__ == '__main__':
+ try:
+ main()
+ except AuthError as e:
+ log('⛔', e)
+ sys.exit(3)
diff --git a/skill/seecut/scripts/agy_read.sh b/skill/seecut/scripts/agy_read.sh
new file mode 100644
index 0000000..ac89227
--- /dev/null
+++ b/skill/seecut/scripts/agy_read.sh
@@ -0,0 +1,12 @@
+#!/bin/zsh
+# 素材理解用:让 agy 读一段视频/图片,自带新项目隔离 + 超时 + 代理。
+# 用法: zsh agy_read.sh <素材文件> "<要它回答什么>" [超时秒=540] > 输出.txt
+# 长视频先 ffmpeg 切 ≤25s 段并降 540p;prompt 已自动追加"禁后台 OCR/转录子任务"。
+F="$1"; Q="$2"; T="${3:-540}"
+[ -f "$F" ] || { echo "用法: agy_read.sh <文件> \"<问题>\" [超时秒]"; exit 2; }
+[ -n "$JIANJI_PROXY" ] && export https_proxy=$JIANJI_PROXY http_proxy=$JIANJI_PROXY HTTPS_PROXY=$JIANJI_PROXY HTTP_PROXY=$JIANJI_PROXY
+D=$(mktemp -d -t jianji_read); cp "$F" "$D/"; N=$(basename "$F")
+AGY=$(command -v agy || echo ~/.local/bin/agy)
+cd "$D" && perl -e "alarm $((T+60)); exec @ARGV" "$AGY" -p "看 @$N 。$Q
+直接凭观看作答,禁止启动任何后台 OCR/转录/采样子任务,不要读取其它文件。" --new-project --add-dir . --model gemini-3.8-flash-high --dangerously-skip-permissions --print-timeout ${T}s
+RC=$?; rm -rf "$D"; exit $RC
diff --git a/skill/seecut/scripts/geom-check.mjs b/skill/seecut/scripts/geom-check.mjs
new file mode 100644
index 0000000..1ae318b
--- /dev/null
+++ b/skill/seecut/scripts/geom-check.mjs
@@ -0,0 +1,70 @@
+// 3A 几何自检(硬门 H1)。整套 seek+读 bbox 在浏览器内一次 evaluate 跑完(禁每帧往返)。
+// 用法: node geom-check.mjs <build目录> 退出码 0=全绿 1=有FAIL 2/3=环境错误/超时
+// 打标契约(见 references/07): data-check="box"|"bg" · data-anchor=目标id · data-word=关键词 + data-t=该词起始秒
+// 人像外框 #<person_wrap_id>;project.json 里 steady=各信息拍稳态秒, spring=[[选择器,入场秒],...]
+import path from 'path';
+import { loadProject, chromium, chromePath, watchdog } from './_common.mjs';
+const buildDir=process.argv[2]; if(!buildDir){console.error('用法: node geom-check.mjs <build目录>');process.exit(2);}
+const P=loadProject(buildDir);
+const WD=watchdog(120000,'geom-check');
+const C={N:P.N,FPS:P.fps,W:P.width,H:P.height,STEP:2,STEADY:P.steady,TL:P.timeline,PW:P.person_wrap_id,
+ OVERLAP_MAX:P.overlap_max??0.15,ANCHOR_DIST:0.40,ANCHOR_COVER:0.60,NOFACE_MAX:P.noface_max??5.0,FULLFRAME:0.45};
+const b=await chromium(P.B).launch({headless:true,executablePath:chromePath()});
+const pg=await (await b.newContext({viewport:{width:P.width,height:P.height},deviceScaleFactor:1})).newPage();
+await pg.goto('file://'+path.join(P.B,P.html),{waitUntil:'load',timeout:30000});
+await pg.evaluate(()=>document.fonts&&document.fonts.ready).catch(()=>{});
+await new Promise(r=>setTimeout(r,400));
+const R=await pg.evaluate((C)=>{
+ const tl=(window.__timelines||{})[C.TL]; if(!tl) return {err:'找不到 window.__timelines.'+C.TL};
+ const {N,FPS,W,H,STEP,STEADY,OVERLAP_MAX,ANCHOR_DIST,ANCHOR_COVER,NOFACE_MAX,FULLFRAME}=C;
+ const eff=el=>{let o=1,n=el;while(n&&n!==document.body){const cs=getComputedStyle(n);
+ if(cs.display==='none'||cs.visibility==='hidden')return{vis:false};o*=parseFloat(cs.opacity)||0;n=n.parentElement;}
+ const r=el.getBoundingClientRect();
+ return{vis:o>0.1&&r.width>2&&r.height>2&&r.bottom>0&&r.top<H&&r.right>0&&r.left<W,x:r.left,y:r.top,w:r.width,h:r.height,cx:r.left+r.width/2,cy:r.top+r.height/2};};
+ const inter=(a,c)=>Math.max(0,Math.min(a.x+a.w,c.x+c.w)-Math.max(a.x,c.x))*Math.max(0,Math.min(a.y+a.h,c.y+c.h)-Math.max(a.y,c.y));
+ const FAILS=[],WARN=[];
+ if(!STEADY.length) WARN.push('[配置] project.json 未给 steady(信息拍稳态秒),撞位/圈锚/密度未检');
+ for(const t of STEADY){tl.time(t);
+ const boxes=[...document.querySelectorAll('[data-check="box"]')].map(el=>({id:el.id||el.className,...eff(el)})).filter(e=>e.vis);
+ for(let i=0;i<boxes.length;i++)for(let j=i+1;j<boxes.length;j++){const a=boxes[i],c=boxes[j];
+ const r=inter(a,c)/Math.min(a.w*a.h,c.w*c.h); if(r>OVERLAP_MAX)FAILS.push(`[撞位] t=${t}s "${a.id}"✕"${c.id}" ${(r*100)|0}%`);}
+ if(boxes.length<2)WARN.push(`[空拍?] t=${t}s 可见 box 仅 ${boxes.length} 个`);
+ const pw=document.getElementById(C.PW);const Pp=pw?eff(pw):{vis:false};
+ if(Pp.vis&&(Pp.w*Pp.h)/(W*H)<FULLFRAME)for(const bx of boxes){const r=inter(bx,Pp)/Math.min(bx.w*bx.h,Pp.w*Pp.h);
+ if(r>0.12)FAILS.push(`[压人像] t=${t}s "${bx.id}" ${(r*100)|0}%`);}
+ // 被人像盖住(z 序遮挡):不管人像多大都查——Round2-4.2 实测字卡被人像盖 1.5s,bbox 撞位和 agy 都没抓到
+ if(Pp.vis){ const pwEl=document.getElementById(C.PW);
+ for(const el of document.querySelectorAll('[data-check="box"]')){ const E=eff(el); if(!E.vis) continue;
+ const pts=[[.5,.5],[.25,.25],[.75,.25],[.25,.75],[.75,.75]].map(([u,v])=>[E.x+E.w*u,E.y+E.h*v]).filter(([x,y])=>x>=0&&y>=0&&x<W&&y<H);
+ const hid=pts.filter(([x,y])=>{const top=document.elementFromPoint(x,y); return top&&pwEl.contains(top)&&!el.contains(top);}).length;
+ if(pts.length&&hid>=3) FAILS.push(`[被人像盖住] t=${t}s "${el.id||el.className}" ${hid}/${pts.length} 采样点在人像下面`);}}
+ for(const ae of document.querySelectorAll('[data-anchor]')){const te=document.getElementById(ae.getAttribute('data-anchor'));if(!te)continue;
+ const A=eff(ae),T=eff(te);if(!A.vis||!T.vis)continue;const dist=Math.hypot(A.cx-T.cx,A.cy-T.cy);
+ const cov=Math.max(0,Math.min(A.x+A.w,T.x+T.w)-Math.max(A.x,T.x))/T.w;
+ if(dist>T.h*ANCHOR_DIST)FAILS.push(`[圈歪] t=${t}s "${te.id}" 偏 ${dist|0}px`);
+ if(cov<ANCHOR_COVER)FAILS.push(`[圈偏] t=${t}s "${te.id}" 覆盖 ${(cov*100)|0}%`);}}
+ const words=[...document.querySelectorAll('[data-word]')].map(el=>({l:el.getAttribute('data-word'),t:parseFloat(el.getAttribute('data-t')),el}));
+ const first={};let nf=0,nfMax=0;
+ for(let i=0;i<N;i+=STEP){tl.time(i/FPS);const pw=document.getElementById(C.PW);const pv=pw?eff(pw).vis:true;
+ if(!pv){nf+=STEP;nfMax=Math.max(nfMax,nf);}else nf=0;
+ for(const w of words)if(first[w.l]===undefined&&eff(w.el).vis)first[w.l]=i/FPS;}
+ const nfs=nfMax/FPS; if(nfs>NOFACE_MAX)FAILS.push(`[无脸] 最长 ${nfs.toFixed(1)}s > ${NOFACE_MAX}s`);
+ for(const w of words){const f=first[w.l]; if(isNaN(w.t)){WARN.push(`[timing] "${w.l}" 缺 data-t`);continue;}
+ if(f===undefined)WARN.push(`[timing] "${w.l}" 全程未见`); else if(f<w.t-0.05)FAILS.push(`[抢拍] "${w.l}" @${f.toFixed(2)}s 早于词 @${w.t}s`);}
+ return{FAILS,WARN,nfs,words:words.map(w=>({l:w.l,t:w.t,f:first[w.l]}))};
+},C);
+if(R.err){console.error(R.err);process.exit(2);}
+const spring=await pg.evaluate(({items,TL})=>{const tl=window.__timelines[TL];
+ const sc=el=>{try{const m=new DOMMatrixReadOnly(getComputedStyle(el).transform);return Math.hypot(m.a,m.b);}catch(e){return 1;}};
+ return items.map(([sel,t])=>{const el=document.querySelector(sel);if(!el)return{sel,miss:true};let pk=0;
+ for(let x=t;x<=t+0.6;x+=0.02){tl.time(x);pk=Math.max(pk,sc(el));}return{sel,peak:+pk.toFixed(3),ok:pk>1.02};});},{items:P.spring,TL:P.timeline});
+spring.filter(s=>!s.miss&&!s.ok).forEach(s=>R.FAILS.push(`[无弹簧] ${s.sel} 峰值 ${s.peak}`));
+if(!P.spring.length) R.WARN.push('[配置] project.json 未给 spring 采样点,弹簧 overshoot 未检');
+console.log(`=== 3A 几何自检 · ${P.B} ===`);
+console.log('弹簧: '+(spring.map(s=>`${s.sel}=${s.miss?'缺':s.peak}${s.ok?'✓':'✗'}`).join(' ')||'—'));
+console.log(`无脸最长: ${R.nfs.toFixed(2)}s`);
+R.words.forEach(w=>console.log(` ${w.l}: 首现 @${w.f?.toFixed(2)??'??'} / 词 @${w.t} ${w.f!==undefined&&w.f>=w.t-0.05?'✓':'✗'}`));
+console.log(`FAIL ${R.FAILS.length}`);R.FAILS.forEach(f=>console.log(' ✗ '+f));
+console.log(`WARN ${R.WARN.length}`);R.WARN.forEach(w=>console.log(' ⚠ '+w));
+console.log(R.FAILS.length?'❌ 有 FAIL':'✅ 3A 全绿');
+clearTimeout(WD); await b.close(); process.exit(R.FAILS.length?1:0);
diff --git a/skill/seecut/scripts/grab_evidence.mjs b/skill/seecut/scripts/grab_evidence.mjs
new file mode 100644
index 0000000..51e69bb
--- /dev/null
+++ b/skill/seecut/scripts/grab_evidence.mjs
@@ -0,0 +1,15 @@
+// 找证据:把口播提到的真实网页截成图(参考片"真实证据优先")。截完必须读图核敏感字(总纲第7条)再入片。
+// 用法: node grab_evidence.mjs <输出目录> <url> [<url>...] 可选环境: EVID_W=1280 EVID_H=800 EVID_FULL=1 JIANJI_PROXY=http://127.0.0.1:1087
+// playwright-core 从当前目录或 skill scripts 目录解析(npm i playwright-core)。
+import fs from 'fs'; import path from 'path'; import { chromium, chromePath, watchdog } from './_common.mjs';
+const [,,outDir,...urls]=process.argv; if(!outDir||!urls.length){console.error('用法: node grab_evidence.mjs <输出目录> <url>...');process.exit(2);}
+fs.mkdirSync(outDir,{recursive:true}); watchdog(60000*urls.length+30000,'grab_evidence');
+const px=process.env.JIANJI_PROXY;
+const b=await chromium(process.cwd()).launch({headless:true,executablePath:chromePath(),...(px?{proxy:{server:px}}:{})});
+const ctx=await b.newContext({viewport:{width:+(process.env.EVID_W||1280),height:+(process.env.EVID_H||800)},deviceScaleFactor:2,locale:'zh-CN'});
+for(const [i,u] of urls.entries()){const pg=await ctx.newPage();
+ try{await pg.goto(u,{waitUntil:'networkidle',timeout:45000});}catch(e){console.log(`⚠ ${u} 加载未完全: ${e.message.split('\n')[0]}`);}
+ await new Promise(r=>setTimeout(r,1500));
+ const f=path.join(outDir,`evid_${String(i+1).padStart(2,'0')}_${new URL(u).hostname}.png`);
+ await pg.screenshot({path:f,fullPage:!!process.env.EVID_FULL}); console.log('✓',f,'←',u); await pg.close();}
+await b.close(); console.log('截完。下一步:逐张读图核敏感字,再登记到 素材台账.md');
diff --git a/skill/seecut/scripts/jianying_layers.mjs b/skill/seecut/scripts/jianying_layers.mjs
new file mode 100644
index 0000000..20da45c
--- /dev/null
+++ b/skill/seecut/scripts/jianying_layers.mjs
@@ -0,0 +1,138 @@
+// 剪映分层素材:把 master.html 拆成"纸底 PNG + 人像分状态视频 + 信息层逐元素透明 PNG + 原声",外加音效候选事件。
+// 用法: node jianying_layers.mjs <build目录> [输出目录=<build>/../jianying/layers]
+// 打标契约(见 references/10-剪映分层工程.md):
+// 信息层元素加 data-layer="显示名"(可选 data-layer-cat= evbg|card|cardimg|hl|title|hand,默认 card;决定轨道上下顺序)
+// 嵌套的 data-layer 子元素会在截父元素时自动隐藏(各自单独成段)
+// 人像:#<person_wrap_id>(外框,含卡化边框/圆角)里放 <img id=person_img_id>;纸底/噪点等背景不打标
+// 原理与坑(2-4.1 一线实测):剪映引擎不收 alpha 视频 → 信息层用透明 PNG + 不透明度关键帧;关键帧要求素材从头开始 → 人像按状态切成独立视频。
+import fs from 'fs'; import path from 'path'; import { execFileSync } from 'child_process';
+import { loadProject, chromium, chromePath, watchdog } from './_common.mjs';
+const [, , buildDir, outArg] = process.argv;
+if (!buildDir) { console.error('用法: node jianying_layers.mjs <build目录> [输出目录]'); process.exit(2); }
+const P = loadProject(buildDir);
+const OUT = path.resolve(outArg || path.join(P.B, '../jianying/layers'));
+const PNG = path.join(OUT, 'png'); fs.mkdirSync(PNG, { recursive: true });
+const FPS = P.fps, N = P.N, W = P.width, H = P.height;
+watchdog(Math.max(600000, N * 3000), 'jianying_layers');
+const pad = n => String(n).padStart(4, '0');
+const PD = path.join(P.B, P.person_dir);
+const NP = fs.existsSync(PD) ? fs.readdirSync(PD).filter(f => /^p\d+\.jpg$/.test(f)).length : 0;
+
+const b = await chromium(P.B).launch({ headless: true, executablePath: chromePath() });
+const pg = await (await b.newContext({ viewport: { width: W, height: H }, deviceScaleFactor: 1 })).newPage();
+await pg.goto('file://' + path.join(P.B, P.html), { waitUntil: 'load', timeout: 30000 });
+await pg.evaluate(() => document.fonts && document.fonts.ready).catch(() => {});
+await new Promise(r => setTimeout(r, 400));
+const setT = async (i) => pg.evaluate(async ({ t, tl, pid, src }) => {
+ window.__timelines[tl].time(t);
+ const im = document.getElementById(pid); if (im && src) { im.src = src; try { await im.decode(); } catch (e) {} }
+}, { t: i / FPS, tl: P.timeline, pid: P.person_img_id, src: NP ? 'file://' + path.join(PD, 'p' + pad(Math.min(i + 1, NP)) + '.jpg') : null });
+
+// 1) 一次 evaluate 扫完全部帧:每个 data-layer 元素 + 人像外框的有效不透明度与 bbox
+const scan = await pg.evaluate(({ N, FPS, W, H, tl, pw }) => {
+ const T = window.__timelines[tl];
+ const els = [...document.querySelectorAll('[data-layer]')];
+ const eff = el => { let o = 1, n = el; while (n && n.nodeType === 1) { const cs = getComputedStyle(n);
+ if (cs.display === 'none' || cs.visibility === 'hidden') return { op: 0 }; o *= parseFloat(cs.opacity); n = n.parentElement; }
+ const r = el.getBoundingClientRect(); const on = r.width > 2 && r.height > 2 && r.bottom > 0 && r.top < H && r.right > 0 && r.left < W;
+ return { op: on ? o : 0, x: r.left, y: r.top, w: r.width, h: r.height }; };
+ const meta = els.map((el, k) => { if (!el.id) el.id = '__jl' + k;
+ return { id: el.id, name: el.getAttribute('data-layer') || el.id, cat: el.getAttribute('data-layer-cat') || 'card',
+ nest: [...el.querySelectorAll('[data-layer]')].map(c => { if (!c.id) c.id = '__jl' + els.indexOf(c); return '#' + c.id; }) }; });
+ const res = els.map(() => []), person = [];
+ const pwel = document.getElementById(pw);
+ for (let i = 0; i < N; i++) { T.time(i / FPS); els.forEach((el, k) => res[k].push(eff(el))); person.push(pwel ? eff(pwel) : { op: 0 }); }
+ return { meta, res, person };
+}, { N, FPS, W, H, tl: P.timeline, pw: P.person_wrap_id });
+if (!scan.meta.length) { console.error('master.html 里没有 data-layer 标记的元素(见 references/10 打标契约)'); process.exit(2); }
+
+// 2) 信息层:可见 run → 按"位置移动"切状态(弹入缩放回弹不算新状态;第 0 帧初始化闪现丢弃)
+const same = (a, c) => Math.hypot((a.x + a.w / 2) - (c.x + c.w / 2), (a.y + a.h / 2) - (c.y + c.h / 2)) < 20 && Math.abs(a.w / c.w - 1) < 0.08;
+const ctr = q => [q.x + q.w / 2, q.y + q.h / 2];
+const segs = [];
+scan.meta.forEach((m, k) => {
+ const f = scan.res[k]; let i = 0;
+ while (i < N) {
+ if (f[i].op <= 0.02) { i++; continue; }
+ let j = i; while (j + 1 < N && f[j + 1].op > 0.02) j++;
+ if (j - i < 2 && i === 0) { i = j + 1; continue; }
+ const groups = []; let s = i;
+ while (s <= j) { if (f[s].op < 0.98) { s++; continue; }
+ let e = s; while (e + 1 <= j && f[e + 1].op >= 0.98 && same(f[e + 1], f[s])) e++;
+ if (e - s + 1 >= 3) groups.push([s, e]); s = e + 1; }
+ if (!groups.length) groups.push([Math.floor((i + j) / 2), Math.floor((i + j) / 2)]);
+ for (let g = groups.length - 1; g > 0; g--) { const [a1, b1] = ctr(f[groups[g - 1][1]]), [a2, b2] = ctr(f[groups[g][0]]);
+ if (Math.hypot(a1 - a2, b1 - b2) < 20) { groups[g - 1][1] = groups[g][1]; groups.splice(g, 1); } }
+ groups.forEach(([gs, ge], g) => segs.push({ name: groups.length > 1 ? `${m.name}_态${g + 1}` : m.name, id: m.id, cat: m.cat, nest: m.nest,
+ start: g === 0 ? i : groups[g - 1][1] + 1, end: g === groups.length - 1 ? j : ge, cap: Math.max(gs, ge - 1),
+ fade_in: g === 0, fade_out: g === groups.length - 1 }));
+ i = j + 1;
+ }
+});
+
+// 3) 人像:外框 bbox 稳定 ≥0.3s 的段 = 状态;状态之间 = 过渡(剪映里用 x/y/scale 关键帧做)
+const pf = scan.person, states = []; { let s = 0;
+ while (s < N) { if (pf[s].op < 0.5) { s++; continue; }
+ let e = s; while (e + 1 < N && pf[e + 1].op >= 0.5 && Math.abs(pf[e + 1].x - pf[s].x) < 0.5 && Math.abs(pf[e + 1].y - pf[s].y) < 0.5 && Math.abs(pf[e + 1].w - pf[s].w) < 0.5 && Math.abs(pf[e + 1].h - pf[s].h) < 0.5) e++;
+ if (e - s + 1 >= Math.round(0.3 * FPS)) states.push({ s, e, box: [pf[s].x, pf[s].y, pf[s].w, pf[s].h].map(Math.round) });
+ s = e + 1; } }
+// 每个状态的时间段 = 从"进入它的过渡开始"到"离开它的过渡开始"
+// 人像中途隐藏(opacity≈0)的时段不能算过渡(Round2-4.2 实测:隐藏段被记成 137 帧过渡,草稿里人像一直可见)
+const vis = i => pf[i].op >= 0.5;
+states.forEach((st, k) => {
+ st.name = `人像_状态${k + 1}`; st.fade_in = false; st.fade_out = false;
+ let from = k === 0 ? 0 : states[k - 1].e + 1;
+ let h = -1; for (let i = from; i < st.s; i++) if (!vis(i)) h = i; // 进入本状态前最后一个隐藏帧
+ if (h >= 0) { from = h + 1; st.fade_in = true; }
+ if (k === 0) { let f = st.s; while (f > 0 && vis(f - 1)) f--; if (f > 0) st.fade_in = true; from = f; }
+ st.from = from; st.anim_frames = k === 0 || st.fade_in ? Math.max(0, st.s - from) : st.s - from;
+ let to = k === states.length - 1 ? N - 1 : states[k].e;
+ const nxt = k === states.length - 1 ? N : states[k + 1].s;
+ let firstHide = -1; for (let i = st.e + 1; i < nxt; i++) if (!vis(i)) { firstHide = i; break; }
+ if (firstHide >= 0) { to = firstHide - 1; st.fade_out = true; }
+ else if (k === states.length - 1) to = N - 1;
+ st.to = to;
+});
+
+// 4) 截图:背景 PNG、信息层透明 PNG、人像分状态视频
+await pg.addStyleTag({ content: `#${P.person_wrap_id}{visibility:hidden !important;} [data-layer]{visibility:hidden !important;}` });
+await setT(0); const paper = path.join(OUT, '纸底.png'); await pg.screenshot({ path: paper });
+await pg.addStyleTag({ content: 'html,body{background:transparent !important;}' });
+for (const s of segs) {
+ s.file = path.join(PNG, `${String(s.start).padStart(4, '0')}_${s.name}.png`);
+ await setT(s.cap);
+ await pg.evaluate(({ id, nest }) => {
+ let st = document.getElementById('__cap'); if (!st) { st = document.createElement('style'); st.id = '__cap'; document.head.appendChild(st); }
+ st.textContent = `body *{visibility:hidden !important;} #${id}, #${id} *{visibility:visible !important;} ` + nest.map(n => `${n}, ${n} *{visibility:hidden !important;}`).join(' ');
+ }, { id: s.id, nest: s.nest });
+ await pg.screenshot({ path: s.file, omitBackground: true });
+}
+await pg.evaluate(() => { const st = document.getElementById('__cap'); if (st) st.remove(); });
+// 人像:只显示外框子树,外框强制停在该状态的稳态几何,逐帧截取该区域(圆角外露出纸底色,和底层纸底同色)
+await pg.addStyleTag({ content: `body *{visibility:hidden !important;} #${P.person_wrap_id}, #${P.person_wrap_id} *{visibility:visible !important;}` });
+for (const st of states) {
+ const dir = path.join(OUT, 'tmp_' + st.name); fs.mkdirSync(dir, { recursive: true });
+ const [x, y, w, h] = st.box;
+ for (let i = st.from; i <= st.to; i++) {
+ await setT(i);
+ await pg.evaluate(({ pw, x, y, w, h }) => { const el = document.getElementById(pw);
+ Object.assign(el.style, { left: x + 'px', top: y + 'px', width: w + 'px', height: h + 'px', transform: 'none', opacity: 1 }); }, { pw: P.person_wrap_id, x, y, w, h });
+ await pg.screenshot({ path: path.join(dir, `f${pad(i - st.from)}.png`), clip: { x, y, width: w + (w % 2), height: h + (h % 2) } });
+ }
+ st.file = path.join(OUT, st.name + '.mp4');
+ execFileSync('ffmpeg', ['-v', 'error', '-y', '-framerate', String(FPS), '-i', path.join(dir, 'f%04d.png'), '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '18', st.file]);
+ fs.rmSync(dir, { recursive: true, force: true });
+ console.log(` 人像 ${st.name} ${(st.from / FPS).toFixed(2)}-${((st.to + 1) / FPS).toFixed(2)}s box=${st.box} 过渡 ${st.anim_frames} 帧`);
+}
+// 5) 原声:从源片抽(project.json 的 source 字段;没有就从最终成片抽)
+const src = P.source || P.final_video;
+let voice = null;
+if (src) { voice = path.join(OUT, '原声.m4a'); execFileSync('ffmpeg', ['-v', 'error', '-y', '-i', path.resolve(P.B, src), '-vn', '-c:a', 'aac', '-b:a', '192k', voice]); }
+// 6) 音效候选事件:信息层出现/换状态/换图 + 人像过渡
+const events = [];
+segs.forEach(s => events.push({ t: +(s.start / FPS).toFixed(3), kind: s.fade_in ? '出现' : '换状态', cat: s.cat, name: s.name }));
+states.slice(1).forEach(st => events.push({ t: +(st.from / FPS).toFixed(3), kind: '人像过渡', cat: 'person', name: st.name }));
+events.sort((a, c) => a.t - c.t);
+fs.writeFileSync(path.join(OUT, 'manifest.json'), JSON.stringify({ fps: FPS, frames: N, width: W, height: H, paper, voice, segs, person_states: states, events }, null, 1));
+console.log(`信息层 ${scan.meta.length} 个元素 → ${segs.length} 段 PNG;人像 ${states.length} 个状态;音效候选事件 ${events.length} 个 → ${path.join(OUT, 'manifest.json')}`);
+await b.close(); process.exit(0);
diff --git a/skill/seecut/scripts/jianying_plan.py b/skill/seecut/scripts/jianying_plan.py
new file mode 100644
index 0000000..43fb383
--- /dev/null
+++ b/skill/seecut/scripts/jianying_plan.py
@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""把 jianying_layers.mjs 的 manifest(+ 可选 sfx_plan.json)生成剪映分层工程 plan(jy14-headless-plan/v1)。
+用法: python3 jianying_plan.py <layers/manifest.json> --name 草稿名 --out plan.json [--sfx sfx_plan.json] [--preview preview.mp4]
+轨道:主轨=纸底 PNG;人像轨=按状态切的视频(x/y/scale 线性关键帧做过渡);信息层=逐元素透明 PNG(不透明度关键帧淡入淡出,
+ 按 cat 从下到上 evbg→card→cardimg→hl→title→hand,不重叠的段挤进同一轨);音频=原声 +(可选)音效轨。
+坐标约定(2-4.1 实测,作者 UI 验收未报偏差):scale=1 = 素材"适应画布";x/y 以半个画布为 1、y 向上为正。
+然后用 jianying-draft 引擎:build → verify-build → publish(publish 前剪映主程序须退出、先备份 root_meta_info.json)。
+"""
+import argparse, json, math, os, subprocess
+
+ap = argparse.ArgumentParser()
+ap.add_argument('manifest'); ap.add_argument('--name', required=True); ap.add_argument('--out', required=True)
+ap.add_argument('--sfx'); ap.add_argument('--preview')
+a = ap.parse_args()
+man = json.load(open(a.manifest, encoding='utf-8'))
+FPS = man['fps']; CW, CH = man['width'], man['height']
+US = lambda f: int(round(f * 1_000_000 / FPS)) # 帧→微秒(30fps 不能用整除,否则 build 报 Source trim exceeds,Round2-4.2 实测)
+FR = US(1); TOTAL = US(man['frames'])
+
+
+def media_us(path):
+ return int(float(subprocess.check_output(['ffprobe', '-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', path]).decode()) * 1e6)
+ORDER = ['evbg', 'card', 'cardimg', 'hl', 'title', 'hand']
+FADE_OUT = 5 * FR
+
+
+def fit(w, h):
+ return min(CW / w, CH / h)
+
+
+def pos(cx, cy):
+ return round((cx - CW / 2) / (CW / 2), 5), round((CH / 2 - cy) / (CH / 2), 5)
+
+
+# ---------- 人像 ----------
+person = []
+sts = man['person_states']
+for k, st in enumerate(sts):
+ x, y, w, h = st['box']; sc = round(w / (w * fit(w, h)), 4); px, py = pos(x + w / 2, y + h / 2)
+ seg = {'source': st['file'], 'start_us': US(st['from']), 'duration_us': min(US(st['to'] + 1) - US(st['from']), media_us(st['file'])), 'volume': 0.0}
+ if k == 0 or st['anim_frames'] <= 0:
+ seg.update(scale=sc, x=px, y=py)
+ else: # 从上一状态的几何线性过渡到本状态
+ x0, y0, w0, h0 = sts[k - 1]['box']; qx, qy = pos(x0 + w0 / 2, y0 + h0 / 2); d = st['anim_frames'] * FR
+ d = min(d, seg['duration_us'])
+ seg['keyframes'] = {'scale': [{'at_us': 0, 'value': round(sc * w0 / w, 4)}, {'at_us': d, 'value': sc}],
+ 'x': [{'at_us': 0, 'value': qx}, {'at_us': d, 'value': px}],
+ 'y': [{'at_us': 0, 'value': qy}, {'at_us': d, 'value': py}]}
+ op = [] # 人像中途隐藏/再出现:不透明度淡入淡出(3 帧)
+ if st.get('fade_in') and seg['start_us'] > 0: op += [(0, 0.0), (min(3 * FR, seg['duration_us'] // 2), 1.0)]
+ if st.get('fade_out'):
+ if not op: op = [(0, 1.0)]
+ t = seg['duration_us'] - min(3 * FR, seg['duration_us'] // 2)
+ if t > op[-1][0]: op.append((t, 1.0))
+ op.append((seg['duration_us'], 0.0))
+ if len(op) >= 2:
+ seg.setdefault('keyframes', {})['opacity'] = [{'at_us': a, 'value': v} for a, v in op]
+ person.append(seg)
+
+
+# ---------- 信息层 ----------
+def seg_of(s):
+ # 淡入提前 1 帧起、2 帧淡满:元素在成片出现的那一帧已可见,音效落点对得上画面(2-4.1 实测)
+ st = US(max(0, s['start'] - 1)) if s['fade_in'] else US(s['start'])
+ d = US(s['end'] + 1) - st
+ seg = {'source': s['file'], 'start_us': st, 'duration_us': d}
+ kf = []
+ if s['fade_in'] and st > 0:
+ kf += [(0, 0.0), (min(2 * FR, d // 2), 1.0)]
+ if s['fade_out'] and st + d < TOTAL:
+ fo = min(FADE_OUT, d // 2)
+ if not kf: kf = [(0, 1.0)]
+ if d - fo > kf[-1][0]: kf.append((d - fo, 1.0))
+ kf.append((d, 0.0))
+ if len(kf) >= 2:
+ seg['keyframes'] = {'opacity': [{'at_us': t, 'value': v} for t, v in kf]}
+ return seg
+
+
+def pack(items):
+ lanes = []
+ for sg in items:
+ for lane in lanes:
+ if lane[-1]['start_us'] + lane[-1]['duration_us'] <= sg['start_us']:
+ lane.append(sg); break
+ else:
+ lanes.append([sg])
+ return lanes
+
+
+tracks = [{'type': 'video', 'segments': [{'source': man['paper'], 'start_us': 0, 'duration_us': TOTAL}]}]
+layout = ['主轨: 纸底 PNG(静态,可换底色/底图)']
+BELOW_PERSON = ['evbg'] # 证据背景(满屏截图底)在人像下面,其余信息层在人像上面(2-4.1 回归测试发现)
+for cat in (BELOW_PERSON + ['__person__'] + [c for c in ORDER if c not in BELOW_PERSON] + sorted({s['cat'] for s in man['segs']} - set(ORDER))):
+ if cat == '__person__':
+ tracks.append({'type': 'video', 'segments': person})
+ layout.append('人像: ' + ' | '.join(f"{s['name']} {s['from'] / FPS:.2f}-{(s['to'] + 1) / FPS:.2f}s" for s in sts))
+ continue
+ items = sorted([seg_of(s) for s in man['segs'] if s['cat'] == cat], key=lambda g: g['start_us'])
+ for n, lane in enumerate(pack(items)):
+ tracks.append({'type': 'video', 'segments': lane})
+ layout.append(f'信息层 {cat}#{n + 1}: ' + ' | '.join(os.path.basename(g['source'])[5:-4] for g in lane))
+if man.get('voice'):
+ tracks.append({'type': 'audio', 'segments': [{'source': man['voice'], 'start_us': 0, 'duration_us': TOTAL, 'volume': 1.0}]})
+ layout.append('音频: 原声')
+sfx = []
+if a.sfx:
+ sfx = json.load(open(a.sfx, encoding='utf-8'))['items']
+ items = sorted([{'source': e['source'], 'start_us': e['at_us'], 'duration_us': e['duration_us'],
+ 'source_start_us': e['source_start_us'], 'source_duration_us': e['duration_us'], 'volume': e['volume']} for e in sfx],
+ key=lambda g: g['start_us'])
+ for lane in pack(items):
+ tracks.append({'type': 'audio', 'segments': lane})
+ layout.append(f'音效: {len(sfx)} 个')
+plan = {'schema': 'jy14-headless-plan/v1', 'name': a.name, 'canvas': {'width': CW, 'height': CH, 'fps': FPS}, 'tracks': tracks}
+json.dump(plan, open(a.out, 'w', encoding='utf-8'), ensure_ascii=False, indent=1)
+open(os.path.splitext(a.out)[0] + '_轨道说明.txt', 'w', encoding='utf-8').write('\n'.join(layout) + '\n')
+print(f"{a.out}:{len(tracks)} 轨(视频 {sum(t['type'] == 'video' for t in tracks)} / 音频 {sum(t['type'] == 'audio' for t in tracks)})")
+
+# ---------- 可选:ffmpeg 按同一 plan 合成预览(非剪映原生导出,只供快速看) ----------
+if a.preview:
+ def lin(kfs, st):
+ e = f"{kfs[-1]['value']}"
+ for p, q in reversed(list(zip(kfs, kfs[1:]))):
+ t0, t1 = st + p['at_us'] / 1e6, st + q['at_us'] / 1e6
+ e = f"if(lt(t,{t1:.4f}),{p['value']}+({q['value']}-{p['value']})*(t-{t0:.4f})/{t1 - t0:.4f},{e})"
+ return f"if(lt(t,{st + kfs[0]['at_us'] / 1e6:.4f}),{kfs[0]['value']},{e})"
+ probe = lambda f, k: int(subprocess.check_output(['ffprobe', '-v', 'error', '-show_entries', f'stream={k}', '-of', 'csv=p=0', f]).decode().split()[0])
+ inputs = ['-loop', '1', '-t', f'{TOTAL / 1e6:.3f}', '-i', man['paper']]; fc = [f'[0:v]format=rgba,scale={CW}:{CH}[b0]']; last, k = 'b0', 1
+ for t in tracks[1:]: # 严格按轨道顺序从下往上叠
+ if t['type'] != 'video': continue
+ for sg in t['segments']:
+ st, d = sg['start_us'] / 1e6, sg['duration_us'] / 1e6
+ if t['segments'] is person:
+ inputs += ['-itsoffset', f'{st:.3f}', '-i', sg['source']]
+ w0, h0 = probe(sg['source'], 'width'), probe(sg['source'], 'height'); f0 = fit(w0, h0); kf = sg.get('keyframes', {})
+ S = lin(kf['scale'], st) if 'scale' in kf else str(sg.get('scale', 1))
+ X = lin(kf['x'], st) if 'x' in kf else str(sg.get('x', 0))
+ Y = lin(kf['y'], st) if 'y' in kf else str(sg.get('y', 0))
+ fc.append(f"[{k}:v]scale=w='trunc({w0}*{f0}*({S})/2)*2':h='trunc({h0}*{f0}*({S})/2)*2':eval=frame[p{k}]")
+ fc.append(f"[{last}][p{k}]overlay=x='{CW / 2}+({X})*{CW / 2}-w/2':y='{CH / 2}-({Y})*{CH / 2}-h/2':eval=frame:enable='between(t,{st:.3f},{st + d - 0.001:.3f})'[v{k}]")
+ else:
+ inputs += ['-loop', '1', '-t', f'{st + d:.3f}', '-i', sg['source']]; f = f'[{k}:v]format=rgba'
+ op = sg.get('keyframes', {}).get('opacity', [])
+ if len(op) >= 2:
+ if op[0]['value'] == 0: f += f",fade=t=in:st={st:.3f}:d={op[1]['at_us'] / 1e6:.3f}:alpha=1"
+ if op[-1]['value'] == 0: f += f",fade=t=out:st={st + op[-2]['at_us'] / 1e6:.3f}:d={(op[-1]['at_us'] - op[-2]['at_us']) / 1e6:.3f}:alpha=1"
+ fc.append(f + f'[o{k}]'); fc.append(f"[{last}][o{k}]overlay=0:0:enable='between(t,{st:.3f},{st + d - 0.001:.3f})'[v{k}]")
+ last, k = f'v{k}', k + 1
+ amap = []
+ if man.get('voice'):
+ inputs += ['-i', man['voice']]; amap.append(f'[{k}:a]'); k += 1
+ for e in sfx:
+ inputs += ['-i', e['source']]
+ fc.append(f"[{k}:a]atrim=start={e['source_start_us'] / 1e6:.3f}:duration={e['duration_us'] / 1e6:.3f},asetpts=PTS-STARTPTS,"
+ f"volume={20 * math.log10(max(e['volume'], 1e-4)):.1f}dB,adelay={e['at_us'] // 1000}|{e['at_us'] // 1000}[a{k}]")
+ amap.append(f'[a{k}]'); k += 1
+ audio = []
+ if amap:
+ fc.append(''.join(amap) + f'amix=inputs={len(amap)}:normalize=0:duration=first[aout]'); audio = ['-map', '[aout]', '-c:a', 'aac', '-b:a', '192k']
+ subprocess.check_call(['ffmpeg', '-v', 'error', '-y', *inputs, '-filter_complex', ';'.join(fc), '-map', f'[{last}]', *audio,
+ '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '18', '-r', str(FPS), '-t', f'{TOTAL / 1e6:.3f}', a.preview])
+ print('预览(非剪映原生导出):', a.preview)
diff --git a/skill/seecut/scripts/preflight.sh b/skill/seecut/scripts/preflight.sh
new file mode 100644
index 0000000..1957f76
--- /dev/null
+++ b/skill/seecut/scripts/preflight.sh
@@ -0,0 +1,23 @@
+#!/bin/zsh
+# 开工预检:缺什么先报,别跑到一半才发现(总纲第11/15条)。用法: zsh preflight.sh [build目录]
+ok(){ print " ✓ $1"; }; bad(){ print " ✗ $1"; MISS=1; }; warn(){ print " ⚠ $1"; }
+print "=== SeeCut 预检 ==="
+command -v ffmpeg >/dev/null && ok ffmpeg || bad "ffmpeg(brew install ffmpeg)"
+if command -v node >/dev/null; then NV=$(node -v | sed 's/v//;s/\..*//'); [ "$NV" -ge 22 ] && ok "node $(node -v)" || bad "node $(node -v) 太旧(HyperFrames 要求 ≥ 22)"; else bad "node(≥ 22)"; fi
+python3 -c "import faster_whisper" 2>/dev/null && ok faster_whisper || bad "faster_whisper(pip install --user faster-whisper)"
+AGY=$(command -v agy || echo ~/.local/bin/agy); [ -x "$AGY" ] && ok "agy $($AGY --version 2>/dev/null | head -1)" || bad "agy(Antigravity CLI,见 README)"
+[ -n "$https_proxy$JIANJI_PROXY" ] && ok "代理 ${JIANJI_PROXY:-$https_proxy}" || warn "未设代理(agy/海外截图需要:export JIANJI_PROXY=http://127.0.0.1:1087)"
+ls ~/Library/Caches/ms-playwright/chromium_headless_shell-*/*/chrome-headless-shell >/dev/null 2>&1 && ok "无头 Chrome(ms-playwright 缓存)" || warn "无 ms-playwright headless shell(设 JIANJI_CHROME 指向现成 Chrome,别新下)"
+[ -n "$JIANJI_PROXY" ] && export HTTPS_PROXY=${HTTPS_PROXY:-$JIANJI_PROXY} HTTP_PROXY=${HTTP_PROXY:-$JIANJI_PROXY} # hyperframes CLI 只认大写
+if command -v hyperframes >/dev/null; then ok "hyperframes CLI(全局)"
+elif HV=$(perl -e 'alarm 60; exec @ARGV' npx -y hyperframes@latest --version 2>/dev/null); then ok "hyperframes CLI(npx,$HV)→ 用 npx -y hyperframes@latest catalog/add"
+else bad "hyperframes CLI 不可用(npx 也失败:查代理,需大写 HTTPS_PROXY)→ 官方组件库用不了,先修再开工"; fi
+JY=${JIANYING_HEADLESS_ROOT:-<未设置>}
+[ -f "$JY/engine/jy14_headless.py" ] && ok "剪映草稿引擎($JY)→ 交剪映分层草稿" || warn "没有剪映草稿引擎(可选,github.com/mcncarl/jianying-headless,非商业协议)→ 只交成片(带音效) + 分层工程包"
+SD=${JIANJI_SFX_DIR:-$HOME/Downloads/音效}
+[ -d "$SD" ] && ok "音效库 $SD($(ls "$SD" | wc -l | tr -d ' ') 个)" || warn "音效库 $SD 不存在 → 设 JIANJI_SFX_DIR;自己的库先跑 scripts/sfx_ledger.py 建台账"
+if [ -n "$1" ]; then
+ [ -f "$1/project.json" ] && ok "project.json" || bad "$1/project.json(配置契约见 references/07)"
+ node -e "require.resolve('playwright-core',{paths:['$1']})" 2>/dev/null && ok "playwright-core(工程目录)" || bad "playwright-core:cd $1 && npm i playwright-core(别 sudo)"
+fi
+[ -z "$MISS" ] && print "✅ 必需项齐全" || print "❌ 有必需项缺失,先装再开工(或报告用户)"
diff --git a/skill/seecut/scripts/render.mjs b/skill/seecut/scripts/render.mjs
new file mode 100644
index 0000000..2f50e9e
--- /dev/null
+++ b/skill/seecut/scripts/render.mjs
@@ -0,0 +1,37 @@
+// 逐帧渲染:人像 <img> 逐帧换 src(禁 video scrub)+ timeline.time(i/fps) 绝对 seek。带进度+看门狗。
+// 用法: node render.mjs <build目录> [full|probe] [probe帧号,逗号分隔]
+// 迭代版提速:RENDER_SCALE=0.5 node render.mjs build full → 半分辨率出帧(版式不变),终版不设(全分辨率)
+// 前置: <build>/project.json;ffmpeg -i 源片 -vf fps=<fps> -vsync cfr -q:v 3 -start_number 1 <build>/person/p%04d.jpg
+import fs from 'fs'; import path from 'path';
+import { loadProject, chromium, chromePath, watchdog } from './_common.mjs';
+const [,,buildDir,mode='probe',list]=process.argv;
+if(!buildDir){console.error('用法: node render.mjs <build目录> [full|probe] [帧号]');process.exit(2);}
+const P=loadProject(buildDir);
+const OUT=path.join(P.B, mode==='full'?'frames':'probe_frames'); fs.mkdirSync(OUT,{recursive:true});
+const frames = mode==='full' ? [...Array(P.N).keys()]
+ : (list ? list.split(',').map(Number) : [...Array(12).keys()].map(i=>Math.round((i+0.5)*P.N/12)));
+const pad=n=>String(n).padStart(4,'0');
+const PD=path.join(P.B,P.person_dir); const NP=fs.existsSync(PD)?fs.readdirSync(PD).filter(f=>/^p\d+\.jpg$/.test(f)).length:0;
+watchdog(mode==='full'?Math.max(900000,P.N*4000):120000,`render(${mode})`);
+let last=Date.now(); const st=setInterval(()=>{if(Date.now()-last>60000){console.error('⏰ 60s 无帧进展,退出');process.exit(4);}},15000); st.unref&&st.unref();
+const b=await chromium(P.B).launch({headless:true,executablePath:chromePath()});
+const SCALE=+(process.env.RENDER_SCALE||P.output_scale||1); // 终版=output_scale(源片宽/构图宽,如 1080/720=1.5);迭代版设 RENDER_SCALE=0.5
+const pg=await (await b.newContext({viewport:{width:P.width,height:P.height},deviceScaleFactor:SCALE})).newPage();
+const errs=[]; pg.on('console',m=>{if(m.type()==='error')errs.push(m.text());});
+await pg.goto('file://'+path.join(P.B,P.html),{waitUntil:'load',timeout:30000});
+await pg.evaluate(()=>document.fonts&&document.fonts.ready).catch(()=>{});
+await new Promise(r=>setTimeout(r,400));
+const gd=await pg.evaluate(n=>window.__timelines&&window.__timelines[n]?window.__timelines[n].duration():null,P.timeline);
+if(gd==null){console.error(`找不到 window.__timelines.${P.timeline}`);process.exit(2);}
+const dd=gd-P.duration;
+console.log(`${dd<-0.15?'⚠️ 动画比视频短(结尾会空)':dd>0.15?'ℹ️ 动画比视频长 '+dd.toFixed(2)+'s(尾部溢出,按绝对时间取帧不影响画面;若是循环动画撑长要查)':'✓ 时长'}: GSAP=${gd.toFixed(2)}s 视频=${P.duration}s;人像帧 ${NP};输出 ${frames.length} 帧 ×${SCALE} → ${OUT}`);
+for(const i of frames){
+ const psrc=NP?'file://'+path.join(PD,'p'+pad(Math.min(i+1,NP))+'.jpg'):null;
+ await pg.evaluate(async({t,psrc,tl,pid})=>{window.__timelines[tl].time(t);
+ const im=document.getElementById(pid); if(im&&psrc){im.src=psrc; try{await im.decode();}catch(e){}}},
+ {t:i/P.fps,psrc,tl:P.timeline,pid:P.person_img_id});
+ await pg.screenshot({path:path.join(OUT,`f${pad(i)}.png`)}); last=Date.now();
+ if(mode==='full'&&i%50===0) console.log(` ${i}/${P.N} ${new Date().toLocaleTimeString()}`);
+}
+if(errs.length) console.log('页面报错:',errs.slice(0,5));
+console.log('DONE',new Date().toLocaleTimeString()); await b.close(); process.exit(0);
diff --git a/skill/seecut/scripts/schemas/check.json b/skill/seecut/scripts/schemas/check.json
new file mode 100644
index 0000000..2e3c4df
--- /dev/null
+++ b/skill/seecut/scripts/schemas/check.json
@@ -0,0 +1,4 @@
+{"type":"object","required":["fingerprint","checks","evidence_gaps"],"properties":{
+"fingerprint":{"type":"object","required":["texts","duration_sec"],"properties":{"texts":{"type":"array","items":{"type":"string"}},"duration_sec":{"type":"number"}}},
+"checks":{"type":"array","items":{"type":"object","required":["id","pass","evidence"],"properties":{"id":{"type":"string"},"pass":{"type":"boolean"},"evidence":{"type":"string"}}}},
+"evidence_gaps":{"type":"array","items":{"type":"object","required":["time","phrase","suggested_evidence"],"properties":{"time":{"type":"string"},"phrase":{"type":"string"},"suggested_evidence":{"type":"string"}}}}}}
diff --git a/skill/seecut/scripts/schemas/pair.json b/skill/seecut/scripts/schemas/pair.json
new file mode 100644
index 0000000..bc23d16
--- /dev/null
+++ b/skill/seecut/scripts/schemas/pair.json
@@ -0,0 +1,4 @@
+{"type":"object","required":["fingerprint","dimensions","winner","confidence","reason"],"properties":{
+"fingerprint":{"type":"object","required":["X_texts","Y_texts","X_duration_sec","Y_duration_sec"],"properties":{"X_texts":{"type":"array","items":{"type":"string"}},"Y_texts":{"type":"array","items":{"type":"string"}},"X_duration_sec":{"type":"number"},"Y_duration_sec":{"type":"number"}}},
+"dimensions":{"type":"array","items":{"type":"object","required":["name","better","evidence"],"properties":{"name":{"type":"string"},"better":{"type":"string","enum":["X","Y","平手"]},"evidence":{"type":"string"}}}},
+"winner":{"type":"string","enum":["X","Y"]},"confidence":{"type":"integer","minimum":1,"maximum":5},"reason":{"type":"string"}}}
diff --git a/skill/seecut/scripts/sfx.py b/skill/seecut/scripts/sfx.py
new file mode 100644
index 0000000..1a124da
--- /dev/null
+++ b/skill/seecut/scripts/sfx.py
@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""音效:选点 → 算对齐/裁剪/音量 → 检查 → 混进成片(同一份 sfx_plan 也喂给 jianying_plan.py 进剪映草稿)。
+
+1) 计划:python3 sfx.py plan --choices sfx_choices.json --voice 原声或成片.mp4 [--words seg_words.json] --out sfx_plan.json
+ sfx_choices.json = 执行窗按 references/09-音效规范 挑的落点:
+ [{"t": 4.40, "kind": "impact", "sfx": "咚-重击.mp3", "why": "割韭菜印章落地", "gain_db": -3}, ...] (gain_db 可选)
+ t = 画面事件时刻(元素出现帧,取自 layers/manifest.json 的 events 或 GSAP 时间轴)
+ kind ∈ hook(开头抓耳) / pop(弹出) / whoosh(滑入换幕缩窗) / impact(砸下落定) / ding(要点完成) /
+ click(按键点选) / page(翻页换图) / error(红叉翻车) / correct(对勾) / money(钱) / other
+2) 混音:python3 sfx.py mix --plan sfx_plan.json --video 成片.mp4 --out 成片_带音效.mp4
+音效文件:<skill>/references/sfx/音效库台账.json 里的文件名,到 $JIANJI_SFX_DIR(默认 ~/Downloads/音效)下找。
+"""
+import argparse, json, math, os, re, subprocess, sys
+
+SKILL = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+LEDGER = os.path.join(SKILL, 'references/sfx/音效库台账.json') # 默认台账;用户自己的库用 sfx_ledger.py 生成后 --ledger 指过来
+SFX_DIR = os.path.expanduser(os.environ.get('JIANJI_SFX_DIR', '~/Downloads/音效'))
+# 声音起点相对画面事件的偏移(2-4.1 实测):砸下类要等弹簧落地那帧;whoosh 要跨过切点
+OFFSET = {'impact': 0.12, 'whoosh': -0.08}
+# 目标峰值(相对人声峰值,dB):压在人声下面(2-4.1 实配 -16~-11)
+TARGET = {'hook': -12, 'impact': -12, 'error': -14, 'page': -14, 'whoosh': -15, 'pop': -16, 'ding': -16,
+ 'click': -15, 'correct': -15, 'money': -14, 'other': -15}
+LOW_FREQ = {'impact'} # 低频重击压在关键词上会"吃字"
+
+
+def peak_db(path, start=0.0, dur=None):
+ cmd = ['ffmpeg', '-hide_banner', '-ss', f'{start:.3f}', '-i', path]
+ if dur: cmd += ['-t', f'{dur:.3f}']
+ out = subprocess.run(cmd + ['-af', 'volumedetect', '-f', 'null', '-'], capture_output=True, text=True).stderr
+ m = re.search(r'max_volume: (-?[\d.]+) dB', out)
+ return float(m.group(1)) if m else -20.0
+
+
+def cmd_plan(a):
+ lp = a.ledger or LEDGER
+ if not os.path.exists(lp):
+ sys.exit('没有音效台账:先用 scripts/sfx_ledger.py <你的音效文件夹> --out 台账.json 建一份,再加 --ledger 台账.json --sfx-dir <文件夹>')
+ led = {r['file']: r for r in json.load(open(lp, encoding='utf-8'))}
+ sfx_dir = os.path.expanduser(a.sfx_dir or SFX_DIR)
+ choices = json.load(open(a.choices, encoding='utf-8'))
+ fps = a.fps
+ vpk = peak_db(a.voice)
+ words = []
+ if a.words:
+ w = json.load(open(a.words, encoding='utf-8'))
+ if isinstance(w, dict) and 'segments' in w: # faster_whisper 分段格式
+ w = [x for sg in w['segments'] for x in sg.get('words', [])]
+ elif isinstance(w, dict):
+ w = w.get('words', [])
+ for x in w:
+ if isinstance(x, dict) and 'start' in x and 'end' in x:
+ words.append((float(x['start']), float(x['end']), x.get('word', x.get('text', ''))))
+ items, warns = [], []
+ for c in sorted(choices, key=lambda c: c['t']):
+ r = led.get(c['sfx'])
+ if not r:
+ sys.exit(f"台账里没有 {c['sfx']}(文件名要和 references/sfx/音效库台账.json 一致)")
+ src = os.path.join(sfx_dir, r['file'])
+ kind = c.get('kind', 'other')
+ t = c['t'] + OFFSET.get(kind, 0.0)
+ t = math.ceil(round(t * fps, 6)) / fps # 向上取整到帧:声音不能早于画面
+ trim = float(r['trim_start'])
+ dur = min(float(r.get('first_hit_len') or r['duration']), 0.8 if kind != 'hook' else 1.5, float(r['duration']) - trim - 0.02)
+ if dur <= 0.05:
+ sys.exit(f"{r['file']} 起音点后几乎没有声音,换一个")
+ gain_db = TARGET.get(kind, -15) + vpk - peak_db(src, trim, dur) + float(c.get('gain_db', 0)) # choices 可写 gain_db 单条微调(如 -3 避让口播)
+ vol = round(min(1.0, 10 ** (gain_db / 20)), 3)
+ if kind in LOW_FREQ and float(c.get('gain_db', 0)) > -3:
+ hit = [(ws, we, wd) for ws, we, wd in words if ws - 0.05 <= t <= we + 0.05]
+ if hit:
+ we = max(h[1] for h in hit)
+ warns.append(f"{t:.2f}s 的 {r['file']}(低频重击)压在口播「{''.join(h[2] for h in hit)}」上 → 挪到词说完 {math.ceil(we * fps) / fps:.2f}s,或降 3dB")
+ if r.get('koubo_use') == '慎用':
+ warns.append(f"{t:.2f}s 用了慎用音效 {r['file']}:确认语义特别贴,一条片最多 1 次")
+ items.append({'at_us': int(round(t * 1e6)), 't': round(t, 3), 'event_t': c['t'], 'kind': kind, 'why': c.get('why', ''),
+ 'source': src, 'source_start_us': int(round(trim * 1e6)), 'duration_us': int(round(dur * 1e6)), 'volume': vol})
+ # 检查:开头抓耳 / 密度 / 重复
+ ts = [i['t'] for i in items if i['kind'] != 'hook'] # 开头抓耳音效不计入密度(作者要求开头必须有)
+ if not any(i['t'] <= 0.5 for i in items):
+ warns.append('开头 0.5 秒内没有音效:总纲要求开头给一个醒目的音效(kind=hook,如 叮当声/叮叮_/重磅出场)')
+ for i, t in enumerate(ts):
+ win = [x for x in ts if t <= x < t + 3.0]
+ if len(win) > 2:
+ warns.append(f'{t:.2f}-{t + 3:.2f}s 有 {len(win)} 个音效,超过"任意 3 秒最多 2 个" → 删掉意义最弱的'); break
+ total = a.duration or (max(ts) + 1 if ts else 1)
+ if ts and len(ts) / total > 0.7:
+ warns.append(f'全片 {len(ts)} 个 / {total:.1f}s = {len(ts) / total:.2f} 个每秒,超过 0.7')
+ from collections import Counter
+ for f, n in Counter(os.path.basename(i['source']) for i in items).items():
+ if n > 2: warns.append(f'{f} 用了 {n} 次(>2 次易单调,换一个同类)')
+ json.dump({'voice_peak_db': vpk, 'items': items, 'warnings': warns}, open(a.out, 'w', encoding='utf-8'), ensure_ascii=False, indent=1)
+ print(f'{len(items)} 个音效 → {a.out}')
+ for w in warns: print(' ⚠', w)
+ if not warns: print(' ✓ 检查全过(开头抓耳 / 密度 / 关键词避让 / 重复)')
+
+
+def cmd_mix(a):
+ plan = json.load(open(a.plan, encoding='utf-8'))['items']
+ inputs, fc, labels = ['-i', a.video], [], ['[0:a]']
+ for k, e in enumerate(plan, 1):
+ inputs += ['-i', e['source']]
+ fc.append(f"[{k}:a]atrim=start={e['source_start_us'] / 1e6:.3f}:duration={e['duration_us'] / 1e6:.3f},asetpts=PTS-STARTPTS,"
+ f"volume={e['volume']},adelay={e['at_us'] // 1000}|{e['at_us'] // 1000}[s{k}]")
+ labels.append(f'[s{k}]')
+ fc.append(''.join(labels) + f'amix=inputs={len(labels)}:normalize=0:duration=first[aout]')
+ subprocess.check_call(['ffmpeg', '-v', 'error', '-y', *inputs, '-filter_complex', ';'.join(fc), '-map', '0:v', '-map', '[aout]',
+ '-c:v', 'copy', '-c:a', 'aac', '-b:a', '192k', a.out])
+ print('带音效成片:', a.out)
+
+
+ap = argparse.ArgumentParser(); sub = ap.add_subparsers(dest='cmd', required=True)
+p = sub.add_parser('plan'); p.add_argument('--choices', required=True); p.add_argument('--voice', required=True)
+p.add_argument('--words'); p.add_argument('--out', required=True); p.add_argument('--ledger'); p.add_argument('--sfx-dir'); p.add_argument('--fps', type=float, required=True); p.add_argument('--duration', type=float)
+m = sub.add_parser('mix'); m.add_argument('--plan', required=True); m.add_argument('--video', required=True); m.add_argument('--out', required=True)
+a = ap.parse_args()
+cmd_plan(a) if a.cmd == 'plan' else cmd_mix(a)
diff --git a/skill/seecut/scripts/sfx_ledger.py b/skill/seecut/scripts/sfx_ledger.py
new file mode 100644
index 0000000..5fc94b4
--- /dev/null
+++ b/skill/seecut/scripts/sfx_ledger.py
@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""给任意本地音效库建台账(开放给用户:用自己的音效,不用我们的)。
+用法: python3 sfx_ledger.py <音效文件夹> --out <台账.json> [--listen]
+ 自动实测(免费、确定性):时长、起音点 trim_start(能量包络首次到峰值 10%)、第一下长度 first_hit_len、共几下 hits。
+ --listen:再用 agy(Gemini 能听音频)逐个听,补 类别/听感/适合配什么/口播适用度(4 路并行;只信音色描述,时间一律用实测)。
+ 不加 --listen 时,类别按文件名关键词猜(唰/转场→whoosh、叮→ding、咚/重击→impact、翻页→page、点击/咔→click、错误→error、正确→correct、金币/到账→money、出现/弹→pop),猜不到记 other,建议人工或 --listen 补。
+然后:sfx.py plan --ledger <台账.json> --sfx-dir <音效文件夹> ...
+"""
+import argparse, json, os, re, subprocess, sys
+from concurrent.futures import ThreadPoolExecutor
+
+EXT = ('.mp3', '.wav', '.m4a', '.aac', '.ogg', '.flac')
+GUESS = [('whoosh', '唰|转场|whoosh|swoosh|swish'), ('ding', '叮|ding|ping|bell|铃'), ('impact', '咚|重击|重磅|boom|hit|impact|拳'),
+ ('page', '翻页|page|flip'), ('click', '点击|咔|click|key|按键'), ('error', '错误|error|wrong|fail'),
+ ('correct', '正确|correct|success'), ('money', '金币|到账|收银|coin|cash|money'), ('pop', '出现|弹|pop|bubble|字幕')]
+
+
+def pcm(path, sr=16000):
+ import numpy as np
+ raw = subprocess.run(['ffmpeg', '-v', 'error', '-i', path, '-ac', '1', '-ar', str(sr), '-f', 'f32le', '-'], capture_output=True).stdout
+ return np.abs(np.frombuffer(raw, dtype=np.float32)), sr
+
+
+def measure(path):
+ import numpy as np
+ a, sr = pcm(path)
+ if not len(a):
+ return None
+ w = max(1, sr // 100) # 10ms 包络
+ env = np.convolve(a, np.ones(w) / w, 'same'); pk = env.max() or 1e-9
+ on = env >= pk * 0.10
+ trim = int(np.argmax(on)) / sr
+ # 分段:有声段之间静音 ≥0.15s 算新的一下
+ segs, i, n, gap = [], 0, len(on), int(0.15 * sr)
+ while i < n:
+ if not on[i]: i += 1; continue
+ j = i
+ while j < n:
+ k = j
+ while k < n and not on[k]: k += 1
+ if k - j >= gap or k >= n: break
+ j = k + 1
+ while j < n and on[j]: j += 1
+ segs.append((i / sr, j / sr)); i = j + 1
+ return {'duration': round(len(a) / sr, 3), 'trim_start': round(trim, 3),
+ 'first_hit_len': round(segs[0][1] - segs[0][0], 3) if segs else round(len(a) / sr - trim, 3), 'hits': len(segs) or 1}
+
+
+def guess(name):
+ for cat, pat in GUESS:
+ if re.search(pat, name, re.I): return cat
+ return 'other'
+
+
+def listen(path):
+ skill = os.path.dirname(os.path.abspath(__file__))
+ q = ('这是短视频剪辑用的一个音效文件。只输出一行 JSON(不要其它文字):{"听感":"一句话描述音色","类别":"从[pop/whoosh/impact/ding/page/click/error/correct/money/hook/梗/氛围/other]选一",'
+ '"适合配":["2-3个画面动作"],"口播科普适用度":"常用/偶尔/慎用"}')
+ try:
+ out = subprocess.run(['zsh', os.path.join(skill, 'agy_read.sh'), path, q, '180'], capture_output=True, text=True, timeout=260).stdout
+ m = re.search(r'\{.*"听感".*\}', out, re.S)
+ return json.loads(m.group(0)) if m else {}
+ except Exception:
+ return {}
+
+
+ap = argparse.ArgumentParser(); ap.add_argument('dir'); ap.add_argument('--out', required=True); ap.add_argument('--listen', action='store_true')
+a = ap.parse_args()
+files = sorted(f for f in os.listdir(a.dir) if f.lower().endswith(EXT))
+if not files: sys.exit(f'{a.dir} 里没有音频文件')
+rows = []
+for f in files:
+ m = measure(os.path.join(a.dir, f))
+ if m: rows.append({'file': f, **m, 'category': guess(f), 'koubo_use': '偶尔', 'desc': ''})
+if a.listen:
+ with ThreadPoolExecutor(4) as ex:
+ for r, d in zip(rows, ex.map(lambda r: listen(os.path.join(a.dir, r['file'])), rows)):
+ if d:
+ r['desc'] = d.get('听感', ''); r['fits'] = d.get('适合配', []); r['koubo_use'] = d.get('口播科普适用度', r['koubo_use'])
+ if r['category'] == 'other' and d.get('类别'): r['category'] = d['类别']
+json.dump(rows, open(a.out, 'w', encoding='utf-8'), ensure_ascii=False, indent=1)
+from collections import Counter
+print(f'{len(rows)} 个音效 → {a.out};类别:{dict(Counter(r["category"] for r in rows))};有 {sum(r["hits"] > 1 for r in rows)} 个不止一下(只取第一下)')