# 2026-05-30

## 将 Selector 实现改为过程宏生成

### 变更内容
- 在 `onebot-api-macros` crate 中新增 `#[derive(Selector)]` 过程宏，用于自动生成事件类型的 Selector 过滤方法。
- 所有事件类型（`MessageEvent`、`RequestEvent`、`NoticeEvent`、`MetaEvent` 及其子类型）现在通过 `#[derive(Selector)]` 自动生成以下代码：
  - `selector()` 入口方法
  - `filter` / `and_filter` / `filter_async` / `and_filter_async` 通用过滤方法
  - 每个字段的 `filter_<field>` / `and_filter_<field>` / `filter_<field>_async` / `and_filter_<field>_async` 方法
  - 枚举变体的 `match_<variant>` / `on_<variant>` / `on_<variant>_async` 方法
  - 枚举 Selector 上的变体转换方法（如 `group_upload()`、`friend()` 等）
  - 对标记了 `#[selector(variants(...))]` 的字段，生成快捷过滤方法（如 `ban()`、`and_ban()`、`not_ban()` 等）
- 删除了 `src/event/` 下约 1600+ 行手写的 Selector impl 代码。

### 受影响文件
- `macros/src/lib.rs`：导出新宏
- `macros/src/selector.rs`（新增）：实现 `#[derive(Selector)]`
- `src/lib.rs`：re-export `Selector` 宏
- `src/event/message.rs`：添加 `derive(Selector)`，删除手写代码
- `src/event/request.rs`：添加 `derive(Selector)`，删除手写代码
- `src/event/notice.rs`：添加 `derive(Selector)`，删除手写代码
- `src/event/meta.rs`：添加 `derive(Selector)`，删除手写代码
- `src/event.rs`：添加 `derive(Selector)`，删除手写代码（EventMessage、EventNotice、EventRequest、EventMetaEvent、Event）
- `Cargo.toml`：将 `onebot-api-macros` 改为本地 path 依赖
- `Cargo.lock`：更新锁定信息

### 新增宏属性
- `#[selector(through = "method_name")]`：用于结构体字段，生成从当前 Selector 到字段内部类型的转换方法。支持自动解引用 `Box<T>`。

### 设计说明
- `String` 字段的过滤闭包参数映射为 `&str`，其他非基础类型字段映射为 `&T`，基础类型（i32、i64、bool 等）按值传递。
- 宏通过 `#[cfg(feature = "selector")]` 包裹所有生成代码，保持 feature-gate 一致性。
- 宏的实现使用了 `syn` + `quote`，支持结构体和枚举两种模式。

## Added
- 在 `macros/docs/` 下新增 `selector.md` 和 `api_sender.md` 文档。
  - `selector.md`: 详细说明 `#[derive(Selector)]` 过程宏的功能、用法、支持的属性（`variants`、`through`）以及类型处理规则。
  - `api_sender.md`: 详细说明 `#[api_sender]` 属性宏的功能、`#[api(...)]` 属性的各项参数（`response`、`extract`、`map`）以及完整使用示例。
- 涉及文件：`macros/docs/selector.md`, `macros/docs/api_sender.md`
- 目的：为 `onebot-api-macros` 的两个过程宏提供详细的使用文档，方便开发者理解和使用。

## Added
- 在 `AGENTS.md` 中新增 **Macros documentation rule** 章节。
  - 规定：每当对 `macros/` 目录进行修改（新增、删除、修改过程宏及其行为）时，`macros/docs/` 下的文档必须同步更新。
  - 新增宏：在 `macros/docs/` 创建同名 markdown 文件。
  - 删除宏：从 `macros/docs/` 删除对应文档。
  - 修改宏行为：更新现有文档以反映新行为。
- 涉及文件：`AGENTS.md`
- 目的：将宏文档同步作为正式项目规范，避免文档与实现脱节。

## 新增 Quick Operation traits 及实现

**变更内容：**
扩展了 `quick_operation` 模块，新增 6 个 quick operation trait 及其对应实现，覆盖群消息管理和请求事件处理场景。

**新增 traits：**
- `QuickReplyAt<T>` — 群消息回复并自动 @ 发送者
- `QuickDeleteMsg<T>` — 撤回当前消息
- `QuickKick<T>` — 踢出群成员
- `QuickBan<T>` — 禁言群成员
- `QuickHandleFriendRequest<T>` — 同意/拒绝好友请求
- `QuickHandleGroupRequest<T>` — 同意/拒绝入群请求

**受影响文件：**
- `src/quick_operation.rs` — 新增 6 个 trait 定义
- `src/event/message.rs` — 为 `MessageEventGroup`、`MessageEventPrivate`、`MessageEvent` 实现新 traits
- `src/event/request.rs` — 将 `RequestEventFriend` 和 `RequestEventGroup` 字段改为 `pub`，并为它们及 `RequestEvent` 实现新 traits

**变更原因：**
OneBot V11 协议在群消息事件中定义了 `reply`、`at_sender`、`delete`、`kick`、`ban`、`ban_duration` 等快速操作字段，在请求事件中可通过 `set_friend_add_request` 和 `set_group_add_request` API 快速处理。此前仅实现了 `QuickSendMsg`，本次补充完整覆盖了协议规范中的常用快速操作，提升开发体验。
