back
loading skill details...
Use when the user wants to extract spoken text from a Douyin video link and produce a corrected, readable Chinese transcript
---
name: douyin-text
description: Use when the user wants to extract spoken text from a Douyin video link and produce a corrected, readable Chinese transcript
user-invocable: true
---
# 抖音视频语音文案提取
从抖音视频中提取**语音内容**：Python 只负责下载视频和 Whisper 原始转录；Claude Code 基于原始转录完成动态校对、自然分段、核心观点提炼，并**一次性生成**最终 Markdown 文档。
## 核心原则
每次用户调用 `/douyin-text`，必须严格按以下 4 步执行：
1. **Python 提取原始转录**
- 下载视频
- 提取音频
- Whisper 生成完整原始转录
- **不生成 Markdown 文档**
- **不生成"整理后文案"**
- **不生成"核心观点"**
2. **Claude 读取 Python 输出的 JSON**
- 拿到 `transcription_raw` 原始转录文本
- 拿到视频元信息：链接、作者、视频描述
3. **Claude 完成动态校对、自然分段、核心观点**
- 根据上下文修正 Whisper 识别错误
- 去除口癖、重复、无意义语气词
- 按语义自然分段
- 重新提炼 3-5 条核心观点
4. **Claude 一次性生成最终 Markdown 文件**
- 不读取任何旧 Markdown
- 不回写半成品
- 用 `Write` 工具直接创建成品文档
不需要额外配置 Claude API 或 OpenAI API。
AI 动态校对由当前 Claude Code 会话完成。
---
## 使用方法
```bash
/douyin-text <抖音视频链接>
```
示例：
```bash
/douyin-text https://v.douyin.com/xxxxx
```
---
## 参数
- `url`：抖音视频链接，必填
- 支持 `https://v.douyin.com/xxxxx`
- 支持 `https://www.douyin.com/video/xxxxx`
- `--whisper-model`：Whisper 模型大小，可选 `tiny/base/small/medium/large`，默认 `small`
- `--desc`：仅提取视频描述文字，不下载视频
- `--cookies-browser`：从浏览器导入 cookies，默认 `chrome`
- `--cookies-file`：使用 cookies.txt 文件
- `--no-cookies`：不使用 cookies
- `--update-ytdlp`：更新 yt-dlp
---
## 必须执行的工作流
当用户调用：
```bash
/douyin-text <链接>
```
Claude 必须严格按以下 4 步执行。**绝对禁止跳步、合并步骤，或直接使用 Python 生成的旧版完整 Markdown。**
### 步骤 1：Python 提取原始转录（不生成 Markdown）
在 skill 目录运行（**必须带 `--raw-json` 参数**）：
```bash
cd C:/Users/10911/.claude/skills/douyin-text && python extract.py --raw-json '<用户提供的链接>'
```
如果用户传了 `--whisper-model` 等参数，要原样传给 `extract.py`：
```bash
cd C:/Users/10911/.claude/skills/douyin-text && python extract.py --raw-json --whisper-model medium 'https://v.douyin.com/xxxxx/'
```
这一步的职责仅限于：
- 下载视频
- 提取音频
- Whisper 生成完整原始转录
这一步不会生成任何 Markdown 文档、不会生成"整理后文案"、不会生成"核心观点"。
### 步骤 2：解析 JSON 原始数据
`--raw-json` 模式会向 stdout 输出 JSON，结构如下：
```json
{
"url": "https://v.douyin.com/xxxxx",
"author": "作者昵称",
"description": "视频描述文字",
"transcription_raw": "Whisper 原始转录全文",
"error": null
}
```
Claude 必须：
- 从 stdout 解析 JSON（可能混在脚本日志中，取最后一段合法 JSON 块）
- 如果 `error` 不为 null 或 `transcription_raw` 为空，立即向用户报告错误并停止；不得编造内容
- 不得读取 `output/` 目录下任何已有 Markdown 文件
### 步骤 3：Claude 完成动态校对、自然分段、核心观点
Claude 基于 `transcription_raw` 完成以下处理（全部在 Claude 侧，不再调用 Python）：
**3.1 动态校对**
- 根据上下文修正明显 ASR/Whisper 识别错误
- 修正人名、地名、书名、成语、诗词、专有名词、常识性错词
- 去除明显语气词、口癖、无意义重复
- 不添加原文没有的信息
- 不改变说话人的核心观点
- 不把口播稿改成过度正式的论文腔
**3.2 自然分段**
- 按语义自然分段
- 每段表达一个相对完整的意思
- 段落之间用空行分隔
**3.3 提炼核心观点**
- 3-5 条
- 完整、通顺的中文句子
- 不保留明显错词
- 不使用过碎、半截、乱码式表达
- 概括观点，而不是复制原句碎片
### 步骤 4：一次性生成最终 Markdown 文件
Claude 使用 `Write` 工具**一次性**创建最终 Markdown 文件。
**绝对禁止：**
- 不得先生成半成品再回写
- 不得读取并修改 Python 生成的旧版 Markdown
- 不得分多次 Edit 同一个文件
**文件路径规则：**
```
C:/Users/10911/.claude/skills/douyin-text/output/douyin_<YYYYMMDD_HHMMSS>_<作者>.md
```
- 时间戳取当前时间
- 作者名清理掉 Windows 非法字符 `\ / : * ? " < > |`，并截断到 20 字符
- 如果作者名为空，省略该段，文件名形如 `douyin_<时间戳>.md`
**文件内容结构（严格按以下格式生成）：**
```markdown
📹 抖音视频语音文案
══════════════════════════════════════════════════
🔗 链接：<url>
👤 作者：@<author>
📝 视频描述：<description>
══════════════════════════════════════════════════
🎤 原始语音转录（<字数> 字）
──────────────────────────────────────────────────
<transcription_raw，保持原文不动，含 Whisper 输出的换行>
══════════════════════════════════════════════════
✨ 整理后文案
──────────────────────────────────────────────────
<Claude 校对、自然分段后的版本，段落间用空行分隔>
══════════════════════════════════════════════════
💡 核心观点
──────────────────────────────────────────────────
1. <观点一>
2. <观点二>
3. <观点三>
══════════════════════════════════════════════════
```
- "原始语音转录"区域字字必须等于 `transcription_raw`，不得做任何替换、整理或省略
- 如果 `author` 或 `description` 为空，对应行可省略，但其余结构必须完整保留
- 字数 = `len(transcription_raw)`
### 步骤 5：回复用户
最终回复必须包含：
- 生成的 Markdown 文件完整路径
- 简短摘要（1-2 句话）
- 如发现典型纠错，列出 3-8 个例子（原始 → 校对后）
---
## AI 动态校对规则
### 应该修正的内容
明显由语音识别造成的错误，例如：
| Whisper 可能输出 | 应修正为 |
| ------------------ | -------------------- |
| 普提祖师 | 菩提祖师 |
| 普提老祖 | 菩提老祖 |
| 西邮季 | 西游记 |
| 金斗云 | 筋斗云 |
| 七十二遍 | 七十二变 |
| 斗战圣佛 | 斗战胜佛 |
| 元风五年 | 元丰五年 |
| 被扁黄周 | 被贬黄州 |
| 回首向来消瘦处 | 回首向来萧瑟处 |
| 规去也无风雨也无情 | 归去，也无风雨也无晴 |
这些只是示例。实际执行时，Claude 应根据上下文动态判断，不局限于固定规则表。
### 需要谨慎处理的内容
如果某个词可能有多种解释，不要强行改。
例如：
- “苏氏家族”不应强行改成“苏轼家族”
- “行者”在《西游记》语境下可能是“孙行者”，不应随意删除
- 口播中的特殊表达，如果不是明显错词，应尽量保留原意
### 不应该做的事
- 不要修改“原始语音转录”区域。
- 不要添加原文没有的信息。
- 不要把说话人的观点换成 Claude 自己的观点。
- 不要为了文采过度润色。
- 不要删除重要论证内容。
- 不要只输出一整段长文本。
- 不要让“核心观点”保留乱码、半句、错词。
---
## 整理后文案格式要求
“整理后文案”必须自然分段。
### 好的格式
```markdown
菩提祖师是孙悟空非常重要的师父。在《西游记》里，他是真正教给孙悟空本领的人。
孙悟空的名字，是菩提祖师给的；孙悟空的筋斗云、七十二变，也都是菩提祖师传授的。
相比之下，唐僧给孙悟空的更多是一路上的磨炼和约束。唐僧没有教孙悟空本领，却让他在取经路上经历约束、受苦和修行。
所以，菩提祖师给的是本事和根基，唐僧给的是磨炼和修行。两个人对孙悟空都重要，只是重要的方式不同。
```
### 不好的格式
```markdown
我问你个问题,孙悟空的师父是谁? 唐僧,普提老祖。你怎么知道是普提祖师? 他叫他本领。大多数人会认为是唐僧。但是你看,在孙悟空整个西邮季的这一百回里面...
```
问题：
- 没有分段
- 错词未修正
- 可读性差
- 像字幕拼接，不像整理文案
---
## 长文本处理规则
如果原始转录很长，Claude 仍应完整处理 `transcription_raw` 全文。
如果单次处理上下文过长：
1. `transcription_raw` 全文必须原样写入"原始语音转录"区域，不得截断。
2. 分批校对"整理后文案"。
3. 合并成一个完整、自然分段的版本。
4. 再统一生成核心观点。
5. 最后一次性 `Write` 生成最终 Markdown 文件。
不要只整理前 300 字就结束。
不要分多次 Edit 同一个最终文件。
---
## 输出规则
| 内容长度 | 控制台行为 | 文件保存 |
| --------- | ------------------------------ | ------------------ |
| ≤ 1000 字 | 可在回复中展示较完整内容 | 保存校对后的完整版 |
| > 1000 字 | 回复摘要 + 文件路径 + 典型纠错 | 保存校对后的完整版 |
---
## 故障处理
| 情况 | 处理方式 |
| --------------------------- | ------------------------------------------------------ |
| Python 脚本下载失败 | 如实报告错误，提示确保浏览器已登录抖音，或尝试 cookies |
| Whisper 未安装 | 提示安装 `openai-whisper` |
| moviepy 未安装 | 提示安装 `moviepy` |
| 找不到 ffmpeg | 提示安装 ffmpeg 或 imageio-ffmpeg |
| Whisper 转录失败 | 如实报告错误，不编造文案 |
| Claude 后处理时不确定某个词 | 保留原词，或在最终回复中说明“疑似” |
| 原始转录过长 | 分段校对后合并，但仍**一次性** `Write` 生成最终文件 |
---
## 注意事项
- 仅支持公开可见的视频。
- 首次使用会下载 Whisper 模型。
- CPU 模式下 small 模型处理 1 分钟视频约 30 秒。
- 提取的文案仅供个人学习使用。
- Claude Code 动态校对不需要额外配置 AI API。
- 如果用户只要求“提取原始转录”，仍应保留原始转录并说明是否跳过校对。don't have the plugin yet? install it then click "run inline in claude" again.