bbc-skill

bbc-skill — Bilibili 评论采集器

下载 Bilibili 视频的所有评论（顶层评论 + 嵌套评论 + 置顶评论）， 并生成可供 Claude Code 后续分析的数据。

更新检查

每次安装每 24 小时最多检查一次；未经用户明确同意，绝不修改技能目录。

1. 如果 <this-skill-dir>/.last_update 存在且距今不到 24 小时，则完全跳过此步骤。

2. 否则，从上游获取最新标签：

   git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
     | awk '{print $2}' | sed 's|refs/tags/||' \
     | sort -V | tail -1
   

3. 与此技能 frontmatter 中的 metadata.version 比较。如果上游标签更新（semver），告知用户一行消息并询问：

   “此技能有可用的新版本：vX.Y.Z → vA.B.C。要我执行 git pull 吗？”

   如果用户同意，运行 git -C <this-skill-dir> pull --ff-only。无论是否同意，都刷新 .last_update，避免 24 小时内重复询问。

4. 如果上游版本相同或更旧，则静默刷新 .last_update 并继续。

5. 遇到任何错误时（离线、不是 Git 检出目录——例如通过 ClawHub 安装的副本、只读路径、无权限），静默忽略错误并继续处理用户的任务。不要提及失败。

适用场景

在用户遇到以下情况时触发此技能：

• 要求获取 / 抓取 / 下载 / 导出 / 收集 / 分析某个 Bilibili 视频（BV 号、URL 或视频页面）的评论。
• 要求分析自己 Bilibili 视频的观众反馈 / 情绪倾向 / 关键词 / 热门评论 / IP 分布。
• 提供类似 https://www.bilibili.com/video/BVxxxxxxxxxx/ 的 Bilibili URL。
• 提及自己的 UP主 UID，并要求对其视频进行批量分析。

以下情况不要使用：发布 / 删除评论、下载视频、弹幕、直播数据或私信。

前提条件

1. Python 3.9+（仅使用标准库——无需安装 pip 包）。

2. Bilibili 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 值。
   • 通过 --browser auto 自动检测浏览器（macOS 上的 Firefox / Chrome / Edge）。Firefox 效果最佳；Chrome/Edge 需要使用已登录的配置文件，并已将 cookie 写入磁盘。

身份验证委托（原则 7）： 此技能不会运行 OAuth 流程。用户应通过浏览器登录；Agent 只使用由此产生的 cookie。

快速开始

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

python3 -m bbc cookie-check

成功时的响应封装（stdout）：

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

抓取单个视频的所有评论：

python3 -m bbc fetch BV1NjA7zjEAU

也可以传入 URL：

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

输出（默认路径为 ./bilibili-comments/<BV>/）：

• comments.jsonl — 每行一条评论，已扁平化
• summary.json — 视频元数据 + 统计信息 + 前 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 schema（供 Agent 发现功能使用）

查看完整参数详情，请调用 bbc <cmd> --help 或 bbc schema <cmd>——不要猜测标志名称。

Agent 契约

Stdout 与 stderr

• stdout：稳定的 JSON 封装 {"ok":true,"data":...} 或 {"ok":false,"error":...}。当 stdout 不是 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 可重新获取。

分析工作流（供 Agent 使用）

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 的 schema 记录在 references/agent-contract.md 中。 对任意视频运行此技能，即可在本地生成真实样本。

安全等级

所有命令均为只读（等级：open）。不会修改、删除或发送消息。所有 fetch 命令均支持试运行。

参考资料

• references/api-endpoints.md — 使用的 Bilibili API 字段
• references/cookie-extraction.md — 各浏览器的 Cookie 解密
• references/agent-contract.md — 完整封装 + schema 契约

限制

• API 返回的 all_count 包含置顶评论。完整性检查：top_level + nested + pinned == declared_all_count。
• 如果用户已注销，较早的评论（>2 年）可能返回的数据较少。
• 反机器人机制：过大的 --max 值或重复运行可能触发 HTTP 412。 客户端会在请求之间暂停 1 秒，并在遇到 412 时进行退避。