Metadata-Version: 2.4
Name: ErisPulse-BilibiliAdapter
Version: 0.2.0
Summary: ErisPulse Bilibili 私信适配器 — Cookie/扫码双登录、事件驱动收发、多账户
Author-email: wsu2059 <wsu2059@qq.com>
License: MIT
Project-URL: homepage, https://github.com/ErisPulse/ErisPulse-BilibiliAdapter
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bilibili-api-python>=16.3.0
Requires-Dist: qrcode>=7.4
Dynamic: license-file

[English](README.en.md) | [简体中文](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [Русский](README.ru.md)

> [!WARNING]
> **免责声明与使用限制**
>
> - 本项目仅供个人学习与技术研究，**与哔哩哔哩（bilibili）官方不存在任何关联**，未获得其授权、支持或认可。
> - B 站未提供官方机器人 API，本项目基于网页端协议模拟登录实现。此类用法违反平台用户协议，**账号存在被限流、禁言乃至封禁的风险**，一切后果由使用者自行承担。
> - **严禁**将本项目用于任何营销、广告、群发、垃圾信息、批量抓取、骚扰或其他商业化滥用用途。已有同类项目使用者因滥用行为被平台追究乃至承担法律责任的先例，请务必引以为戒。
> - 使用本项目即视为已阅读、理解并同意以上条款及 [LICENSE](LICENSE) 中的附加使用限制；开发者不对使用本项目造成的任何直接或间接损失负责。

<div align="center">

<img src="https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/.github/assets/ErisPulseLogo.png" width="180" alt="ErisPulse-BilibiliAdapter" />

# ErisPulse-BilibiliAdapter

**ErisPulse B 站私信适配器 — 扫码登录 / Cookie 凭据 / 私信收发**

<p>
  <a href="https://pypi.org/project/ErisPulse-BilibiliAdapter/"><img src="https://img.shields.io/pypi/v/ErisPulse-BilibiliAdapter?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"></a>
  <a href="https://pypi.org/project/ErisPulse-BilibiliAdapter/"><img src="https://img.shields.io/badge/Python-3.10+-FFD43B?style=for-the-badge&logo=python&logoColor=blue" alt="Python"></a>
  <a href="https://github.com/ErisPulse/ErisPulse-BilibiliAdapter/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="License"></a>
  <img src="https://raw.githubusercontent.com/ErisPulse/.github/main/assets/badges/adapter.svg" alt="ErisPulse">
</p>

</div>

---

## 简介

BilibiliAdapter 是基于 [bilibili-api-python](https://github.com/Passkou/bilibili-api) 的 B 站私信适配器，提供私信收发能力。

- 私信接收：文本 / 图片消息轮询接收（默认 45 秒 ± 10 秒抖动，可配置），转标准 OneBot12 事件
- 图片收发：接收转 image 段（URL）；发送支持 URL / 本地路径
- 多账户：`accounts` 下每个账户一个 B 站账号，独立会话监听
- 扫码安全：二维码会话令牌防未授权轮询；凭据面板密码形态展示

## 安装

```bash
epsdk install BilibiliAdapter
```

или:

```bash
pip install ErisPulse-BilibiliAdapter
```

## 配置说明

**方式一：扫码登录（推荐）**

```toml
[BilibiliAdapter.accounts.default]
login_mode = "qrcode"
bot_id = ""                    # auto-detect
enabled = true
```

> 配置完成后在 **Dashboard → 组件配置 → Bilibili → 添加账户向导** 中选择「扫码登录 B 站」，使用 B 站 APP 扫码确认，凭据自动写入配置。

**方式二：Cookie 凭据**

```toml
[BilibiliAdapter.accounts.default]
login_mode = "cookie"
sessdata = "YOUR_SESSDATA"     # required
bili_jct = "YOUR_BILI_JCT"     # required
buvid3 = "YOUR_BUVID3"         # optional
dedeuserid = "YOUR_UID"        # optional
bot_id = ""                    # auto-detect
enabled = true
```

> Cookie 获取：浏览器登录 B 站 → F12 开发者工具 → Application → Cookies → 复制对应字段。

**全局配置（`[BilibiliAdapter]`）：**
- `poll_interval`：私信轮询间隔（秒），默认 45；实际每轮带 ±10 秒随机抖动以降低风控特征，下限 5

**配置项说明（每个账户）：**
- `login_mode`：登录方式，`cookie`（手填凭据）或 `qrcode`（面板扫码，推荐）
- `sessdata` / `bili_jct`：登录态 Cookie（cookie 模式必填，面板密码形态显示）
- `buvid3`：设备指纹 Cookie（可选，降低风控概率）
- `dedeuserid`：账号 UID（可选，也是 bot_id 的默认来源）
- `bot_id`：账号 UID（留空登录后自动获取）

## 消息发送示例

```python
from ErisPulse import sdk
bili = sdk.adapter.get("bilibili")

# 发送文本私信（target 为对方 UID）
await bili.Send.To("user", "123456789").Text("Hello Bilibili!")

# 发送图片（URL 或本地路径）
await bili.Send.To("user", "123456789").Image("https://example.com/pic.jpg")

# 回复消息（链式修饰）
await bili.Send.To("user", "123456789").Reply("msg_key").Text("收到！")

# 多账户
await bili.Send.Using("account2").To("user", "123456789").Text("来自第二个账号")

# OneBot12 标准段发送
message = [
    {"type": "text", "data": {"text": "第一行"}},
    {"type": "image", "data": {"file": "https://example.com/img.jpg"}},
]
await bili.Send.To("user", "123456789").Raw_ob12(message)
```

## 标准 Api 动作

```python
# 自身信息
result = await bili.Api.get_self_info()           # {user_id, user_name, avatar}

# 用户公开信息（昵称/头像）
result = await bili.Api.get_user_info("123456789")

# 拉取指定会话历史消息
result = await bili.Api.get_session_msgs("123456789", begin_seqno=0)

# 运行状态与版本
result = await bili.Api.get_status()
result = await bili.Api.get_version()

# 多账户
result = await bili.Api.Using("account2").get_self_info()
```

## 事件监听示例

### 使用 Event 模块（推荐）

```python
@sdk.adapter.on_message()
async def on_message(event):
    if event["platform"] == "bilibili":
        sender = event["user_id"]             # 对方 UID
        text = event["alt_message"]           # 纯文本内容
        await event.reply("收到！")           # 快捷回复
```

### 使用平台原生事件

```python
@sdk.adapter.on("message")
async def handle_message(event):
    if event["platform"] == "bilibili":
        raw = event["bilibili_raw"]           # B 站原始私信数据
        print(f"私信来自: {raw.get('sender_uid')}")
```

## 平台事件映射关系

| B 站私信事件 | Adapter 事件 |
|--------------|--------------|
| TEXT（文本消息） | message（text 段） |
| PICTURE（图片消息） | message（image 段） |
| WITHDRAW（撤回） | 仅记录日志 |

## 注意事项：
1. **B 站无官方个人 Bot API**，本适配器通过模拟登录使用 Web 私信接口，属非官方用法
2. **请控制发送频率**：高频/批量私信极易触发风控（账号私信功能被临时禁言），建议模块侧加节流
3. 请勿用于骚扰、营销群发等违规用途，遵守 B 站社区规则
4. Cookie 凭据等同账号登录态，注意保管；面板中凭据字段以密码形态显示
5. 私信仅支持单聊；粉丝群聊暂不支持
6. 图片接收转 image 段（URL），发送图片支持 URL / 本地路径
7. 登录态失效（Cookie 过期）时适配器会记录错误日志，请重新扫码或更新 Cookie

---

### 参考链接
- [ErisPulse 主库](https://github.com/ErisPulse/ErisPulse/)
- [bilibili-api-python](https://github.com/Passkou/bilibili-api)
- [bilibili-API-collect](https://github.com/SocialSisterYi/bilibili-API-collect)
- [模块开发指南](https://www.erisdev.com/#docs/developer-guide/README.md)
