git:20260713.b3764fd to git:20260905.676e35e

---

name: yichen-volc-asr

description: |

火山引擎音视频转写 + 口播自动粗剪 skill。用于语音转文字、视频转文字、音频识别、生成时间戳/SRT 字幕，也用于帮我剪口播、自动粗剪、删重复、删停顿、删口误、生成粗剪 MP4。

触发场景：用户说"帮我转写这个视频"、"音视频转文字"、"识别这个音频"、"帮我剪口播"、"自动剪辑"时使用。

metadata:

triggers:

- /转写

- /剪口播

- 转写视频

- 转写音频

- 视频转文字

- 音频转文字

- 音视频转写

- 识别这个视频

- 识别这个音频

- 视频识别

- 音频识别

- 生成字幕

- 帮我剪口播

- 自动剪辑

- 自动粗剪

- 删停顿

- 删口误

- 删重复

---

# 火山 ASR 转写 + 口播自动粗剪

这个 skill 同时负责两类任务：

- 纯转写：把本地音视频识别成文字、时间戳和字幕。

- 口播粗剪：基于 ASR 时间戳删重复、停顿、口误和废句，生成可进剪映精修的粗剪 MP4 和 SRT。

## 安全规则

1. 原片不动。先复制一个工作副本，再对工作副本转写、复转写或剪辑。

2. 不要直接删除任何文件。临时文件清理必须得到用户明确允许，并且只能先放到垃圾篓。

3. 原片、工作副本、粗剪成片、复转写临时文件必须分开保存。

4. 不要把 TOS、ASR Token、Cookie、API Key 写入 skill、普通记忆或日志；只从环境变量或用户指定的私有配置读取。

5. ASR 扣费顺序固定为：先用火山控制台中仍有试用/时长包的豆包语音应用；试用/时长包确认用完后，才允许切到付费应用。试用和付费 AppID 都必须从环境变量读取，不在公开 skill 里硬编码。

6. 试用和付费 token 必须分开：试用应用使用 `VOLC_ASR_TRIAL_TOKEN`，付费应用使用 `VOLC_ASR_PAID_TOKEN` 或旧的 `VOLC_ASR_TOKEN`。在试用包未用完前，不要用付费 token 冒充默认 token。

7. 在试用/时长包未确认用完前，不得设置 `VOLC_ASR_TRIAL_EXHAUSTED=1`，也不得让 `VOLC_ASR_APP_ID` 指向付费应用；如确实要临时绕过，必须明确说明会扣费并获得用户确认。

8. 长音频 ASR 提交成功后，不要重复跑同一文件来“再试一次”。优先等当前任务完成，或用已保存的 `{工作副本}.asr_pending.json` / `--request-id` 恢复查询，避免重复消耗试用时长或余额。

## 使用方法

```bash

# 基础用法：转写 + 分析 + 自动剪辑

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>'

# 只看标注不执行剪辑

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --dry-run

# 忽略 ASR 缓存，重新识别

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-cache

# 不执行 ffmpeg 剪辑，仍生成转写、标注和 SRT

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-execute

# 只转写，不做剪辑分析或生成 SRT

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --transcribe-only

# 只恢复查询已提交任务，不重新上传/提交

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --request-id '<火山ASR request_id>' --no-execute

```

脚本默认使用 `VOLC_ASR_TRIAL_APP_ID`，并优先读取 `VOLC_ASR_TRIAL_TOKEN`。只有确认试用/时长包已经用完后，才设置 `VOLC_ASR_TRIAL_EXHAUSTED=1`，脚本才会切到 `VOLC_ASR_PAID_APP_ID` 并读取 `VOLC_ASR_PAID_TOKEN` 或旧的 `VOLC_ASR_TOKEN`。如确实需要切到其他火山语音应用，先设置 `VOLC_ASR_APP_ID`；若该应用不是试用包应用且未标记试用已用完，脚本会停止，除非同时显式设置 `VOLC_ASR_ALLOW_NON_TRIAL_APP=1`。

如果本机旧环境里只有 `VOLC_ASR_TOKEN`，脚本不会默认把它用于试用应用，避免 token 属于付费应用却误以为在走试用。只有确认 `VOLC_ASR_TOKEN` 本身就是试用 token 时，才可临时设置 `VOLC_ASR_ALLOW_LEGACY_TOKEN=1` 兼容旧配置。

脚本会在提交成功后写入 `{工作副本}.asr_pending.json`，只保存 `request_id`、AppID、音频 URL 和状态，不保存 token/密钥。复跑时如果没有完成缓存，会优先恢复这个未完成任务；只有明确传 `--force-new` 才会重新上传并提交新任务。

## 输出文件

| 文件 | 说明 |

|------|------|

| `{工作副本}_cut.mp4` | 粗剪后的视频，可导入剪映 |

| `{工作副本}_cut.srt` | 字幕文件，剪映可导入 |

| `{工作副本}.txt` | 完整转写文字和时间戳 |

| `{工作副本}.asr_cache.json` | ASR 缓存，复跑可复用 |

| `{工作副本}.asr_pending.json` | 未完成ASR任务记录，可用于恢复查询，不能当作完成结果 |

## 纯转写流程

1. 确认输入文件存在、大小正常；必要时用 `ffprobe` 看时长和编码。

2. 复制原片为工作副本，例如 `source_for_asr.mp4`。

3. 运行 `python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-execute`。

4. 交付转写稿、时间戳、字幕草稿和缓存路径。

5. 明确说明本次没有做剪辑。

## 口播自动粗剪流程

当用户要“帮我剪口播”“自动粗剪”“删重复/停顿/口误/断句”时：

1. 复制原片为工作副本，避免原片被改动。

2. 用火山 ASR 生成带时间戳的转写稿和 `.asr_cache.json`。

3. 写一份可读删留方案：

- `KEEP`：干净、有信息量、叙事必要的内容。

- `DELETE`：口误、重复、长停顿、废句、半句话、无效语气词。

- `CHECK`：内容可能有用，但啰嗦或听感不确定。

4. 用源片时间码生成删除区间或保留区间。

5. 生成粗剪 MP4。长口播、多段删减时优先使用稳定的分段提取 + concat 流程。

6. 对粗剪 MP4 做复转写审核。

7. 通过审核后，输出粗剪 MP4、SRT、转写稿、删留方案和复查说明。

## 剪辑规则

| # | 规则 | 说明 |

|---|------|------|

| 1 | 停顿删除 | 相邻片段时间缺口较长的静音可删除 |

| 2 | 纯语气词删除 | 整段仅为嗯、啊、呃、哦等语气词时删除 |

| 3 | 相邻重复删除 | 优先删前保后，灰色地带人工判断 |

| 4 | 句中语气词保留 | 语气词在句子中间时整段保留 |

| 5 | 连续前缀词清理 | 然后、所以、其实、就是说等连续开头时清理冗余 |

| 6 | 短片段谨慎处理 | 非纯语气词短片段默认保留 |

| 7 | 智能 margin | 保留片段前后加缓冲，避免吞字 |

| 8 | Smoothing | 过短保留片段合并到相邻片段，避免闪帧 |

## 三层审核

每一层都检查：

- 有没有字、短语、句子或段落级重复。

- 有没有把完整句子剪断。

- 有没有残留口误、废句、半句话、只有开头没有结尾的片段。

- 有没有明显停顿、空白或节奏断裂。

- 有没有误删承接句，导致逻辑突然跳跃。

- 段落结构是否仍然顺。

### 第一层：剪前删留方案

删除区间必须对应重复、口误、废句、明显停顿或不可用残句；边界不能切进完整句子中间，除非后面有更干净的完整版本。

### 第二层：粗剪成片复转写

粗剪渲染后，对粗剪 MP4 重新转写。成片转写里不能有明显重复、残句、长停顿、逻辑跳跃或硬切造成的句子不完整。

### 第三层：最终通过

最新版粗剪必须通过一次完整审核后，才能说“可以进入剪映精修”。如果没通过，继续出新版本。

建议用一条人工确认过的粗剪成片作为质量标尺。以后口播粗剪以这个标准为基准：没有重复片段、没有明显停顿、没有把完整句子剪断。

## 最终回复要求

- 纯转写：给出转写稿路径、字幕路径、缓存路径，并说明没有做剪辑。

- 口播粗剪：给出粗剪 MP4 路径、SRT 路径、转写稿路径、删留方案路径、复查结论。

- 如果失败，说明缺少的环境变量、文件不存在、上传失败、ASR 失败或 ffmpeg 报错。