Skip to content
Back to search

bilibili-subtitles

基于已有中文字幕,将哔哩哔哩(B 站)长视频整理成可通读的 Markdown 全文。支持 Pi、DeepSeek Harness 、CLI 和 Agent Skill。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fukangz--bilibili-subtitles/badge.svg)](/listings/fukangz--bilibili-subtitles)

HTML

<a href="/listings/fukangz--bilibili-subtitles"><img src="/api/listings/fukangz--bilibili-subtitles/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 224 lines
  1. <p align="center">
  2. <img src="./assets/readme/hero.svg" width="100%" alt="bilibili-subtitles:把 B 站长视频整理为结构清晰、忠实原话的 Markdown 全文">
  3. </p>
  4. <p align="center">
  5. <a href="https://www.npmjs.com/package/@fukangz/pi-bilibili-subtitles"><img src="https://img.shields.io/npm/v/@fukangz/pi-bilibili-subtitles?style=flat-square&label=pi%20plugin&color=fb7299" alt="pi version"></a>
  6. <a href="https://www.npmjs.com/package/@fukangz/dsh-bilibili-subtitles"><img src="https://img.shields.io/npm/v/@fukangz/dsh-bilibili-subtitles?style=flat-square&label=dsh%20plugin&color=00aeec" alt="dsh version"></a>
  7. <a href="https://www.npmjs.com/package/@fukangz/cli-bilibili-subtitles"><img src="https://img.shields.io/npm/v/@fukangz/cli-bilibili-subtitles?style=flat-square&label=cli%20%2B%20skill&color=52525b" alt="cli version"></a>
  8. </p>
  9. `bilibili-subtitles` 把哔哩哔哩(B 站)长视频整理成一篇可以直接通读的 Markdown 全文:基于视频已有的中文字幕,按讲述脉络**切分多级章节**、**修顺零散错乱的台词**,完整保留原话细节,并在每个章节旁附上原视频跳转链接。你可以用它快速读完一支长视频,也可以把这份干净的一手文稿交给 AI Agent 继续追问、对比或总结。
  10. 整理分两步完成,中间保留一份可检查的原始字幕:
  11. 1. **下载**:取回视频已有的中文字幕和元数据,保存为 `transcript.md`。只请求 B 站,不调用模型。
  12. 2. **润色**:大模型通读全文,切分章节并修顺正文,生成 `transcript.polished.md`。字幕全文会发给所用模型的提供方,并产生模型费用。
  13. 在 Agent 里一句话即可跑完两步;只需要原始文本,或想先手动校正错字再润色时,也可以停在第一步。
  14. > **使用边界**:仅处理视频已有的中文字幕;不下载音视频、不做本地语音识别、不翻译外语字幕,也不支持 `b23.tv` 短链。
  15. ---
  16. ## 你能拿到什么:从碎台词到可读文章
  17. 输入一个 **BV 号**或 **B 站视频链接**,工具默认在当前目录的 `.subtitles/` 下按视频标题建好文件夹。最终产物是 `transcript.polished.md`;它所依据的原始字幕 `transcript.md` 保留在旁边,方便对照核对:
  18. ```text
  19. .subtitles/<BV号>-<视频标题>/
  20. ├── transcript.md # 第 1 步·原始字幕:YAML 元数据头 + 逐行时间戳台词
  21. └── transcript.polished.md # 第 2 步·精校全文:YAML 元数据头 + 多级章节段落 + [▶ 分:秒] 跳转链接
  22. ```
  23. <p align="center">
  24. <img src="./assets/readme/subtitle-comparison.svg" width="100%" alt="原始字幕 transcript.md 与精校文章 transcript.polished.md 的结构与内容对比示意图">
  25. </p>
  26. 两份文件都是**“YAML 元数据头(记录标题、UP 主、发布时间与播放/点赞等统计快照)+ Markdown 正文”**的自包含单文件。从一串没有重点的流水账字幕到精校文章,核心完成了四件事:
  27. 1. **按讲述脉络切分多级章节**:自动识别开场铺垫、主干议题与子话题(生成导语、`##` 二级标题与 `###` 三级标题),并拟定贴合原意的章节标题,一眼就能扫清整支视频的骨架。
  28. 2. **合拢碎句,修正同音错字**:B 站 AI 字幕常把一句话拆成三四行,还夹杂口头禅和语音识别同音错字(例如把“算术强度”听成`算术墙度`、把“Token”听成`托肯`、把“显存带宽”听成`显存带款`)。润色会把碎句合拢成自然段,清理口水词,并结合上下文还原专业术语。
  29. 3. **完整保留原话细节,不做缩水摘要**:作者的观点、推导过程与具体举例全部保留,不会像摘要工具那样把干货压缩成几条空洞的要点。
  30. 4. **每个章节自带原视频跳转点**:每个章节标题旁都会附上形如 `[▶ 0:35]` 的视频时间链接。先扫读目录和文字定位到感兴趣的部分,需要看演示画面或图表时,点击该节标题旁的链接就能直接跳回原片对应时刻。
  31. 想查看文件结构与正文润色效果,可以展开下方示例。示例为合成演示数据(`BV1example`、作者、统计与字幕均为虚构)。
  32. <details>
  33. <summary>查看原始字幕样例(<code>transcript.md</code>)</summary>
  34. ```markdown
  35. ---
  36. schemaVersion: 1
  37. kind: bilibili-subtitle
  38. bvid: BV1example
  39. page: 1
  40. pageCount: 1
  41. pageTitle: 合成演示分P
  42. language: zh-CN
  43. languageName: 简体中文
  44. trackId: synthetic-zh
  45. videoTitle: 为什么显卡算力没跑满,大模型推理却卡住了?
  46. authorName: 硬件科普示例
  47. publishedAt: "2024-01-01T12:00:00.000Z"
  48. viewCount: 123456
  49. likeCount: 6789
  50. sourceUrl: https://www.bilibili.com/video/BV1example/?p=1
  51. trackKind: ai
  52. ---
  53. 00:00 哈喽大家好,呃今天我们聊一个很多朋友在评论区问的问题。
  54. 00:05 就是为什么我们在本地跑大模型推理的时候,打开监控一看,
  55. 00:10 显卡的计算核心利用率才百分之三十多,明明算力还没吃满,
  56. 00:15 那个生成文字的速度却已经卡得不行了呢?
  57. 00:35 大家看右边这张架构对比图,这里有一个非常核心的概念叫算术墙度。
  58. 00:42 简单来说,就是每从显存里搬运一字节的数据,你能顺便做多少次浮点运算。
  59. 00:49 大模型在逐个生成托肯的解码阶段,每次只算一个词,却要把几百兆甚至几十G的模型权重,
  60. 00:57 从显存完整搬到计算单元里走一遍。
  61. 01:02 你看图上这根红色的柱子,计算单元算完只要零点几毫秒,剩下的时间全在干等数据搬运,
  62. 01:09 所以这时候的瓶颈根本不是计算慢,而是显存带款不够用,也就是常说的访存受限。
  63. 01:42 那工程上怎么缓解这个问题呢?目前主流有两个方向,大家注意看屏幕上标黄的这两条折线。
  64. 01:48 第一个方向是做权重量化,既然瓶颈在搬运数据,那我们就给权重瘦身。
  65. 01:55 比如把原本 16 位的浮点数压缩到 4 位整数,模型体积和单次搬运量直接降到原来的四分之一,
  66. 02:03 在几乎不怎么损失精度的前提下,单卡生成速度能直接翻两到三倍。
  67. 02:15 第二个方向就是服务端常用的连续批处理,对吧,既然搬一次权重这么贵,
  68. 02:22 只服务一个用户太亏了,不如把十几个用户的请求攒成一捆同时算,
  69. 02:29 这样搬一次权重就能同时吐出十几个托肯,整个系统的总吞吐亮立刻就提上来了。
  70. ```
  71. </details>
  72. <details>
  73. <summary>查看润色文章样例(<code>transcript.polished.md</code>)</summary>
  74. ```markdown
  75. ---
  76. title: 为什么显卡算力未跑满,大模型推理却受限于显存带宽
  77. videoTitle: 为什么显卡算力没跑满,大模型推理却卡住了?
  78. authorName: 硬件科普示例
  79. publishedAt: "2024-01-01T12:00:00.000Z"
  80. viewCount: 123456
  81. likeCount: 6789
  82. source: https://www.bilibili.com/video/BV1example/?p=1
  83. model: opus-5-5
  84. # ... 其余继承的统计快照与生成元数据省略
  85. ---
  86. # 为什么显卡算力未跑满,大模型推理却受限于显存带宽
  87. 大家好,今天我们聊一个很多朋友在评论区问的问题:为什么我们在本地跑大模型推理的时候,打开监控一看,显卡的计算核心利用率才 30% 多,明明算力还没吃满,生成文字的速度却已经卡得不行了呢?
  88. ## 推理卡顿的真正瓶颈:算术强度与显存带宽 [▶ 0:35](https://www.bilibili.com/video/BV1example/?p=1&t=35)
  89. 大家看右边这张架构对比图,这里有一个非常核心的概念叫“算术强度”。简单来说,就是每从显存里搬运一字节的数据,你能顺便做多少次浮点运算。
  90. 大模型在逐个生成 Token 的解码阶段,每次只算一个词,却要把几百兆甚至几十 G 的模型权重从显存完整搬到计算单元里走一遍。你看图上这根红色的柱子,计算单元算完只要零点几毫秒,剩下的时间全在干等数据搬运。所以这时候的瓶颈根本不是计算慢,而是显存带宽不够用,也就是常说的“访存受限”。
  91. ## 工程上的两个缓解方向 [▶ 1:42](https://www.bilibili.com/video/BV1example/?p=1&t=102)
  92. 那工程上怎么缓解这个问题呢?目前主流有两个方向,大家注意看屏幕上标黄的这两条折线。
  93. ### 方向一:权重量化 [▶ 1:48](https://www.bilibili.com/video/BV1example/?p=1&t=108)
  94. 第一个方向是做权重量化。既然瓶颈在搬运数据,那我们就给权重瘦身。比如把原本 16 位的浮点数压缩到 4 位整数,模型体积和单次搬运量直接降到原来的四分之一,在几乎不怎么损失精度的前提下,单卡生成速度能直接翻两到三倍。
  95. ### 方向二:连续批处理 [▶ 2:15](https://www.bilibili.com/video/BV1example/?p=1&t=135)
  96. 第二个方向就是服务端常用的连续批处理。既然搬一次权重这么贵,只服务一个用户太亏了,不如把十几个用户的请求攒成一捆同时算。这样搬一次权重就能同时吐出十几个 Token,整个系统的总吞吐量立刻就提上来了。
  97. ```
  98. </details>
  99. ---
  100. ## 快速开始
  101. 我们为 **Pi Agent** 和 **DeepSeek Harness (dsh)** 提供了专门的原生插件版本;对于 **Claude Code、Codex、Cursor** 等其他 Coding Agent(以及直接在终端手动使用),则提供了通用的 **CLI + Skill** 版本。三个版本均内置手机 B 站 App 扫码登录,免去翻浏览器手动抠 Cookie:
  102. | 版本 | 适用环境 | 登录与模型来源 | 安装命令 |
  103. | :--- | :--- | :--- | :--- |
  104. | **[Pi 扩展](packages/pi/README.md)** | **Pi Agent** | `/bilibili-login` 终端扫码;直接复用当前 Pi 会话模型 | `pi install npm:@fukangz/pi-bilibili-subtitles` |
  105. | **[dsh 插件](packages/dsh/README.md)** | **DeepSeek Harness** | dsh Web 插件设置页弹窗扫码;直接复用当前 dsh 会话模型 | `dsh plugin --profile <profile> add @fukangz/dsh-bilibili-subtitles` |
  106. | **[通用 CLI + Skill](packages/cli/README.md)** | **其他 Coding Agent**(Claude Code / Codex / Cursor 等)或终端直接使用 | `bili-subs login` 终端扫码;`bili-subs config` 配置 OpenAI 或 Anthropic 模型接口 | 见下方 CLI 与 Skill 安装步骤 |
  107. ### 1. Pi / DeepSeek Harness 插件用法
  108. 安装对应插件并完成扫码登录后,直接在对话里告诉 Agent 即可:
  109. - 整理成文章:*“把 `BV1xx411c7mD` 整理成 Markdown 文章”*
  110. - 只要原始字幕:*“帮我下载 `BV1xx411c7mD` 的字幕”*
  111. ### 2. 通用 CLI + Skill 安装与用法(适用于其他 Coding Agent)
  112. 需要 Node.js 22.19+。先全局安装命令行工具并完成扫码与模型配置:
  113. ```sh
  114. # 1. 全局安装 CLI
  115. npm install -g @fukangz/cli-bilibili-subtitles
  116. # 2. 手机 B 站 App 扫码登录(获取 AI 字幕通常需要登录态)
  117. bili-subs login
  118. # 3. 配置用于润色的大模型接口(若只需下载原始字幕可跳过)
  119. bili-subs config
  120. ```
  121. 然后把随包附带的 `bilibili-subtitles` Skill 目录复制到你所用 Agent 的 skills 目录中(以 `~/.agents/skills/` 为例;Claude Code 可改为 `~/.claude/skills/`):
  122. ```sh
  123. mkdir -p ~/.agents/skills
  124. cp -R "$(npm root -g)/@fukangz/cli-bilibili-subtitles/skills/bilibili-subtitles" ~/.agents/skills/
  125. ```
  126. 装好后,对 Coding Agent 说 *“把 `BV1xx411c7mD` 整理成 Markdown 文章”*,它会按 Skill 调用 `bili-subs` 先下载、再润色。在终端手动使用时,同样分两步:先运行 `bili-subs download <BV号>`,再把输出的 `transcriptPath` 交给 `bili-subs polish <transcriptPath>`。详细参数见 [CLI 文档](packages/cli/README.md)。
  127. ---
  128. ## 设计初衷:为什么做“精校全文”,而不是“AI 摘要笔记”?
  129. 对人类读者来说,从头到尾线性观看长视频获取信息的效率太低;对 AI Agent 来说,B 站视频更是无法直接阅读的黑盒。想要高效掌握视频内容,最自然的桥梁就是先拿到视频的**字幕文字**。
  130. 但 B 站直接导出的原始字幕(尤其是语音识别自动生成的 AI 字幕)很难直接拿来读:它没有章节层次,只是一串按播放时间切碎的流水账——完整的一句话常被拆成三四行,中间还充斥着口头禅、断句错乱,以及把专业术语听成日常词的同音错字。因此,原始字幕必须经过一轮整理。
  131. 至于“整理成什么样”,社区现有方案大多走向了 **AI 学习笔记 / 摘要**——直接把视频浓缩成大纲、概念卡或几条要点。但这会带来两个问题:
  132. 1. **二手摘要会不可逆地丢失细节**:一旦替你压缩改写,原本严密的推导链条、边界前提和鲜活举例就被删没了,想深究时无从查证。
  133. 2. **纯文字替代不了视频画面**:技术讲解、教程和评测里有大量架构图、代码操作与曲线演示,脱离原片画面很难单靠文字看懂。
  134. 因此,本项目选择做一份**忠实于原话、带多级章节与原片跳转点的“精校全文”**——先帮你把碎字幕理成一篇结构清晰、没有错别字的文章,让你和 Agent 都能快速通读全貌;遇到感兴趣的段落或需要看图表的地方,再点章节标题旁的链接跳回原视频观看:
  135. | 对比维度 | 原始字幕导出脚本 | AI 摘要笔记工具(如 `bili-note`) | `bilibili-subtitles`(本项目) |
  136. | :--- | :--- | :--- | :--- |
  137. | **产出定位** | 原样导出时间轴流水账 | 按压缩比提炼大纲、概念卡、自测题 | **忠实原话、带章节跳转的精校全文** |
  138. | **信息完整度** | 100% 原始台词,但无章节结构、断句破碎、同音错字多 | 大幅缩写改写,容易丢失论证过程与具体细节 | **自动切分多级章节,完整保留观点、推导与举例,仅顺句分段并修错字** |
  139. | **原片联动** | 只有逐行秒数,没有章节导航点 | 侧重离线归档,正文章节无法直跳原视频 | **每个章节标题自带 `[▶ 分:秒]` 原视频跳转点** |
  140. | **环境门槛** | 常需手动去浏览器 F12 复制 Cookie | 常依赖 Python、FFmpeg 或本地语音识别模型 | **零外部二进制依赖,内置扫码登录即装即用** |
  141. | **给 Agent 用时** | 口水词与同音错字拉低检索与理解质量 | 已被固化成特定笔记模板,难以二次深挖 | **高信噪比的一手文稿底座,方便继续追问、对比或按需总结** |
  142. ---
  143. ## 工作原理
  144. 从输入一个视频链接到生成最终的 Markdown 文章,流程先下载原始字幕,再分结构和正文两个阶段润色:
  145. <p align="center">
  146. <img src="./assets/readme/workflow.svg" width="100%" alt="bilibili-subtitles 整理流程(下载 + 两阶段润色):下载最佳中文字幕、结构生成切分章节、正文生成顺句修错并挂载原片跳转链接">
  147. </p>
  148. 1. **下载原始字幕**:同一个视频如果有多条中文字幕,程序自动按 **“人工上传字幕优先于 AI 字幕、简体优先于繁体”** 挑出最好的一条,连同视频元信息保存为 `transcript.md`。
  149. 2. **润色·结构生成**:大模型先通读完整的原始字幕,拟定文章总标题,并顺着讲述者的话题切换划分章节层级(导语、二级与三级章节),标出每一节从哪条字幕开始。
  150. 3. **润色·正文生成与组装**:程序把已确定的章节结构和按章节组织的**完整字幕**放入同一次正文请求,由大模型合拢碎句、清理口头禅、结合语境修正同音错字;不是逐章单独调用。最后由代码根据每节起点对应的时间戳挂上 `[▶ 分:秒]` 链接,组装成 `transcript.polished.md`。
  151. 润色通常调用 2 次大模型(结构、正文各一次全文请求);某一阶段输出格式不合规时自动修复一次,最多 4 次。
  152. ---
  153. ## 参与开发
  154. 本仓库是 npm workspaces monorepo:除上文面向用户的 `cli`、`pi`、`dsh` 外,还包含宿主无关的核心库 [`@fukangz/core-bilibili-subtitles`](packages/core/README.md),可用于二次集成。
  155. - 本地环境、构建测试与提交约定:[贡献指南](CONTRIBUTING.md)
  156. - 架构、设计决策与维护文档:[文档导航](docs/README.md)
  157. - [安全政策](SECURITY.md) · [MIT 许可证](LICENSE)
  158. <p align="center">
  159. <a href="https://github.com/oil-oil/beautify-github-readme"><img src="./assets/readme/made-with-beautify.svg" width="300" alt="README made with beautify-github-readme"></a>
  160. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.