前言¶

在 DSH 里做知识整理、长视频摘要或二次创作时，常见做法是手动复制 CC 字幕，或单独跑一套下载脚本再转 Markdown。平台字幕往往要登录才能拿到接口地址，没有字幕轨时还要另找 ASR；导出格式、清洗和时间轴对齐又各是一套工具。下面介绍社区插件 dsh-bilibili-subtitles（维护者 Chenfan2，分类：联网工具），它把「取字幕 → 清洗 → 多格式输出 → 质量报告」收进一条流水线，并可在 DSH 桌面端或 Web/CLI profile 中安装使用。

这是什么¶

dsh-bilibili-subtitles 面向 Bilibili 链接、本地视频或已有字幕文件：优先使用外挂字幕与 B 站平台/CC/AI 字幕，在不可得时再降级到内嵌轨、硬字幕 OCR 或 Whisper ASR。输出可为 Markdown、Word（.docx）、PDF、TXT、SRT 及结构化 JSON，并附带覆盖率等指标的质量报告。

仓库与说明见 GitHub；社区目录页：SkillHub 插件条目。当前 package.json 版本为 0.2.0，许可证 MIT。插件以当前 DSH 进程权限运行，安装前请自行审阅源码与许可证。

核心功能¶

输入与字幕来源¶

• B 站链接：BV/av、分 P、番剧 ep/ss、b23.tv 短链；分 P 可用 --pages auto/all/1,3-5 选择。
• 本地：视频文件配合 --subtitle 外挂字幕，或走内嵌 / OCR / ASR 路径。
• 来源优先级（README 描述）：外挂 SRT/VTT/ASS/Bilibili JSON → 平台/CC/AI 字幕 → 本地内嵌 → 硬字幕 OCR → Whisper ASR。

文档与清洗¶

• 格式：--format 支持 md,docx,pdf,txt,srt,json 组合。
• 清洗：去重、广告/水印过滤、短句合并、按语义/停顿分段、术语表（--glossary）、说话人标记保留。
• 双语：--bilingual 对两条字幕轨按时间对齐；单轨双行可自动拆分。
• 质量报告：生成 *.quality.json，含覆盖率、重叠、低置信度、乱码与语速异常等；status 为 ok / warn / fail，失败时不假装成功。

环境与可选依赖¶

• Python 3.10+；核心依赖标准库，DOCX 需 python-docx。
• 可选：faster-whisper（ASR）、LibreOffice 或 reportlab（PDF）、rapidocr_onnxruntime + ffmpeg（OCR）、ffmpeg（内嵌字幕/抽帧，也可用 imageio-ffmpeg）。

在 DSH 中优先使用 load_workspace_dependencies 提供的 Python（自带 python-docx）；ASR/PDF 等可选包可装到工作区并通过 PYTHONPATH 引入。

安装与启用¶

DSH 桌面端：侧栏「插件」→「添加插件」→ 粘贴仓库地址：

https://github.com/Chenfan2/dsh-bilibili-subtitles

Web / CLI profile（README 原文命令）：

dsh plugin --profile web add github:Chenfan2/dsh-bilibili-subtitles

仅 skill、不需要插件 UI：将插件目录复制到 $DSH_HOME/skills/dsh-bilibili-subtitles，或解压对应 zip 到该路径。

本地直接跑 Python 入口时，可在插件目录执行：

pip install -r requirements.txt
# 可选
pip install faster-whisper reportlab imageio-ffmpeg rapidocr_onnxruntime

package.json 要求 Node >=22，DSH >=0.2.0-rc.2 <0.3.0-0。

典型用法¶

平台字幕导出¶

B 站仅在登录会话下返回平台/AI 字幕的 subtitle_url。推荐设置环境变量 BILIBILI_SESSDATA（勿提交仓库或发给他人；工具不把 Cookie 写入日志/质量报告）：

$env:BILIBILI_SESSDATA = "你的 SESSDATA"
python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

也可用 --sessdata、--cookie、--cookies cookies.txt。未登录时平台字幕会报 LOGIN_REQUIRED；若已安装 faster-whisper，可加 --asr 语音转写兜底，或自备 --subtitle。

命令示例¶

# 平台字幕 → Markdown + Word
python main.py "https://www.bilibili.com/video/BV1xx411c7mD" --format md,docx

# 指定输出文件
python main.py "BV1xx411c7mD" --format docx -o "笔记.docx"

# 本地视频 + 外挂字幕
python main.py input.mp4 --subtitle input.srt --format md,docx

# 批量目录
python main.py ./videos --format md,docx --out-dir output/batch

默认输出目录为 output/。每个视频典型产物包括 <标题>_<BV号>.md、.docx、.quality.json、.segments.json；批量任务另有 _manifest.json。

常用参数节选：--timestamps / --no-timestamps、--merge-sentences、--title、--template、--asr-model small、--ocr（本地硬字幕）、--json-summary（stdout 机器可读摘要）。完整列表见 python main.py --help。

失败降级与退出码¶

README 中约定的降级顺序包括：外挂解析失败则继续平台/内嵌；需登录则提示 SESSDATA 并在允许时 ASR 兜底；无字幕轨报 NO_SUBTITLE；单格式渲染失败时其他格式仍继续。批量中单条失败不影响已成功项，错误记入 *.error.json 与 manifest。

退出码：0 成功，2 输入/API/解析，3 无字幕/需登录/质量失败，4 缺少依赖，5 渲染失败，1 未预期错误。

适用场景与注意¶

适合：需要把 B 站或本地视频字幕整理成笔记、交付稿（Word/PDF）、可检索 Markdown，或需要 SRT/JSON 进下游流水线；希望一条命令带质量报告、批量目录的场景。

局限（以 README 为准）：平台字幕受视频、账号、地区与 UP 主设置限制；AI 字幕可能有错字与时间轴漂移；双语为时间对齐而非翻译；OCR 仅本地视频且偏实验；长视频 ASR 较慢，small 模型首次下载约 460MB。仅处理你有权使用的视频与字幕；输出会保留标题、UP 主与链接以便溯源。

DSH 生态强调「一切皆插件」；SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-bilibili-subtitles 把 B 站与本地多种字幕来源统一成可交付文档，并在登录、无轨、缺依赖等情况下给出明确错误与降级路径。若要安装或查变更，请以 GitHub 仓库 与上述安装命令为准。