docs: sync current api documentation

Author: YinMo19

Cargo.toml

@@ -3,7 +3,7 @@ name = "botrs"
 version = "0.13.0"
 edition = "2024"
 authors = ["YinMo19"]
-description = "A Rust QQ Bot framework based on QQ Guild Bot API"
+description = "A Rust QQ bot framework for QQ gateway events and bot OpenAPI"
 license = "MIT"
 repository = "https://github.com/YinMo19/botrs"
 keywords = ["qq", "bot", "guild", "api", "async"]

README.md

@@ -1,14 +1,14 @@
-# BotRS - Rust QQ Guild Bot Framework
+# BotRS - Rust QQ Bot Framework
 ## Author: YinMo19
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Rust](https://img.shields.io/badge/rust-1.70+-blue.svg)](https://www.rust-lang.org)
+[![Rust](https://img.shields.io/badge/rust-1.85+-blue.svg)](https://www.rust-lang.org)
 [![GitHub](https://img.shields.io/badge/github-YinMo19-blue.svg)](https://github.com/YinMo19)
 [![Crates.io](https://img.shields.io/crates/v/botrs.svg)](https://crates.io/crates/botrs)
 
 > 本实现不是 qqbot 的官方 rust 版本实现。
 
-BotRS 是一个用 Rust 实现的 QQ 频道机器人框架，基于 [QQ 频道机器人 API](https://bot.q.qq.com/wiki/develop/api/)。它提供了类型安全、高性能、易于使用的接口来开发 QQ 频道机器人。
+BotRS 是一个用 Rust 实现的 QQ 机器人框架，基于 [QQ 频道机器人 API](https://bot.q.qq.com/wiki/develop/api/) 与当前开放平台接口，覆盖频道、私信、群和 C2C 消息场景。它提供类型安全、异步、session-first 的接口来开发 QQ 机器人。
 
 ## 快速开始
 

docs/.vitepress/config.mts

@@ -3,7 +3,7 @@ import { defineConfig } from "vitepress";
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
     title: "BotRS",
-    description: "A Rust QQ Bot framework based on QQ Guild Bot API",
+    description: "A Rust QQ bot framework for QQ gateway events and bot OpenAPI",
     head: [
         ["link", { rel: "icon", href: "/favicon.ico" }],
         ["meta", { name: "theme-color", content: "#646cff" }],
@@ -17,7 +17,7 @@ export default defineConfig({
             label: "English",
             lang: "en",
             title: "BotRS",
-            description: "A Rust QQ Bot framework based on QQ Guild Bot API",
+            description: "A Rust QQ bot framework for QQ gateway events and bot OpenAPI",
             themeConfig: {
                 nav: [
                     { text: "Guide", link: "/guide/introduction" },
@@ -101,12 +101,12 @@ export default defineConfig({
                             text: "Performance and Security",
                             items: [
                                 {
-                                    text: "Performace",
-                                    link: "/guide/performance.md",
+                                    text: "Performance",
+                                    link: "/guide/performance",
                                 },
                                 {
                                     text: "Security",
-                                    link: "/guide/security.md",
+                                    link: "/guide/security",
                                 },
                             ],
                         },
@@ -256,7 +256,7 @@ export default defineConfig({
             label: "简体中文",
             lang: "zh-CN",
             title: "BotRS",
-            description: "基于 QQ 频道机器人 API 的 Rust QQ 机器人框架",
+            description: "面向 QQ 网关事件与机器人 OpenAPI 的 Rust QQ 机器人框架",
             themeConfig: {
                 nav: [
                     { text: "指南", link: "/zh/guide/introduction" },
@@ -341,11 +341,11 @@ export default defineConfig({
                             items: [
                                 {
                                     text: "高性能指南",
-                                    link: "/zh/guide/performance.md",
+                                    link: "/zh/guide/performance",
                                 },
                                 {
                                     text: "安全指南",
-                                    link: "/zh/guide/security.md",
+                                    link: "/zh/guide/security",
                                 },
                             ],
                         },

docs/README.md

@@ -9,15 +9,8 @@ docs/
 ├── .vitepress/          # VitePress configuration
 │   └── config.mts       # Site configuration
 ├── guide/               # English guides
-│   ├── introduction.md
-│   ├── installation.md
-│   ├── quick-start.md
-│   └── configuration.md
 ├── api/                 # English API reference
-│   ├── client.md
-│   └── event-handler.md
 ├── examples/            # English examples
-│   └── getting-started.md
 ├── zh/                  # Chinese documentation
 │   ├── guide/           # Chinese guides
 │   ├── api/             # Chinese API reference
@@ -36,31 +29,31 @@ docs/
 
 ### Prerequisites
 
-- Node.js 16+ 
-- npm 7+
+- Node.js 22 (same as CI)
+- pnpm 9
 
 ### Local Development
 
 ```bash
 # Install dependencies
-npm install
+pnpm install
 
 # Start development server
-npm run docs:dev
+pnpm docs:dev
 
 # Build for production
-npm run docs:build
+pnpm docs:build
 
 # Preview production build
-npm run docs:preview
+pnpm docs:preview
 ```
 
 ### Available Scripts
 
-- `npm run docs:dev` - Start development server with hot reload
-- `npm run docs:build` - Build static site for production
-- `npm run docs:preview` - Preview production build locally
-- `npm run docs:serve` - Serve built documentation
+- `pnpm docs:dev` - Start development server with hot reload
+- `pnpm docs:build` - Build static site for production
+- `pnpm docs:preview` - Preview production build locally
+- `pnpm docs:serve` - Serve built documentation
 
 ## Documentation Guidelines
 
@@ -145,15 +138,13 @@ VitePress supports extended markdown features:
 - Syntax highlighting with line numbers
 - Custom containers (info, tip, warning, danger)
 - Code group tabs
-- Math expressions
-- Mermaid diagrams
 
 ## Deployment
 
 The documentation is automatically deployed when changes are pushed to the main branch. The build process:
 
-1. Installs dependencies
-2. Runs `npm run docs:build`
+1. Installs dependencies with pnpm
+2. Runs `pnpm docs:build`
 3. Deploys to the hosting platform
 
 ## Maintenance

docs/api/bot-api.md

@@ -1,6 +1,6 @@
 # BotApi
 
-`BotApi` is the stateless REST client used by a bot while handling events. After a gateway event arrives, handlers usually call it through the event session to send replies, recall channel messages, upload group/C2C files, manage announcements, schedules and pins, inspect reaction users, or create API permission requests.
+`BotApi` is the shared typed REST client used by a bot while handling events. After a gateway event arrives, handlers usually call it through the event session to send replies, recall messages, upload group/C2C files, manage guild/channel resources, announcements, schedules, pins, reactions, permissions, roles, mute state, or audio controls.
 
 When your bot is driven by `Client`, you normally do not construct `BotApi` yourself. Every event callback receives a session that exposes the shared API client:
 
@@ -26,15 +26,19 @@ let me = api.get_bot_info().await?;
 | Area | Methods |
 | --- | --- |
 | Bot identity and gateway discovery | `get_bot_info`, `get_gateway` |
-| Guild channel messages | `send_message`, `recall_message` |
-| Group and C2C messages | `send_group_message`, `send_c2c_message` |
-| Direct messages | `create_direct_message`, `send_direct_message` |
+| Guilds and channels | `get_guild`, `list_bot_guilds`, `get_channel`, `list_channels`, `create_channel`, `update_channel`, `delete_channel`, `create_private_channel` |
+| Members, roles, and mute | `get_guild_member`, `list_guild_members`, `delete_guild_member`, `list_roles`, `create_role`, `update_role`, `delete_role`, `add_member_role`, `delete_member_role`, `mute_guild`, `mute_member`, `mute_members` |
+| Channel permissions and voice members | `get_channel_permissions`, `update_channel_permissions`, `get_channel_role_permissions`, `update_channel_role_permissions`, `list_voice_channel_members` |
+| Guild channel messages | `get_message`, `list_messages`, `send_message`, `update_message`, `recall_message`, `send_setting_guide` |
+| Group and C2C messages | `send_group_message`, `send_c2c_message`, `recall_group_message`, `recall_c2c_message` |
+| Direct messages | `create_direct_message`, `send_direct_message`, `recall_direct_message`, `send_direct_setting_guide` |
 | Group/C2C files | `post_group_file`, `post_c2c_file` |
-| Announcements | `create_announce`, `create_recommend_announce`, `delete_announce` |
+| Announcements | `create_channel_announce`, `delete_channel_announce`, `create_announce`, `create_recommend_announce`, `delete_announce` |
 | Schedules | `get_schedules`, `get_schedule`, `create_schedule`, `update_schedule`, `delete_schedule` |
 | API permissions | `get_api_permissions`, `post_permission_demand` |
 | Reactions | `put_reaction`, `delete_reaction`, `get_reaction_users` |
-| Pins | `put_pin`, `delete_pin`, `get_pins` |
+| Pins | `put_pin`, `delete_pin`, `clean_pins`, `get_pins` |
+| Audio controls | `post_audio`, `put_mic`, `delete_mic` |
 
 ## Sending Messages
 
@@ -48,7 +52,9 @@ let params = GroupMessageParams::new_text("hello group");
 group_session.send_message(params).await?;
 ```
 
-Guild channel messages and DMs use `MessageParams` / `DirectMessageParams`. Group and C2C messages use `GroupMessageParams` / `C2CMessageParams`, matching QQ's open-message shape. For ark, embed, markdown, keyboard, or media payloads, set the corresponding field on the parameter struct.
+Guild channel messages and DMs use `MessageParams` / `DirectMessageParams`. Group and C2C messages use `GroupMessageParams` / `C2CMessageParams`, matching QQ's open-message shape.
+
+Inside event handlers, prefer the session helpers when they fit: `send_text_message`, `send_markdown_message`, `send_ark_message`, `send_embed_message`, `send_keyboard_message`, and group/C2C `send_media_message`. For lower-level API calls, use params constructors such as `new_markdown`, `new_ark`, `new_embed`, `new_keyboard`, and `new_media`; they fill the protocol message type for you.
 
 ## Files and Media
 
@@ -59,10 +65,7 @@ let media = session
     .post_file(1, "https://example.com/image.png", None)
     .await?;
 
-let mut params = GroupMessageParams::default();
-params.msg_type = 7;
-params.media = Some(media);
-session.send_message(params).await?;
+session.send_media_message(media).await?;
 ```
 
 When `srv_send_msg` is `Some(true)`, the platform sends the uploaded file directly, so you usually do not need a separate media message.
@@ -73,7 +76,7 @@ These APIs are direct wrappers around their protocol payloads:
 
 - Announcements can be created from an existing message or from a list of recommended channels.
 - Schedules support listing, fetching one item, creating, updating, and deleting.
-- Pins support pinning one message, unpinning one message, and listing pinned message ids.
+- Pins support pinning one message, unpinning one message, clearing all pins, and listing pinned message ids.
 - API permission requests take `channel_id`, `APIPermissionDemandIdentify`, and a description.
 
 ```rust

docs/api/client.md

@@ -10,7 +10,7 @@ let mut client = Client::new(token, intents, MyHandler, /* is_sandbox: */ false)
 client.start().await?;
 ```
 
-`Client::new` returns `Result<Client<H>>` because it constructs the underlying `HttpClient` and may fail if TLS / DNS configuration is invalid.
+`Client::new` returns `Result<Client<H>>` because it validates the token and constructs the underlying `HttpClient`.
 
 ## Constructors
 
@@ -21,14 +21,14 @@ client.start().await?;
 
 ## Lifecycle
 
-- `start().await` — connects, identifies, and runs the event loop. Returns once the loop terminates (gracefully or via fatal error).
+- `start().await` — performs startup REST calls, starts gateway sessions, and runs the event loop until the event channel closes.
 Dropping the running `Client` task closes the gateway connection.
 
 There are no `stop` / `is_connected` / `get_session_info` methods — the framework intentionally exposes a small surface and pushes session details into events instead. Use `EventHandler::ready` and `EventHandler::resumed` to observe lifecycle changes.
 
 ## Reconnect behaviour
 
-`start()` reconnects automatically on transient gateway failures, applying the throttling described in the [gateway guide](../guide/gateway.md). When a fatal failure (invalid token, unrecoverable handshake) is detected, `start()` resolves with the propagated `BotError`.
+`start()` propagates startup failures from token validation, `get_bot_info`, and `get_gateway`. After gateway sessions are spawned, transient gateway failures are retried with the throttling described in the [gateway guide](../guide/gateway.md); unrecoverable identify failures stop that shard's reconnect loop and are logged by the session manager.
 
 ## Graceful shutdown
 

docs/api/context.md

@@ -22,7 +22,11 @@ async fn ready(&self, session: ReadySession) {
 
 async fn message_create(&self, mut session: ChannelReplySession) {
     let message = session.message().clone();
-    if message.content.as_deref() == Some("!ping") {
+    if message.author.bot {
+        return;
+    }
+
+    if message.content.trim() == "!ping" {
         let _ = session.reply("pong").await;
     }
 }

docs/api/error-types.md

@@ -23,8 +23,8 @@ pub type Result<T> = std::result::Result<T, BotError>;
 | `MethodNotAllowed(String)`                   | 405.                                                     |
 | `Forbidden(String)`                          | 403 / permission denied.                                 |
 | `RateLimit { retry_after: u64 }`             | 429 with parsed `Retry-After` (in seconds).              |
-| `SequenceNumber(String)`                     | Gateway sequence skew that demands resume / reconnect.   |
-| `Server(String)`                             | 5xx responses without structured codes.                  |
+| `SequenceNumber(String)`                     | Reserved sequence/order error from the low-level mapper. |
+| `Server(String)`                             | 5xx responses with the parsed platform diagnostic.       |
 | `Auth(String)`                               | Higher-level authentication / session issue.             |
 | `Connection(String)`                         | Gateway lifecycle / heartbeat failure.                   |
 | `Config(String)`                             | Invalid configuration before requests run.               |
@@ -83,4 +83,4 @@ Constants for these codes are exposed from `botrs::error`, for example `botrs::e
 
 - [Bot API](./bot-api.md) — every route that can produce these errors.
 - [Token](./token.md) — credential refresh logic that surfaces `Auth` errors.
-- [Gateway guide](../guide/gateway.md) — how the framework reacts to `Connection` / `SequenceNumber` errors.
+- [Gateway guide](../guide/gateway.md) — how the framework handles gateway connection failures.

docs/api/event-handler.md

@@ -94,11 +94,12 @@ impl EventHandler for MyBot {
 
     async fn message_create(&self, mut session: ChannelReplySession) {
         let message = session.message().clone();
-        if message.author.as_ref().and_then(|author| author.bot).unwrap_or_default() { return; }
-        if let Some(content) = &message.content {
-            if content.trim() == "!ping" {
-                let _ = session.reply("Pong!").await;
-            }
+        if message.author.bot {
+            return;
+        }
+
+        if message.content.trim() == "!ping" {
+            let _ = session.reply("Pong!").await;
         }
     }
 }

docs/api/models/messages.md

@@ -11,14 +11,14 @@ Group and C2C messages have their own models:
 - `GroupMessage` maps to `GROUP_AT_MESSAGE_CREATE`; the key routing field is `group_openid`.
 - `C2CMessage` maps to `C2C_MESSAGE_CREATE`; the key routing field usually comes from `author.user_openid`.
 
-These event models retain platform-provided message id, content, attachments, mentions, timestamp, references, and internal `event_id`. For plain replies, prefer `session.reply(...)` from the matching reply session. For richer replies, build the matching parameter struct manually.
+These event models retain platform-provided message id, content, attachments, mentions, timestamp, references, and internal `event_id`. Message id, content, author, routing id, and timestamp are required fields on normal message events; group/C2C messages also carry the required open-message `message_type`. Optional protocol fields stay optional.
+
+Attachments use `MessageAttachment`. When an attachment appears, the filename, content type, size, and URL are plain fields. `id` stays optional because open-message attachment payloads may omit it, while `width` and `height` default to `0` for non-image or payloads that do not include dimensions.
 
 ```rust
 let message = session.message();
-if let Some(content) = &message.content {
-    if content.trim() == "/ping" {
-        session.reply("pong").await?;
-    }
+if !message.author.bot && message.content.trim() == "/ping" {
+    session.reply("pong").await?;
 }
 ```
 
@@ -33,14 +33,22 @@ Outbound sending uses four parameter types:
 | `GroupMessageParams` | Group messages |
 | `C2CMessageParams` | C2C messages |
 
-The most common helpers are `new_text` and `with_reply`:
+Use session helpers inside reply-capable handlers:
+
+```rust
+session.reply("pong").await?;
+session.send_markdown_message("# hello").await?;
+session.send_embed_message(embed).await?;
+```
+
+For direct `BotApi` calls or custom fields, use params constructors:
 
 ```rust
 let params = MessageParams::new_text("pong").with_reply(message_id);
 session.send_message(params).await?;
 ```
 
-For complex messages, set fields directly:
+The rich constructors are `new_markdown`, `new_ark`, `new_embed`, `new_keyboard`, and, for group/C2C messages, `new_media`. Set fields directly only when you need a protocol field not covered by those constructors:
 
 - `embed` for embed messages.
 - `ark` for ark templates.
@@ -64,9 +72,9 @@ let params = DirectMessageParams::new_text("hello");
 session.send_direct_message(&dm_session.guild_id, params).await?;
 ```
 
-## Open Message msg_type
+## Open Message Types
 
-Group and C2C messages use the platform's numeric `msg_type`. Text generally keeps the default value 0; media uses 7; markdown, ark, embed, and other types follow the platform's protocol values. Guild channel messages use the Rust-modeled `MessageCreateType`.
+Group and C2C messages still serialize to the platform's open-message type codes, but normal user code should use session helpers or params constructors instead of setting the numeric value by hand. Guild channel and direct-message params use `MessageCreateType` internally.
 
 ## See Also