# 2026-06-02 变更记录

## [feat] 新增 Deno TS OneBot V11 mock 服务端框架

### 变更内容

- 在 `mock/server/` 下新增 OneBot V11 mock 服务端框架，提供 `Server` 统一入口和
  `CommunicationService` 通信接口。
- 新增 API handler 注册、fallback handler、echo
  自动回填、默认失败响应和运行时错误提取能力。
- 新增
  `WsService`、`WsReverseService`、`HttpService`、`HttpPostService`、`SseService`
  五个通信实现，分别覆盖 WebSocket、反向 WebSocket、HTTP API、HTTP POST
  事件推送和 SSE 事件推送。

### 涉及文件

- `mock/server/mod.ts` [Added] 新增 mock server 统一导出入口
- `mock/server/server.ts` [Added] 新增 `Server`、`ServerBuilder` 和 API handler
  路由逻辑
- `mock/server/types.ts` [Added] 新增 OneBot V11 mock server
  类型、接口和错误类型
- `mock/server/services/mod.ts` [Added] 新增通信服务统一导出入口
- `mock/server/services/shared.ts` [Added] 新增通信服务公共基类和协议辅助函数
- `mock/server/services/ws.ts` [Added] 新增 WebSocket 服务端通信实现
- `mock/server/services/ws_reverse.ts` [Added] 新增反向 WebSocket 客户端通信实现
- `mock/server/services/http.ts` [Added] 新增 HTTP API 服务端通信实现
- `mock/server/services/http_post.ts` [Added] 新增 HTTP POST 事件推送通信实现
- `mock/server/services/sse.ts` [Added] 新增 SSE 事件服务端通信实现
- `changelogs/2026-06-02.md` [Added] 新增当天变更记录

### 影响

- 调用方可以通过 Deno TS 在 mock 环境中启动 OneBot V11 服务端，注册 API
  响应并主动推送事件。
- `HttpService` 仅支持处理 API 请求，`HttpPostService` 和 `SseService`
  仅支持事件推送；调用不支持能力时会返回明确错误。

### 原因

- 为 mock 环境提供与当前 Rust 项目通信架构相对应的服务端框架，便于测试 OneBot
  V11 客户端通信行为。

## [docs] 新增 mock server 使用文档

### 变更内容

- 在 `mock/server/docs/` 下新增 OneBot V11 mock server 使用文档。
- 补充 `Server` 核心 API、五种通信服务、鉴权方式、事件发送、API handler
  和错误处理说明。
- 提供 WebSocket、反向 WebSocket、HTTP API、HTTP POST 事件推送、SSE 事件推送和
  HTTP 双通道组合示例。

### 涉及文件

- `mock/server/docs/README.md` [Added] 新增 mock server 模块使用文档
- `changelogs/2026-06-02.md` [Changed] 追加本次文档变更记录

### 影响

- 调用方可以根据文档快速选择合适的通信服务并编写 mock server 示例。
- 不影响现有代码行为。

### 原因

- 为新增的 Deno TS mock server 模块补充使用说明，降低测试和接入成本。

## [feat] 新增五种协议 mock 服务端命令行入口

### 变更内容

- 在 `mock/mock/` 下新增五个 OneBot V11 mock 服务端入口文件，分别对应
  WebSocket、反向 WebSocket、HTTP API、HTTP POST 事件推送和 SSE 事件推送。
- 为每个入口提供命令行参数解析，可配置端口、路径、token、机器人账号、事件账号、
  事件类型、消息内容和发送间隔等参数。
- 为支持 API 的协议注册默认 `get_login_info`、`get_status`、`send_msg`、
  `send_private_msg` 和 `send_group_msg` 响应，便于直接联调客户端。

### 涉及文件

- `mock/mock/ws.ts` [Added] 新增 WebSocket mock 服务端命令行入口
- `mock/mock/ws_reverse.ts` [Added] 新增反向 WebSocket mock 客户端命令行入口
- `mock/mock/http.ts` [Added] 新增 HTTP API mock 服务端命令行入口
- `mock/mock/http_post.ts` [Added] 新增 HTTP POST 事件推送 mock 命令行入口
- `mock/mock/sse.ts` [Added] 新增 SSE 事件服务端命令行入口
- `changelogs/2026-06-02.md` [Changed] 追加本次 mock 命令行入口变更记录

### 影响

- 调用方可以直接通过 `deno run --allow-net mock/mock/<协议>.ts` 启动对应协议的
  OneBot V11 mock 服务，无需手写示例文件。
- 新增文件仅位于 mock 目录，不影响 Rust crate 的库 API 或现有通信实现。

### 原因

- 满足使用 `mock/server` 模块快速启动五种 OneBot V11 协议 mock 服务端的需求，
  方便通过命令行参数进行本地联调和测试。

## [feat][BREAKING] 将 OneBot 数值字段和 API 参数扩展为 i64

### 变更内容

- 将消息 ID、QQ 号、群号、时间戳、禁言时长、超时时间和 CSRF Token 等 OneBot
  数值字段由 `i32` 调整为 `i64`。
- 同步更新 `APISender` trait、`Client` 实现、quick operation trait、消息事件结构体、
  消息段构建器和过程宏测试中的相关签名。
- 更新相关文档注释中的返回类型说明。

### 涉及文件

- `src/api.rs` [Changed] 将公开 API trait 中相关参数和返回值类型由 `i32` 调整为 `i64`
- `src/api/return_type.rs` [Changed] 将 OneBot API 响应结构中的数值字段调整为 `i64`
- `src/communication/utils.rs` [Changed] 同步更新 `Client` 的 `APISender` 实现签名
- `src/event/message.rs` [Changed] 更新消息事件、发送者信息和 quick operation 实现中的数值类型
- `src/message/segment_builder.rs` [Changed] 将图片、语音和视频消息段的超时参数调整为 `i64`
- `src/message/send_segment.rs` [Changed] 将发送消息段数据结构中的 `timeout` 字段调整为 `i64`
- `src/message/signal_segment_builder.rs` [Changed] 将单消息段构建器的 `timeout` 参数调整为 `i64`
- `src/quick_operation.rs` [Changed] 将 quick operation trait 的消息返回值和禁言时长调整为 `i64`
- `macros/tests/test_api_sender.rs` [Changed] 更新过程宏测试中的 API 签名和响应字段类型
- `changelogs/2026-06-02.md` [Changed] 追加本次类型调整变更记录

### 影响

- 公开 API 签名发生破坏性变更；调用方需要将相关 `i32` 参数、返回值和结构体字段适配为
  `i64`。
- 可避免 OneBot ID、时间戳和长时长参数超出 `i32` 范围时发生反序列化或类型截断问题。

### 原因

- OneBot V11 中 QQ 号、群号、消息 ID 和时间戳等值可能超过 `i32` 可表示范围，使用
  `i64` 更符合协议数据规模并提升兼容性。

## [docs] 新增 git 提交前 changelog 校验规则

### 变更内容

- 在 `AGENTS.md` 中新增 Git 提交规则，要求提交信息使用中文。
- 明确提交前需要读取本次改动涉及的 `changelogs/` 记录，并与 git 修改文件进行对比。
- 要求发现 git 修改未被 changelog 提及时，必须先同步追加到当天 changelog 后再提交。

### 涉及文件

- `AGENTS.md` [Changed] 新增 Git 提交规则，补充中文提交信息和 changelog 对照要求
- `changelogs/2026-06-02.md` [Changed] 追加本次文档规则变更记录

### 影响

- 后续提交流程会更严格，提交前需要确保 changelog 覆盖所有 git 修改文件。
- 不影响 Rust crate 的编译、运行或公开 API。

### 原因

- 避免 git 修改遗漏在 changelog 之外，保证变更记录与实际提交内容保持一致。
