dsh-bili-asr

Readme

# dsh-bili-asr

> DeepSeek Harness 插件：解析 **B站(bilibili)** 视频链接，一键提取**完整脚本 / 字幕**，并导出 `SRT` / `TXT` / `JSON`。

![跨平台](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)
![许可](https://img.shields.io/badge/license-MIT-green)
![DSH](https://img.shields.io/badge/DSH-%3E%3D0.1.0--rc.5-lightgrey)

---

## 功能特性

- 🎬 **链接宽容解析**：支持 `BV 号` / `av 号` / `b23.tv` 短链 / `bilibili.com` 链接 / **分享文本**（如 `【标题】 https://b23.tv/xxxx`）。
- 💬 **字幕轨优先**：优先读取视频自带字幕（AI 字幕 / CC 字幕），秒出、无额外依赖。
- 🎙️ **无字幕自动转写**：无字幕时用本地 **whisper (large-v3-turbo)** 转写音频，自动下载音频并转为 16kHz 单声道。
- 🧾 **带时间戳全文**：返回 `[mm:ss] 文本` 的完整转写，逐条时间轴。
- 📦 **一键导出**：导出 `SRT` / `TXT` / `JSON` 三种格式到 `baseDir/.bili-exports/`。
- 🌍 **跨平台**：纯 Node 实现（`fetch` + `node:fs` + `node:child_process`），不依赖 powershell 或 Windows 路径，Windows / macOS / Linux 通用。
- 🧠 **作为模型工具**：注册为 `bili_script` 宿主工具，代理自动调用，无需 UI 操作。

## 工作原理

<!-- 流程图见 screenshots/flow.svg -->
<p align="center">
  <img src="screenshots/flow.svg" alt="提取流程" width="520">
</p>

1. **识别链接**：`parseBiliUrl` / `extractBiliUrl` 抠出 BV / av / b23 链接；`b23.tv` 短链自动跟随重定向拿到真实地址。
2. **获取视频信息**：调用 `x/web-interface/view`，得到标题、UP主、分P(cid) 等。
3. **取字幕**：先试 `x/player/v2`（含 WBI 签名 `wbi/v2`）读取字幕轨。
   - **有字幕** → 直接取字幕 JSON，标记 `source = subtitle`。
   - **无字幕** → 走本地 whisper：
     - `playurl` 取最低码率 `dash.audio` 并下载；
     - `ffmpeg` 转 16kHz 单声道 `wav`；
     - `whisper-cli -m <模型> -f <wav> -l auto` 转写，解析 stdout 时间戳，标记 `source = asr`。
4. **构建全文**：按分P整理为带时间戳文本，同时生成 `SRT` / `TXT` / `JSON`。
5. **导出**：写入 `baseDir/.bili-exports/<标题>.<ext>`，并返回文件路径。

## 支持范围

| 输入 | 示例 |
| --- | --- |
| BV 号 | `BV1dL8K6HEm3` |
| av 号 | `av170001` |
| b23.tv 短链 | `https://b23.tv/xxxx` |
| 完整链接 | `https://www.bilibili.com/video/BV1dL8K6HEm3` |
| 分享文本 | `【标题】 https://b23.tv/xxxx` |

- **多分P视频**：默认遍历所有分P；URL 带 `?p=N` 时只取指定分P。
- 标题、UP主、时长、来源（字幕轨 / 本地转写 / 无脚本）均会返回。

## 安装

> 通过 DeepSeek Harness 的 `dsh plugin add` 安装（本质是 pnpm 安装到 profile，并自动加入 `dsh.profile.bundles`）。

```bash
# 方式一：从 git 直接安装（推荐，含 macOS / Linux）
dsh plugin add git+https://github.com/rudyz666/dsh-bili-asr.git

# 方式二：克隆后装本地
git clone https://github.com/rudyz666/dsh-bili-asr.git
cd dsh-bili-asr
dsh plugin add ./
```

安装完成后 **重启 DSH Desktop**，`bili_script` 工具即随启动自动加载（常驻，重启不丢失）。

## 使用

重启后在聊天里贴一个 B站 链接，代理会自动调用 `bili_script`：

```
解析这个视频的脚本：BV1dL8K6HEm3
```

**返回内容**：
- 标题、UP主、时长、来源（`字幕轨` / `本地语音转写`）
- 总条数 + 带时间戳的完整文本 `[mm:ss] 内容`
- 导出文件路径（`baseDir/.bili-exports/<标题>.srt|.txt|.json`）

工具在**需要在脚本/台词/字幕**时调用，模型判断后自动触发。

## 本地转写依赖（无字幕视频需要）

**字幕轨视频开箱即用**（只走 B站 API，无需额外安装）。**无字幕视频**需要本机有 `whisper-cli` 与 `ffmpeg`：

| 平台 | 安装 | 说明 |
| --- | --- | --- |
| **macOS** | `brew install whisper-cpp ffmpeg` | 二进制在 `/opt/homebrew/bin`（Apple Silicon）或 `/usr/local/bin`（Intel） |
| **Windows** | 下载 whisper.cpp 的 `whisper-cli.exe` 与 `ffmpeg.exe`（放入 PATH 或缓存目录） | 也支持已有的 GPU(cuBLAS) 版 |
| **Linux** | 用发行版包管理器安装 `whisper-cpp` / `ffmpeg` | 或源码编译 |

> 工具会**自动下载 Whisper 模型** `ggml-large-v3-turbo-q8_0.bin`（约 **874MB，仅首次**），缓存到 `baseDir/.bili-asr/`。GPU 版 whisper 自动优先（检测到 `cublas` 目录即为 GPU）。

若二进制不在 PATH，可用环境变量指定绝对路径：

```bash
export BILI_WHISPER_BIN=/path/to/whisper-cli   # Windows 用 set
export BILI_FFMPEG_BIN=/path/to/ffmpeg
```

## 性能与无 GPU 说明

**GPU 不是必需**：插件对硬件是无感的，它只是调用 `whisper-cli`。**没有独立显卡（如 Mac、纯 CPU 机器）也能正常转写**，准确率与 GPU 版完全一致（同一 `large-v3-turbo q8_0` 模型），只是**速度慢**。

- **有 GPU（如 NVIDIA RTX，cuBLAS 版）**：芜湖，快。实测 14 分钟视频约 **30 秒**。
- **无 GPU / Mac（CPU 版）**：能跑、结果相同、耗时长。14 分钟视频通常**数分钟**（取决于芯片与机型）。

**macOS 提速可选（Apple Silicon）**：用支持 **Metal** 的构建来获得 GPU 加速。Homebrew 默认 build 不保证带 Metal，但**不带也能用**（纯 CPU）。如需要：

```bash
# 用 Metal 构建 whisper.cpp（更快的 Apple Silicon 路径）
git clone https://github.com/ggml-org/whisper.cpp && cd whisper.cpp
WHISPER_METAL=1 make -j
# 把生成的 whisper-cli 路径通过 BILI_WHISPER_BIN 指向它
export BILI_WHISPER_BIN=$PWD/whisper-cli
```

> 参考：[whisper.cpp 官方仓库](https://github.com/ggml-org/whisper.cpp)、[Homebrew whisper-cpp](https://formulae.brew.sh/formula/whisper-cpp)、[Intel Mac 用 Metal 指南](https://github.com/Retroniks/whisper-macos-metal-guide)。

> 嫌慢的话，也可换更小的模型（如 `medium` / `small`）换速度，但中文准确率略降。

## 配置

在 profile 的 `cordis.patch.yml` 里用 `- id: dsh-bili-asr` 覆盖插件配置（`config` 会整块替换，需同时给出要保留的键）：

```yaml
- id: dsh-bili-asr
  config:
    baseDir: '/Users/you/.dsh/bili-asr'   # 缓存与导出目录根
    writeFiles: true                       # 是否写导出文件（默认 true）
```

| 键 | 默认 | 说明 |
| --- | --- | --- |
| `baseDir` | `$DSH_HOME` 或 `~/.dsh/bili-asr` | 缓存 `.bili-asr/` 与导出 `.bili-exports/` 的根目录 |
| `writeFiles` | `true` | 是否把 SRT/TXT/JSON 写到磁盘 |

## 插件包结构

```
dsh-bili-asr/
├── index.js          宿主插件：注册 bili_script 模型工具（defineTool）
├── lib/
│   └── bili.js       核心：B站 API / 字幕 / whisper 转写 / 导出（纯 Node 跨平台）
├── cordis.patch.yml  注册宿主行（dsh.bundle.patch）
├── package.json      包清单（dsh.bundle.patch + 依赖 + dshhub 元数据）
├── README.md
├── LICENSE
└── screenshots/
    ├── flow.svg            提取流程
    └── architecture.svg    插件集成结构
```

<!-- 架构图见 screenshots/architecture.svg -->
<p align="center">
  <img src="screenshots/architecture.svg" alt="插件结构" width="620">
</p>

## 常见问题（FAQ）

**Q：视频有字幕，但返回"无脚本"？**
A：该视频可能只有硬字幕（烧录在画面里，不是单独字幕轨）。这种情况请依赖本地 whisper 转写；若仍报"无脚本"，检查 `whisper-cli` / `ffmpeg` 是否已安装（见上文平台表）。

**Q：报"本地 whisper/ffmpeg 二进制缺失"？**
A：说明当前机器没有这俩工具。按上表安装（macOS 用 `brew`，Windows 下载或放 PATH），或设置 `BILI_WHISPER_BIN` / `BILI_FFMPEG_BIN`。

**Q：转写很慢 / 占资源？**
A：首次会下载约 874MB 模型（仅一次）。转写用 CPU 或 GPU（优先检测 `cublas` 版）。长视频耗时随时长增长。

**Q：`git push` 时不走代理 / 连接重置？**
A：若你本机有代理（如 Clash `127.0.0.1:7890`），让 git 走代理：
```bash
git config --global http.proxy  http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
```

**Q：怎么卸载？**
A：`dsh plugin remove dsh-bili-asr`（会自动从 `dsh.profile.bundles` 移除），再重启。缓存目录 `baseDir/.bili-asr` 与导出 `baseDir/.bili-exports` 需手动删除。

## 技术说明

- 依赖 `@deepseek-ai/dsh-tools`（`defineTool`）与 `@deepseek-ai/schemastery`（`Config` schema），均为 DSH 官方包。
- 只依赖宿主侧，**无客户端 bundle**，因此无需 Web 重建，直接作为 profile bundle 加载。
- 网络统一走 B站公开 Web API（`x/web-interface/*`、`x/player/*`），并带 `User-Agent` / `Referer` 头。

## 许可

[MIT](./LICENSE)