laohan-sucai v0.1.0A

Immutable. This exact content is served forever at /api/v1/blob/8bfd648ccb426291.

---
name: laohan-sucai
description: B-roll 素材搜索引擎，从口播稿自动配素材。输入口播稿→逐句提取关键名词→翻译英文场景词→多源聚合搜索（Pexels/Pixabay/Coverr/Mixkit）→GLM 文本相关性打分选片→批量下载+自动署名，末尾输出清单供确认。只产素材不合成视频（合成归剪辑⑧或 laohan-donghua）。Use when 用户说"配素材""找B-roll""加素材""口播稿配画面""补视频素材"。
version: "0.1.0"
---

# B-roll 素材搜索

从口播稿自动配 B-roll 素材。纯搜索引擎：产出素材文件+清单+署名表，不合成视频。

## 核心理念

口播视频里 B-roll 的作用是让观众在听到抽象概念时有画面锚点。本 skill 解决"中文口播稿怎么自动配到贴的免费可商用素材"——核心难点是中英场景词翻译 + 多源聚合 + 选片打分。

**只产素材不合成**：合成视频是剪辑⑧或 laohan-donghua 的职责。本 skill 产出落到 `broll-assets/`，由后续环节按时间轴 overlay。

## 设计契约（7 项已定，2026-07-10）

| 维度 | 决策 |
|------|------|
| 输出形态 | 只产素材不合成（纯引擎） |
| 场景词 | 全自动：整稿提词→搜→GLM 打分选→下载，仅末尾确认 |
| 数据源 | 多源聚合：Pexels 主力 + Pixabay + Coverr + Mixkit |
| 选片 | GLM 文本相关性打分（素材描述/标签 vs 该句口播，选 top1-2） |
| 无结果 | 留空标记"无素材"，不凑（交动画层/手动补） |
| 确认形态 | 清单+预览：`素材清单.md` + `_credits.md`，过一遍不满意手换 |
| 存放 | laohan-skills 仓库（MIT，symlink 同步） |

## 与工作流的分工

- **真实场景用素材**（本 skill）：人物工作/城市/科技设备/自然等有实拍可搜的
- **抽象概念用动画**（laohan-donghua）：数据流/AI 概念/流程示意等搜不到实拍的
- 搜不到素材的句子 → 留空标记，不强行凑，留给动画层或手动补

## 工作流

### 1. 解析口播稿

读 `01-口播稿.md`，按句号/换行分句，给每句编号。过滤纯过渡句（语气词/连接词无实义）。

### 2. 逐句提取场景词

对每句：
- 提取关键名词/动词（去掉"你""我""感觉"等无场景义的词）
- 翻译成英文场景词（Pexels/Pixabay 用英文搜效果最好）
- 每句出 1-3 组场景词（主词 + 备选词）

例：「你刷到 FDE 高薪招聘」→ `job offer / hiring / career` 或 `office work / computer`

### 3. 多源聚合搜索

按场景词搜，每源拿 top 候选：

| 源 | 类型 | key | 限流 | 署名 |
|----|------|-----|------|------|
| **Pexels** | 视频/图 | 免费 key | 200/h, 20000/月 | 摄影师+Pexels 链接 |
| **Pixabay** | 视频/图 | 免费 key | 100/分钟 | 宽松，鼓励署名 |
| **Coverr** | 视频 | 需查 | — | 免署名 |
| **Mixkit** | 视频 | 需查 | — | 免署名 |

每句每源最多 3 候选，去重合并。API key 从环境变量读（`PEXELS_API_KEY`/`PIXABAY_API_KEY`）。

### 4. GLM 相关性打分选片

对每句的候选集，用 GLM 对「候选素材的描述/标签文本」与「该句口播」打相关性分（0-10），选 top1-2。

- 输入：口播句 + 每个候选的 description/tags（API 返回的文本，不看画面）
- 输出：每句 0-2 个选中素材 + 分数
- 全部低于阈值（如 5 分）→ 该句标记"无素材"，不凑

> 为什么文本打分不用多模态看画面：M1 本地跑不动大 vision 模型；API vision 每期几十张图贵慢；素材 API 自带的描述文本质量够用于初筛。画面匹配留给末尾人工确认环节。

### 5. 批量下载

下载选中素材到 `broll-assets/`：
- 文件名：`{句编号}_{源}_{关键词}_{原文件名}.{ext}`（如 `03_pexels_hiring_video-office.mp4`）
- 视频优先下载 SD/预览质量（B-roll overlay 用不着 4K，省带宽）
- 下载失败 → 标记跳过，不卡流程

### 6. 产出清单 + 署名

**`素材清单.md`**：
```markdown
# B-roll 素材清单

| 句编号 | 口播句 | 场景词 | 选中素材 | 预览 | 出处 | 相似度 |
|--------|--------|--------|---------|------|------|--------|
| 03 | 你刷到FDE高薪招聘 | hiring | video-office.mp4 | [缩略图] | Pexels/John | 8.2 |
| 07 | 其实跟你没关系 | career | (无素材) | — | — | — |
```

**`_credits.md`**（自动署名表，发布时随片附上）：
```markdown
# 素材署名

- video-office.mp4 — Photo by John Doe on Pexels (https://pexels.com/...)
- ...
```

### 7. 末尾确认

输出清单 + 缩略图预览（清单里嵌图片路径或起本地预览页）。Jeffrey 过一遍：
- 满意 → 素材就位，等⑧/donghua 合成
- 某句不满意 → 手动换该文件（重跑该句搜索或手动塞素材）
- "无素材"的句 → 决定交动画层还是手动补

## 产物

```
broll-assets/
├── 03_pexels_hiring_video-office.mp4
├── 05_pixabay_career_meeting.mp4
├── ...
├── 素材清单.md          ← 每句对应素材+预览+出处+相似度
└── _credits.md          ← 自动署名表（发布随片附）
```

## 输入输出契约

- **输入**：`episodes/<slug>/01-口播稿.md`（或任意口播稿文件）
- **输出**：`episodes/<slug>/07-剪辑/broll-assets/`（按工作流⑧产物归位）
- **不输出**：合成视频（归⑧/donghua）

## 依赖

| 依赖 | 用途 | 安装 |
|------|------|------|
| Pexels API key | 主力视频源 | 注册 pexels.com/api（免费） |
| Pixabay API key | 兜底视频/图 | 注册 pixabay.com（免费） |
| GLM API | 相关性打分选片 | `$ZAI_API_KEY` 已有 |
| ffmpeg（可选） | 截缩略图预览 | `brew install ffmpeg` |
| curl | API 调用+下载 | 系统自带 |

## 触发方式

```bash
/laohan-sucai episodes/2026-07-10-fde/01-口播稿.md
"给这期口播配素材""找B-roll""加素材"
```

## 实现状态（2026-07-10）

- ✅ spec 已定（本文件，7 项设计契约）
- ⬜ scripts/ 实现（提词→多源搜→GLM打分→下载→清单）
- ⬜ references/ 源适配器文档（各 API 字段/限流/署名要求）

> spec 先行，实现待 chengfeng adapter 验证 + ⑧链子跑通后再做（避免预付实现成本）。当前 FDE 期停在⑥封面，⑧未到。

## 注意事项

- 素材 API 英文搜索效果最好，中文稿必须先翻场景词
- 200/时限流：每期约 15-20 句 × 3 候选 = 45-60 请求，远低于限流，单期不会撞限流；批量回填历史期时注意间隔
- 署名是发布义务（尤其 Pexels），`_credits.md` 必须随片发布，别漏
- 视频质量只下 SD/预览版即可，B-roll overlay 不需要 4K
- 本 skill 不碰字幕/剪口播（那是 chengfeng 剪口播），不合成视频（那是 donghua）