# 统一消息上下文

消息上下文是本程序中最重要的概念，也是贯穿整个程序执行流程的一个对象，无论命令、过滤器或是其它插件类型，都需要使用这个对象，在代码中常以 `ctx_msg`、`ctx` 等形式出现，它是字典类型，其中保存了当前（目前正在处理的这条）消息的上报类型、消息内容、消息类型、发送者、接受者、消息源名称等等重要信息。消息源适配器的主要工作，就是将不同消息源的上报数据统一成下方所定义的消息上下文的格式。

下面定义一个统一化之后的消息上下文对象应当符合的形式：

| 字段名                          | 是否必须（是／否／建议） | 数据类型 | 支持的值                        | 说明                                       |
| ---------------------------- | ------------ | ---- | --------------------------- | ---------------------------------------- |
| `raw_ctx`                    | 是            | dict | -                           | 消息源上报过来的原始数据                             |
| `post_type`                  | 是            | str  | `message`                   | 上报类型，可以随意设置，但此字段值非 `message` 的消息上下文将会被某一层过滤器过滤掉 |
| `time`                       | 建议           | int  | -                           | 消息、事件等发生的时间戳                             |
| `msg_id`                     | 建议           | str  | -                           | 消息的唯一 ID                                 |
| `msg_type`                   | 是            | str  | `private`、`group`、`discuss` | 消息类型，标识私聊消息或群组消息等                        |
| `format`                     | 是            | str  | `text`、`media` 等            | 可随意填写，但实际上能够直接理解的只有 `text`，对于 `media` 格式，只有语音识别过滤器对 Mojo-Webxin 进行了单独支持 |
| `content`                    | 是            | str  | -                           | 消息内容文本                                   |
| `receiver`                   | 建议           | str  | -                           | 接受者显示名（当有备注名时为备注名，否则为昵称，见表格下方注释 1）       |
| `receiver_name`              | 否            | str  | -                           | 接受者昵称                                    |
| `receiver_id`／`receiver_tid` | 建议           | str  | -                           | 接受者 ID（分别是固定 ID 和 临时 ID，见注释 2）           |
| `sender`                     | 建议           | str  | -                           | 发送者显示名（当有备注名时为备注名，否则为昵称）                 |
| `sender_name`                | 否            | str  | -                           | 发送者昵称                                    |
| `sender_id`／`sender_tid`     | 是            | str  | -                           | 发送者 ID                                   |
| `group`                      | 建议           | str  | -                           | 来源群组显示名                                  |
| `group_id`／`group_tid`       | 是（当为群组消息时）   | str  | -                           | 来源群组 ID                                  |
| `discuss`                    | 建议           | str  | -                           | 来源讨论组显示名                                 |
| `discuss_id`／`discuss_tid`   | 是（当为讨论组消息时）  | str  | -                           | 来源讨论组 ID                                 |

- 注释 1：消息的接受者通常情况下表示当前消息源中登录的账号。
- 注释 2：所有 `xxx_id` 和 `xxx_tid` 分别表示固定 ID 和临时 ID：固定 ID（`xxx_id`）表示重新登录不会变的 ID，通常即为该消息平台的账号（微信 ID、QQ 号）；临时 ID（`xxx_tid`）表示在消息源的此次登录中不会变的 ID，但下次登录可能同一个用户的 ID 和上次不同，对于某些平台（如微信），可能有时完全无法获取到固定 ID，此时临时 ID 将成为发送消息时的重要依据。当没有（或无法获取）固定 ID 时，可将固定 ID 置空，如果同时也没有临时 ID，将意味着程序可能无法回复消息（因为没有任何能够唯一标记消息来源的值），当有固定 ID 没有临时 ID 时，应直接将临时 ID 设置为和固定 ID 相同。