# bilibili-transcribe

Adopt this skill: https://proskills.md/skills/media/chubbyguan-chubbyskills-bilibili-transcribe

Page: https://proskills.md/skills/media/chubbyguan-chubbyskills-bilibili-transcribe
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: bilibili-transcribe/SKILL.md
size: 3062
sha: 89b7a62329d5df74d75eb9d42e4015a28d1a7465
upstream: https://github.com/chubbyguan/chubbyskills/blob/main/bilibili-transcribe/SKILL.md

````text
---
name: bilibili-transcribe
description: >
  哔哩哔哩视频 → 下载 → 转录 → 存为 Markdown 的完整工作流。
  支持 BV 号和完整链接，无需登录。
metadata:
  category: "media"
  triggers: "[\"用户发送 B 站视频链接\", \"把这个 B 站视频转成文字\", \"帮我转录这个 bilibili\"]"
  version: "1.0.0"
  tags: "[\"media\", \"audio\", \"video\", \"transcription\", \"bilibili\"]"
---

# B 站视频转录 Skill

**字幕优先**：先尝试抓取官方/自动字幕（秒级、免 GPU、免 funasr）；抓不到再下载音频用 SenseVoice-Small 转录，存为 Markdown 文件。加 `--no-subtitle` 可强制走音频转录。

## 环境要求

```bash
# Python 3.9+
python -m venv .venv
source .venv/bin/activate

# 依赖
pip install funasr modelscope torch torchaudio

# 系统依赖
# macOS: brew install ffmpeg yt-dlp
# Ubuntu: sudo apt install ffmpeg && pip install yt-dlp
```

## 使用方法

```bash
python scripts/transcribe.py "https://www.bilibili.com/video/BV1rrQGBeEen/"
python scripts/transcribe.py "BV1rrQGBeEen"
python scripts/transcribe.py "BV1rrQGBeEen" --no-subtitle   # 强制音频转录

# 批量处理：每行一个 B站 URL 或 BV 号
python scripts/batch_transcribe.py urls.txt -o ./output
```

## 流程

### Step 1: yt-dlp 下载音频

B 站有反爬机制，需要加 User-Agent 和 Referer：

```bash
yt-dlp --extract-audio --audio-format mp3 --audio-quality 128K \
  --user-agent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..." \
  --referer "https://www.bilibili.com" \
  "https://www.bilibili.com/video/BV1rrQGBeEen/"
```

### Step 2: SenseVoice-Small 转录

```python
from funasr import AutoModel
from funasr.utils.postprocess_utils import rich_transcription_postprocess

model = AutoModel(
    model="iic/SenseVoiceSmall",
    trust_remote_code=True,
    vad_model="fsmn-vad",
    vad_kwargs={"max_single_segment_time": 30000},
    device="cpu",
)

result = model.generate(input=audio_path, language="zh", use_itn=True, batch_size_s=60)
```

### Step 3: 生成 Markdown

自动创建带 frontmatter 的 Markdown 文件。

### 批量模式

`scripts/batch_transcribe.py` 会逐条调用单篇转录脚本，默认单条失败后继续处理下一条；需要严格模式时加 `--stop-on-error`。

## 性能数据

| 视频时长 | 转录耗时 |
|------|------|
| 5 min | ~10s |
| 10 min | ~20s |
| 30 min | ~60s |

## 已知限制

- B 站 4K/1080P60 需要大会员，普通用户可下载 720P 以下
- SenseVoice-Small 模型首次下载约 893MB
- 不支持说话人分离
- 合集视频会下载第一个分 P

## 参考项目

- [yt-dlp/yt-dlp](https://github.com/yt-dlp/yt-dlp) - 视频下载工具
- [FunAudioLLM/SenseVoice](https://github.com/FunAudioLLM/SenseVoice) - 语音识别模型

## ⚖️ 合规声明

仅供**个人学习与研究**使用。请遵守目标平台的服务条款（ToS）与 robots 规则，控制请求频率，不要用于批量抓取、商用爬取或侵犯他人权益的场景。下载内容的版权归原作者所有。
````

## File: bilibili-transcribe/scripts/batch_transcribe.py
size: 2396
sha: 27d2ffc812bb7b3fbedf01e9c5d1a6a7fabcb1d1
upstream: https://github.com/chubbyguan/chubbyskills/blob/main/bilibili-transcribe/scripts/batch_transcribe.py

```text
#!/usr/bin/env python3
"""
Bilibili batch transcription wrapper.

Input is a plain text file with one Bilibili URL or BV id per line. Empty lines
and lines starting with # are ignored.

Usage:
    python3 batch_transcribe.py urls.txt -o output/bilibili
    python3 batch_transcribe.py urls.txt -o output/bilibili --no-subtitle
"""

import argparse
import os
import subprocess
import sys

def read_sources(path):
    with open(path, encoding="utf-8") as f:
        for line in f:
            item = line.strip()
            if item and not item.startswith("#"):
                yield item

def main():
    parser = argparse.ArgumentParser(description="B站批量转录")
    parser.add_argument("input", help="文本文件：每行一个 B站 URL 或 BV 号")
    parser.add_argument("--output", "-o", default=".", help="输出目录")
    parser.add_argument("--no-subtitle", action="store_true", help="跳过字幕，强制音频转录")
    parser.add_argument("--stop-on-error", action="store_true", help="遇到失败立即停止")
    args = parser.parse_args()

    script = os.path.join(os.path.dirname(os.path.abspath(__file__)), "transcribe.py")
    sources = list(read_sources(args.input))
    os.makedirs(args.output, exist_ok=True)

    print(f"📦 B站批量任务：{len(sources)} 条", file=sys.stderr)
    ok, failed = [], []
    for index, source in enumerate(sources, 1):
        print(f"\n[{index}/{len(sources)}] {source}", file=sys.stderr)
        cmd = [sys.executable, script, source, "--output", args.output]
        if args.no_subtitle:
            cmd.append("--no-subtitle")
        result = subprocess.run(cmd, capture_output=True, text=True)
        if result.stderr:
            print(result.stderr, file=sys.stderr, end="" if result.stderr.endswith("\n") else "\n")
        if result.returncode == 0:
            output = result.stdout.strip().splitlines()[-1] if result.stdout.strip() else ""
            ok.append(output)
            print(f"  ✅ {output}", file=sys.stderr)
        else:
            failed.append(source)
            print(f"  ❌ 失败：{source}", file=sys.stderr)
            if args.stop_on_error:
                break

    print(f"\n🏁 完成：成功 {len(ok)} 条，失败 {len(failed)} 条", file=sys.stderr)
    for path in ok:
        print(path)
    return 1 if failed else 0

if __name__ == "__main__":
    sys.exit(main())
```

## File: bilibili-transcribe/scripts/transcribe.py
size: 6267
sha: 8c5af7126722a2e0819c0cec36928f0d8f7492c2
upstream: https://github.com/chubbyguan/chubbyskills/blob/main/bilibili-transcribe/scripts/transcribe.py

```text
#!/usr/bin/env python3
"""
B 站视频一键转录工具（字幕优先）

策略：先尝试抓官方/自动字幕（秒级、免 GPU、免 funasr）；
抓不到再回退到下载音频 + SenseVoice-Small 转录。

用法：
    python transcribe.py "https://www.bilibili.com/video/BV1rrQGBeEen/"
    python transcribe.py "BV1rrQGBeEen" ./output
    python transcribe.py "BV1rrQGBeEen" --no-subtitle   # 强制走音频转录
"""

import argparse
import os
import re
import shutil
import sys
import tempfile

SKILL_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
ROOT = SKILL_ROOT if os.path.isdir(os.path.join(SKILL_ROOT, "chubby_common")) else os.path.dirname(SKILL_ROOT)
if ROOT not in sys.path:
    sys.path.insert(0, ROOT)

from chubby_common.config import PlatformConfig
from chubby_common import funasr, markdown, vtt, ytdlp

# 字幕语言优先级（中文优先）
SUB_LANGS = "zh-Hans,zh-CN,zh,zh-Hant,ai-zh,en,en-US"
SUB_PRIORITY = ("zh-hans", "zh-cn", "zh", "zh-hant", "ai-zh", "en")

CFG = PlatformConfig(
    id="bilibili",
    name="Bilibili",
    tag="B站",
    default_title="B站视频",
    language="zh",
    referer="https://www.bilibili.com",
)

def extract_bvid(url: str) -> str:
    m = re.search(r"(BV[\w]+)", url)
    if m:
        return m.group(1)
    raise ValueError(f"无法从输入中提取 BV 号：{url}")

def get_info(url: str, bvid: str) -> tuple:
    """返回 (title, uploader)。失败时回退到 bvid。"""
    try:
        r = ytdlp.run_ydl(
            CFG,
            ["--print", "%(title)s|||%(uploader)s", "--skip-download", url],
            timeout=CFG.info_timeout,
            capture=True,
        )
        line = r.stdout.strip().split("\n")[0]
        title, _, uploader = line.partition("|||")
        uploader = uploader.strip()
        if uploader in ("NA", "None"):  # yt-dlp 缺失字段会输出 NA
            uploader = ""
        return (title.strip() or bvid, uploader)
    except Exception:
        return bvid, ""

def try_subtitles(url: str, tmpdir: str):
    """尝试下载字幕。返回 (text, lang) 或 None。"""
    print("  💬 尝试抓取字幕...", file=sys.stderr)
    try:
        ytdlp.run_ydl(
            CFG,
            [
                "--skip-download",
                "--write-subs",
                "--write-auto-subs",
                "--sub-langs",
                SUB_LANGS,
                "--sub-format",
                "vtt",
                "-o",
                os.path.join(tmpdir, "sub.%(ext)s"),
                url,
            ],
            timeout=CFG.subtitle_timeout,
        )
    except Exception:
        return None
    files = vtt.find_vtt_files(tmpdir)
    if not files:
        print("  💬 无字幕，回退音频转录", file=sys.stderr)
        return None
    chosen = vtt.pick_subtitle(files, SUB_PRIORITY)
    text = vtt.parse_vtt(chosen)
    if len(text) < 50:
        return None
    lang = "zh" if re.search(r"[一-鿿]", text) else "en"
    print(f"  ✅ 命中字幕（{lang}，{len(text)} 字）", file=sys.stderr)
    return text, lang

def download_audio(url: str, output_dir: str, title: str) -> str:
    safe = markdown.sanitize_filename(title, "audio")
    print(f"  ⬇️  下载音频：{title[:50]}...", file=sys.stderr)
    path = ytdlp.download_audio(CFG, url, output_dir, filename=f"{safe}.mp3")
    size_mb = os.path.getsize(path) / (1024 * 1024)
    print(f"  ✅ 音频：{size_mb:.1f} MB", file=sys.stderr)
    return path

def transcribe_audio(audio_path: str) -> str:
    text, _ = funasr.transcribe(audio_path, language=CFG.language)
    return text

def build_markdown(title, text, url, uploader, transcriber, lang):
    return markdown.note_markdown(
        title,
        text,
        {
            "type": "note",
            "platform": "bilibili",
            "source": url,
            "author": uploader or "",
            "tags": ["B站"],
            "language": lang,
            "transcriber": transcriber,
        },
    )

def main():
    parser = argparse.ArgumentParser(description="B 站视频转录（字幕优先）")
    parser.add_argument("url", help="B 站链接或 BV 号")
    parser.add_argument("output", nargs="?", default=".", help="输出目录")
    parser.add_argument("--output", "-o", dest="output_opt", help="输出目录")
    parser.add_argument("--no-subtitle", action="store_true", help="跳过字幕，强制音频转录")
    args = parser.parse_args()
    output_dir = args.output_opt or args.output

    bvid = extract_bvid(args.url)
    url = f"https://www.bilibili.com/video/{bvid}/"

    print("=" * 50, file=sys.stderr)
    print("Step 1: 获取视频信息...", file=sys.stderr)
    print("=" * 50, file=sys.stderr)
    title, uploader = get_info(url, bvid)
    print(f"  📺 {title}  | UP: {uploader or '未知'}", file=sys.stderr)

    tmpdir = tempfile.mkdtemp(prefix="bilibili-")
    try:
        text, lang, transcriber = None, "zh", "SenseVoice-Small"

        if not args.no_subtitle:
            print("\n" + "=" * 50, file=sys.stderr)
            print("Step 2: 字幕优先...", file=sys.stderr)
            print("=" * 50, file=sys.stderr)
            sub = try_subtitles(url, tmpdir)
            if sub:
                text, lang = sub
                transcriber = "字幕"

        if text is None:
            print("\n" + "=" * 50, file=sys.stderr)
            print("Step 2b: 下载 + 转录...", file=sys.stderr)
            print("=" * 50, file=sys.stderr)
            audio_path = download_audio(url, tmpdir, title)
            text = transcribe_audio(audio_path)

        body = build_markdown(title, text, url, uploader, transcriber, lang)
        safe = markdown.sanitize_filename(title, bvid)
        output_path = os.path.join(output_dir, f"{safe}.md")
        os.makedirs(output_dir, exist_ok=True)
        with open(output_path, "w", encoding="utf-8") as f:
            f.write(body)

        print("\n✅ Done!", file=sys.stderr)
        print(f"  来源：{transcriber} | 字数：{len(text)}", file=sys.stderr)
        print(f"  Output: {output_path}", file=sys.stderr)
        print(output_path)
    finally:
        shutil.rmtree(tmpdir, ignore_errors=True)

if __name__ == "__main__":
    main()
```

## File: bilibili-transcribe/requirements.txt
size: 64
sha: 01c44a9dc99973442fd026994f01d7d39329d122
upstream: https://github.com/chubbyguan/chubbyskills/blob/main/bilibili-transcribe/requirements.txt

```text
funasr>=1.0.0
modelscope>=1.10.0
torch>=2.0.0
torchaudio>=2.0.0
```

## File: README.md
upstream: https://github.com/chubbyguan/chubbyskills/blob/main/README.md

````text
<div align="center">

**中文** · [English](./README.en.md)

# 🧰 Chubby Skills

### 信息流会忘，知识库会记，Agent 会用。

把视频、播客、文章和本地文档保存为 Markdown，整理成能搜索、能回查来源、能交给 Agent 使用的素材库。

[![License](https://img.shields.io/badge/License-MIT-3B82F6?style=for-the-badge)](./LICENSE)
[![Version](https://img.shields.io/badge/Version-0.15.0-10B981?style=for-the-badge)](https://github.com/chubbyguan/chubbyskills/releases/tag/v0.15.0)
[![Skills](https://img.shields.io/badge/Skills-14-10B981?style=for-the-badge)](#skill-目录)
[![Stars](https://img.shields.io/github/stars/chubbyguan/chubbyskills?style=for-the-badge&color=F59E0B)](https://github.com/chubbyguan/chubbyskills/stargazers)

[快速开始](#快速开始) · [安装到 Agent](#安装到-agent) · [Skill 目录](#skill-目录) · [文档](#文档入口) · [更新日志](./CHANGELOG.md) · [💬 讨论区](https://github.com/chubbyguan/chubbyskills/discussions)

</div>

## 这是什么

Chubby Skills 是一套面向内容创作者和个人知识库的 **14 个 Agent Skills 与命令行工具**。你可以按需安装技能，让 Agent 处理素材；也可以直接运行命令，把采集、入库、搜索和资料包导出串起来。

适合经常收藏视频、文章和播客，希望在写作时找到原文、核对出处的人。产物保存在本地 Markdown 文件中，可以用 Obsidian、文本编辑器或你的 Agent 继续处理。

```text
链接 / 本地文档 → Markdown 原文与附件 → 本地搜索 → 带出处的资料包 → Agent 整理选题
```

| 你想做什么 | 项目提供什么 |
|---|---|
| 保存平台素材 | 视频字幕与转录、播客转录、文章和图文采集 |
| 导入已有资料 | Markdown、TXT、PDF 文字层导入，保留来源和引用的本地附件 |
| 写作时找回证据 | 关键词搜索、可选语义检索、原文读取；采集入库后自动更新索引 |
| 整理一份选题资料 | 导出 Markdown / JSON 资料包，包含原文摘录、行号、来源和文件摘要 |
| 让 Agent 使用知识库 | 独立技能包，以及提供搜索、原文读取等工具的可选 MCP 服务 |
| 持续跟踪可靠来源 | 订阅公开 RSS / Atom / JSON Feed、YouTube 频道与用户自带 Provider 输出；发现、审核、转录与入库分离 |

先看[输出样例](./examples/README.md)，或直接运行下面的本地示例。

### 平台可用性速览

声明能力（非实时探测），最近逐平台实测见[真实平台验证](./docs/live-verification.md)，完整失败模式见[平台状态](./docs/platform-status.md)：

| 平台 | 状态 | 轻量路径 |
|---|---|---|
| B站 / YouTube | 稳定 | 字幕优先，仅需 `yt-dlp` |
| 公众号 | 测试 | HTML 需 `beautifulsoup4`，PDF 兜底 |
| 抖音 / TikTok / 微博 / 知乎 | 测试·重依赖 | 视频转录需 `funasr` + `ffmpeg` |
| 播客 | 重依赖 | `funasr`（SenseVoice-Small），可选 DashScope / Groq 云转录 |
| X / 小红书 | 手动兜底 | 零依赖采集正文；X 长文章可配 `X_COOKIES` 抓登录态全文，失败可手动补全文。凭据怎么拿、上次是否成功：`chubby doctor --credentials` |
| RSS / YouTube 频道订阅 | P0 + P1 | 公开 Feed；支持 RSSHub / RSS-Bridge BYO 标签，默认只发现 |
| 本地文档 | 稳定 | 零依赖，Markdown/TXT/PDF 文字层 |

本项目不做反爬对抗，选择轻量接口加手动兜底，原因与适用边界见[为什么不对抗风控](./docs/platform-fallbacks.md#为什么不对抗风控)。

<a id="安装方式"></a>

## 快速开始

核心链路只用 Python 标准库：**不装第三方包、不配 API Key、不下载模型**。需要 Python 3.11 及以上——先 `python3 --version` 确认一下：macOS 自带的是 3.9，核心命令能跑，但 `subscribe` 订阅链路会在导入时失败，建议 `brew install python@3.12` 或直接用下面的 venv 步骤。

### 60 秒跑通（一）：抓一条真实链接

X 推文和小红书图文都走 Python 标准库，**不需要 yt-dlp、ffmpeg 或任何模型**（逐平台能力与失败模式见[平台状态](./docs/platform-status.md)）：

```bash
git clone https://github.com/chubbyguan/chubbyskills.git
cd chubbyskills
python3 tools/chubby.py init --vault "$PWD/creator-vault"
python3 tools/chubby.py ingest "https://x.com/OpenAI/status/1663696190960173056" --no-enrich
python3 tools/chubby.py search "ChatGPT"
```

```text
✅ 已写入配置：/path/to/chubbyskills/chubby.yaml
✅ 已准备队列：/path/to/chubbyskills/inbox/links.txt
✅ 已准备状态：/path/to/chubbyskills/.chubby/runs.jsonl
✅ 已准备报告目录：/path/to/chubbyskills/runs

✅ 完成：success=1 / failed=0 / dry_run=0
🧾 报告：/path/to/chubbyskills/runs/2026-10-05.md
/path/to/chubbyskills/creator-vault/00_Inbox/The-ChatGPT-iOS-app-is-now-available-in---<来源哈希>.md

The ChatGPT iOS app is now available in
  00_Inbox/The-ChatGPT-iOS-app-is-now-available-in---<来源哈希>.md
  # The ChatGPT iOS app is now available in   > 👤 OpenAI @OpenAI | 👍 754 · 💬 115 …
```

抓下来的笔记自带来源、作者、时间和互动数，引用时能回查到原帖：

```yaml
title: "The ChatGPT iOS app is now available in "
platform: x
source: "https://x.com/OpenAI/status/1663696190960173056"
author: "OpenAI @OpenAI"
created: 2023-05-30
likes: 754
```

把链接换成你要存的任意推文或小红书图文即可。

> **平台采集会波动。** 上面是**一条样本**，不构成成功率：没有登录态时可能被风控拦住，X 长文章默认只取到预览。失败时先看[平台状态](./docs/platform-status.md)和[替代处理方式](./docs/platform-fallbacks.md)，或保存正文后走下面这条。

### 60 秒跑通（二）：导入自己的文件

这条完全不碰外网，任何环境都能跑通。导入一份文档，再把它搜回来（把示例换成你自己的 `.md`、`.markdown` 或 `.txt`；已知原始网页时加 `--source-url "原始网页地址"`）：

```bash
mkdir -p demo-input
cat > demo-input/notes.md <<'NOTE'
# 内容复用笔记

内容复用从保留原文和来源开始。同一份材料可以用于选题、文章和播客，但引用前要重新核对上下文。
NOTE

python3 tools/chubby.py import demo-input/notes.md --no-enrich
python3 tools/chubby.py search "内容复用"
```

```text
✅ 完成：success=1 / failed=0 / dry_run=0
🧾 报告：/path/to/chubbyskills/runs/2026-10-05.md
/path/to/chubbyskills/creator-vault/00_Inbox/内容复用笔记--<来源哈希>.md

内容复用笔记
  00_Inbox/内容复用笔记--<来源哈希>.md
  # 内容复用笔记  内容复用从保留原文和来源开始。同一份材料可以用于选题、文章和播客，但引用前要重新核对上下文。
```

最后导出带出处的资料包——这是这个项目真正产出的东西：

```bash
python3 tools/chubby.py brief --topic "内容复用" \
  --output "$PWD/creator-vault/30_Output/brief.md"
```

```text
{
  "markdown": "/path/to/chubbyskills/creator-vault/30_Output/brief.md",
  "json": "/path/to/chubbyskills/creator-vault/30_Output/brief.json"
}
```

`brief.md` 里是逐字摘录、原文行号、来源链接和文件 SHA-256，可以直接回查（文件名后缀由来源路径推导，SHA-256 覆盖导入副本的内容与元数据，两者都会随你实际使用的路径和时间变化）：

```text
## E1 · 内容复用笔记

笔记相对路径：`00_Inbox/内容复用笔记--c2f47ab83782202c.md`
原始来源：未提供可打开的网页链接。
采集时间：2026-10-05T10:54:57+08:00
文件 SHA-256：`<导入副本的内容哈希>`

原文第 22–22 行：
```

产物落在三处：

- `creator-vault/00_Inbox/`：带来源信息的 Markdown 和引用的本地附件。
- `creator-vault/30_Output/brief.md` 与 `brief.json`：资料包本体。
- `.chubby/runs.jsonl` 与 `runs/`：任务状态和运行报告，方便检查失败与重试。

`brief` 全程在本地完成，不调用云模型，也不判断原文观点是否正确；上面的演示材料是人工样例。再次导出请换一个文件名，确认要替换已生成的资料包后再加 `--force`。

### 可选：把 `chubby` 装成命令

上面用的是 `python3 tools/chubby.py`，不装也能跑。想要 `chubby init` 这种形式：

```bash
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -e .   # 提供 chubby 命令，等价于 python3 tools/chubby.py
```

也可以装成普通包（`pip install .`，或 `pipx install git+https://github.com/chubbyguan/chubbyskills.git`）。非 editable 安装下，知识库命令全部可用——`init` / `import` / `search` / `brief` / `index` / `doctor` / `subscribe`（含 `digest` 与 `site build`），用户状态写在**你当前所在目录**，不会写进安装目录。

**平台采集 `ingest` 同样可用**：14 个 skill 目录随包一起安装（目录名 `bilibili-transcribe` 不是合法 Python 包名，构建时映射为 `bilibili_transcribe`，你不需要关心）。想把这些 skill 直接装进 Agent 而不是通过 CLI 调用，仍从仓库跑 `tools/install_skill.py`；两种方式互不影响。

已有知识库时把 `--vault` 换成它的根目录（例如 `docs/quickstart.md` 里的 `$HOME/Documents/creator-vault`）；已有配置的调整见[创作者工作流](./docs/creator-workflow.md)。

## 处理你的素材

### 平台链接

按所需能力安装运行依赖。以 YouTube 字幕为例：

```bash
bash setup.sh light
python3 -m pip install yt-dlp
python3 tools/chubby.py doctor --platform youtube
python3 tools/chubby.py ingest "替换为你的真实链接" --no-enrich
python3 tools/chubby.py search "原文中的关键词"
```

`light` 检查 Python 并提示轻量路径，不安装字幕或转录依赖。B站和 YouTube 优先取字幕；没有字幕时需要视频转录依赖。查看 [Skill 目录](#skill-目录)选择平台，并按下表补依赖：

| 处理路径 | 安装 / 配置 |
|---|---|
| Markdown / TXT 导入、关键词检索、资料包 | Python 标准库，无需额外包 |
| X / 小红书图文 | Python 标准库；`bash setup.sh light` 检查环境，登录态与平台限制仍可能影响采集 |
| B站 / YouTube 字幕 | `python3 -m pip install yt-dlp` |
| 本地视频转录 | `bash setup.sh video`；需要系统 `ffmpeg`，本地模型首次使用会下载 |
| 本地播客转录 | `bash setup.sh podcast`；使用 SenseVoice-Small（与视频转录共用 funasr 依赖） |
| 公众号及其 PDF 路径 | `bash setup.sh wechat` |
| 通用 PDF 文字层导入 | `python3 -m pip install 'pymupdf>=1.24'` |

平台抓取受 Cookie、字幕、地区和页面变化影响。失败时查看[平台状态](./docs/platform-status.md)和[替代处理方式](./docs/platform-fallbacks.md)，也可以保存正文后走本地导入。支持范围与最近的实测结果分开记录，见[真实平台验证](./docs/live-verification.md)。

YouTube 在部分出口 IP 上要求登录证明（`Sign in to confirm you are not a bot`）。两个环境变量会透传到所有平台技能的 yt-dlp 调用：`YTDLP_COOKIES_FROM_BROWSER`（如 `chrome`，对应 `--cookies-from-browser`）和 `YTDLP_REMOTE_COMPONENTS`（如 `ejs:github`，让 yt-dlp 下载 JS 挑战求解组件）。两者均为可选，按需配置。

X 长文章（Articles）默认只能抓到预览文本并给出警告；配置 `--cookies` 或 `X_COOKIES`（自己账号的 `auth_token` + `ct0`）后走登录态接口抓全文，失效时回退为预览。详见 [x-ingest](./x-ingest/SKILL.md)。

### 本地文档与 PDF

```bash
python3 tools/chubby.py import "/你的资料目录/report.md" --no-enrich
python3 tools/chubby.py import "/你的资料目录/report.pdf" \
  --source-url "https://example.org/original-report" --no-enrich
```

导入器保留原文件，把文档引用的目录内附件复制到产物旁；缺失或越界的本地附件会报错。PDF 只提取文字层，不做 OCR；扫描件需先由其他工具识别。详见[文档导入](./docs/document-import.md)。

### 播客与可选云转录

默认在本地转录音频：

```bash
python3 tools/chubby.py ingest "/你的音频目录/episode.mp3" \
  --skill podcast --provider local --no-enrich
```

本地模型默认 SenseVoice-Small，也可选 Qwen3-ASR-0.6B（`--provider local --model qwen3-asr-0.6b`，需自行 `pip install qwen-asr transformers torch`）。2026-10 在 M3 Pro CPU 上的实测
````
