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

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

自动更新

每天自动静默更新一次。检查 <skill_directory>/.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，需要批量分析其所有视频

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

前置条件

Python 3.9+（纯标准库，零 pip 依赖）。
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/<BV>/）：

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

命令一览

| 命令 | 用途 | |---|---| | bbc fetch <BV\|URL> | 抓取单个视频全部评论 | | bbc fetch-user <UID> | 批量抓取某 UP 主所有视频的评论 | | bbc summarize <dir> | 基于已有 comments.jsonl 重建 summary.json | | bbc cookie-check | 验证 cookie 是否有效，打印当前登录用户 | | bbc schema [cmd] | 返回命令的 JSON 结构（供 AI 自动识别） |

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

AI 调用规范

stdout 与 stderr 分工

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

退出码

| 码 | 含义 | |---|---| | 0 | 成功 | | 1 | 运行时/API 错误 | | 2 | 认证错误（cookie 无效/缺失） | | 3 | 参数校验错误（BV 号格式错误、非法参数） | | 4 | 网络错误（超时/重试耗尽） |

错误返回格式

{
  "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 完成后：

先读 summary.json（< 10 KB），建立全局认知：视频元数据、评论总数、时间分布、Top-N。
主题分析：用 Grep 或 head/tail 读取 comments.jsonl — 每行一条完整 JSON，除非文件很小否则不要全量加载。
典型分析方向：
- 情感分布 → 分批扫描 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 文件