Merge branch 'AstrBotDevs:master' into cmd_suggestion

Author: elecvoid243

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -816,8 +816,9 @@ async def step(self):
         # 如果有工具调用，还需处理工具调用
         if llm_resp.tools_call_name:
             if self.tool_schema_mode == "skills_like":
-                llm_resp, _ = await self._resolve_tool_exec(llm_resp)
-                if not llm_resp.tools_call_name:
+                requery_resp, _ = await self._resolve_tool_exec(llm_resp)
+                if not requery_resp.tools_call_name:
+                    llm_resp = requery_resp
                     logger.warning(
                         "skills_like tool re-query returned no tool calls; fallback to assistant response."
                     )
@@ -845,6 +846,10 @@ async def step(self):
 
                     await self._complete_with_assistant_response(llm_resp)
                     return
+                else:
+                    llm_resp.tools_call_name = requery_resp.tools_call_name
+                    llm_resp.tools_call_args = requery_resp.tools_call_args
+                    llm_resp.tools_call_ids = requery_resp.tools_call_ids
 
             tool_call_result_blocks = []
             cached_images = []  # Collect cached images for LLM visibility

astrbot/core/provider/sources/openai_source.py

@@ -669,10 +669,14 @@ async def _query_stream(
                     # Gemini and some OpenAI-compatible proxies omit this field
                     if not hasattr(tc, "index") or tc.index is None:
                         tc.index = idx
-            try:
-                state.handle_chunk(chunk)
-            except Exception as e:
-                logger.error("Saving chunk state error: " + str(e))
+            # 跳过 delta=None 的 chunk，避免 SDK 内部 _convert_initial_chunk_into_snapshot
+            # 第 747 行 choice.delta.to_dict() 抛出 NoneType 错误。
+            # refs: AstrBot#6689 / openai-python#5069 / #5047
+            if delta is not None:
+                try:
+                    state.handle_chunk(chunk)
+                except Exception as e:
+                    logger.error("Saving chunk state error: " + str(e))
             # logger.debug(f"chunk delta: {delta}")
             # handle the content delta
             reasoning = self._extract_reasoning_content(chunk)
@@ -700,10 +704,14 @@ async def _query_stream(
             if _y:
                 yield llm_response
 
-        final_completion = state.get_final_completion()
-        llm_response = await self._parse_openai_completion(final_completion, tools)
-
-        yield llm_response
+        try:
+            final_completion = state.get_final_completion()
+            llm_response = await self._parse_openai_completion(final_completion, tools)
+            yield llm_response
+        except Exception as e:
+            logger.error("get_final_completion error: " + str(e))
+            # 流式内容已通过 yield 发出，记录错误后正常结束即可
+            return
 
     def _extract_reasoning_content(
         self,

astrbot/core/utils/t2i/network_strategy.py

@@ -156,9 +156,11 @@ async def render_custom_template(
         if options:
             default_options |= options
 
-        if SHIKI_RUNTIME_TEMPLATE_PATTERN.search(tmpl_str):
-            tmpl_data = {"shiki_runtime": get_shiki_runtime()} | tmpl_data
-        tmpl_str = inject_shiki_runtime(tmpl_str)
+        # 在线程池中执行 Shiki 注入，避免 1.2MB JS 处理阻塞事件循环
+        loop = asyncio.get_running_loop()
+        tmpl_str, tmpl_data = await loop.run_in_executor(
+            None, self._prepare_template_sync, tmpl_str, tmpl_data
+        )
         post_data = {
             "tmpl": tmpl_str,
             "json": return_url,
@@ -219,3 +221,11 @@ async def render(
             },
             return_url,
         )
+
+    @staticmethod
+    def _prepare_template_sync(tmpl_str: str, tmpl_data: dict) -> tuple[str, dict]:
+        """在线程池中执行的同步模板预处理（避免阻塞事件循环）"""
+        if SHIKI_RUNTIME_TEMPLATE_PATTERN.search(tmpl_str):
+            tmpl_data = {"shiki_runtime": get_shiki_runtime()} | tmpl_data
+        tmpl_str = inject_shiki_runtime(tmpl_str)
+        return tmpl_str, tmpl_data

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`