# 视频文案提取

> |

- **Type:** Skill
- **Install:** `agentstack add skill-backtthefuture-video-transcript-video-transcript`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Backtthefuture](https://agentstack.voostack.com/s/backtthefuture)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Backtthefuture](https://github.com/Backtthefuture)
- **Source:** https://github.com/Backtthefuture/video-transcript

## Install

```sh
agentstack add skill-backtthefuture-video-transcript-video-transcript
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 视频文案提取专家

> 输入视频链接或本地路径 → 自动探测 → 后台下载 → 提音频 → FunASR 转录 → 严格逐字稿(stdout + 落盘)

## 阶段 0 · 定位 skill 根目录(第一件事)

被触发时你必须先定位自己,跑这段:

```bash
VT_HOME="$(
  for d in "$HOME/.workbuddy/skills/video-transcript" \
           "$HOME/.agents/skills/video-transcript" \
           "$HOME/.Codex/skills/video-transcript" \
           "$HOME/.codex/skills/video-transcript" \
           "$HOME/.claude/skills/video-transcript" \
           "$(pwd)/.Codex/skills/video-transcript" \
           "$(pwd)/.claude/skills/video-transcript" \
           "$(pwd)/skills/video-transcript" \
           "$HOME/.Codex/plugins/video-transcript/video-transcript" \
           "$HOME/.claude/plugins/video-transcript/video-transcript"; do
    [ -f "$d/SKILL.md" ] && echo "$d" && break
  done
)"
export VT_HOME
echo "VT_HOME=$VT_HOME"
```

如果输出为空,说明 skill 安装位置非标准。让用户给出路径,然后手工 `export VT_HOME=`。
之后**所有命令**都通过 `"$VT_HOME/scripts/transcript.py"`,不要用相对路径或绝对路径硬编码。

## 阶段 1 · 意图分流(贴链接 = 直接转录,不问)

**默认规则:用户贴视频链接 → 直接进入转录流程,不需要询问。**

只有在以下情况才需要询问或分流:
- 用户明确说"只下载"、"下载视频"、"保存MP4"、"不用转录" → 走纯下载,调用 `video-download`
- 用户只说"处理这个视频"但**没有附链接** → 问用户要链接

| 用户行为 | 处理 |
|---|---|
| 贴视频链接(视频号/抖音/小红书/B站/YouTube),无其他说明 | **直接进入转录流程(阶段 3),不问** |
| 贴链接 + 说"文案/逐字稿/转文字" | 直接进入转录流程 |
| 明确说"只下载"、"保存MP4"、"不用转录" | 走纯下载(见下方) |
| 只说"处理视频"但没附链接 | 问用户要链接 |

仅下载时,定位并调用 `video-download`:

```bash
VD_HOME="$(
  for d in "$HOME/.workbuddy/skills/video-download" \
           "$HOME/.agents/skills/video-download" \
           "$HOME/.Codex/skills/video-download" \
           "$HOME/.codex/skills/video-download" \
           "$HOME/.claude/skills/video-download" \
           "$(pwd)/skills/video-download"; do
    [ -f "$d/SKILL.md" ] && echo "$d" && break
  done
)"
export VD_HOME
echo "VD_HOME=$VD_HOME"
python3 "$VD_HOME/scripts/download_video.py" "" --json
```

仅下载完成后,按 `video-download` 的验收标准返回 durable MP4 路径、metadata 路径、时长、分辨率、视频/音频编码和文件大小;不要再进入转录流程。

## 阶段 2 · 依赖体检(首次/可疑时)

> **已验证过且环境没变化的,跳过体检直接跑转录。** 体检只在首次使用、换电脑、报错时做。

第一次跑或者遇到报错时,先做体检:

```bash
python3 "$VT_HOME/scripts/transcript.py" --doctor
```

如果有 ✗ 项,告诉用户:
- 缺 ffmpeg / playwright / chromium / API Key 等 → 跑一键安装向导:
  ```bash
  bash "$VT_HOME/install.sh"
  ```
- 体检全 ✓ 才进入阶段 3。

## 阶段 3 · 触发方式与执行

> 运行环境提示:WorkBuddy 中请用隔离 venv 的 python 执行(已装 funasr/playwright):
> `/Users/superhuang/.workbuddy/binaries/python/envs/default/bin/python "$VT_HOME/scripts/transcript.py"`

**用户给了视频链接(URL 或本地路径)就直接跑,不需要等确认:**

```bash
python3 "$VT_HOME/scripts/transcript.py" ""
```

唯一引擎:**FunASR SenseVoice-Small**(中文最优,CPU 高速,自带标点)。

支持的输入:
- B 站:`https://www.bilibili.com/video/BVxxx` 或 `b23.tv/xxx` 短链
- 抖音:`https://www.douyin.com/video/xxx`、`v.douyin.com/xxx`、`douyin.com/jingxuan?modal_id=xxx`
- 小红书:`xiaohongshu.com/discovery/item/xxx`、`xiaohongshu.com/explore/xxx`、`xhslink.com/xxx`
- YouTube:`youtube.com/watch?v=xxx`、`youtu.be/xxx`
- 微信视频号:`https://weixin.qq.com/sph/xxx`、`channels.weixin.qq.com/finder-preview/pages/sph?id=xxx`
- 本地视频文件路径

脚本自动:
0. **探测** — 启动 headless 浏览器,拿标题、时长、视频/音频直链;打印 📊 评估表 + 预估耗时
1. **下载** — 复用探测拿到的直链(不重启浏览器);B 站走 dash 流(分别下载 video/audio + ffmpeg 合并);其他平台直接 mp4
   - 微信视频号会先调用 `video-download` 下载为本地 MP4,再进入转录流程;解析方式由 `video-download/.env` 的 `WECHAT_RESOLVER` 决定
2. **提音频** — ffmpeg 提取 16k 单声道 wav(输入已是 wav 则跳过)
3. **转录** — FunASR SenseVoice-Small,CPU 高速(约 6x 实时),自带中文标点;按句号切句 + 字数比例估算时间戳
4. **分段** — 口述话题转折检测("第 N 个/点"等标记优先切段) + 60s 兜底,输出段落级时间戳

### ⚠️ 你(agent)必须做的三件事

**(1) 评估表复述 — 给用户等待预期**

脚本启动后,stderr 第一段就会打印 📊 视频探测评估表。**你必须立刻把它复述给用户**,告诉他:
- 视频标题、时长、分段数
- **预估耗时**(给用户一个等待预期,这点最重要)

不要等转录跑完才说,**先复述评估表 → 再继续等待转录**。如果用户看不到时长和耗时预估,会以为程序卡死。

例:
> 视频探测完成:
> - 平台:B 站 / 标题:《xxx》
> - 时长 17 分 12 秒,会切成 3 段独立转录
> - **预估耗时 3 分 20 秒 ~ 5 分 25 秒**,正在跑,稍等...

**(2) 转录完成后,直接在对话中输出「整理优化版」全文**

核心交付物是**整理优化版**。脚本会把原始逐字稿打印到 stdout 并落盘 `*_transcript.md`,但**原始稿不在对话里全文展示**——它仅作为整理素材与对照存档。

**正确做法(必须按此执行)**:
1. 读取落盘的 `*_transcript.md`(stdout 可能截断,一律以文件为准)
2. 整理出优化版(见第 (3) 条)
3. **直接在对话回复中完整输出整理优化版全文**(纯 Markdown,不要用代码块包裹)
4. 同时生成 .md + .html 文件落盘
5. 调用 `present_files` 打开 .html 预览 + .md 附件
6. 末尾附一行说明文件落盘路径

**「直接输出全文」= 整理优化版的每个章节、每个段落、对照表,全部写在你的回复正文里,不能只展示前几段,不能只给文件不给内容。用户要的是打开对话就能直接读完的完整文案。**

错误做法:
- ❌ 在对话里把原始无标点逐字稿逐行贴出(用户明确不想要)
- ❌ 只展示整理优化版前几段就省略
- ❌ 总结/精简整理优化版内容(要逐段展示)

**(3) 必须同时产出「整理优化版」(默认,勿等用户要求)**

转录完成后,**默认自动**整理一版 `*_整理优化版.md` + `.html`,不要等用户提。用户曾因缺此版本反馈"格式和之前不一样"——这是默认交付标准,不是可选项。

做法:读取落盘的 `*_transcript.md` 全文(注意:stdout 可能截断,一律以落盘文件为准),基于逐字稿做四件事:
0. **分段对齐(先做,决定章节结构)** — 章节边界必须以**视频口述结构**为准,不能沿用脚本 60s 机械切分:
   - 口述编号开头的论述(如"第一个问题""第四个点""第五个就是""还有一个问题")必须**完整成节**,不得被切成两节;
   - 相邻段落属同一话题论述的,须**合并回一节**(例:"第五个就是…奢华无边界"与其延续"个人成功→佣金预判→重排场轻实操"同属一个问题,须同一节);
   - 口述中非编号的"药方/建议/补充"内容可单列小节,但同一话题内不要人为分叉;
   - 时间戳为段落级,相邻节时间范围**允许重叠**(如实反映口述边界,不强求对齐到秒)。
1. **补标点断句** — FunASR 自带标点但仍有口语碎句,按语义补全句读、修正为通顺表达
2. **合并碎句** — 按语义合并为自然段落(每段 1-3 个自然段),替换"每句一行"的碎行
3. **修正识别错误** — 专名/术语/人名/成语按上下文纠错(例:内飞泰→内啡肽、普利高金→普里高津、Errorglass→Ira Glass、补梦我→补梦网);不确定的标 `〔?〕`,不要硬猜
4. **语义化小标题** — 为每章起有信息量的标题(例:"一厘米的切口,挖一千米深"),替代机器截断标题;标题可带编号(如"问题五:奢华堆砌无边界,个人光环消耗信任"),与口述编号对应

文末必须附 **「识别修正对照表」**:分「已修正(确信度高)」和「存疑(〔?〕标注,建议对照原视频核对)」两栏,逐条列出 原词 → 修正词。**保留原话原意,不总结、不增删观点。**

生成方式:用通用渲染脚本 `$VT_HOME/scripts/make_optimized.py`:
1. `--dump-template` 输出 content.json 骨架
2. 按骨架填入整理好的 sections(语义标题/时间戳/补标点段落)与 fixes(对照表),保存为 content.json
3. `python3 "$VT_HOME/scripts/make_optimized.py" --content content.json` → 自动生成 `.md` + `.html`(样式与旧版整理优化版一致:工具栏复制/下载按钮 + 目录 + 语义章节 + 对照表)
若不便用脚本,也可按同样结构手工写 .md/.html。

输出命名:`YYYY-MM-DD_标题(≤30字)_整理优化版.md/.html`,放在 `$VT_HOME/outputs/`,与原始 `_transcript.md` 并存作为对照。

## 阶段 4 · 输出去处

脚本会**三个去处同时输出**(均为原始逐字稿,作为整理素材与对照存档):
1. **stdout 直出**原始 Markdown 全文 — 仅作 agent 整理时的读取来源,**不在对话里全文展示**
2. **.md 落盘**到 `$VT_HOME/outputs/YYYY-MM-DD__transcript.md` — 原始稿,源码存档
3. **.html 预览版**同步生成到同目录 — 原始稿预览

> **展示优先级**:对话与预览面板呈现的核心是**整理优化版**(见阶段 3 第 (3) 条);原始稿文件保留作对照,一般不主动展开。

**取消落盘**:`--no-save`
**改保存路径**:`--output-dir  来源: 微信视频号 | 链接:  | 时长 12:06 | 引擎: FunASR(SenseVoice-Small) | 生成: 2026-08-08 18:48
> 关键词: 内容 · 观众 · 创作

## 目录

1. 卖豪宅的杰森今天给我发了 [00:00]
2. 但在我看到的是他这个账号出现 [01:02]

## 1. 卖豪宅的杰森今天给我发了 [00:00 - 01:02]

卖豪宅的杰森今天给我发了一个邀请函，他说他的新公司要搬了，然后邀请我去参加他的聚会。我拒绝了，因为我从来不参加任何聚会。

## 2. 但在我看到的是他这个账号出现 [01:02 - 01:51]

但是我看到的是，他这个账号出现了巨大的问题。我一个个讲一下，优点我就不说了，今天就说问题吧。
```

特性(funasr 引擎):
- **口述话题转折切分**:识别"第 N 个/点""还有一个问题""接下来""再说一遍"等口述标记,在话题转折处**优先切段**,避免"第五个问题"这类完整论述被拦腰切断;无标记时保持 60s 节奏(规则见 `scripts/transcript.py` 的 `_is_topic_marker`)
- **自带中文标点**:SenseVoice 输出自带逗号/句号/问号,无需后处理补标点
- **语义小标题**:规则法生成(去口语弱词 + 首句截断 ≤14 字,太短拼关键词),替代"第 N 段"
- **一键目录**:段落 > 3 时自动在头部生成"标题 + 起始时间戳"导航
- **句级切分 + 时间戳**:按句号切句,按字数比例估算每句时间戳(基于 wav 总时长)
- **元信息头**:来源平台 / 时长 / 引擎 / 生成时间,便于存档追溯
- **关键词**:全文 jieba 高频词提取,放头部
- **文件命名**:`YYYY-MM-DD_标题(≤30字)_transcript.md`,不再超长
- **段落级时间戳**:每段开头标 `[MM:SS - MM:SS]`,定位方便
- **降级**:无 jieba 时标题回退为首句截断;无任何文字时标注"(未识别到语音)"
- **逐字转录**:保留口语词("呃""那""啊""就是")、网络梗、停顿,不总结、不改写
- **无人声段落**:用 `_(此处无人声,XX秒)_` 标注

## 阶段 5 · 异常处理

| 场景 | 处理 |
|---|---|
| `--doctor` 报缺依赖 | 跑 `bash "$VT_HOME/install.sh"` |
| funasr 未安装 | `pip install funasr torchaudio` |
| 首次运行联网失败 | 首次需联网下载模型(约 234M,远小于 Whisper 1.5GB);国内可重试或检查网络 |
| 返回整段文本无分段 | 预期行为:脚本按句号切句 + 字数比例估算时间戳;整理优化版阶段按口述编号最终对齐 |
| 抖音图文笔记(note 链接) | 提示用户不支持图文,仅支持视频 |
| 平台前端改版导致抓取失败 | 看 `$VT_HOME/FALLBACK.md` 走人工兜底 |
| 微信视频号提示缺少 video-download | 重跑 `bash "$VT_HOME/install.sh"` 自动装配套 skill,或手动 `npx skills add Backtthefuture/video-download -a claude-code -g -y` |
| 微信视频号提示缺少 SPH_COOKIE/YUANBAO_COOKIE | 该提示只在 `WECHAT_RESOLVER=cookie` 时出现;默认已改为 `yuanbao-login`,无需配 Cookie |
| 微信视频号公共 Worker 失效(错误码 1042) | 已自动回退到**元宝登录态解析**(推荐),无需处理;见下方说明 |

视频号解析方式由 `video-download/.env` 决定。**默认即元宝登录态(`yuanbao-login`),开箱即用**。如需显式配置:

```env
# 默认(推荐):复用本地元宝登录态,免 Cookie、免第三方
WECHAT_RESOLVER=yuanbao-login
# 备选:公共 Worker(失效时自动回退元宝)
# WECHAT_RESOLVER=public-worker
# 备选:手动 Cookie
# WECHAT_RESOLVER=cookie
```

也可临时显式覆盖:

```bash
VIDEO_DOWNLOAD_WECHAT_RESOLVER=public-worker python3 "$VT_HOME/scripts/transcript.py" "https://weixin.qq.com/sph/xxx"
```

### 微信视频号:元宝登录态解析(默认)

公共 Worker(`sph.litao.workers.dev`)已失效(返回微信错误码 1042)。`download_video.py` 现在**默认走元宝登录态解析**(`WECHAT_RESOLVER=yuanbao-login`):复用 `~/.workbuddy/credentials/yuanbao_state.json` 的持久化登录态,走腾讯官方接口,不导出 Cookie、不依赖第三方服务;配置为 `public-worker` 时失败也会自动回退到这条链路。

安装时(`install.sh`)会自动引导扫码建立登录态;也可手动维护:

```bash
# 建立/更新登录态(弹出浏览器,微信扫码一次)
python3 "$VT_HOME/scripts/sph_resolver.py" --login

# 检查登录态是否有效
python3 "$VT_HOME/scripts/sph_resolver.py" --check

# 直接解析视频号链接(输出 JSON,含 direct_url)
python3 "$VT_HOME/scripts/sph_resolver.py" "https://weixin.qq.com/sph/xxx"
```

登录态有效期与微信授权一致,过期后重新 `--login` 扫码即可。

## 命令行选项

| 参数 | 说明 |
|---|---|
| `input` | 视频 URL 或本地文件路径(必需,`--doctor` 时可省) |
| `--title` | 视频标题(默认用探测到的) |
| `--no-save` | 不落盘 .md(默认会保存到 `$VT_HOME/outputs/`) |
| `--output-dir` | 改保存路径 |
| `--doctor` | 体检模式:检查依赖+配置 |

## Notes

- **唯一引擎 FunASR(SenseVoice-Small)**:中文 CER 7.81%(vs Whisper 20%)、模型仅 234M(vs 1.5GB)、CPU 约 6x 实时(M4 实测 12:56 音频纯转录 76s);**自带中文标点**(逗号/句号/问号);按句号切句 + 字数比例估算时间戳,口述话题转折标记同样适用
- 时间戳精度为段落级(不是词级/句级),用于章节定位
- 默认 stdout 直接输出原始 Markdown 全文(仅作 agent 整理的读取来源,**不在对话里展示**);**同时**落盘;对话/预览呈现的是整理优化版
- 预估耗时模型(基于实测):`时长/6 + 60s`(含提音频与模型加载),给 ±20% 范围
- 可选热词:在 `$VT_HOME/.env` 配 `FUNASR_HOTWORD=词1 词2` 可提升专有名词识别率
- 全部离线运行,不需要任何 API Key

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Backtthefuture](https://github.com/Backtthefuture)
- **Source:** [Backtthefuture/video-transcript](https://github.com/Backtthefuture/video-transcript)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-backtthefuture-video-transcript-video-transcript
- Seller: https://agentstack.voostack.com/s/backtthefuture
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.