B站评论猎手（for win） —— 哔哩哔哩评论采集工具

下载 B 站视频的全部评论（主评论 + 子评论 + 置顶），生成可供后续分析的结构化数据。

自动更新

每天自动静默更新一次。检查 /.last_update 时间戳，若超过 24 小时则执行：

git -C <skill_directory> pull --ff-only && date +%s > <skill_directory>/.last_update

拉取失败（离线/冲突/非 git 仓库等）则忽略，继续正常使用。除非用户主动询问，否则不提及更新。

适用场景

以下情况触发本技能：

• 获取/下载/导出/采集/分析指定 B 站视频的评论（BV 号、视频链接）
• 分析自己视频的受众反馈/情感/关键词/热评/IP 分布
• 用户提供了 https://www.bilibili.com/video/BVxxxxxxxxxx/ 格式的链接
• 用户提供了 UP 主 UID，需要批量分析其所有视频

不适用于：发表/删除评论、下载视频、弹幕、直播数据、私信。

前置条件

1. Python 3.9+（纯标准库，零 pip 依赖）。
2. B 站 Cookie。用户需要已登录 bilibili.com。推荐方式：
• 安装 Chrome/Edge 扩展

Get cookies.txt LOCALLY

（开源、纯本地、不上传）。

• 在已登录的 bilibili.com 页面点击 Export → 保存

www.bilibili.com_cookies.txt。

• 通过 --cookie-file 或环境变量 $BBC_COOKIE_FILE 传入。

备选方案：

• 环境变量 $BBC_SESSDATA 直接传 SESSDATA 值。
• 浏览器自动检测（Firefox 全平台；Chrome/Edge 支持 macOS 和 Windows；

搜狗浏览器支持 Windows）通过 --browser auto。Firefox 效果最佳；

Chrome/Edge 需确保已登录且 cookie 已写入磁盘。Windows 上通过 DPAPI 解密，

无需额外 pip 依赖。

认证委托：本技能不执行 OAuth 流程。用户自行在浏览器登录，工具仅读取已有 cookie。

快速开始

抓取前先验证 cookie 是否有效：

python3 -m bbc cookie-check

成功输出（stdout）：

{"ok":true,"data":{"mid":441831884,"uname":"探索未至之境","vip":false}}

抓取单个视频的全部评论：

python3 -m bbc fetch BV1NjA7zjEAU

也支持直接传链接：

python3 -m bbc fetch "https://www.bilibili.com/video/BV1NjA7zjEAU/"

输出目录（默认 ./bilibili-comments//）：

• comments.jsonl — 一行一条评论，已展开嵌套
• summary.json — 视频元数据 + 统计 + Top-N
• raw/ — 原始 API 响应存档
• .bbc-state.json — 断点续传状态

命令一览

用 bbc --help 或 bbc schema 获取完整参数说明，不要自行猜测参数名。

AI 调用规范

stdout 与 stderr 分工

• stdout：稳定 JSON 格式 {"ok":true,"data":...} 或 {"ok":false,"error":...}。非 TTY 环境默认 JSON 输出，加 --format table 切换为可读表格。
• stderr：人类可读日志 + 长任务进度事件（NDJSON 格式）。

退出码

错误返回格式

{
  "ok": false,
  "error": {
    "code": "auth_expired",
    "message": "SESSDATA 已过期，请重新登录 B 站",
    "retryable": true,
    "retry_after_auth": true
  }
}

错误码：validation_error、auth_required、auth_expired、not_found、rate_limited、api_error、network_error。详见 bbc schema。

预演模式

所有 fetch 命令均支持 --dry-run，预览将要发起的请求而不实际联网：

python3 -m bbc fetch BV1NjA7zjEAU --dry-run

幂等性

对同一输出目录重复执行 fetch 会从 .bbc-state.json 续传（跳过已抓取页）。加 --force 可强制重抓。

分析流程（供 AI 参考）

fetch 完成后：

1. 先读 summary.json（< 10 KB），建立全局认知：视频元数据、评论总数、时间分布、Top-N。
2. 主题分析：用 Grep 或 head/tail 读取 comments.jsonl — 每行一条完整 JSON，除非文件很小否则不要全量加载。
3. 典型分析方向：
• 情感分布 → 分批扫描 message 字段
• 核心粉丝 → 按 mid 分组，统计评论数，汇总 like
• UP 主互动 → 筛选 is_up_reply=true
• 受众地域 → ip_location 直方图
• 反馈时间线 → 按 ctime_iso 按日/周分桶

summary.json 结构说明见 references/agent-contract.md。可对任意视频运行以获取本地实际样本。

安全等级

所有命令均为只读（安全等级：open）。无修改、无删除、无发消息。所有 fetch 命令均支持预演模式。

参考文档

• references/api-endpoints.md — 使用的 B 站 API 字段
• references/cookie-extraction.md — 各浏览器 cookie 解密方式
• references/agent-contract.md — 完整返回格式与结构约定

已知限制

• API 返回的 all_count 包含置顶评论。完整性校验：主评论 + 子评论 + 置顶 == 声明的 all_count。
• 超过 2 年的老评论，若发布者已注销可能返回稀疏数据。
• 反爬机制：过大的 --max 值或频繁重跑可能触发 HTTP 412。客户端会在请求间等待 1 秒，遇到 412 自动退避。

踩坑经验

（以下由 AI 在实际使用中自动积累）

Windows 兼容

• 首次启动时 cookie 自动检测需要 Chrome/Edge/搜狗 浏览器已登录且 cookie 已刷新到磁盘
• DPAPI 解密依赖 PowerShell [System.Security.Cryptography.ProtectedData]::Unprotect()，无需额外安装
• 若自动检测失败，改用 $BBC_SESSDATA 环境变量或 --cookie-file 传 cookie 文件