openclaw-skills/docs/research-notes/phase-2.5-favlist-deep-dive.md

# B站收藏夹 API 深度调研

**调研时间**: 2026-02-06  
**调研人**: 阿里巴巴助手  
**文档类型**: 技术补充调研

---

## 1. 收藏夹隐私机制

### 1.1 公开 vs 私密

B站收藏夹支持两种隐私状态：

| 状态 | 说明 | 谁能查看 |
|------|------|----------|
| **公开** | 用户主动设置为公开 | 任何人（包括未登录用户）|
| **私密** | 默认状态 | 仅用户本人 |

### 1.2 设置方式

用户需要在两个地方设置才能完全公开：
1. **电脑端**: 收藏夹管理 → 编辑 → 设置公开
2. **手机端**: 设置 → 安全隐私 → 空间隐私设置 → 公开显示我的收藏

> ⚠️ **关键发现**: 很多用户不知道需要同时设置两端，导致"设置了公开但别人看不到"

### 1.3 对用户的影响

- **默认情况**: 所有收藏夹都是**私密的**
- **大多数用户**: 不会主动设置为公开
- **实际可用性**: 获取他人收藏夹内容非常有限

---

## 2. 收藏夹 API 详情

### 2.1 API 端点汇总

#### 获取用户创建的所有收藏夹列表
```
GET https://api.bilibili.com/x/v3/fav/folder/created/list-all
```

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| up_mid | num | 是 | 目标用户mid |
| type | num | 否 | 0=全部, 2=视频稿件 |
| rid | num | 否 | 目标内容id（查询某视频在哪些收藏夹）|

**认证**: Cookie (SESSDATA) 或 APP

**注**: 查询私密收藏夹时需要相应用户登录

#### 获取收藏夹元数据
```
GET https://api.bilibili.com/x/v3/fav/folder/info
```

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| media_id | num | 是 | 收藏夹完整id（fid + mid后2位）|

**返回关键字段**:
```json
{
  "code": 0,
  "data": {
    "id": 1052622027,       // 收藏夹完整id
    "fid": 10526220,        // 收藏夹原始id
    "mid": 509372,          // 创建者mid
    "title": "收藏夹标题",
    "cover": "封面URL",
    "media_count": 100,     // 内容数量
    "state": 0,             // 状态（0=正常）
    "fav_state": 0,         // 是否已收藏（需登录）
    "cnt_info": {
      "collect": 50,        // 被收藏数
      "play": 10000,        // 播放量
      "thumb_up": 100       // 点赞数
    }
  }
}
```

#### 获取收藏夹内容列表
```
GET https://api.bilibili.com/x/v3/fav/resource/list
```

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| media_id | num | 是 | 收藏夹完整id |
| pn | num | 否 | 页码，默认1 |
| ps | num | 否 | 每页数量，默认20 |
| keyword | str | 否 | 搜索关键词 |
| order | str | 否 | 排序：mtime=收藏时间，view=播放量 |
| type | num | 否 | 0=全部，2=视频 |
| platform | str | 否 | web |

**认证**: Cookie (SESSDATA)

**返回字段**:
```json
{
  "code": 0,
  "data": {
    "info": { /* 收藏夹信息 */ },
    "medias": [
      {
        "id": 583785685,      // 视频avid
        "type": 2,            // 2=视频稿件
        "title": "视频标题",
        "cover": "封面URL",
        "intro": "简介",
        "page": 1,            // 分P数
        "duration": 600,      // 时长（秒）
        "upper": {
          "mid": 123456,
          "name": "UP主昵称"
        },
        "cnt_info": {
          "play": 10000,
          "danmaku": 500,
          "collect": 100
        },
        "bv_id": "BV1xx411c7mD",
        "bvid": "BV1xx411c7mD",
        "pubtime": 1609459200,  // 发布时间
        "fav_time": 1609545600  // 收藏时间
      }
    ]
  }
}
```

#### 批量获取内容信息
```
GET https://api.bilibili.com/x/v3/fav/resource/infos
```

**参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| resources | str | 是 | 格式：`{id}:{type},{id}:{type}` |
| platform | str | 否 | web |

**resources格式**:
- `{内容id}:{内容类型}`
- 类型: 2=视频稿件, 12=音频, 21=视频合集
- 多个用逗号分隔

**示例**: `583785685:2,523:21,15664:12`

### 2.2 错误码说明

| code | 含义 | 说明 |
|------|------|------|
| 0 | 成功 | 正常返回 |
| -400 | 请求错误 | 参数缺失或格式错误 |
| -403 | 访问权限不足 | 收藏夹为私密，或Cookie无效 |
| -404 | 不存在 | 收藏夹id不存在 |
| -101 | 账号未登录 | SESSDATA失效或缺失 |
| 11201 | 收藏夹不可见 | 私密收藏夹，无权限访问 |

---

## 3. 获取收藏夹的可行性分析

### 3.1 获取他人收藏夹

**可行性**: ⚠️ **很低**

**原因**:
1. 默认私密，大多数用户不会公开
2. 即使公开，也需要用户主动在两处设置
3. 公开收藏夹通常只展示精选内容

**适用场景**:
- 分析特定UP主的公开收藏（如教程合集）
- 获取用户自己公开的收藏夹（需用户授权后）

### 3.2 获取自己的收藏夹

**可行性**: ✅ **高**

**前提条件**:
1. 获取完整的 Cookie (SESSDATA)
2. Cookie 未过期
3. 账号状态正常

**bili-auth 方案的限制**:
- bili-auth 返回 OAuth token，但**不直接提供 SESSDATA**
- 部分 API 需要完整的 Cookie，不仅仅是 access_token
- 可能需要额外步骤将 OAuth 凭证转换为可用 Cookie

### 3.3 技术路径对比

| 方案 | 可行性 | 复杂度 | 风险 |
|------|--------|--------|------|
| **OAuth + 公开收藏夹** | 🟡 低 | 低 | 低 |
| **OAuth + Cookie提取** | ✅ 中 | 高 | 中 |
| **手动Cookie输入** | ✅ 高 | 低 | 高（用户体验差）|

---

## 4. 对 OpenClaw 技能的影响

### 4.1 功能调整建议

**原规划**（包含收藏夹）:
- 获取关注列表 ✅
- 监控UP主动态 ✅
- 视频搜索 ✅
- 收藏夹同步 ❌（受限）

**建议调整为**:

| 功能 | 优先级 | 说明 |
|------|--------|------|
| **我的收藏夹** | P1 → P2 | 需完整Cookie，实现复杂 |
| **UP主公开收藏** | P2 | 仅展示UP主主动公开的内容 |
| **收藏夹元数据** | P2 | 可获取标题、数量等基本信息 |

### 4.2 用户交互设计

**如果实现"我的收藏夹"功能**:

1. **授权时明确提示**:
   > "获取收藏夹需要完整登录态，可能存在账号风险，建议使用小号"

2. **降级方案**:
   - 如果无法获取收藏夹 → 提示用户手动输入Cookie
   - 或仅展示公开收藏夹内容

3. **功能限制**:
   - 仅读取，不提供"添加到收藏夹"功能
   - 仅展示前N个收藏夹，避免频繁调用

### 4.3 技术实现建议

**如果决定支持收藏夹**:

```python
# 伪代码示例
async def get_fav_list(uid, cookie):
    """获取用户收藏夹列表"""
    url = "https://api.bilibili.com/x/v3/fav/folder/created/list-all"
    params = {"up_mid": uid}
    headers = {"Cookie": cookie}
    
    resp = await fetch(url, params, headers)
    if resp.code == -403:
        return {"error": "收藏夹为私密或Cookie无效"}
    return resp.data

async def get_fav_content(media_id, cookie, pn=1):
    """获取收藏夹内容"""
    url = "https://api.bilibili.com/x/v3/fav/resource/list"
    params = {
        "media_id": media_id,
        "pn": pn,
        "ps": 20,
        "platform": "web"
    }
    headers = {"Cookie": cookie}
    
    resp = await fetch(url, params, headers)
    return resp.data
```

**关键注意点**:
- 缓存收藏夹列表（1小时）
- 分页获取内容，避免单次请求过大
- 错误处理：-403时友好提示用户

---

## 5. 结论与建议

### 5.1 关于收藏夹功能的结论

| 方面 | 评估 |
|------|------|
| **技术可行性** | ✅ 可实现，但需完整Cookie |
| **用户可用性** | 🟡 中（需用户理解和授权）|
| **数据完整性** | ⚠️ 受限（大部分为私密）|
| **风险等级** | 🟡 中（需处理Cookie）|

### 5.2 MVP 功能建议

**Phase 1**: 不包含收藏夹功能
- 聚焦：关注列表 + UP主动态 + 视频搜索
- 更简单，风险更低

**Phase 2**: 可选添加收藏夹（如果用户需求强烈）
- 实现"我的收藏夹"（需完整Cookie）
- 明确提示风险
- 提供降级方案

### 5.3 如果用户询问"为什么看不到收藏夹"

标准回答：
> B站收藏夹默认是私密的，大部分用户不会主动公开。如果需要获取您的收藏夹，需要：
> 1. 在B站设置中将其设为公开
> 2. 或者提供完整登录Cookie（存在风险，建议使用小号）

---

## 附录

### API 快速参考

```bash
# 获取用户收藏夹列表
curl -G 'https://api.bilibili.com/x/v3/fav/folder/created/list-all' \
  --data-urlencode 'up_mid=509372' \
  -b 'SESSDATA=xxx'

# 获取收藏夹内容
curl -G 'https://api.bilibili.com/x/v3/fav/resource/list' \
  --data-urlencode 'media_id=1052622027' \
  --data-urlencode 'pn=1' \
  --data-urlencode 'ps=20' \
  -b 'SESSDATA=xxx'
```

### 相关文档
- 主调研报告: [bilibili-plugin-feasibility.md](./bilibili-plugin-feasibility.md)
- 数据API调研: [phase-2-data-api.md](./research-notes/phase-2-data-api.md)

---

*本文档为 B站插件调研的补充材料*