毛绒小队

---
name: soft-crew
description: 用产品自己的网站或事实，给创始人和独立开发者做一条约 30 到 40 秒的可爱发布短片。五只毛绒小玩偶在一个动画编辑器里现场把片子做出来，画面里是产品真实的截图和真实的产出，最后落在产品标志和网址上。成品是 1920x1080、30 帧、H.264 yuv420p、小于 25 MB 的 MP4（英文或中文），一个能在浏览器里拖动查看、可以修改的 HTML 影片，以及一份分镜。默认无声，靠屏幕字幕表达，也可以混入用户提供的音乐。不需要图像、视频或音频模型。当有人要发布视频、产品短片、预告片、产品发布用的社交短视频，或者想用真实界面做一条可爱、毛绒风格的产品片时使用。
version: 1.0.0
---

# 毛绒小队

`assets/film.html` 就是整部影片的引擎。每一帧都只由帧号决定，通过 `window.renderFrame(n)` 画在一张画布上。角色、笑点、节奏和版式都已经写在里面。你要做的是收集真实素材、填一份简报、渲染、亲眼看。不要重画角色，也不要改故事。

需要精确的设计参数或规则背后的原因时，读 `references/style.md`。不需要读引擎源码。

**开源优先。** Lemo-Opuscar 的积木玩具风格（一种影片风格，MIT 协议，技升上有收录）是最接近的开源替代方案，不过观感不同：它用的是玩具积木，不是软绒布料。如果用户更喜欢积木，或者想用那个项目自己的工具，告诉他们有这个选择，并指向它的收录页。

## 小队成员

| 名字（英文） | 身形 | 工作 | 贯穿全片的笑点 |
|---|---|---|---|
| 阿拽（Tug） | 宽宽的铁锈色土豆，带补丁，两颗纽扣眼不一样 | 用绳子把界面拖进来 | 用力过猛摔个四脚朝天，绳子落在头上 |
| 小抹（Dab） | 高高的青绿色袜子，尖顶耷拉着 | 把产品的颜色刷满画面 | 伸长身子去够，然后一滴颜料落在鼻子上 |
| 咚咚（Thump） | 方方的梅子色靠垫，四角有流苏 | 骑着印章落下，给每条字幕盖章 | 全片到处蹦，一落地镜头就抖 |
| 嘀嗒（Tick） | 细长腿上的蓝色小蛋，顶着天线 | 操作时间线，按下播放 | 被甩出时间线尽头 |
| 迟迟（Late） | 长长的粉色抱枕，大耳朵，围巾飘着 | 送东西 | 永远迟到，合影拍完才端着五杯咖啡赶到 |

## 需要问的信息

简报里缺什么，一次性在同一条消息里问清楚。

1. 产品名。
2. 一句话说明它做什么，用对方自己的话。
3. 3 到 6 张真实截图或真实产出，或者可以截图的网站。如果产品的看点就在于东西会变（票数上涨、构建完成、修车进度往前走），要一段录屏或一个能播放的页面，见“会动的界面”。
4. 结尾要放的网址。
5. 语言：英文或中文。一条片子只用一种语言。
6. 可选：标志文件、产品主色、对方有权使用的音乐文件。

如果简报里既没有界面也没有网站，只问**一次**。没人回答，就用带明确标注的占位卡片制作，并在交付说明的最前面讲清楚。

## 步骤

1. **拿到真实素材。** 从网站截图：`node scripts/shoot.mjs https://their.site/page screens/a.png --size 1440x900`（每张几秒；手机视图用 `--size 390x844 --dsf 3`）。`shoot.mjs` 接受网址、普通路径或 `file://` 路径。选能看到产品在干活、结果清楚可见的界面。每张都打开看。只有确实属于这个产品的素材才能出现。

   **自己搭的界面**（产品确实会显示的页面，或者虚构演示）：按 **1440x740** 制作，正好填满预览区，用 `--size 1440x740 --dsf 1.5` 截图。手机用 390x844。在这个尺寸下正文不小于 20 像素，否则成片里会低于 14 像素。

   **虚构演示：** 这时每张界面都是编的，之所以允许，只因为片子带标注，所以要把 `fictional` 设为 `true`，界面上的任何数字也要写明是虚构的。真实产品则不同：你画出来的界面算编造，必须是产品的截图，或者经产品方确认一致的重建。
2. **写 `brief.json`**，字段见下表。
3. **构建：** `node scripts/build.mjs brief.json out/film.html`。超出限制会被拒绝，并告诉你是哪一项。
4. **先做短测试：** `nice -n 10 node scripts/render.mjs out/film.html out/test.mp4 --short`。约 20 秒。这是真实的剪辑：开场、每张界面、结尾。反复调整时加 `--scale 0.5`（约 8 秒），但可读性只有在宽度 1280 以上才会测量。
5. **检查：** `node scripts/check.mjs out/test.mp4 --short`。按报告改简报，回到第 3 步。
6. **看这条 MP4 里的真实画面。** 见下面的“亲眼看”。单帧重渲染：`node scripts/render.mjs out/film.html frame.png --frame 300`，不到 5 秒。
7. **渲染正片：** `nice -n 10 node scripts/render.mjs out/film.html out/film.mp4`。38 秒的片子在笔记本上约 30 秒，脚本会打印真实耗时，同时写出 `out/storyboard.html`，并打印每个段落的帧号和时间，看片时要用。一次只跑一个渲染，在前台运行。
8. **检查正片：** 真实产品用 `node scripts/check.mjs out/film.mp4 --real --brand "产品名"`。只有带标注的虚构演示或含占位卡片的片子才去掉 `--real`。每条片子都保留 `--brand`，虚构的也一样，名字对上时会打印一行确认。然后 `node scripts/check.mjs out/film.html`，再用 `node scripts/drive.mjs out/film.html` 实际操作拖动条、播放和减弱动效模式。
9. **从最终 MP4 里抽帧看，** 再交付。

安装 Playwright：`npm install playwright`（如果装在别处，把 `NODE_PATH` 设为对应的 `node_modules`）。`render.mjs`、`shoot.mjs`、`live.mjs` 和 `drive.mjs` 需要它。`check.mjs` 和 `build.mjs` 只需要 Node 和 ffmpeg。每个脚本都会自己关闭浏览器。

片长由界面决定：3 张 30.5 秒，4 张 33.5 秒，5 张 37.5 秒，6 张 40.5 秒，一张会动的界面最多再加约 1.5 秒。不用手动设置。

## 简报字段

| 字段 | 含义 | 限制 | 信息不足时 |
|---|---|---|---|
| `lang` | 影片语言 | `en` 或 `zh` | 跟随请求所用的语言 |
| `name` | 产品名，大字盖章，结尾再出现 | 英文 28，中文 14 字符 | 原样使用对方给的名字。没有就问；没人回答就停下，片子不能没有名字 |
| `line` | 名字下面的一句话 | 英文 70，中文 36 | 复述对方的原话或网站自己的标题。不加任何主张、受众或数字，并列为推断项 |
| `url` | 结尾的网址 | 40，不带 `https://` | 用真实的。没有真实链接：用产品名作纯文本，并告知对方 |
| `accent` | 小抹的颜料，也是后面界面的背景色 | `#RRGGBB` | 从产品界面上取主色。没有就不填，默认 `#D9532C` |
| `logo` | 结尾显示在名字上方的图片路径 | PNG、JPG、WebP 或 SVG，透明或纯色底 | 不填，名字变成大字标。绝不替对方画标志 |
| `fictional` | 每一帧都显示标注 | 只有虚构演示才设 `true` | 真实产品一律 `false` |
| `fictionalLabel` | 标注文字 | 英文 22，中文 11；必须含 "Fictional" 或“虚构” | 保留 “Fictional example” 或“虚构示例” |
| `screens` | 真实素材，按片中顺序 | 3 到 6 项 | 真实素材不足 3 张：用占位卡片补足并说明。多于 6 张：挑能看到结果的 |
| `screens[].file` | 图片路径，相对于简报 | PNG、JPG、WebP 或 SVG | 用 `shoot.mjs` 截。从竖屏手机到超宽仪表盘都能处理 |
| `screens[].caption` | 这张界面展示了什么，盖在旁边 | 英文 44，中文 22 | 用平实的话复述界面上看得到的内容。不写界面没有展示的功能，不编数字 |
| `screens[].sequence` | 一个放编号图片的文件夹：会动的界面，代替 `file`，在展示时段内播放 | 2 到 60 张，按文件名排序 | 静态界面不填。产品的看点在于变化时才用，见“会动的界面” |
| `screens[].moments` | 会动的界面里发生变化的位置，用播放进度的比例表示。每处小队都会惊呼，最后一处欢呼 | 0 到 1 的列表 | `[1]`：结尾欢呼一次。有明显变化时，看帧后填到变化发生的位置 |
| `screens[].crop` | 放大图片的一部分：`[x,y,w,h]`，用比例表示 | 每项 0 到 1 | 不填。检查器提示看不清时，再裁到关键部分 |
| `screens[].placeholder` | 没有界面时设 `true`，显示带标注的卡片 | 代替 `file` | 问过一次之后才用。卡片上写“占位：这里放真实界面”，能通过检查器，但会给出警告，你必须转告对方。`--real` 不接受它 |

哪张界面配哪个笑点，由数量决定：3 张是拉绳、刷漆、拖动播放头；4 张是拉绳、刷漆、拖动播放头、迟迟；5 张是拉绳、印章、刷漆、拖动播放头、迟迟；6 张再在最后加一次拉绳。**不论几张，顺序都是：** 第一张放陌生人一眼能懂的，最后一张放最好的结果，因为最后一张展示最久；如果有会动的界面，它不论排在哪里，都是首映段的高光。3 张时就是：这是什么、怎么用、结果如何。界面不必按简报的顺序排。

每个笑点在展示时段都自带一次出错和补救：钉子崩掉，阿拽跺脚把界面震正；一滴颜料从咚咚甩到小抹鼻子上；嘀嗒落在小抹头上；盖歪的字幕被顶正；迟迟把界面倒着送来。这期间角色不会挡住界面，你不用安排什么。

示例：

```json
{"lang":"zh","name":"小记","line":"把一场会议变成一张待办清单。","url":"xiaoji.example","accent":"#2F6FEB",
 "screens":[{"file":"screens/a.png","caption":"贴上你的会议记录"},
            {"file":"screens/b.png","caption":"得到一张清楚的待办清单"},
            {"file":"screens/c.png","caption":"一键发给团队"}]}
```

## 会动的界面

静态截图展示不了“全程看得见”。如果这正是产品的承诺，就用会动的界面。有两种做法，最后都是给 `screens[].sequence` 一个文件夹。

**1. 带钩子的页面。** 在页面上提供 `window.setScreenFrame(n)`，`n` 从 0 到总帧数减 1。它必须只根据 `n` 立刻画出那一帧，不用定时器、动画或随机数。然后运行：`node scripts/live.mjs screens/results-live.html screens/results-seq --size 1440x740 --frames 45`，每帧约 0.1 秒。没有钩子、第二次画出来不一样、或者从头到尾没变化的页面，都会被拒绝。

```html
<script>
window.setScreenFrame = (n) => {
  const q = n / (window.SCREEN_FRAMES - 1);          // 0 到 1
  document.querySelector('#bar').style.width = q * 52 + '%';
  document.querySelector('#pct').textContent = Math.round(q * 52) + '%';
};
</script>
```

**2. 真实录屏抽帧。** 从真实录屏里抽帧：`ffmpeg -i demo.mov -vf "fps=15,scale=1440:-2" -t 3 -threads 2 screens/seq/frame-%03d.jpg`。不超过 60 张。

简报写法：`{"sequence":"screens/results-seq","caption":"看大家选了什么","moments":[0.45,0.95]}`。界面在展示时段内播放一次，从第一帧开始，停在最后一帧。它还会在首映段作为高光再放一遍。一张会动就够，最多两张：每张会让 `film.html` 增加最多 5 MB。播放的数字必须是真实的，否则片子必须标注为虚构。把每个 moment 放在陌生人能看到变化的地方，并打开每个位置的画面确认。

## 检查器看什么

`check.mjs` 可以在任何目录下检查任何 MP4，它读取渲染脚本存放在文件内部的报告。它测量观众实际看到的东西：文字溢出、贴近画面边缘或被角色压住；界面清晰展示时被角色挡住；首映段任何一帧界面被角色挡住；会动的界面几乎没变化；超过 2.6 秒没有笑点或反应；界面清晰展示不足 1.8 秒；画面冻结；空白凑时长；前 3 秒没有动静；界面发白；常见文字在成片尺寸下高度不足 8 像素；在真实帧里测得的低对比度；语言混杂；残留的模板或示例文字。没有报告的文件（比如你重新压缩过）只做通用检查并给出警告，这不等于版式合格。所以渲染之后不要再压缩。`--crf` 和 `--music` 正是为此放在渲染脚本里的。

**提示看不清时：** 设置 `crop`，或换一张字更大的界面。**名字太长：** 会换成两行并缩到字号下限。如果检查器说角色压住了文字，就缩短名字或那句话。

## 亲眼看

从最终 MP4 抽出真实画面，一张张打开：`ffmpeg -ss 2.2 -i out/film.mp4 -frames:v 1 -threads 2 v1.png`。至少每秒看一帧，时间用渲染时打印的段落表。重点看 0.3 秒、1.2 秒、每个展示时段里界面歪掉、颜料滴落或翻转的瞬间、首映段和最后一帧。**检查器判断不了可爱，也判断不了真假。** 前三秒能不能让陌生人笑出来、每条字幕对这张界面是否属实、有没有界面读起来不对，只有你能看出来。

相信结果之前，先用特殊素材试一下：深色产品、竖屏手机和超宽仪表盘的版式各不相同。

## 音乐

默认无声，靠字幕表达意思。如果用户提供了有权使用的音乐文件：`node scripts/render.mjs out/film.html out/film.mp4 --music song.mp3 --music-start 0 --music-gain 0.7`。脚本会淡入淡出并裁到片长。动作按 120 BPM 剪辑，每 15 帧一拍，所以 120 BPM 的曲子会踩在笑点上；用 `--music-start` 对齐第一拍。绝不生成音乐，也不运行任何音频模型。没人提供音乐就不要加。

## 信息缺失时

- **简报单薄：** 复述用户给的事实，不编造，交付时列出每一条推断内容。
- **没人能回答：** 按上表的默认做法继续，并列出你的假设。
- **没有真实链接：** 在 `url` 里用产品名作纯文本，并告知对方。
- **想要不同的时长：** 改界面数量，范围是 30.5 到 40.5 秒。要更短的片段，用 `--from` 和 `--to` 加分镜里的帧号，并告诉用户这已经不符合发布片的长度。不要剪掉结尾。
- **想改笑点或角色：** 这需要改引擎，直接说明，简报覆盖不了。
- **渲染出来太大：** `--crf 25` 可以减小体积。超过 25 MB 时脚本也会自动提高这个值。

绝不编造客户、数字、用户评价或资历，也绝不把编出来的界面当成产品的真实界面。虚构演示必须带标注。

## 交付物

- `film.mp4`：1920x1080、30 帧、H.264 yuv420p，小于 25 MB。
- `film.html`：可修改的影片。双击打开，不需要服务器，也不发任何请求。用滑块或方向键拖动，空格键播放。改 `film-config` 块里的 JSON 就能改文字。
- `storyboard.html`：每个段落，附真实画面、时间和内容说明。
- 一份简短清单，列出推断内容和占位卡片。

## 交付前检查

- [ ] `node scripts/check.mjs film.mp4` 退出码为 0，真实产品要加 `--real --brand "产品名"`
- [ ] `node scripts/check.mjs film.html` 和 `node scripts/drive.mjs film.html` 退出码为 0
- [ ] 我从最终 MP4 抽了真实画面并打开看过，包括前 3 秒和每张界面
- [ ] 片中每张界面都是真实的产品素材，或者是已告知用户的带标注占位卡片
- [ ] 每条字幕和那句话对这个产品都属实，来自用户给的事实，没有编造功能或数字
- [ ] 全片只用一种语言，产品术语除外
- [ ] 最后一帧的标志和网址是对的
- [ ] 所有假设都已列给用户

## 什么时候不要用

- 严肃、正式或敏感的主题，毛绒玩偶不合适：医疗结果、悼念、法律。
- 还没有东西可以展示的产品：这条片子建立在真实界面上。
- 必须一步步教学的演示。这是 35 秒左右的预告。
- 需要旁白或生成音乐的片子。
- 想把知名角色或品牌吉祥物放进小队：小队是固定的原创角色。

## 运行要求

Node 18 或更高，带 libx264 的 ffmpeg。渲染、截图和操作测试需要 Playwright。在一台 M 系列 Mac 上同时跑着其他任务时测得：1080p 全片 25 到 35 秒；短测试约 25 秒；单帧不到 5 秒；检查器约 15 秒。不需要网络、账号或模型。字体都是系统字体，并有备用字体。