fix: docs (#8229)

* Update listen-message-event.md

* Update other.md

* Update send-message.md

* Update ai.md

* Update ai.md

* Update send-message.md

* Update listen-message-event.md

* Delete docs/zh/dev/star/guides/env.md

* Delete docs/en/dev/star/guides/env.md

* Update simple.md

* Update discord.md

* Update discord.md

* Update matrix.md

* Update matrix.md

* Update index.md

* Update index.md

* Update openapi.md

* Update ppio.md

* Update ppio.md

* Update function-calling.md

* Update function-calling.md

* Update config.mjs

* docs: add EN desktop deployment page

* Update plugin.md

* Update ai.md

* Update ai.md

* Update ai.md

* Update desktop.md

Author: lingyun14beta

docs/.vitepress/config.mjs

@@ -287,6 +287,7 @@ export default defineConfig({
             collapsed: false,
             items: [
               { text: "Package Manager", link: "/astrbot/package" },
+              { text: "Desktop Client", link: "/astrbot/desktop" },
               { text: "One-click Launcher", link: "/astrbot/launcher" },
               { text: "Docker", link: "/astrbot/docker" },
               { text: "Kubernetes", link: "/astrbot/kubernetes" },

docs/en/deploy/astrbot/desktop.md

@@ -0,0 +1,33 @@
+# Deploy with AstrBot Desktop Client
+
+`AstrBot-desktop` is designed for quick local deployment of AstrBot on your personal computer, supporting Windows, macOS, and Linux.
+
+Among the various deployment options, the desktop client is best suited for personal local use. It is not recommended for long-term server operation or production environments. For production deployments, consider [Docker](/en/deploy/astrbot/docker) or [Kubernetes](/en/deploy/astrbot/kubernetes) instead.
+
+Compared to command-line or container-based solutions, the desktop client offers an out-of-the-box experience, ideal for users who want to get started without dealing with environment setup.
+
+Repository: [AstrBotDevs/AstrBot-desktop](https://github.com/AstrBotDevs/AstrBot-desktop)
+
+## Who Is It For
+
+- Users who want quick local deployment with a graphical interface.
+- Beginners who don't want to manually manage Docker / Python environments.
+- Personal devices that stay online, primarily for individual or small team daily use.
+
+## Key Features
+
+- Multi-platform installers, ready to use after download.
+- GUI-based configuration, lowering the barrier for first-time deployment.
+- Suitable as a locally resident client.
+
+## Download and Install
+
+1. Open [AstrBot-desktop Releases](https://github.com/AstrBotDevs/AstrBot-desktop/releases).
+2. Download the installer for your operating system (e.g. `.exe`, `.dmg`, `.rpm`, `.deb`).
+3. Launch the desktop client after installation and follow the setup wizard to complete initialization.
+
+## Difference from Launcher Deployment
+
+- Desktop client: focuses on an out-of-the-box GUI experience.
+- Launcher deployment: focuses on automated script-based startup, suitable for users who prefer a traditional deployment workflow.
+- See [Launcher Deployment](/en/deploy/astrbot/launcher).

docs/en/dev/openapi.md

@@ -26,15 +26,113 @@ X-API-Key: abk_xxx
 - `POST /api/v1/chat`: request body must include `username`
 - `GET /api/v1/chat/sessions`: query params must include `username`
 
+## Scope Permissions
+
+When creating an API Key, you can configure `scopes`. Each scope controls the range of accessible endpoints:
+
+| Scope | Purpose | Accessible Endpoints |
+| --- | --- | --- |
+| `chat` | Access chat capabilities and query sessions | `POST /api/v1/chat`, `GET /api/v1/chat/sessions` |
+| `config` | Retrieve available config file list | `GET /api/v1/configs` |
+| `file` | Upload attachment files and get `attachment_id` | `POST /api/v1/file` |
+| `im` | Send proactive IM messages, query bot/platform list | `POST /api/v1/im/message`, `GET /api/v1/im/bots` |
+
+If the API Key does not include the required scope for the target endpoint, the request will return `403 Insufficient API key scope`.
+
 ## Common Endpoints
 
+**Chat**
+
+Interact with AstrBot's built-in Agent. Supports plugin calls, tool calls, and other capabilities — consistent with IM-side chat.
+
 - `POST /api/v1/chat`: send chat message (SSE stream, server generates UUID when `session_id` is omitted)
 - `GET /api/v1/chat/sessions`: list sessions for a specific `username` with pagination
 - `GET /api/v1/configs`: list available config files
+
+**File Upload**
+
 - `POST /api/v1/file`: upload attachment
-- `POST /api/v1/im/message`: proactive message via UMO
+
+**Proactive IM Messages**
+
+- `POST /api/v1/im/message`: send a proactive message via UMO
 - `GET /api/v1/im/bots`: list bot/platform IDs
 
+## `message` Field Format (Important)
+
+The `message` field in `POST /api/v1/chat` and `POST /api/v1/im/message` supports two formats:
+
+1. String: plain text message
+2. Array: message segments (message chain)
+
+### 1. Plain Text Format
+
+```json
+{
+  "message": "Hello"
+}
+```
+
+### 2. Message Segment Array Format
+
+```json
+{
+  "message": [
+    { "type": "plain", "text": "Please see this file" },
+    { "type": "file", "attachment_id": "9a2f8c72-e7af-4c0e-b352-111111111111" }
+  ]
+}
+```
+
+Supported `type` values:
+
+| type | Required Fields | Optional Fields | Description |
+| --- | --- | --- | --- |
+| `plain` | `text` | - | Text segment |
+| `reply` | `message_id` | `selected_text` | Quote-reply a message |
+| `image` | `attachment_id` | - | Image attachment segment |
+| `record` | `attachment_id` | - | Audio attachment segment |
+| `file` | `attachment_id` | - | Generic file segment |
+| `video` | `attachment_id` | - | Video attachment segment |
+
+* The `reply` segment is currently only supported for `/api/v1/chat`, not for `POST /api/v1/im/message`.
+
+Notes:
+
+- `attachment_id` comes from the upload result of `POST /api/v1/file`.
+- `reply` cannot be the only segment; at least one content segment (e.g. `plain/image/file/...`) is required.
+- A request with only `reply` or empty content will return an error.
+
+### `message` Usage in Chat API
+
+`POST /api/v1/chat` additionally requires `username`, with optional `session_id` (a UUID is auto-generated if omitted).
+
+```json
+{
+  "username": "alice",
+  "session_id": "my_session_001",
+  "message": [
+    { "type": "plain", "text": "Please summarize this PDF" },
+    { "type": "file", "attachment_id": "9a2f8c72-e7af-4c0e-b352-111111111111" }
+  ],
+  "enable_streaming": true
+}
+```
+
+### `message` Usage in IM Message API
+
+`POST /api/v1/im/message` requires `umo` + `message`.
+
+```json
+{
+  "umo": "webchat:FriendMessage:openapi_probe",
+  "message": [
+    { "type": "plain", "text": "This is a proactive message" },
+    { "type": "image", "attachment_id": "9a2f8c72-e7af-4c0e-b352-222222222222" }
+  ]
+}
+```
+
 ## Example
 
 ```bash

docs/en/dev/star/guides/ai.md

@@ -157,13 +157,21 @@ In the example below, we define a Main Agent responsible for delegating tasks to
 Define Tools:
 
 ```py
+from astrbot.api import logger
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.agent.tool import FunctionTool, ToolExecResult, ToolSet
+from astrbot.core.astr_agent_context import AstrAgentContext
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+
+
 @dataclass
 class AssignAgentTool(FunctionTool[AstrAgentContext]):
     """Main agent uses this tool to decide which sub-agent to delegate a task to."""
 
     name: str = "assign_agent"
     description: str = "Assign an agent to a task based on the given query"
-    parameters: dict = field(
+    parameters: dict = Field(
         default_factory=lambda: {
             "type": "object",
             "properties": {
@@ -178,7 +186,7 @@ class AssignAgentTool(FunctionTool[AstrAgentContext]):
 
     async def call(
         self, context: ContextWrapper[AstrAgentContext], **kwargs
-    ) -> str | CallToolResult:
+    ) -> ToolExecResult:
         # Here you would implement the actual agent assignment logic.
         # For demonstration purposes, we'll return a dummy response.
         return "Based on the query, you should assign agent 1."
@@ -190,7 +198,7 @@ class WeatherTool(FunctionTool[AstrAgentContext]):
 
     name: str = "weather"
     description: str = "Get weather information for a location"
-    parameters: dict = field(
+    parameters: dict = Field(
         default_factory=lambda: {
             "type": "object",
             "properties": {
@@ -205,7 +213,7 @@ class WeatherTool(FunctionTool[AstrAgentContext]):
 
     async def call(
         self, context: ContextWrapper[AstrAgentContext], **kwargs
-    ) -> str | CallToolResult:
+    ) -> ToolExecResult:
         city = kwargs["city"]
         # Here you would implement the actual weather fetching logic.
         # For demonstration purposes, we'll return a dummy response.
@@ -218,7 +226,7 @@ class SubAgent1(FunctionTool[AstrAgentContext]):
 
     name: str = "subagent1_name"
     description: str = "subagent1_description"
-    parameters: dict = field(
+    parameters: dict = Field(
         default_factory=lambda: {
             "type": "object",
             "properties": {
@@ -233,7 +241,7 @@ class SubAgent1(FunctionTool[AstrAgentContext]):
 
     async def call(
         self, context: ContextWrapper[AstrAgentContext], **kwargs
-    ) -> str | CallToolResult:
+    ) -> ToolExecResult:
         ctx = context.context.context
         event = context.context.event
         logger.info(f"the llm context messages: {context.messages}")
@@ -255,7 +263,7 @@ class SubAgent2(FunctionTool[AstrAgentContext]):
 
     name: str = "subagent2_name"
     description: str = "subagent2_description"
-    parameters: dict = field(
+    parameters: dict = Field(
         default_factory=lambda: {
             "type": "object",
             "properties": {
@@ -270,7 +278,7 @@ class SubAgent2(FunctionTool[AstrAgentContext]):
 
     async def call(
         self, context: ContextWrapper[AstrAgentContext], **kwargs
-    ) -> str | CallToolResult:
+    ) -> ToolExecResult:
         return "I am useless :(, you shouldn't call me :("
 ```
 
@@ -335,6 +343,32 @@ class Conversation:
 
 :::
 
+### Quickly Adding LLM Records to a Conversation `add_message_pair`
+
+```py
+from astrbot.core.agent.message import (
+    AssistantMessageSegment,
+    UserMessageSegment,
+    TextPart,
+)
+
+conv_mgr = self.context.conversation_manager
+provider_id = await self.context.get_current_chat_provider_id(event.unified_msg_origin)
+curr_cid = await conv_mgr.get_curr_conversation_id(event.unified_msg_origin)
+user_msg = UserMessageSegment(content=[TextPart(text="hi")])
+llm_resp = await self.context.llm_generate(
+    chat_provider_id=provider_id,  # Chat model ID
+    contexts=[user_msg],  # When prompt is not specified, contexts is used as input; if both prompt and contexts are provided, prompt is appended to the end of the LLM input
+)
+await conv_mgr.add_message_pair(
+    cid=curr_cid,
+    user_message=user_msg,
+    assistant_message=AssistantMessageSegment(
+        content=[TextPart(text=llm_resp.completion_text)]
+    ),
+)
+```
+
 ### Main Methods
 
 #### `new_conversation`

docs/en/dev/star/guides/env.md

@@ -250,6 +250,22 @@ async def on_astrbot_loaded(self):
 
 ```
 
+#### On Waiting for LLM Request
+
+This hook is triggered when AstrBot is preparing to call the LLM but has not yet acquired the session lock.
+
+It is suitable for sending feedback such as "Waiting for request..." to the user, or for obtaining the LLM request outside the lock without waiting for it to be released.
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+
+@filter.on_waiting_llm_request()
+async def on_waiting_llm(self, event: AstrMessageEvent):
+    await event.send(event.plain_result("🤔 Waiting for request..."))
+```
+
+> You cannot use yield to send messages here. If you need to send, please use the `event.send()` method directly.
+
 #### On LLM Request
 
 In AstrBot's default execution flow, the `on_llm_request` hook is triggered before calling the LLM.

docs/en/dev/star/guides/listen-message-event.md

@@ -1,4 +1,3 @@
-
 # Sending Messages
 
 ## Passive Messages
@@ -93,14 +92,14 @@ from astrbot.api.event import filter, AstrMessageEvent
 async def test(self, event: AstrMessageEvent):
     from astrbot.api.message_components import Video
     # fromFileSystem requires the user's protocol client and bot to be on the same system.
-    music = Video.fromFileSystem(
+    video = Video.fromFileSystem(
         path="test.mp4"
     )
     # More universal approach
-    music = Video.fromURL(
+    video = Video.fromURL(
         url="https://example.com/video.mp4"
     )
-    yield event.chain_result([music])
+    yield event.chain_result([video])
 ```
 
 ![Sending video messages](https://files.astrbot.app/docs/source/images/plugin/db93a2bb-671c-4332-b8ba-9a91c35623c2.png)

docs/en/dev/star/guides/send-message.md

@@ -39,4 +39,4 @@ Explanation:
 > The file containing the plugin class must be named `main.py`.
 
 All handler functions must be written within the plugin class. To keep content concise, in subsequent sections, we may omit the plugin class definition.
-```
+

docs/en/dev/star/guides/simple.md

@@ -4,7 +4,7 @@ layout: home
 
 hero:
   name: >-
-    <a href="https://trendshift.io/repositories/12875" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12875" alt="Soulter%2FAstrBot | Trendshift" style="width: 250px; height: 55px; margin-bottom: 16px;" width="250" height="55"/></a>
+    <a href="https://trendshift.io/repositories/21369" target="_blank"><img src="https://trendshift.io/api/badge/repositories/21369" alt="AstrBotDevs%2FAstrBot | Trendshift" style="width: 250px; height: 55px; margin-bottom: 16px;" width="250" height="55"/></a>
   text: "Agentic AI assistant for personal and group chats"
   tagline: Connect any IM / 1000+ plugins / General Agent Orchestration
   actions:

docs/en/index.md

@@ -55,7 +55,9 @@ If you find this tedious, you can directly use administrator permissions, but it
 ![Generated URL location](https://files.astrbot.app/docs/source/images/discord/image-5.png)
 
 6. Enter your Discord server, your bot should now show as online
+
 ![Bot online](https://files.astrbot.app/docs/source/images/discord/image-7.png)
+
 @ mention the bot you just created (or don't mention it), type `/help`. If it responds successfully, the test is successful.
 
 ## Pre-acknowledgment Emoji