Metadata-Version: 2.4
Name: python-library-onebot-protocol
Version: 0.4.0
Summary: OneBot 风格消息载荷与消息段模型
Requires-Python: >=3.10
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# onebot-protocol

OneBot 通信协议，定义消息收发的公共数据结构。基于 OneBot 11 标准，使用 Pydantic 提供类型安全的模型定义。

模块职责：`models.py` 定义全部公共消息模型与兼容归一化；`__init__.py` 只导出稳定名称。

## `MessagePayload`（OneBot 11 字段名）

| 字段 | 说明 |
|------|------|
| `post_type` | 事件类型，如 `message`（可选） |
| `message_type` | `group` 或 `private` |
| `self_id` | 机器人 QQ 号（可选） |
| `message_id` | 消息 ID；空时自动生成 UUID |
| `user_id` | 发送方 QQ；私聊时亦为会话对端 |
| `sender_name` | 发送方显示名；群聊优先使用群名片（可选） |
| `timestamp` | 平台消息 Unix 时间戳（可选） |
| `mentioned_self` | 群消息是否明确 @ 当前机器人；`null` 表示旧 Adapter 未提供 |
| `group_id` | 群号；群聊会话标识 |
| `message` | 消息段列表 |

解析时仍接受旧名别名：`source_type`→`message_type`、`bot_id`→`self_id`、`messages`→`message`、`session_id`→`group_id`/`user_id`。

Adapter 应无损上报消息，并用 `mentioned_self` 传递寻址事实；是否触发回复由宿主业务层决定，不属于协议模型的过滤职责。

## 特性

- 消息段类型包含文本、提及、图片、语音、视频、文件、位置、回复和合并转发
- 图片、语音、音频、视频、文件段共用 `FileData`（`name`、`content`、`mime_type`、`size`）
- 支持 discriminated union，根据 `type` 字段自动解析消息类型

## 文件载荷 `FileData`

| 字段 | 说明 |
|------|------|
| `name` | 显示用文件名（可选） |
| `content` | 内容引用，如 URL、平台资源标识或 Base64 等（可选，编码由实现方约定） |
| `mime_type` | MIME 类型（可选） |
| `size` | 字节大小（可选） |

`image` / `voice` / `audio` / `video` / `file` 各段类型的 `data` 均为对应子类，字段与 `FileData` 相同。

## 支持的消息类型

| 类型 | 说明 |
|------|------|
| `text` | 纯文本 |
| `mention` | @某人 |
| `mention_all` | @所有人 |
| `image` | 图片 |
| `voice` | 语音 |
| `audio` | 音频 |
| `video` | 视频 |
| `file` | 文件 |
| `location` | 位置 |
| `reply` | 回复 |
| `forward` | 合并转发；节点可包含嵌套消息段 |

## 合并转发

`forward.data` 包含 `message_id` 和 `content`。`content` 中每个节点可带 `user_id`、`nickname`、`time` 与 `message`；`message` 使用相同的消息段模型，因此可以继续包含 `forward`。
