bilibili-source

bilibili-source

获取 Bilibili 视频的真实、可核实数据，以便引用，而不是猜测。互动数据是任何诚实分析“为什么这条视频表现不错”的基础，而手动填写或估算数据是知识库腐化最快的方式。此技能让获取数据变得轻而易举，因此没有理由编造数据。

快速开始

scripts/bili-fetch.sh BV1xxxxxxxxx

通过单次 view/detail API 调用，返回包含所有数据的一个 JSON 对象：

{
  "bvid": "BV1xxxxxxxxx",
  "aid": 1234567890,
  "fetched_at": "2026-06-07T13:54:17Z",
  "url": "https://www.bilibili.com/video/BV1xxxxxxxxx",
  "title": "<video title>",
  "up": { "name": "<UP name>", "mid": 12345678, "fans": 45600 },
  "pubdate": "2026-01-10T00:50:47Z",
  "tname": "<partition, may be empty>",
  "tags": ["<tag>", "<tag>"],
  "videos": 1,
  "duration_s": 372,
  "stat": { "view": 48000, "like": 1200, "coin": 180, "favorite": 950,
            "share": 64, "reply": 210, "danmaku": 130 },
  "pages": [ { "cid": 12345678, "page": 1, "part": "<part title>", "duration": 372 } ]
}

bili-fetch.sh 接受用户可能粘贴的任何格式——BVID、av 号、b23.tv 短链接或完整 URL——并对其进行规范化。对于多 P 视频，会在 pages[] 中返回每个分 P 的 cid（获取该分 P 的弹幕或字幕时需要对应的 cid）。

脚本

脚本	功能	登录
scripts/bili-fetch.sh <ref>	核心脚本：完整元数据 + 实时统计（先运行此脚本）	否
scripts/bili-danmaku.sh <ref> [P]	获取指定分 P 的完整弹幕文本	否
scripts/bili-subs.sh <ref> [browser]	获取字幕/转录文本轨道	是
scripts/bili-selftest.sh	测试匿名元数据、弹幕及指定 API 数据结构	否
scripts/bili-access.py	诊断身份、权限、字幕数据结构及分 P 媒体；重放/探测/验证报告	仅显式指定 Cookie 文件

Shell 获取脚本会执行（不要把它们当作参考资料阅读）。bili-danmaku.sh 会复用 bili-fetch.sh 来解析分 P 的 cid，因此两个脚本必须并列放在 scripts/ 中。

弹幕是与时间同步、叠加在视频上的评论——这是 Bilibili 特有的信号，可反映观众在何时以及如何作出反应，定性信息比单纯的回复数更丰富：

scripts/bili-danmaku.sh BV1xxxxxxxxx     # P1; add a part number for multi-part videos

确保数据真实的规则

• 实时指标 → 始终标注 fetched_at。 几分钟后重新获取同一视频，数据就会变化（一次会话中，播放量可能增加几次）。这不是错误——而是数据实时性的证明。没有时间戳的“12,000 次播放”毫无意义，而且会悄然过时。
• 严禁编造。 如果无法获取某个数字，就写“未获取/未核实”，绝不要估算。此技能的意义就在于获取数据很容易。
• 脚本已处理好网络方面的问题，不必重新折腾：它们会移除本地代理（Bilibili 是中国大陆的服务，127.0.0.1 代理会导致访问失败），发送浏览器 User-Agent 和 Referer（避免偶发的 HTTP 412），并采用退避策略重试。如果手动调用 API，也要这样做——参见 references/bilibili_api.md。有一个陷阱，移除环境变量无法解决：代理环境变量缺失时，Python urllib 会回退到 macOS 系统代理，导致批量请求间歇性出现 503——请使用显式的 ProxyHandler({}) 构建 opener（详见参考文档中的 Request basics）。
• CJK 后处理陷阱。 后续对获取的中文文本或文件名执行 grep/sort 时，sort/comm 可能会错误处理 CJK 排序规则，并报告虚假的“缺失”/“损坏”结果。请用 find -name 或 grep -F 验证，不要用 comm。

字幕需要登录（不可绕过）

统计数据和弹幕无需登录。字幕则需要登录。 已在许多新旧视频以及匿名 Cookie 上进行验证：匿名请求时，公开播放器 API 返回的字幕列表为空，yt-dlp 也会提示 “Subtitles are only available when logged in.”。不存在免登录途径——不要尝试绕过限制。

因此，bili-subs.sh 需要通过浏览器 Cookie 获取用户的 Bilibili 会话。由于它会读取用户的登录会话，运行前请先征得用户同意：

scripts/bili-subs.sh BV1xxxxxxxxx chrome   # or firefox / safari / edge

ai-zh 轨道是 Bilibili 自动生成的 AI 字幕——应将其视为转录草稿（可能存在同音字和分段错误），并在生成内容中标记为 AI-ASR，不要声称这是经人工校对的逐字稿。如果视频没有字幕轨道，就没有内容可获取——不要编造字幕。参考文档中介绍了使用 SESSDATA 环境变量调用 API 的替代方案。

下载或进行 ASR 前诊断访问权限

对已获授权的来源运行 scripts/bili-access.py probe --bvid BV0000000000 --page 1；仅当该账号访问已获授权时，才添加 --cookie-file <authorized-netscape-jar>。此诊断绝不读取任意浏览器 Cookie。省略 --cid，以便从 view 元数据解析所选 P。诊断现有证据时，离线重放捕获的 nav/view/player/playurl/ffprobe JSON。

下载前检查 download_allowed；只有在 verify-report 读取了实际 ASR 输入的最新 ffprobe 后，才检查 asr_allowed。将经过身份验证的身份与目标视频的付费权益分开处理：仅登录会员身份并不意味着可以观看每位创作者的付费视频。如果是付费预览、权益被拒绝或状态未知，请停止；不要将预览内容送去进行完整内容的 ASR。将时长与所选 CID/P 比较，而非多分 P 视频的总时长。有关 JSON 状态、命令和退出码，请阅读访问诊断契约；在仓库根目录运行 uv run python -m unittest discover -s bilibili-source/tests -v，以进行确定性的合成测试。

在将故障归因之前，请检查每个 interfaces 条目的 http 和可选的 error：HTTP 403/412 响应会保留其状态，不代表网络故障或 Cookie 已过期。网络错误、超时和无效 JSON 有各自独立的类别；这些诊断无法证明拥有付费权益。

深入了解

如需查看完整的端点目录（UP 粉丝历史、视频标签、实时观看人数、弹幕存档、SESSDATA 字幕路径、收藏夹枚举——x/v3/fav/*，需要登录，无需 WBI）、space/wbi/* 端点所需的 WBI 请求签名算法，以及每个注意事项和经过测试的命令，请参阅 references/bilibili_api.md。

已验证状态

• 统计数据／元数据／弹幕（view/detail、relation/stat、dm/list.so、online/total）：已于 2026-06-07 验证，无需登录。多次重新获取指标，结果均相符且经独立核对；弹幕数量与 stat.danmaku 相符。
• 字幕：已于 2026-06-07 确认需要登录（所有测试视频对匿名用户均返回空结果）。Cookie 路径需要 yt-dlp。SESSDATA/Cookie jar API 路径已于 2026-08-29 验证，测试范围约 400 个视频（包括分 P 视频）。
• 收藏夹（x/v3/fav/folder/created/list-all、x/v3/fav/resource/list）：已于 2026-08-29 验证，登录状态下使用不带 WBI 的普通参数；连续获取 26 页，未触发速率限制。枚举需要登录（即使账号有公开可读的收藏夹，匿名用户调用 list-all 也会收到 code 0 和空列表）；只有在已知媒体 ID 的情况下，匿名用户才能读取公开收藏夹的内容。

维护

此技能封装了一个会随时间变化的第三方 API——字段可能重命名，端点可能新增 WBI 签名，反机器人机制也可能加强。长时间未使用后，或输出看起来不正确时，在信任它之前请运行健康检查：

scripts/bili-selftest.sh

它会针对一个公开样例测试匿名元数据、弹幕和选定的端点结构，并打印 PASS/FAIL 行。它不会测试经过身份验证的内容获取、目标付费权益或媒体完整性；通过仅代表打印出来的检查项通过，不代表没有静默的错误结果。某行检查失败时，可在 references/bilibili_api.md 中找到修复所需的端点路径、字段名和 WBI 签名；重新确认后，请更新上方的“已验证”日期。