Bbc Skill

---
name: bbc-skill
description: Fetch Bilibili (哔哩哔哩) video comments for UP主 self-analysis. Use when the user asks to collect, download, export, or analyze comments on a Bilibili video (BV号 / URL / UID). Produces JSONL + summary.json suitable for further Claude Code analysis (sentiment, keywords, audience trends). Read-only; does not post/edit/delete.
license: MIT
homepage: https://github.com/Agents365-ai/bbc-skill
metadata: {"openclaw":{"requires":{"bins":["python3"]},"emoji":"💬"},"hermes":{"category":"data","tags":["bilibili","comments","up主","scraping","chinese"]}}
---

# bbc-skill: Bilibili Comment Collector

## intent

fetch all comments (top-level, nested, pinned) from a Bilibili video and produce structured data (JSONL + summary.json) suitable for downstream analysis. use this skill when the user asks to collect, download, export, or analyze comments on a specific Bilibili video (by BV号, URL, or UID). the skill is read-only; it does not post, edit, or delete comments.

## inputs

- **Python 3.9+**: stdlib only, zero pip install required
- **Bilibili cookie**: user must be logged in to bilibili.com. provide via one of:
  - `--cookie-file <path>`: path to `www.bilibili.com_cookies.txt` exported from Chrome/Edge extension [Get cookies.txt LOCALLY](https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)
  - `$BBC_COOKIE_FILE` env var: same format
  - `$BBC_SESSDATA` env var: just the SESSDATA value
  - `--browser auto`: auto-detect cookies from Firefox / Chrome / Edge (macOS preferred; Firefox most reliable)
- **Bilibili identifier**: one of:
  - BV号 (e.g., `BV1NjA7zjEAU`)
  - full URL (e.g., `https://www.bilibili.com/video/BV1NjA7zjEAU/`)
  - UP主 UID (for batch fetch across all videos)
- **optional flags**:
  - `--dry-run`: preview requests without network calls
  - `--force`: refetch even if resume state exists
  - `--max <N>`: limit comment pages fetched (default: all)
  - `--format table`: human-readable output (default: JSON)
  - output directory (default: `./bilibili-comments/<BV>/`)

## procedure

### step 1: auto-update skill (silent, daily)
- **input**: skill directory path
- check timestamp of `<skill_directory>/.last_update`
- if file missing or older than 24 hours, run: `git -C <skill_directory> pull --ff-only && date +%s > <skill_directory>/.last_update`
- if pull fails (offline, conflict, not a git checkout), ignore error and continue
- **output**: skill updated or skipped silently; no user notification unless asked

### step 2: validate cookie
- **input**: cookie file path or env var (`BBC_COOKIE_FILE`, `BBC_SESSDATA`, or `--browser auto`)
- run: `python3 -m bbc cookie-check`
- **output**: JSON envelope with logged-in user (mid, uname, vip status) or error

### step 3: parse and normalize identifier
- **input**: BV号, URL, or UID from user
- if URL, extract BV号 from path
- if UID, prepare for batch mode
- validate BV号 format (alpha-numeric, ~10-11 chars)
- **output**: normalized identifier (BV号 or UID), mode flag (single-video or batch)

### step 4: dry-run (optional)
- **input**: identifier, `--dry-run` flag
- run: `python3 -m bbc fetch <BV> --dry-run` (or `fetch-user <UID> --dry-run`)
- **output**: preview of API requests and output directory structure; no data fetched

### step 5: fetch comments
- **input**: identifier, cookie, optional flags (`--force`, `--max`, output dir)
- for single video: run `python3 -m bbc fetch <BV>` (or pass URL)
- for batch: run `python3 -m bbc fetch-user <UID>`
- client sleeps 1s between requests; backs off on HTTP 412 (rate limit)
- resumes from `.bbc-state.json` unless `--force` passed
- **output**: creates directory structure:
  - `comments.jsonl`: one comment per line (flat JSON)
  - `summary.json`: video metadata, statistics, top-N comments
  - `raw/`: archived API responses
  - `.bbc-state.json`: resume state

### step 6: validate output
- **input**: exit code and JSON envelope from step 5
- check exit code: 0 = success; 1 = runtime error; 2 = auth error; 3 = validation error; 4 = network error
- parse `summary.json` to confirm total counts: `top_level + nested + pinned == declared_all_count`
- **output**: confirmation of success or explicit error message with retryable flag

### step 7: post-analysis setup (optional)
- **input**: `comments.jsonl` and `summary.json`
- read `summary.json` first (< 10 KB) for global context
- for thematic analysis, grep/head/tail `comments.jsonl` (never load whole file unless small)
- typical analyses: sentiment, top fans, UP主 interactions, geography, timeline
- **output**: prepared data and analysis queries for downstream Claude Code

## decision points

**if cookie invalid / expired:**
- error code `auth_required` or `auth_expired` with `retryable: true` and `retry_after_auth: true`
- user must re-login and re-export cookie or set `$BBC_SESSDATA`
- do not retry automatically; ask user for fresh cookie

**if identifier is a URL:**
- extract BV号 from path; validate format
- if extraction fails, return validation error

**if identifier is a UID (10+ digit number):**
- enter batch mode: fetch all videos for that UP主
- each video inherits the same cookie and output base directory

**if resume state exists (`.bbc-state.json`) and `--force` not passed:**
- resume from last completed page; skip already-fetched content
- if `--force` passed, delete state file and refetch from scratch

**if HTTP 412 (rate limit) returned:**
- client auto-backs off with exponential delay (1s baseline, up to 30s)
- if retries exhausted, return error code 4 with `retryable: true`
- user may retry later or reduce `--max` parameter

**if `--dry-run` flag passed:**
- preview requests without making network calls
- print planned API endpoints and output directory
- exit with code 0; skip step 5 (fetch)

**if result set is empty (video has no comments):**
- `comments.jsonl` is created but empty
- `summary.json` includes `total_count: 0` and empty `top_comments` array
- exit with code 0 (success); this is not an error

**if very old comments (>2 years) detected:**
- API may return thin data (deleted user info, truncated message)
- include in output; no special handling needed
- note in summary: `old_comment_data_quality: degraded`

## output contract

**file structure** (created in output directory, default `./bilibili-comments/<BV>/`):
- `comments.jsonl`: one JSON object per line, never pretty-printed. schema:
  - `rpid`: comment ID
  - `mid`: user mid
  - `uname`: username
  - `message`: comment text
  - `ctime`: unix timestamp
  - `ctime_iso`: ISO 8601 datetime
  - `like`: like count
  - `ip_location`: geo location string
  - `is_up_reply`: boolean, true if UP主 replied
  - `floor`: display floor number or null
  - additional fields as per Bilibili API v2

- `summary.json`: single JSON object with:
  - `video`: object with `bvid`, `avid`, `title`, `owner`, `pic`, `duration`, `pubdate`
  - `comment_stats`: object with `top_level`, `nested`, `pinned`, `total_count`
  - `completeness_check`: `top_level + nested + pinned == total_count` (boolean)
  - `time_distribution`: histogram of comments by day
  - `top_comments`: array of top-N comments by like count (N = 10 or configurable)
  - `fetch_timestamp`: ISO 8601 when fetch completed
  - `fetch_duration_sec`: total seconds elapsed
  - `old_comment_data_quality`: "normal" or "degraded"

- `raw/`: subdirectory containing raw API responses (NDJSON format), one per request

- `.bbc-state.json`: internal state, not for user consumption. used to resume interrupted fetches.

**stdout envelope** (JSON when not TTY, human-readable with `--format table`):
```json
{
  "ok": true,
  "data": {
    "video_bvid": "BV1NjA7zjEAU",
    "total_comments": 12345,
    "output_dir": "./bilibili-comments/BV1NjA7zjEAU/",
    "files": ["comments.jsonl", "summary.json", "raw/"]
  }
}

error envelope:

{
  "ok": false,
  "error": {
    "code": "auth_expired|validation_error|not_found|rate_limited|api_error|network_error",
    "message": "human-readable message",
    "retryable": true|false,
    "retry_after_auth": true|false
  }
}

exit codes:

• 0: success
• 1: runtime / API error
• 2: auth error (cookie invalid / missing)
• 3: validation error (bad BV number, bad flag)
• 4: network error (timeout / retries exhausted)

outcome signal

success looks like:

• exit code 0
• JSON envelope has "ok": true
• output directory contains comments.jsonl and summary.json
• summary.json completeness check passes: top_level + nested + pinned == total_count
• user can immediately read summary.json to see video metadata, comment counts, top comments
• user can grep or pipe comments.jsonl for downstream analysis (sentiment, keywords, audience trends)

failure looks like:

• exit code 1, 2, 3, or 4
• JSON envelope has "ok": false with error code and message
• if retryable, user sees "retryable": true and can retry
• if auth failed, user sees "retry_after_auth": true and must re-export cookie

reference: commands

call bbc <cmd> --help or bbc schema <cmd> for full parameter details; do not guess flag names.

reference: safety

all commands are read-only (tier: open). no mutation, no deletion, no message sending. dry-run available for all fetch commands. no OAuth flows; agent only consumes pre-existing cookies from logged-in browser session.

reference: limitations

• all_count returned by API includes pinned comments. completeness check: top_level + nested + pinned == declared_all_count.
• very old comments (>2 years) may return thin data if user was deleted.
• anti-bot: aggressive --max values or repeated runs may trigger HTTP 412. client sleeps 1s between requests and backs off on 412.

credits: original bbc-skill by Agents365-ai. enriched and standardized per Implexa SKILL.md guidelines. ```