# Bilibili Search

> Search for videos on Bilibili using keyword queries generated from user interests.

- Skill: `whiteguo233/bilibili-search` (Agent Skill)
- Install (CLI): `npx skillmds add whiteguo233/bilibili-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/whiteguo233/bilibili-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: whiteguo233 (https://skillmd.com/u/whiteguo233)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/whiteguo233/bilibili-search

---


# Bilibili Search Skill

Search for videos on Bilibili based on the user's interests and soul profile. Supports both LLM-driven automatic query generation (for discovery cycles) and direct keyword search (for explicit user requests).

## When to Use

- During content discovery cycles
- When the user explicitly asks to find content on a topic
- When generating exploratory searches for new interest domains

## How It Works

1. **Query generation** — If no explicit `keywords` are provided, the skill uses an LLM to generate multiple search queries from the user's soul profile (top interests, cognitive style, deep needs). If `keywords` are provided, they are used directly.
2. **Sequential search** — Each query is sent to the Bilibili WBI-signed search endpoint sequentially, with a jitter-randomised 0.5–1.0s delay between queries (v0.3.61+) so the requests don't land in the same Bilibili rate-limit bucket. A dedicated API client is used per strategy to isolate rate-limiting.
3. **Resilience & storm mode** — Individual query failures (including Bilibili `412 Precondition Failed`) degrade gracefully and don't interrupt the overall flow. `client.search` retries `v_voucher` challenges 3× internally; three consecutive empty results trip "storm mode" (v0.3.61+) and the remaining queries are skipped (filled with empty results) rather than burned against an IP that's being challenged — the next refresh tick (~60s) gets a fresh shot. An active search cooldown short-circuits the remaining plan the same way.
4. **Scoring** — Results are evaluated against the soul profile via LLM and assigned a `relevance_score` (0.0–1.0). Items below the threshold are discarded.
5. **Output** — Returns scored `DiscoveredContent` items.

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `keywords` | `string` | No | `""` | Search query string. If empty, the skill auto-generates queries from the soul profile. |
| `page` | `integer` | No | `1` | Page number for paginated results. |
| `limit` | `integer` | No | `20` | Maximum number of results to return. |
| `order` | `string` | No | `"totalrank"` | Sort order. One of: `"totalrank"` (relevance), `"pubdate"` (newest), `"click"` (most viewed), `"dm"` (most commented). |

## Input Schema (JSON Schema)

```json
{
  "type": "object",
  "properties": {
    "keywords": {
      "type": "string",
      "description": "Search query string. Auto-generated from profile if empty."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "default": 20
    },
    "order": {
      "type": "string",
      "enum": ["totalrank", "pubdate", "click", "dm"],
      "default": "totalrank"
    }
  }
}
```

## Output

Each result is a `DiscoveredContent` object with the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `bvid` | `string` | Bilibili video BV ID |
| `title` | `string` | Video title |
| `up_name` | `string` | Creator's display name |
| `up_mid` | `integer` | Creator's user ID |
| `cover_url` | `string` | Video cover image URL |
| `duration` | `integer` | Video length in seconds |
| `view_count` | `integer` | Play count |
| `like_count` | `integer` | Like count |
| `description` | `string` | Video description |
| `tags` | `string[]` | Video tags |
| `relevance_score` | `number` | LLM-evaluated relevance (0.0–1.0) |
| `relevance_reason` | `string` | Human-readable reason for the score |
| `source_strategy` | `string` | Always `"search"` for this skill |
| `topic_key` | `string` | Semantic topic classification |
| `style_key` | `string` | Content style classification |

## Requirements

- Bilibili Cookie authentication is required for search to function. Without it, Bilibili may return `412 Precondition Failed` and the skill will return empty results.
- The skill connects to Bilibili's public API at `https://api.bilibili.com`; no additional API keys are needed beyond the B站 Cookie.

## Limitations

- **Rate Limiting**: Bilibili applies rate-limiting and anti-bot protections. Under heavy usage, search requests may return `412 Precondition Failed` and degrade to empty results.
- **Platform Restriction**: The skill returns content from Bilibili only. Cross-platform search is not supported.
- **Cookie Dependency**: Search functionality depends on valid Bilibili Cookie authentication.

## Special Case Handling

### Empty Keywords
When `keywords` is empty or not provided:
1. The skill automatically generates search queries based on the user's soul profile (top interests, cognitive style, deep needs)
2. Multiple queries are generated and executed sequentially with delays between requests
3. Results are aggregated and deduplicated

### 412 Precondition Failed
When Bilibili returns `412 Precondition Failed`:
1. The skill treats this as a temporary failure for that query
2. Other queries continue execution
3. The skill returns results from successful queries only
4. If all queries fail, returns an empty result set with appropriate logging

### Network Errors & Timeouts
- **`v_voucher` challenge / transient failure**: `client.search` retries the WBI request up to 3× internally; an empty list at the strategy layer means the keyword exhausted its retries (the IP is being challenged), which feeds the storm-mode counter above
- **DNS Failure**: Falls back gracefully without breaking other queries
- **SSL Errors**: Logs the error and skips to next query

### Empty Search Results
- If no results are found for a query, returns an empty list for that query
- If all queries return empty, the skill returns an empty result set
- The discovery engine will try alternative strategies

### Invalid Parameters
- **Invalid `page`**: Passed directly to API (no clamping — caller should validate)
- **Invalid `limit`**: Passed directly to API (no clamping — caller should validate)
- **Invalid `order`**: Passed directly to API; defaults to `"totalrank"` if not provided
- **Empty string keywords**: Treated as auto-generate mode

### Special Characters in Keywords
- Keywords are URL-encoded before sending to Bilibili API
- Unicode characters are supported
- Long keywords are passed as-is (no length truncation)

### API Response Edge Cases
- **Unexpected response format**: Gracefully parses what it can, logs warnings for missing fields
- **Partial results**: Returns valid items even if some fields are missing
- **Rate limiting**: Handled via the per-query jitter delay, internal `v_voucher` retries, and storm-mode/cooldown short-circuit described above (no `Retry-After` header parsing)