mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-15 17:30:13 +08:00
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
This commit is contained in:
lingyun14
@@ -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" },
|
||||
|
||||
33
docs/en/deploy/astrbot/desktop.md
Normal file
33
docs/en/deploy/astrbot/desktop.md
Normal file
@@ -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).
|
||||
@@ -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
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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`。
|
||||
|
||||
|
||||
|
||||
## 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/)。
|
||||
@@ -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.
|
||||
|
||||
@@ -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])
|
||||
```
|
||||
|
||||
|
||||
|
||||
@@ -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.
|
||||
```
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -55,7 +55,9 @@ If you find this tedious, you can directly use administrator permissions, but it
|
||||
|
||||
|
||||
6. Enter your Discord server, your bot should now show as online
|
||||
|
||||
|
||||
|
||||
@ mention the bot you just created (or don't mention it), type `/help`. If it responds successfully, the test is successful.
|
||||
|
||||
## Pre-acknowledgment Emoji
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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`。
|
||||
|
||||
|
||||
|
||||
## 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/)。
|
||||
@@ -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()` 方法。
|
||||
|
||||
@@ -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()
|
||||
```
|
||||
|
||||
@@ -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])
|
||||
```
|
||||
|
||||
|
||||
|
||||
@@ -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` 来注册。
|
||||
|
||||
当用户没有输入子指令时，会报错并，并渲染出该指令组的树形结构。
|
||||
当用户没有输入子指令时，会报错并渲染出该指令组的树形结构。
|
||||
|
||||
|
||||
|
||||
@@ -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`
|
||||
|
||||
|
||||
@@ -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 助手，服务个人与群聊"
|
||||
tagline: 连接 IM / 1000+ 插件扩展 / 通用 Agent 能力编排
|
||||
actions:
|
||||
|
||||
@@ -53,7 +53,9 @@
|
||||
|
||||
|
||||
6. 进入 Discord 服务器，你的机器人应该已经提示在线了
|
||||
|
||||
|
||||
|
||||
@ 刚刚创建的机器人（也可以不 @），输入 `/help`，如果成功返回，则测试成功。
|
||||
|
||||
## 预回应表情
|
||||
|
||||
@@ -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 配置的公开地址)
|
||||
|
||||
|
||||
@@ -40,4 +40,4 @@ Error code: 400 - {'code': 400, 'message': '"auto" tool choice requires --enable
|
||||
```
|
||||
|
||||
|
||||
请暂时使用 `/tool off_all` 禁用所有的函数调用工具即可使用，或者换用其他模型。
|
||||
请在 WebUI 中关闭所有调用工具后即可使用，或者换用其他模型。
|
||||
|
||||
@@ -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) 查看。
|
||||
请前往此文档 [AstrBot - MCP](/use/mcp) 查看。
|
||||
|
||||
Reference in New Issue
Block a user