@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/git-story-film/references/production.md

@@ -1,150 +0,0 @@
-# Production: project layout, rendering, delivery
-
-## Contents
-1. Project layout and git
-2. Preview loop
-3. Streaming 4K delivery
-4. Sound
-5. Pitfalls seen in practice
-6. Samples, teasers and short cuts
-
-## 1. Project layout and git
-
-Work in a folder **outside** the product repository (a repo's own rules often
-forbid HTML/video assets). Copy the engine and example in, then `npm i`.
-
-```
-<film>/
-  core.js studio-ui.js studio.js cels.js materials.js   engine (MIT, keep LICENSE file)
-  render.mjs package.json                  preview renderer (+ puppeteer-core)
-  render-hq.mjs frames.mjs                 from this skill's scripts/
-  fonts/                                   OFL faces + licence files + README
-  OUTLINE.md       outline: story direction, then the whole film
-  cast-sheet.html  character: expressions and actions
-  shots.json       shot list       storyboard/  storyboard page + stills
-  shots.js         shot data for the studio (storyboard.py --js)
-  <name>-cast.js   the protagonist          <name>-world.js  page, marks, writer
-  <name>-*.js      the acts (the raven: -route.js act I, -flight.js acts II+ and ending)
-  <name>-score.js  synthesized score        <name>.html      the film; opens as the studio
-  out/             renders (gitignored)
-```
-
-The film HTML loads `studio-ui.js` right after `core.js`, so opening it in a
-browser gives the studio (`directing.md` §6). The render scripts load it with
-`?bare`, which skips the player entirely.
-
-`.gitignore`: `node_modules/`, `out/`, `.DS_Store`. Commit when the user asks;
-keep languages on branches (e.g. `main` = Chinese, `feat/english_version`)
-and merge fixes from `main` into the language branch.
-
-`defineFilm` in the bundled `core.js` accepts fps 12, 24 or 60 (60 was added
-for delivery; drawings stay on 24/12). The film reads `?fps=` from the URL
-(the example accepts 12/24/60 and falls back to 24), so the same file previews
-at 24 and delivers at 60. `render-hq.mjs --fps N` sets that parameter;
-`engine/render.mjs` (previews) only knows 12 and 24 and never passes `?fps=`,
-so do all preview work at 24.
-
-Name collisions: the engine defines globals (`S`, `W`, `H`, `CX`, `CY`, `key`,
-`arc`, `hash`, `spring`...). A film-level `const S = ...` throws at load and
-the renderer waits forever. Use distinctive names (`ST`, `T2`).
-
-## 2. Preview loop
-
-From the film folder:
-
-```bash
-node frames.mjs film.html load                         # errors? frame count?
-node render.mjs film.html --grid 60 --width 960 --out out/preview   # overview sheet
-node render.mjs film.html --only 96,1300 --out out/preview           # full-size stills
-node render.mjs film.html --strip 618,24 --width 1280 --out out/preview  # consecutive frames
-node frames.mjs film.html shots 12.5,44,96             # stills at seconds
-node frames.mjs film.html score                        # audio levels per second
-```
-
-Look at the overview after every structural change, full-size stills after
-every text or layout change, strips around fast action and every hand-over.
-A still that is blank except the background means something threw or a
-drawing budget was blown; check with `frames.mjs load`.
-
-These are for your own checks. The user reviews in two places: the storyboard
-page (`scripts/storyboard.py`, `directing.md` §4) before the animation, and
-the studio (`directing.md` §6) once the film is animated. No render happens
-until the user approves the film in the studio.
-
-## 3. Streaming 4K delivery
-
-```bash
-node render-hq.mjs film.html --width 3840 --fps 60 --workers 4 --out out
-```
-
-Parallel headless Chrome workers each render a stretch of frames and pipe PNGs
-straight into ffmpeg (no frames on disk: 4K×7,000 PNGs would be >100 GB).
-Segments are joined losslessly, the score is muxed in. The closing frame is
-also written once at the start, so players and feeds use it as the cover; the
-audio is delayed by that frame. `--no-cover` disables it; `--param k=v` passes
-URL parameters (e.g. a font trial).
-
-Throughput on a 12-core Mac: ~25 frames/s at 4K, so a 2-minute 60 fps film is
-~5–6 minutes. Verify every delivery:
-
-```bash
-ffprobe -v error -show_entries format=duration,size:stream=width,height,r_frame_rate,nb_frames -of compact out/x.mp4
-ffmpeg -v error -i out/x.mp4 -f null - && echo decode OK
-```
-
-Report duration, resolution, fps, size and "decode OK". A decode pass is not
-a viewing: say what you actually looked at.
-
-ffmpeg may be installed but not on the non-interactive PATH; export
-`/opt/homebrew/bin` before calling it.
-
-## 4. Sound
-
-The score is Web Audio on the same timeline (`<name>-score.js`), rendered
-offline by the page. Place every cue from the route data (hop landings,
-reveals), never from hard-coded seconds, so a timing change cannot desync it.
-Pencil scratches and sparse piano for sketches, a pad when the ink arrives,
-a tick per landing, a short chord per stamp.
-
-Check levels: peak under ~0.8, quiet stretches still audible. Put gain after
-a compressor rather than raising the master into clipping. You cannot hear
-the result: tell the user the levels were measured but not listened to.
-
-## 5. Pitfalls seen in practice
-
-- **Two renders at once**: two 4-worker renders on one machine crashed a
-  Chrome worker ("Target closed"). Queue renders; one at a time.
-- **Stopping a render**: kill both the node process and ffmpeg, then delete
-  `out/.<name>-*` staging folders and any half-written mp4.
-- **Background waits**: a wait loop that checks one file name can hang when a
-  rename step never runs; check the log for the finish line and the process.
-- **Rendering while switching branches**: a script that checks out branches
-  in the working folder must not overlap with edits; use `git worktree` for
-  side experiments.
-- **Apostrophes** in single-quoted JS strings break the whole file.
-- **A frame counter's `S`/`T` shadowing** globals: see project layout.
-- **A still that looks right can hide a timing bug**: pops at hand-overs and
-  stutter only show in strips or playback.
-
-## 6. Samples, teasers and short cuts
-
-The first-look preview is the 30-second storyboard page, and the animated
-preview is the studio, so a sample MP4 is only needed when the user wants a
-file to share early. The example's act I (`raven-route.js`) is not a
-standalone film: the feature card (`featureCard`), dates and the camera's
-extended route live in `raven-flight.js`. For a sample, keep every script
-loaded and shorten the
-`TIMELINE` array in the film HTML to the segments you want (and end the score
-there). Nothing else changes, and the sample stays frame-identical to the
-final film.
-
-For a teaser that plays the same story faster, map output time to story time
-(`story = start + (t - start) * k`) in one wrapper, and run the score's cue
-times through the same map. Quantize poses on the *output* clock after the
-map, not on the story clock, or a 1.45× speed-up exposes drawings for odd
-frame counts. Hops shorter than ~8 frames stop reading as hops: shorten the
-walk instead of speeding it up past that.
-
-To leave out the ending, drop its segments from `TIMELINE`; `render-hq.mjs`
-then uses the new last frame as the cover, which is usually a mid-flight frame:
-pass `--no-cover`.

package/skills/git-story-film/references/story.md

@@ -1,137 +0,0 @@
-# Turning a repository into a story
-
-The film is for people who have never used the project. Its job is to answer
-"what can this do for me?", told as the project growing up. The git history
-supplies the order and the proof; the user's product pitch supplies the point.
-How the growth is staged (a journey, something growing, a machine being
-built...) is the form, covered in `forms.md`. This file covers what every form
-needs.
-
-## Contents
-1. Gather evidence (data)
-2. The arc: setup, development, turning point and resolution
-3. Choosing beats
-4. Recurring devices
-5. Acts and looks
-6. Claims you must not overstate
-
-## 1. Gather evidence (data)
-
-Run `scripts/git_timeline.py <repo>` and read the README's feature sections
-and docs site. Collect:
-
-- first commit, public launch/first release, latest release, busiest day;
-- `feat`/`perf` commits and PR numbers as candidate beats;
-- reverts: a revert makes a good early setback;
-- the product's own vocabulary (e.g. "The Harness of Harnesses", agent names).
-
-Cite real hashes and PR numbers on screen. Never invent a commit, a
-contributor count or a benchmark number. If you show an illustrative score
-(A 66, B 81), say so in the storyboard notes.
-
-Author counts are unreliable: one person often appears under several names.
-Prefer "1,686 commits" over "39 hands".
-
-Selecting is the director's main job with data. Two minutes holds about 20
-beats out of thousands of commits. Write down what you left out and why, so
-the user can overrule it.
-
-## 2. The arc: setup, development, turning point and resolution
-
-A timeline is not a story until something is at stake. Shape the history into
-four movements, and name the commits each one rests on:
-
-| | What it does | Typical git material |
-|---|---|---|
-| Setup | who the protagonist is, the problem, the first line | first commit, init, the README's first promise |
-| Development | abilities arrive one by one; each shows the viewer a use | `feat` commits, the first release, integrations |
-| Turning point | the pressure peaks: something breaks, gets rebuilt or changes direction | reverts, rewrites, the busiest day, a pivot, the hero feature's hard part |
-| Resolution | where it has landed and what it means for the viewer now | latest release, the overview, the closing card |
-
-Early commits make better comedy than features (hatching, a stranger's note,
-a revert as a fall); use them in the setup. Give the turning point the most screen time after the
-hero feature. The ending should pay off something set up in the first 20
-seconds (a keepsake dropped, a first line becoming the signature).
-
-The raven film ended in three moves, and most forms can adapt them:
-1. Pull back over the whole history: the commit tokens in their real daily
-   counts.
-2. A signature written by the protagonist (e.g. "Made by Raven, / made for
-   you.").
-3. A closing card: product name, tagline, the protagonist peeking over the
-   name and blinking, and a hand-drawn search box that types the repo URL
-   beside the official GitHub mark. This frame is also the video's cover
-   (`production.md` §3).
-
-## 3. Choosing beats
-
-Aim for ~20 beats in two minutes (4–6 s each, longer for the hero feature).
-For each beat decide: the feature card text, what the viewer sees, the line
-the protagonist says, and the commit it rests on.
-
-Prefer features a newcomer can picture. From the raven film:
-
-1. The orchestration / "one request becomes a task graph" idea, shown as a
-   real request split among helpers ("research three rivals, write a scraper,
-   watch it overnight, make a deck"). Threading one request through several
-   beats makes the built-in agents understandable.
-2. Each built-in agent gets its own small visual payoff (sources, "12 tests
-   passed ✓", a night shift ending at dawn, three slides).
-3. Third-party agents joining: named birds with name tags. Use only names the
-   project actually supports (check presets/docs).
-4. The hero feature (here: self-evolution) gets the most time and a process
-   the viewer can follow: gates, candidates, scores, "kept", "next round".
-5. Memory, skills on demand, import, reminders, playbooks, upgrades without
-   restart: one visual gag each.
-
-## 4. Recurring devices
-
-Every form needs a few devices that carry the data and hold the film
-together. Find this form's equivalent of each:
-
-| Device | Job | In the raven journey |
-|---|---|---|
-| The time axis | where "now" is | the branch, drawn solid up to today and faint dashed beyond; new segments are drawn as the raven arrives |
-| Commit token | one unit per commit, real daily counts | shiny beads hung under their day (ravens hoard shiny things) |
-| Margin notes | the proof | handwritten hash / PR number with an arrow, pinned to the page so they scroll away |
-| Feature card (top right) | the product speaking | big: feature name; small: what it does for the viewer; tiny: date and running commit count; holds until the next feature so it can be read |
-| A keepsake | set up early, paid off at a milestone | the eggshell hat, dropped at v0.1.0 |
-
-In other forms the token might be a leaf, a brick, a coin or a stamp in a
-diary. Keep one token per commit either way.
-
-Captions (top left) are the protagonist speaking, in the first person unless
-the outline chose a narrator. The card is the product speaking. Keep them
-different.
-
-## 5. Acts and looks
-
-A look changes at an important commit (a seam in a journey, a season in
-growth, a new level) and needs a story reason. The raven film:
-
-| Act | Material | Reason |
-|---|---|---|
-| Draft days | pencil | the first commits are a sketch |
-| Going public | ink | open source is permanent; the wash inks the mascot |
-| The hero feature | riso print | many proof prints, pick the best |
-| Working with others | screen print | flat colours tell the helpers apart |
-| Rebuilding internals | blueprint | skeleton and structure |
-| Everything together | mixed | all materials in one sky |
-
-The look family can be something else entirely: pixel art for a levels film
-(`craft.md` §8), cut paper, chalk on a blackboard, a watercolour diary. The
-rule stays the same: every change sits on a commit and has a reason the viewer
-could say out loud.
-
-## 6. Claims you must not overstate
-
-Read the docs for each feature you show. Typical traps:
-
-- A development-time tool (e.g. a benchmark-driven evolver) is not the product
-  "rewriting itself while you chat". "I can swap out my own feathers" is fine;
-  implying runtime self-modification is not.
-- Only list integrations and channels the code actually has (check the channel
-  adapters before saying "find me in Slack").
-- Illustrative numbers must be marked as illustrative in the storyboard.
-
-Flag these to the user in your summary rather than silently softening them.

package/skills/git-story-film/references/text-and-fonts.md

@@ -1,90 +0,0 @@
-# Text, languages and fonts
-
-## Fonts: licence first
-
-System fonts are licensed for use on that computer, not for rendering into a
-published video. macOS's Chinese handwriting faces (Hannotate/手札体,
-HanziPen/翩翩体, Libian...) belong to commercial foundries (DynaComware etc.).
-Read the font's `name` table copyright before using any face you did not
-download yourself.
-
-Use SIL OFL 1.1 faces, bundled in `fonts/` with their licence files, loaded
-with `FontFace` before the first frame. Bundling also makes every machine
-render identical pixels. `scripts/fetch_fonts.sh <dir> <zh> <en>` downloads a
-set with licences.
-
-Tested choices:
-
-| Use | Face | Notes |
-|---|---|---|
-| Chinese (default) | LXGW WenKai 霞鹜文楷 | calm, legible handwriting-kaishu; the user's final pick |
-| Chinese, playful | Xiaolai 小赖, ZCOOL KuaiLe 站酷快乐体 | cartoonish; wider set |
-| Chinese, avoid | brush/running-script faces | fight the cartoon style |
-| English (default) | Comic Neue (Bold for 600) | upright, reads as handwriting; the user's final pick |
-| English, alternatives | Patrick Hand, Short Stack, Architects Daughter | upright |
-| English, avoid | Caveat, Kalam | the slant was rejected as too italic for captions |
-
-Only list faces in the loader that `fonts/` actually contains: a face that fails
-to load stops the film from ever becoming ready (`frames.mjs load` reports it).
-
-Render a sample sheet with the film's real copy before committing to a face.
-
-Font stack per language:
-- Chinese cut: `"LXGW WenKai", ...`: digits and Latin in the same face, so a
-  date never switches to a slanted script mid-line.
-- English cut: `"Comic Neue", "LXGW WenKai", ...`.
-
-Declare a weight range on each `FontFace` so asking for 600 never triggers
-synthetic bold. If a Latin face runs small next to CJK, use `sizeAdjust`.
-
-## The letter-by-letter writer
-
-Captions appear one character at a time (`writeOn` in
-`examples/raven-story/raven-world.js`). Three bugs it already fixes, keep them fixed:
-
-1. The handwriting face's space is a hairline, so "调度所有 Agent 的 Agent"
-   loses its gaps. Give spaces a minimum advance (a third of the size) and
-   lay out with the same advance.
-2. Set `textAlign = 'left'` inside the writer; an inherited `center` shifts
-   every glyph.
-3. Multiply by the context's current `globalAlpha`, or group fades leave
-   ghost text.
-
-## Copy rules
-
-- One caption voice per film, chosen in the outline: usually the protagonist
-  in the first person, in short sentences, talking to a newcomer. A narrator
-  works too, but don't switch voices mid-film. The feature card is the product
-  speaking and is the only other voice.
-- Chinese: put a space between Chinese and Latin/digits (`多 Agent 编排`,
-  `累计 1,686 次提交`); dates as `6月28日`.
-- English: write it as a native speaker would say it, never a literal
-  translation. Read every line aloud. Examples of fixes the user asked for:
-  - "I'm a raven called Raven" / "Yes, I'm a raven" → both rejected; the
-    second sentence should say something new: "Hi, I'm Raven. Let me show you
-    how I hatched."
-  - "Every commit is one more" → "Each commit is one more for the pile."
-  - "Made By Raven, Made For You." → "Made by Raven, / made for you."
-- Localize, don't transliterate: WeChat in the Chinese cut became Slack in the
-  English cut (only because the product has a Slack channel).
-- Product names keep their official casing ("The Harness of Harnesses";
-  the closing card may use lowercase "the harness of harnesses" if the user
-  wants it). Check with the README.
-- No CJK punctuation in English strings (、，…). Apostrophes in JS strings:
-  use double quotes for "I'm", "don't", "it's".
-- Dates in English: `Jun 28`; counts: `1,686 commits so far`.
-
-## Layout checks after any text change
-
-Longer English lines and wider fonts collide with the feature card, labels
-and birds. After changing copy or font, render full-size stills of every
-text-heavy beat (`node frames.mjs film.html shots <seconds>`, 1920 wide by
-default) and look for:
-
-- caption vs feature card (top-left vs top-right on long lines);
-- caption vs a material seam or its label, and caption vs a raised wing;
-- margin note vs margin note when two stops are close (fade the older one out
-  before the next arrives);
-- labels vs captions (scores, "current me", task pills);
-- text running out of a box (gate plaques, request note, name tags);
-- the date line under the feature card vs the card's subtitle.

package/skills/guizang-product-video-skill/SKILL.md

@@ -1,96 +0,0 @@
----
-name: guizang-product-video-skill
-description: "制作代码驱动的软件产品宣传片和版本更新片（product promo、release notes video、changelog promo）。从真实功能和产品设计出发定方向，用真实组件、GSAP/Three.js 动效、原创配乐和动作音效完成影片，每支片子的视觉手法都从产品本身推导，不套模板。 Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "op7418/guizang-product-video-skill"
----
-
-# 归藏 product video skill
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-用真实组件讲清楚一个软件产品或一次更新，让画面、文案和声音一起推进。本文术语：**默认样式**指 `assets/fallback/`；**起步工程**指 `assets/starter/`，初始产物称**技术样片**；**方向文件**指视频工程里的 `DIRECTION.md`；音效事件统一保存在 `audio.cues`。
-
-## 流程
-
-1. **确认范围、平台与风格。** 已有工程沿用 brief 和用户决定，只处理本次修改。新片补齐：产品/仓库、发布渠道、时长与画幅、语言、是否允许链接，以及用户有没有参考视频。**范围与产品平台面必须由用户拍板**，仓库只能说明有哪些版本，说明不了用户想宣传什么：覆盖全量产品、最新一个版本周期，还是指定版本区间？覆盖哪些平台面（桌面端／CLI·TUI／移动端／服务端 API）？没指定时问一次，答案写入 `plan.json` 的 `scope`（如 `{"versions":"v0.10.12..v0.11.0","platforms":["cli-tui"]}`）并同步进 BRIEF。风格没定时问一次："沿用代码库自己的设计风格（推荐），还是默认的暖白／炭黑风格？"`repo` 用产品设计；`default` 用默认样式包装；`hybrid` 保留产品识别、调整外层排版。常见起点：横版、45–60 秒、中文。
-2. **初始化并检查环境。** 按下方工具入口初始化独立视频目录，再运行环境检查；只对报告的缺项加载 [依赖安装](references/onboarding.md)，装完复查。已有工程直接检查，不重新初始化。
-3. **调查产品，接通组件。** 按 [仓库与风格审计](references/repo-and-style.md) 确定功能、发布状态和证据，记下设计语言、暗色主题和可做母题的产品元素。在浏览器里挂载真实业务组件：补 provider，接口用 fixture，交互用真实点击和输入，放大到视频尺度（[起步工程](references/starter.md)、[组件接入](references/component-pipeline.md)）。先接通一个功能镜头并出静帧。
-4. **定方向，写 `DIRECTION.md`。** 按 [影片方向](references/direction.md)：拆解参考，提炼产品气质，沿不同的轴提出三个方向，选一个并写出理由；列出 3–5 个"因为产品有 X、所以用 Y"的专属手法，并避开本工作区上一支片子的手法；把画面规范写成具体数字；写到每一秒的镜头表。用户想先看方向时，给三个方向和 3–6 张关键静帧，等反馈；否则继续。
-5. **逐镜头搭建。** 每个镜头 = 视图组件 + builder（GSAP 主时间轴、`onRender` 画布层、`onDrive` 真实交互），时间只从 `plan.json` 读。手法从 [视觉手法词汇](references/visual-vocabulary.md) 里选能从产品推导的，`assets/fx-lab/` 的样例改写后再用。每搭完一个镜头就出静帧，对照镜头表（[审片](references/review.md)）。
-6. **配乐与音效。** 按 [配乐与音效](references/audio-sourcing.md) 选音乐来源（用户提供 → 本机可用的生成模型 → 代码合成），编曲从镜头边界推出来，音色从产品气质推出来；音效先用录音素材，缺项再用内置 WAV。用 `sfx_landmarks.py` 实测落点和电平，按 [混音与验收](references/audio-and-qa.md) 对位、让位、混音。
-7. **审片并交付。** 导出全片，看 2 fps 联系表、每个转场的 10 fps 条带和信息密集镜头的全尺寸帧，按 [审片](references/review.md) 修改后重新导出。运行 `check_delivery.py`（`pacing` 只提示该去看哪一段）。交付 MP4、可复现工程和少量预览；说清哪些是自动检查、哪些实际看过/听过、哪些仍未验证。要发布时按 [封面](references/cover.md) 做 3:4 / 4:3 / 16:9 封面，用户没提就用一句话问一下。历史问题查 [案例复盘](references/case-study.md)。
-
-## 硬约束
-
-- **真实功能。** 正式片至少一项可追溯的主张；每项记录发布状态、来源和白话解释。演示数据可以固定，功能效果与数字要有证据。范围与平台以 `plan.scope` 为准，交付时声明没有覆盖的平台面，避免观众以为片子讲的是产品全貌。
-- **原组件，视频尺度。** 功能镜头接入实际业务组件、原样式及状态，界面正文在成片里 ≥ 22px（1080p）。抽象化只用于取景、布局和外层动画。平台确实无法接入时，记录阻碍和替代方式，遵从已有授权。
-- **先有方向，再写代码。** 正式片必须有 `DIRECTION.md`：选定的方向和理由、从产品推导的专属手法、画面规范、镜头表。
-- **不套模板。** 每个视觉手法都要能说出它对应产品的哪一点。案例和 fx-lab 是推导示范，不是风格包；同一工作区连续做片，不原样复用上一支的开场、章节和背景手法。片内也要避免所有元素同一种入场、同一种转场。
-- **清楚排版。** 宣传标题默认英文、中文各一个 span，分别指定字体，中文无衬线；中文说明交代对象、动作和结果。产品内部字体保持原设计；用户指定的语言/字体优先。
-- **首帧就是完整画面。** 没有单独上传封面时，X / Threads 等平台会直接抓第一帧当缩略图。所以片子的前 5–10 帧要放一个完整画面，通常是开场段落的完成态；之后再淡出，开场动画照常播放。第一帧不能是空白底色，也不能是等待入场的背景。`check_delivery.py` 会测前 5 帧。
-- **完整声音。** 默认音乐与独立动作音效都进音轨，关键反馈听得见、音画同步。用户要求静音或省略音效时，记录 `audioExceptionReason`。
-- **隔离工程。** 源码适配、展示依赖和构建配置放在视频工程；原产品代码和依赖不动。
-- **授权与真实验收。** 素材保留来源和许可。默认样式受 [BSL 授权`SOURCE.md` 约束。自动检查只证明结构与文件一致；视觉、语义和听感靠实际审阅，没有试听就如实说明。
-
-## 工具入口
-
-先确认风格，再初始化；三种风格都可以传 `--repo`，其中 repo/hybrid 必填：
-
-```sh
-python3 <skill-dir>/scripts/init_project.py --output <video-dir> --style repo --repo <repo-dir>
-python3 <skill-dir>/scripts/check_environment.py --project <video-dir> --engine browser
-```
-
-# 缺项 → 按 references/onboarding.md 补装 → 使用 --force 复查。
-```
-npx -y @autoaiai/aicut@latest open .
-
-- [影片方向](references/direction.md)：参考拆解、产品气质、三个方向与差异轴、专属手法推导、反重复、画面规范、镜头表。
-- [视觉手法词汇](references/visual-vocabulary.md)：按作用分组的手法，写明表达什么、从哪里推导、怎么实现、何时不用。
-- [起步工程](references/starter.md)：运行时结构（seek、GSAP 主时间轴、onRender、onDrive）、接入仓库、样式链、plan 字段。
-- [审片](references/review.md)：三个审片节点、联系表与转场条带、常见问题对照表。
-- [封面](references/cover.md)：3:4 / 4:3 / 16:9 三种比例的布局思路、选图、文案和导出（起步工程的 `cover.mjs`）。
-- `assets/fx-lab/`：流线场、粒子汇聚、字符场、发光地平线、切片、环绕的可改写样例。
-- `assets/audio/score-example-keys.py`、`score-example-cinematic.py`：两种气质的代码合成配乐示例，借手法，不照搬曲子。
-- [内置音效`SOURCE.md`：11 个原创 WAV；需要改音色时运行 `scripts/make_sfx.py --output <new-sfx-dir>`。
-- `scripts/sfx_landmarks.py <files>`：实测音效的起音点、峰值时间和峰值电平。
-- `scripts/mix_audio.py <plan.json>`：混音、音乐让位、独立音轨和证据报告。
-- `scripts/check_delivery.py <plan.json> [--video <final.mp4>] [--mix-report <audio-mix.json>]`：结构、文件、时间线、方向文件、媒体与画面节奏提示。
-- `python3 -m unittest discover -s <skill-dir>/tests` 与 `node <skill-dir>/tests/integration.mjs --modules <video-dir>/node_modules`：维护此 skill 时运行；日常制片不需要读测试源码。
-```
-
-## Source
-
-Rewritten for AICUT from [`op7418/guizang-product-video-skill`](https://github.com/op7418/guizang-product-video-skill)
-(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/guizang-product-video-skill/references/audio-and-qa.md

@@ -1,113 +0,0 @@
-# 声音与成片检查
-
-## 配乐与音效
-
-先按 [配乐创作与音效查找](audio-sourcing.md) 完成选材：音乐默认用代码原创，音效先找与产品/动作相符的录音素材，缺哪一项才用内置音效补哪一项。先确定音乐气质、节拍和收束位置，再安排动作。原案例使用 120 BPM；其他产品按实际分镜选择速度、旋律和配器，不要求同一首曲子。
-
-建立与 `plan.json` 一致的 `audio.cues`：`at / actionId / file / gain / role`。`at` 是影片绝对秒数；动作的 `at` 是相对镜头开始的秒数，cue 对应 `shot.start + action.at`。音效落在动作发生点，而非机械地加在每个镜头开头。选中用轻 click/pop，结构变化才用 whoosh，通知用能被识别的提示音，结尾给一次收束。
-
-许可要区分“能用于成片”和“能随模板重新分发原音频”。这个 skill 不捆绑原案例的 Pixabay 录音，也不携带商业字体。将音频下载进当前视频项目时记录来源及许可，不把项目许可自动视为 skill 的再分发许可。
-
-## 从“写了音效”到“真的听得见”
-
-每个核心功能组选一个最有反馈感的状态变化（选中、打开、完成、通知），将对应 action 标为 `soundRequired: true`。不是每个字入场都加声，但不能只在最后放个音就跳过中间所有关键动作。完成/通知使用可辨认的双音叮咚或确认音；不要只有 whoosh。
-
-声音检查分三步：先单独听 `sfx-stem.wav`，确认关键事件有音效；再听 master，确认没有被配乐淹没；最后听编码后的 MP4，确认剪辑/导出没有漏掉。只检查文件存在或音轨数量都不够。有能力试听时按动作逐项检查；无法试听要准确标明，不假装已通过听感验收。
-
-找不到合适音效时，直接从 [内置音效目录](../assets/audio/sfx/) 复制所缺的 click/click-alt、pop、toggle、typing、ding-dong、success、error、resolve、whoosh 或 sweep。这些是现成的原创 WAV，不需要先运行生成器；需要调整音色时才改 `make_sfx.py`，输出到新目录。
-
-**增益要按实测电平设。** 内置音效峰值约 −20 dBFS，录音素材接近 0 dBFS；同样的 gain，前者会被配乐盖住。用 `scripts/sfx_landmarks.py` 查每个文件的峰值电平和落点。混音后可以逐个 cue 比较音效轨与压低后音乐在出现那一刻的峰值：音效不应明显低于音乐。
-
-```sh
-# 将代码原创配乐输出到 assets/music.wav。
-# 按 audio-sourcing.md 查找音效，缺项复制内置 WAV；再修改 plan 的动作和 cue。
-python3 <skill-dir>/scripts/mix_audio.py plan.json
-```
-
-`mix_audio.py` 输出 `assets/sfx-stem.wav`、`assets/music-ducked.wav`、`assets/master.wav` 和 `evidence/audio-mix.json`，对混音做双遍响度处理。配乐太响时应调低音乐 gain，音效太轻应调整对应 cue。现有 HyperFrames/Remotion 混音器也可以使用，但保留等价的素材、音效事件、混音来源与最终输出证据。
-
-配置结构（示意；时间应来自实际镜头）：
-
-```json
-{
-  "audioRequired": true,
-  "sfxRequired": true,
-  "audio": {
-    "music": {"file": "assets/music.wav", "gain": 0.65},
-    "cues": [{"at": 12.2, "actionId": "task-finished", "file": "assets/sfx/ding-dong.wav", "gain": 0.7, "role": "sfx"}]
-  }
-}
-```
-
-对应动作例如：镜头从 12 秒开始，`actions` 中有 `{"id":"task-finished","at":0.2,"action":"任务完成通知出现","soundRequired":true}`。cue 应与该动作对齐，听觉落点与动作通常控制在 1 帧内，检查上限为 2 帧。用户明确要无音效时记录 `sfxRequired:false` 和 `audioExceptionReason`；全静音设 `audioRequired:false`。这类例外遵从用户，不由模型自行决定。
-
-## 音效响时给它让位置
-
-默认开启 `audio.ducking`。原来只有固定音乐 gain，重要提示仍可能被盖住；现在按 cue 预先降低音乐，音效结束后再平滑恢复。不是整首曲子一律变小，也不是突然静音。
-
-下表是本 skill 的试听起点，**不是官方音频标准**；根据音乐密度和音效音色调整：
-
-| 声音职责 | 配乐压低 | 起音前压低 / 主要保持 / 恢复 |
-| --- | --- | --- |
-| 点击、切换、轻弹出 | 约 3–3.5 dB | 40ms / 100–120ms / 200–240ms |
-| 输入细节 | 约 2.5 dB | 40ms / 350ms / 250ms |
-| 转场 | 约 4 dB | 40ms / 160–200ms / 300–350ms |
-| 完成、通知、重要确认 | 约 5–6 dB | 40ms / 350–450ms / 350–400ms |
-| 品牌收尾 | 约 5 dB | 40ms / 550ms / 450ms |
-
-混音脚本使用确定的音量包络；多个音效重叠时取当前最深的压低，不把衰减层层相乘。逐项可调：
-
-```json
-{"audio":{"ducking":{"enabled":true}},"cueExample":{"kind":"ding-dong","duck":{"db":6,"attack":0.04,"hold":0.45,"release":0.4}}}
-```
-
-`cueExample` 是字段示意，实际放在 `audio.cues[]`。全局设置会覆盖类型预设，cue 的 `duck` 再覆盖全局；没有理由不要给所有声音同样强度。听到音乐不断抽动时减少不必要的 cue、减小压低或延长恢复。音效仍被掩盖时先检查音色冲突、调整 BGM 与 SFX 相对音量，再看局部压低，不只提高最终 master 音量。
-
-若改用实时侧链，FFmpeg `sidechaincompress` 用第二路信号控制第一路的压缩，需调 threshold/ratio/attack/release；本工具选择已知 cue 的音量自动化，更容易预先让位和重复验证。滤镜语法依据 [FFmpeg volume](https://ffmpeg.org/ffmpeg-filters.html#volume) 与 [sidechaincompress](https://ffmpeg.org/ffmpeg-filters.html#sidechaincompress)，延迟依据 [adelay](https://ffmpeg.org/ffmpeg-filters.html#adelay)。
-
-## 卡点和声音的变化
-
-1. 听/分析实际音乐，确定 BPM 与第一拍时间；节奏不固定时记下实际拍点，不编一个 120 BPM。主要转场可对重拍，轻操作不必全对重拍。
-2. 图像和声音一起调整时间。`cue.at` 是文件开始，`syncOffset` 是文件内部的听觉落点，因此 `cue.at + syncOffset = shot.start + action.at`。落点用 `scripts/sfx_landmarks.py` 实测：点击类取起音点，whoosh/冲击取峰值（它们要比画面先开始）。
-3. 使用节拍网格时填 `audio.beatGrid:{bpm,offset}`；需要对拍的 cue 标 `onBeat:true`，可用 `beatDivision:1|2|4` 对四分/八分/十六分音符。混音记录会报告与动作、最近拍点相差多少帧；只报告，不悄悄挪动音效造成音画错位。
-4. 30–60 秒影片一般选 4–6 种职责：选择/确认、弹出/切换、键入、空间转场、完成/通知、收尾。类别服务画面，不为满足数量虚构异常或通知。短片可更少。
-5. 连续点击可用 click/click-alt 做轻微音色变化，输入声是有节奏的短簇，转场音只留给画面结构变化，叮咚保留给值得注意的状态。不要所有字出现都“叮”一下。
-6. 最后分别听音乐轨、音效轨、完整混音及最终 MP4；检查提示声的第一下是否被盖住、拖尾是否被切断、节奏是否拥挤。
-
-## 混音
-
-音乐应听得见但不疲劳；无配音短片可把最终混音约 -16 LUFS、true peak 不高于 -1 至 -1.5 dBTP 当起点，并依据平台要求和听感调整。不同平台/题材不强制同一数值。有配音时给人声留空间，根据听感做 ducking。
-
-需要标准化时可用 FFmpeg loudnorm 双遍处理：先测量，读取 measured_I/TP/LRA/thresh/offset，再把测量结果带入第二遍；不要仅靠峰值归一化判断听感。最终 AAC 编码后重新测 true peak，因为编码可能产生新峰值。报告 `normalization.normalization_type` 保存第二遍 loudnorm 实际采用的 linear/dynamic 模式。音乐超过片长 1 秒时脚本输出警告并写入报告；自动截断和淡出后需要确认结尾，必要时重新编曲。
-
-核对音乐与画面同长度、片头不突响、片尾自然结束、音效不削波、不突然静音。用播放器试听最终文件；若环境只能测量，明确未完成试听，不能称为“已经听过”。
-
-## 自动检查
-
-```sh
-python3 <skill-dir>/scripts/check_delivery.py plan.json --video renders/final.mp4 --mix-report evidence/audio-mix.json > evidence/delivery-check.json
-ffmpeg -i renders/final.mp4 -af loudnorm=I=-16:TP=-1.5:LRA=8:print_format=json -f null -
-```
-
-正式模式（`demo:false`）中，脚本还会拒绝缺中英标题、缺字体分工、关键动作没有 cue、仅有 BGM、混音记录过期或素材哈希变化。脚本不能从 MP4 中自动分离并判断音效听感；内置导出器会核对传入 master 与混音记录的哈希，其他导出器需自行验证轨道接线。
-
-脚本发现时间缺口/重叠、错误规格、缺少音轨、卖点无来源会失败；阅读时长和类型过于单一发出提醒。不能据此宣布卖点真实、视觉无裁切或音乐好听。
-
-`--video` 还会给出 `pacing`（静止帧比例、最长静止段、硬切次数），只用来定位该回看的片段。大面积纯色背景、小区域运动容易被算成静止；不要为了数字加入无意义动画。画面审阅方法见 [审片](review.md)。
-
-## 最终人工检查
-
-| 检查对象 | 具体看什么 |
-| --- | --- |
-| 叙事 | 第一次看能说出有哪些更新、对自己有什么用 |
-| 阅读 | 中文单独读也知道操作对象、动作、结果；没有泛泛口号；说明出现够早 |
-| 标题 | 英文有实际语义且处于标题层级；中文统一无衬线；两种语言的字体分别加载 |
-| 画面 | 首帧/中间/末帧、所有转场前后；没有误空屏、裁切、跳动、裂图 |
-| 品牌 | 正确产品名、正式完整 Logo、与仓库一致的视觉识别 |
-| 事实 | 功能状态有证据；示例不冒充客户成果或跑分 |
-| 组件 | 原业务组件及样式实际上镜；构建图、状态驱动、来源清单与静帧一致；没有以基础控件或 tokens 复刻冒充整项功能复用 |
-| 音频 | BGM 与关键动作 SFX 都可闻；完成/通知反馈清楚；动作对齐；不刺耳、不爆音、结尾完整 |
-| 链接 | 按用户要求隐藏 URL/CTA，遮挡在缩放移动中不泄漏 |
-| 一致性 | 预览和 MP4 都检查，最终修改确实进入导出文件 |
-
-用最终 MP4 抽取关键帧，而不仅复用导出前截图。交付时附正确文件路径与清楚的成片状态，不把技术样片、未混音版、早期版本误当最终版。