diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 458bc8dabe..cd62409ca9 100644 --- a/docs/.vitepress/config.mjs +++ b/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" }, diff --git a/docs/en/deploy/astrbot/desktop.md b/docs/en/deploy/astrbot/desktop.md new file mode 100644 index 0000000000..58f23c96a8 --- /dev/null +++ b/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). diff --git a/docs/en/dev/openapi.md b/docs/en/dev/openapi.md index c6e9dd3ce5..49e8b28758 100644 --- a/docs/en/dev/openapi.md +++ b/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 diff --git a/docs/en/dev/star/guides/ai.md b/docs/en/dev/star/guides/ai.md index cf7914bca8..0014b25bbf 100644 --- a/docs/en/dev/star/guides/ai.md +++ b/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` diff --git a/docs/en/dev/star/guides/env.md b/docs/en/dev/star/guides/env.md deleted file mode 100644 index 7dd0480b9e..0000000000 --- a/docs/en/dev/star/guides/env.md +++ /dev/null @@ -1,48 +0,0 @@ - -# 开发环境准备 - -## 获取插件模板 - -1. 打开 AstrBot 插件模板: [helloworld](https://github.com/Soulter/helloworld) -2. 点击右上角的 `Use this template` -3. 然后点击 `Create new repository`。 -4. 在 `Repository name` 处填写您的插件名。插件名格式: - - 推荐以 `astrbot_plugin_` 开头； - - 不能包含空格； - - 保持全部字母小写； - - 尽量简短。 -5. 点击右下角的 `Create repository`。 - -![New repo](https://files.astrbot.app/docs/source/images/plugin/image.png) - -## Clone 插件和 AstrBot 项目 - -Clone AstrBot 项目本体和刚刚创建的插件仓库到本地。 - -```bash -git clone https://github.com/AstrBotDevs/AstrBot -mkdir -p AstrBot/data/plugins -cd AstrBot/data/plugins -git clone 插件仓库地址 -``` - -然后，使用 `VSCode` 打开 `AstrBot` 项目。找到 `data/plugins/<你的插件名字>` 目录。 - -更新 `metadata.yaml` 文件，填写插件的元数据信息。 - -> [!NOTE] -> AstrBot 插件市场的信息展示依赖于 `metadata.yaml` 文件。 - -## 调试插件 - -AstrBot 采用在运行时注入插件的机制。因此，在调试插件时，需要启动 AstrBot 本体。 - -您可以使用 AstrBot 的热重载功能简化开发流程。 - -插件的代码修改后，可以在 AstrBot WebUI 的插件管理处找到自己的插件，点击右上角 `...` 按钮，选择 `重载插件`。 - -## 插件依赖管理 - -目前 AstrBot 对插件的依赖管理使用 `pip` 自带的 `requirements.txt` 文件。如果你的插件需要依赖第三方库，请务必在插件目录下创建 `requirements.txt` 文件并写入所使用的依赖库，以防止用户在安装你的插件时出现依赖未找到(Module Not Found)的问题。 - -> `requirements.txt` 的完整格式可以参考 [pip 官方文档](https://pip.pypa.io/en/stable/reference/requirements-file-format/)。 diff --git a/docs/en/dev/star/guides/listen-message-event.md b/docs/en/dev/star/guides/listen-message-event.md index 9e58326ca0..15c958de7d 100644 --- a/docs/en/dev/star/guides/listen-message-event.md +++ b/docs/en/dev/star/guides/listen-message-event.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. diff --git a/docs/en/dev/star/guides/send-message.md b/docs/en/dev/star/guides/send-message.md index 417b60ea00..961cc76fb5 100644 --- a/docs/en/dev/star/guides/send-message.md +++ b/docs/en/dev/star/guides/send-message.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) diff --git a/docs/en/dev/star/guides/simple.md b/docs/en/dev/star/guides/simple.md index d7ed40f957..7ce124098a 100644 --- a/docs/en/dev/star/guides/simple.md +++ b/docs/en/dev/star/guides/simple.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. -``` + diff --git a/docs/en/index.md b/docs/en/index.md index add09acdf0..90ce3ffa64 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -4,7 +4,7 @@ layout: home hero: name: >- - Soulter%2FAstrBot | Trendshift + AstrBotDevs%2FAstrBot | Trendshift text: "Agentic AI assistant for personal and group chats" tagline: Connect any IM / 1000+ plugins / General Agent Orchestration actions: diff --git a/docs/en/platform/discord.md b/docs/en/platform/discord.md index 4298ce38c0..f61f049a4c 100644 --- a/docs/en/platform/discord.md +++ b/docs/en/platform/discord.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 diff --git a/docs/en/platform/matrix.md b/docs/en/platform/matrix.md index 17d673defe..7d8b9bdc61 100644 --- a/docs/en/platform/matrix.md +++ b/docs/en/platform/matrix.md @@ -3,17 +3,40 @@ > [!TIP] > This platform adapter is maintained by the community ([stevessr](https://github.com/stevessr)). If you find it helpful, please support the developer by giving the repository a Star. ❤️ +## Deploying a Matrix Server + +Matrix is an IM protocol with a rich set of server implementations. + +Please refer to [Matrix Server](https://matrix.org/ecosystem/servers/) to view available server implementations. + +## Supported Message Types + +| Message Type | Receive | Send | Notes | +| ------------ | ------- | ---- | ----- | +| Text | Yes | Yes | | +| Image* | Yes | Yes | | +| Audio* | Yes | Yes | | +| Video* | Yes | Yes | | +| File* | Yes | Yes | | +| Poll | Yes | No | | + +\*: Will be persisted locally. The plugin will clean up according to configuration. Files will be uploaded before sending; uploads exceeding the server's size limit will fail. + ## Installing the astrbot_plugin_matrix_adapter Plugin Go to the AstrBot WebUI plugin marketplace, search for `astrbot_plugin_matrix_adapter`, and click Install. -After installation, navigate to Messaging Platforms → Add Adapter → Select Matrix (if the option is missing, try restarting AstrBot or check the plugin installation status). +After installation, navigate to Messaging Platforms (older versions: `Bot`) → Add Adapter → Select Matrix (if the option is missing, try restarting AstrBot or check the plugin installation status). Click `Enable` in the configuration dialog that appears. ## Configuration -Please refer to the repository's [README.md](https://github.com/stevessr/astrbot_plugin_matrix_adapter?tab=readme-ov-file#astrbot-matrix-adapter-%E6%8F%92%E4%BB%B6) for configuration instructions. +- **`matrix_homeserver` (required)**: The full URL of your Matrix server instance, supports delegation-based auto-discovery. For example, the official instance: `https://matrix.org` +- **`matrix_user_id`**: Your full Matrix username, e.g. `@username:homeserver.com` +- **`matrix_auth_method` (required)**: Your login method. Options: `password`, `token`, `oauth2`, `qr`. It is recommended to use `password` or `oauth2/qr` mode (in oauth2/qr mode, please ensure the device used for authentication/scanning can reach the public address configured in AstrBot) + +For more configuration options, please refer to the repository's [README.md](https://github.com/stevessr/astrbot_plugin_matrix_adapter?tab=readme-ov-file#astrbot-matrix-adapter-%E6%8F%92%E4%BB%B6). ## Issue Reporting diff --git a/docs/en/providers/ppio.md b/docs/en/providers/ppio.md index db9ed03b40..3812dc86b2 100644 --- a/docs/en/providers/ppio.md +++ b/docs/en/providers/ppio.md @@ -38,4 +38,4 @@ Send the `/provider` command to the bot to switch to the PPIO Cloud provider you Error code: 400 - {'code': 400, 'message': '"auto" tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set', 'type': 'BadRequestError'} ``` -Temporarily disable all function calling tools with `/tool off_all`, or switch to a different model. +Disable all calling tools in the WebUI, or switch to a different model. diff --git a/docs/en/use/function-calling.md b/docs/en/use/function-calling.md index 2208ddd113..8b0fbff9b7 100644 --- a/docs/en/use/function-calling.md +++ b/docs/en/use/function-calling.md @@ -32,14 +32,9 @@ In AstrBot, web search, todo reminders, and code interpreter tools are provided In addition to providing traditional command invocation, also offer function calling capabilities. -Related commands: +Tool management (enable/disable) can be done in the WebUI. -- `/tool ls` - View the list of available tools -- `/tool on` - Enable a specific tool -- `/tool off` - Disable a specific tool -- `/tool off_all` - Disable all tools - -Some models may not support function calling and will return errors such as `tool call is not supported`, `function calling is not supported`, `tool use is not supported`, etc. In most cases, AstrBot can detect these errors and automatically remove function calling tools for you. If you find that a model doesn't support function calling, you can also use the `/tool off_all` command to disable all tools and try again, or switch to a model that supports function calling. +Some models may not support function calling and will return errors such as `tool call is not supported`, `function calling is not supported`, `tool use is not supported`, etc. In most cases, AstrBot can detect these errors and automatically remove function calling tools for you. If you find that a model doesn't support function calling, you can also disable all calling tools in the WebUI and try again, or switch to a model that supports function calling. Below are some common tool calling demos: diff --git a/docs/zh/dev/star/guides/ai.md b/docs/zh/dev/star/guides/ai.md index ceba128ea2..9de4b498a3 100644 --- a/docs/zh/dev/star/guides/ai.md +++ b/docs/zh/dev/star/guides/ai.md @@ -157,8 +157,9 @@ Multi-Agent（多智能体）系统将复杂应用分解为多个专业化智能 from pydantic import Field from pydantic.dataclasses import dataclass +from astrbot.api import logger from astrbot.core.agent.run_context import ContextWrapper -from astrbot.core.agent.tool import FunctionTool, ToolExecResult +from astrbot.core.agent.tool import FunctionTool, ToolExecResult, ToolSet from astrbot.core.astr_agent_context import AstrAgentContext @dataclass @@ -348,6 +349,8 @@ from astrbot.core.agent.message import ( 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( diff --git a/docs/zh/dev/star/guides/env.md b/docs/zh/dev/star/guides/env.md deleted file mode 100644 index 7dd0480b9e..0000000000 --- a/docs/zh/dev/star/guides/env.md +++ /dev/null @@ -1,48 +0,0 @@ - -# 开发环境准备 - -## 获取插件模板 - -1. 打开 AstrBot 插件模板: [helloworld](https://github.com/Soulter/helloworld) -2. 点击右上角的 `Use this template` -3. 然后点击 `Create new repository`。 -4. 在 `Repository name` 处填写您的插件名。插件名格式: - - 推荐以 `astrbot_plugin_` 开头； - - 不能包含空格； - - 保持全部字母小写； - - 尽量简短。 -5. 点击右下角的 `Create repository`。 - -![New repo](https://files.astrbot.app/docs/source/images/plugin/image.png) - -## Clone 插件和 AstrBot 项目 - -Clone AstrBot 项目本体和刚刚创建的插件仓库到本地。 - -```bash -git clone https://github.com/AstrBotDevs/AstrBot -mkdir -p AstrBot/data/plugins -cd AstrBot/data/plugins -git clone 插件仓库地址 -``` - -然后，使用 `VSCode` 打开 `AstrBot` 项目。找到 `data/plugins/<你的插件名字>` 目录。 - -更新 `metadata.yaml` 文件，填写插件的元数据信息。 - -> [!NOTE] -> AstrBot 插件市场的信息展示依赖于 `metadata.yaml` 文件。 - -## 调试插件 - -AstrBot 采用在运行时注入插件的机制。因此，在调试插件时，需要启动 AstrBot 本体。 - -您可以使用 AstrBot 的热重载功能简化开发流程。 - -插件的代码修改后，可以在 AstrBot WebUI 的插件管理处找到自己的插件，点击右上角 `...` 按钮，选择 `重载插件`。 - -## 插件依赖管理 - -目前 AstrBot 对插件的依赖管理使用 `pip` 自带的 `requirements.txt` 文件。如果你的插件需要依赖第三方库，请务必在插件目录下创建 `requirements.txt` 文件并写入所使用的依赖库，以防止用户在安装你的插件时出现依赖未找到(Module Not Found)的问题。 - -> `requirements.txt` 的完整格式可以参考 [pip 官方文档](https://pip.pypa.io/en/stable/reference/requirements-file-format/)。 diff --git a/docs/zh/dev/star/guides/listen-message-event.md b/docs/zh/dev/star/guides/listen-message-event.md index edb7c7e0a2..18d1f5f2cc 100644 --- a/docs/zh/dev/star/guides/listen-message-event.md +++ b/docs/zh/dev/star/guides/listen-message-event.md @@ -261,7 +261,7 @@ from astrbot.api.event import filter, AstrMessageEvent @filter.on_waiting_llm_request() async def on_waiting_llm(self, event: AstrMessageEvent): - await event.send("🤔 正在等待请求...") + await event.send(event.plain_result("🤔 正在等待请求...")) ``` > 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。 diff --git a/docs/zh/dev/star/guides/other.md b/docs/zh/dev/star/guides/other.md index 774041173c..496582bf67 100644 --- a/docs/zh/dev/star/guides/other.md +++ b/docs/zh/dev/star/guides/other.md @@ -9,8 +9,12 @@ from astrbot.api.event import filter, AstrMessageEvent @filter.command("test") async def test_(self, event: AstrMessageEvent): - from astrbot.api.platform import AiocqhttpAdapter # 其他平台同理 - platform = self.context.get_platform(filter.PlatformAdapterType.AIOCQHTTP) + from astrbot.core.platform.sources.aiocqhttp.aiocqhttp_platform_adapter import AiocqhttpAdapter # 其他平台同理 + # >= v4.0.0 使用： + platform_id = event.get_platform_id() + platform = self.context.get_platform_inst(platform_id) + # < v4.0.0 使用（已废弃）： + # platform = self.context.get_platform(filter.PlatformAdapterType.AIOCQHTTP) assert isinstance(platform, AiocqhttpAdapter) # platform.get_client().api.call_action() ``` diff --git a/docs/zh/dev/star/guides/send-message.md b/docs/zh/dev/star/guides/send-message.md index 84eaf8ed36..0875876650 100644 --- a/docs/zh/dev/star/guides/send-message.md +++ b/docs/zh/dev/star/guides/send-message.md @@ -1,4 +1,3 @@ - # 消息的发送 ## 被动消息 @@ -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 需要用户的协议端和机器人端处于一个系统中。 - music = Video.fromFileSystem( + video = Video.fromFileSystem( path="test.mp4" ) # 更通用 - music = Video.fromURL( + video = Video.fromURL( url="https://example.com/video.mp4" ) - yield event.chain_result([music]) + yield event.chain_result([video]) ``` ![发送视频消息](https://files.astrbot.app/docs/source/images/plugin/db93a2bb-671c-4332-b8ba-9a91c35623c2.png) diff --git a/docs/zh/dev/star/plugin.md b/docs/zh/dev/star/plugin.md index c7b2df5166..622e348ba4 100644 --- a/docs/zh/dev/star/plugin.md +++ b/docs/zh/dev/star/plugin.md @@ -346,11 +346,11 @@ AstrBot 会自动帮你解析指令的参数。 ```python @filter.command("echo") -def echo(self, event: AstrMessageEvent, message: str): +async def echo(self, event: AstrMessageEvent, message: str): yield event.plain_result(f"你发了: {message}") @filter.command("add") -def add(self, event: AstrMessageEvent, a: int, b: int): +async def add(self, event: AstrMessageEvent, a: int, b: int): # /add 1 2 -> 结果是: 3 yield event.plain_result(f"结果是: {a + b}") ``` @@ -377,7 +377,7 @@ async def sub(self, event: AstrMessageEvent, a: int, b: int): 指令组函数内不需要实现任何函数，请直接 `pass` 或者添加函数内注释。指令组的子指令使用 `指令组名.command` 来注册。 -当用户没有输入子指令时，会报错并，并渲染出该指令组的树形结构。 +当用户没有输入子指令时，会报错并渲染出该指令组的树形结构。 ![image](https://files.astrbot.app/docs/source/images/plugin/image-1.png) @@ -462,7 +462,7 @@ async def on_aiocqhttp(self, event: AstrMessageEvent): yield event.plain_result("收到了一条信息") ``` -当前版本下，`PlatformAdapterType` 有 `AIOCQHTTP`, `QQOFFICIAL`, `GEWECHAT`, `ALL`。 +当前版本下，`PlatformAdapterType` 有 `AIOCQHTTP`, `QQOFFICIAL`, `ALL`等。 ##### 管理员指令 @@ -1163,7 +1163,7 @@ async def test(self, event: AstrMessageEvent): # func_tools_mgr = self.context.get_llm_tool_manager() prov = self.context.get_using_provider(umo=event.unified_msg_origin) if prov: - llm_resp = await provider.text_chat( + llm_resp = await prov.text_chat( prompt="Hi!", context=[ {"role": "user", "content": "balabala"}, @@ -1385,7 +1385,7 @@ class HelloWorldTool(FunctionTool): 要将上述工具注册到 AstrBot，可以在插件主文件的 `__init__.py` 中添加以下代码： ```py -from .tools.search import SearchTool +from .tools.search import HelloWorldTool class MyPlugin(Star): def __init__(self, context: Context): @@ -1643,7 +1643,7 @@ persona_mgr = self.context.persona_manager - **Arguments** - `persona_id: str` – 待删除的人格 ID - **Raises** - `Valueable` – 若 `persona_id` 不存在 + `ValueError` – 若 `persona_id` 不存在 ##### `get_default_persona_v3` diff --git a/docs/zh/index.md b/docs/zh/index.md index a62caef61b..745ec8bfd1 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -4,7 +4,7 @@ layout: home hero: name: >- - Soulter%2FAstrBot | Trendshift + AstrBotDevs%2FAstrBot | Trendshift text: "Agentic AI 助手，服务个人与群聊" tagline: 连接 IM / 1000+ 插件扩展 / 通用 Agent 能力编排 actions: diff --git a/docs/zh/platform/discord.md b/docs/zh/platform/discord.md index c5aaaaeb61..89c198a928 100644 --- a/docs/zh/platform/discord.md +++ b/docs/zh/platform/discord.md @@ -53,7 +53,9 @@ ![Generated URL位置](https://files.astrbot.app/docs/source/images/discord/image-5.png) 6. 进入 Discord 服务器，你的机器人应该已经提示在线了 + ![机器人在线](https://files.astrbot.app/docs/source/images/discord/image-7.png) + @ 刚刚创建的机器人（也可以不 @），输入 `/help`，如果成功返回，则测试成功。 ## 预回应表情 diff --git a/docs/zh/platform/matrix.md b/docs/zh/platform/matrix.md index 5a1ae0bbb7..db1d056f27 100644 --- a/docs/zh/platform/matrix.md +++ b/docs/zh/platform/matrix.md @@ -22,7 +22,8 @@ Matrix 是一个 IM 协议，有着丰富的服务端实现。 | 视频* | 是 | 是 | | | 文件* | 是 | 是 | | | 投票 | 是 | 否 | | -*: 会持久化到本地，插件会按配置清理，在发送前会进行上传操作，超过服务器允许大小的上传将会失败 + +\*: 会持久化到本地，插件会按配置清理，在发送前会进行上传操作，超过服务器允许大小的上传将会失败 ## 安装 astrbot_plugin_matrix_adapter 插件 @@ -34,7 +35,7 @@ Matrix 是一个 IM 协议，有着丰富的服务端实现。 ## 配置 -- **`matrix_homeserver` (必填)`**: 你的 matrix 服务器实例的完整URL地址,支持域名委托自动探测。例如官方实例`https://matrix.org` +- **`matrix_homeserver` (必填)**: 你的 matrix 服务器实例的完整URL地址,支持域名委托自动探测。例如官方实例`https://matrix.org` - **`matrix_user_id`**: 你的 matrix 完整用户名。如 `@username:homeserver.com` - **`matrix_auth_method` (必填)** : 你的登陆方式，可选`password`,`token`,`oauth2`,`qr`推荐使用`password`或`oauth2/qr`模式 (oauth2/qr 模式下请确保用于认证/扫码的设备回调可以访问到 astrbot 配置的公开地址) diff --git a/docs/zh/providers/ppio.md b/docs/zh/providers/ppio.md index fceb61dd10..24027c21fe 100644 --- a/docs/zh/providers/ppio.md +++ b/docs/zh/providers/ppio.md @@ -40,4 +40,4 @@ Error code: 400 - {'code': 400, 'message': '"auto" tool choice requires --enable ``` -请暂时使用 `/tool off_all` 禁用所有的函数调用工具即可使用，或者换用其他模型。 \ No newline at end of file +请在 WebUI 中关闭所有调用工具后即可使用，或者换用其他模型。 diff --git a/docs/zh/use/function-calling.md b/docs/zh/use/function-calling.md index d1b076ac25..5984ae30c8 100644 --- a/docs/zh/use/function-calling.md +++ b/docs/zh/use/function-calling.md @@ -30,14 +30,9 @@ outline: deep 等在提供传统的指令调用的基础上，也提供了函数调用的功能。 -相关指令: +相关操作请在 WebUI 中管理工具的开启和关闭。 -- `/tool ls` 查看当前具有的工具列表 -- `/tool on` 开启某个工具 -- `/tool off` 关闭某个工具 -- `/tool off_all` 关闭所有工具 - -某些模型可能不支持函数调用，会返回诸如 `tool call is not supported`, `function calling is not supported`, `tool use is not supported` 等错误。在大多数情况下，AstrBot 能够检测到这种错误并自动帮您去除函数调用工具。如果你发现某个模型不支持函数调用，也可使用 `/tool off_all` 命令关闭所有工具，然后再次尝试。或者更换为支持函数调用的模型。 +某些模型可能不支持函数调用，会返回诸如 `tool call is not supported`, `function calling is not supported`, `tool use is not supported` 等错误。在大多数情况下，AstrBot 能够检测到这种错误并自动帮您去除函数调用工具。如果你发现某个模型不支持函数调用，也可在 WebUI 中关闭所有调用工具，然后再次尝试。或者更换为支持函数调用的模型。 下面是一些常见的工具调用 Demo： @@ -49,4 +44,4 @@ outline: deep ## MCP -请前往此文档 [AstrBot - MCP](/use/mcp) 查看。 \ No newline at end of file +请前往此文档 [AstrBot - MCP](/use/mcp) 查看。