opensource/AstrBot
3
0
Fork 0
mirror of https://github.com/AstrBotDevs/AstrBot.git synced 2026-09-24 16:39:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: merge origin/master into dev

Browse Source
This commit is contained in:
LIghtJUNction
2026-05-19 21:15:22 +08:00
parent 273b6777cf dceacd5a87
commit 987099d4cb
185 changed files with 10524 additions and 3637 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.vitepress/config.mjs
+1 -1
View File
@@ -343,6 +343,7 @@ export default defineConfig({
{ text: "Mattermost", link: "/mattermost" },
{ text: "Misskey", link: "/misskey" },
{ text: "Discord", link: "/discord" },
{ text: "KOOK", link: "/kook" },
{
text: "Satori",
base: "/en/platform/satori",
@@ -357,7 +358,6 @@ export default defineConfig({
collapsed: false,
items: [
{ text: "Matrix", link: "/matrix" },
{ text: "KOOK", link: "/kook" },
{ text: "VoceChat", link: "/vocechat" },
],
},
docs/en/deploy/astrbot/cli.md
+1 -1
View File
@@ -86,7 +86,7 @@ If there are no errors, you will see a log message similar to `🌈 Dashboard st
> [!TIP]
> If you are deploying AstrBot on a server, you need to replace `localhost` with your server's IP address.
>
> The default username and password are `astrbot` and `astrbot`.
> New users must use the random password printed in the startup logs to log in for the first time. Use the username shown in the logs (usually `astrbot`) and change it after first login.
Next, you need to deploy any messaging platform to use AstrBot on that platform.
docs/en/deploy/astrbot/compshare.md
+1 -1
View File
@@ -35,7 +35,7 @@ You can find the public IP in Console -> Basic Network (Public).
![WebUI](https://www-s.ucloud.cn/2025/07/7e9fc6edc1dfa916abc069f4cecc24cf_1753940381771.png)
Login with username `astrbot` and password `astrbot`.
Use the random password printed in startup logs for first-time login, and use the username shown in the logs (usually `astrbot`). Change it immediately after login.
After logging in, you can reset your password and continue setup.
docs/en/deploy/astrbot/docker.md
+1 -1
View File
@@ -84,7 +84,7 @@ If there are no errors, you will see a log message similar to `🌈 Dashboard st
> [!TIP]
> Since Docker isolates the network environment, you cannot use `localhost` to access the dashboard.
>
> The default username and password are `astrbot` and `astrbot`.
> New users must use the random password printed in the startup logs to log in for the first time. Use the username shown in the logs (usually `astrbot`) and change the password after first login.
>
> If deployed on a cloud server, you need to open ports `6180-6200` and `11451` in the cloud provider's console.
docs/en/deploy/astrbot/kubernetes.md
+1 -1
View File
@@ -194,4 +194,4 @@ Edit the `02-deployment.yaml` file and add `volumes` and `volumeMounts` under `s
After deploying and exposing the service, you can access the AstrBot admin panel through the corresponding IP and port.
> The default username and password are `astrbot` and `astrbot`.
> New users must use the random password printed in the startup logs for the first login. Use the username shown in the logs (usually `astrbot`) and change it after logging in.
docs/en/deploy/astrbot/launcher.md
+1 -1
View File
@@ -66,7 +66,7 @@ If everything works, you will see AstrBot logs.
Without errors, you should see a log like `🌈 Management panel started, accessible at` with several URLs. Open one URL to access AstrBot WebUI.
> [!TIP]
> Default username and password: `astrbot` / `astrbot`.
> First-time logins use the random password generated on startup and printed to logs. Use that password (and the username shown in the logs, usually `astrbot`) to log in, then change it immediately.
>
> If WebUI returns 404:
> Download `dist.zip` from [release](https://github.com/AstrBotDevs/AstrBot/releases), extract it into `AstrBot/data`, then restart the computer if needed.
docs/en/dev/astrbot-config.md
+4 -4
View File
@@ -116,7 +116,7 @@ The default AstrBot configuration is as follows:
"dashboard": {
"enable": True,
"username": "astrbot",
"password": "77b90590a8945a7d36c963981a307dc9",
"password": "<your_password_md5>",
"jwt_secret": "",
"host": "0.0.0.0",
"port": 6185,
@@ -492,11 +492,11 @@ List of addresses that bypass the proxy. E.g., `["localhost", "127.0.0.1"]`.
AstrBot WebUI configuration.
Please do not change the `password` value arbitrarily. It is an `md5` encoded password. Change the password in the control panel.
Please do not change the `password` value arbitrarily. It is an `md5` encoded password generated from the random initial password. Check the startup logs for that initial password on first run, then change it in the control panel.
- `enable`: Whether to enable the AstrBot WebUI. Default is `true`.
- `username`: Username for the AstrBot WebUI. Default is `astrbot`.
- `password`: Password for the AstrBot WebUI. Default is the `md5` encoded value of `astrbot`. Do not modify directly unless you know what you are doing.
- `username`: Username for the AstrBot WebUI.
- `password`: Password for the AstrBot WebUI. It is initialized from a random password generated on first startup (logged at startup). Do not modify directly unless you know what you are doing.
- `jwt_secret`: JWT secret key. AstrBot generates this randomly at initialization. Do not modify unless you know what you are doing.
- `host`: Address the AstrBot WebUI listens on. Default is `0.0.0.0`.
- `port`: Port the AstrBot WebUI listens on. Default is `6185`.
docs/en/dev/plugin-platform-adapter.md
+62 -61
View File
@@ -2,63 +2,63 @@
outline: deep
---
# 开发一个平台适配器
# Developing a Platform Adapter
AstrBot 支持以插件的形式接入平台适配器，你可以自行接入 AstrBot 没有的平台。如飞书、钉钉甚至是哔哩哔哩私信、Minecraft。
AstrBot supports integrating platform adapters in plugin form, allowing you to connect platforms that AstrBot does not natively support — such as Lark, DingTalk, Bilibili private messages, or even Minecraft.
我们以一个平台 `FakePlatform` 为例展开讲解。
We will use a platform called `FakePlatform` as an example.
首先，在插件目录下新增 `fake_platform_adapter.py` 和 `fake_platform_event.py` 文件。前者主要是平台适配器的实现，后者是平台事件的定义。
First, add `fake_platform_adapter.py` and `fake_platform_event.py` to your plugin directory. The former handles the platform adapter implementation, while the latter defines the platform event.
## 平台适配器
## Platform Adapter
假设 FakePlatform 的客户端 SDK 是这样：
Assume FakePlatform's client SDK looks like this:
```py
import asyncio
class FakeClient():
'''模拟一个消息平台，这里 5 秒钟下发一个消息'''
'''Simulates a messaging platform that sends a message every 5 seconds'''
def __init__(self, token: str, username: str):
self.token = token
self.username = username
# ...
async def start_polling(self):
while True:
await asyncio.sleep(5)
await getattr(self, 'on_message_received')({
'bot_id': '123',
'content': '新消息',
'content': 'new message',
'username': 'zhangsan',
'userid': '123',
'message_id': 'asdhoashd',
'group_id': 'group123',
})
async def send_text(self, to: str, message: str):
print('发了消息:', to, message)
print('Message sent:', to, message)
async def send_image(self, to: str, image_path: str):
print('发了消息:', to, image_path)
print('Image sent:', to, image_path)
```
我们创建 `fake_platform_adapter.py`：
Now create `fake_platform_adapter.py`:
```py
import asyncio
from astrbot.api.platform import Platform, AstrBotMessage, MessageMember, PlatformMetadata, MessageType
from astrbot.api.event import MessageChain
from astrbot.api.message_components import Plain, Image, Record # 消息链中的组件，可以根据需要导入
from astrbot.core.platform.astr_message_event import MessageSesion
from astrbot.api.message_components import Plain, Image, Record # Message chain components, import as needed
from astrbot.core.platform.message_session import MessageSesion
from astrbot.api.platform import register_platform_adapter
from astrbot import logger
from .client import FakeClient
from .fake_platform_event import FakePlatformEvent
# 注册平台适配器。第一个参数为平台名，第二个为描述。第三个为默认配置。
@register_platform_adapter("fake", "fake 适配器", default_config_tmpl={
# Register the platform adapter. First param: platform name, second: description, third: default config.
@register_platform_adapter("fake", "fake adapter", default_config_tmpl={
"token": "your_token",
"username": "bot_username"
})
@@ -66,52 +66,53 @@ class FakePlatformAdapter(Platform):
def __init__(self, platform_config: dict, platform_settings: dict, event_queue: asyncio.Queue) -> None:
super().__init__(event_queue)
self.config = platform_config # 上面的默认配置，用户填写后会传到这里
self.settings = platform_settings # platform_settings 平台设置。
self.config = platform_config # The default config above; filled in by the user and passed here
self.settings = platform_settings # platform_settings: platform settings
async def send_by_session(self, session: MessageSesion, message_chain: MessageChain):
# 必须实现
# Must be implemented
await super().send_by_session(session, message_chain)
def meta(self) -> PlatformMetadata:
# 必须实现，直接像下面一样返回即可。
# Must be implemented. Simply return as shown below.
return PlatformMetadata(
"fake",
"fake 适配器",
"fake adapter",
)
async def run(self):
# 必须实现，这里是主要逻辑。
# Must be implemented. This is the main logic.
# FakeClient 是我们自己定义的，这里只是示例。这个是其回调函数
# FakeClient is defined by us — this is just an example. This is its callback function.
async def on_received(data):
logger.info(data)
abm = await self.convert_message(data=data) # 转换成 AstrBotMessage
await self.handle_msg(abm)
# 初始化 FakeClient
abm = await self.convert_message(data=data) # Convert to AstrBotMessage
await self.handle_msg(abm)
# Initialize FakeClient
self.client = FakeClient(self.config['token'], self.config['username'])
self.client.on_message_received = on_received
await self.client.start_polling() # 持续监听消息，这是个堵塞方法。
await self.client.start_polling() # Continuously listens for messages; this is a blocking call.
async def convert_message(self, data: dict) -> AstrBotMessage:
# 将平台消息转换成 AstrBotMessage
# 这里就体现了适配程度，不同平台的消息结构不一样，这里需要根据实际情况进行转换。
# Convert the platform message to AstrBotMessage.
# The degree of adaptation is reflected here. Different platforms have different message
# structures; convert accordingly.
abm = AstrBotMessage()
abm.type = MessageType.GROUP_MESSAGE # 还有 friend_message，对应私聊。具体平台具体分析。重要！
abm.group_id = data['group_id'] # 如果是私聊，这里可以不填
abm.message_str = data['content'] # 纯文本消息。重要！
abm.sender = MessageMember(user_id=data['userid'], nickname=data['username']) # 发送者。重要！
abm.message = [Plain(text=data['content'])] # 消息链。如果有其他类型的消息，直接 append 即可。重要！
abm.raw_message = data # 原始消息。
abm.type = MessageType.GROUP_MESSAGE # Also friend_message for private chats. Analyze per platform. Important!
abm.group_id = data['group_id'] # Can be omitted for private chats
abm.message_str = data['content'] # Plain text message. Important!
abm.sender = MessageMember(user_id=data['userid'], nickname=data['username']) # Sender. Important!
abm.message = [Plain(text=data['content'])] # Message chain. Append other message types as needed. Important!
abm.raw_message = data # Raw message.
abm.self_id = data['bot_id']
abm.session_id = data['userid'] # 会话 ID。重要！
abm.message_id = data['message_id'] # 消息 ID。
abm.session_id = data['userid'] # Session ID. Important!
abm.message_id = data['message_id'] # Message ID.
return abm
async def handle_msg(self, message: AstrBotMessage):
# 处理消息
# Handle the message
message_event = FakePlatformEvent(
message_str=message.message_str,
message_obj=message,
@@ -119,11 +120,11 @@ class FakePlatformAdapter(Platform):
session_id=message.session_id,
client=self.client
)
self.commit_event(message_event) # 提交事件到事件队列。不要忘记！
self.commit_event(message_event) # Submit the event to the event queue. Don't forget this!
```
`fake_platform_event.py`：
`fake_platform_event.py`:
```py
from astrbot.api.event import AstrMessageEvent, MessageChain
@@ -136,15 +137,15 @@ class FakePlatformEvent(AstrMessageEvent):
def __init__(self, message_str: str, message_obj: AstrBotMessage, platform_meta: PlatformMetadata, session_id: str, client: FakeClient):
super().__init__(message_str, message_obj, platform_meta, session_id)
self.client = client
async def send(self, message: MessageChain):
for i in message.chain: # 遍历消息链
if isinstance(i, Plain): # 如果是文字类型的
for i in message.chain: # Iterate over the message chain
if isinstance(i, Plain): # If it's a text message
await self.client.send_text(to=self.get_sender_id(), message=i.text)
elif isinstance(i, Image): # 如果是图片类型的
elif isinstance(i, Image): # If it's an image
img_url = i.file
img_path = ""
# 下面的三个条件可以直接参考一下。
# The three conditions below can be used as a reference.
if img_url.startswith("file:///"):
img_path = img_url[8:]
elif i.file and i.file.startswith("http"):
@@ -152,14 +153,14 @@ class FakePlatformEvent(AstrMessageEvent):
else:
img_path = img_url
# 请善于 Debug！
# Make good use of debugging!
await self.client.send_image(to=self.get_sender_id(), image_path=img_path)
await super().send(message) # 需要最后加上这一段，执行父类的 send 方法。
await super().send(message) # Must be called at the end to invoke the parent class's send method.
```
最后，main.py 只需这样，在初始化的时候导入 fake_platform_adapter 模块。装饰器会自动注册。
Finally, in `main.py`, simply import the `fake_platform_adapter` module during initialization. The decorator will handle registration automatically.
```py
from astrbot.api.star import Context, Star
@@ -169,17 +170,17 @@ class MyPlugin(Star):
from .fake_platform_adapter import FakePlatformAdapter # noqa
```
搞好后，运行 AstrBot：
Once set up, run AstrBot:
![image](https://files.astrbot.app/docs/source/images/plugin-platform-adapter/QQ_1738155926221.png)
这里出现了我们创建的 fake。
The `fake` adapter we created now appears here.
![image](https://files.astrbot.app/docs/source/images/plugin-platform-adapter/QQ_1738155982211.png)
启动后，可以看到正常工作：
After starting, you can see it working correctly:
![image](https://files.astrbot.app/docs/source/images/plugin-platform-adapter/QQ_1738156166893.png)
有任何疑问欢迎加群询问~
If you have any questions, feel free to join the community group and ask~
docs/en/dev/star/guides/ai.md
+112 -61
View File
@@ -1,4 +1,3 @@
# AI
AstrBot provides built-in support for multiple Large Language Model (LLM) providers and offers a unified interface, making it convenient for plugin developers to access various LLM services.
@@ -67,6 +66,58 @@ class BilibiliTool(FunctionTool[AstrAgentContext]):
return "1. Video Title: How to Use AstrBot\nVideo Link: xxxxxx"
```
## Registering Tools with AstrBot
Once a Tool is defined, if you want it to be automatically invoked during user conversations, register it in your plugin's `__init__` method:
```py
class MyPlugin(Star):
def __init__(self, context: Context):
super().__init__(context)
# >= v4.5.1:
self.context.add_llm_tools(BilibiliTool(), SecondTool(), ...)
# < v4.5.1:
tool_mgr = self.context.provider_manager.llm_tools
tool_mgr.func_list.append(BilibiliTool())
```
> [!WARNING]
> `context.register_llm_tool()` is deprecated. Do not use it in new plugins.
>
> If you must use it for legacy compatibility, `func_args` must be a **list of dicts** in this format:
> ```py
> func_args = [{"type": "string", "name": "arg_name", "description": "..."}, ...]
> ```
> Passing a list of strings or any other format will raise `AttributeError: 'str' object has no attribute 'pop'`.
### Registering Tools via Decorator
Alternatively, you can use the `@filter.llm_tool` decorator to define and register a tool in one step. Make sure to follow the exact format below, including the docstring — AstrBot parses the docstring to generate the parameter schema:
```py{3,4,5,6,7}
@filter.llm_tool(name="get_weather") # If name is omitted, the function name is used
async def get_weather(self, event: AstrMessageEvent, location: str) -> MessageEventResult:
'''Get weather information.
Args:
location(string): The location to query
'''
resp = self.get_weather_from_api(location)
yield event.plain_result("Weather: " + resp)
```
In `location(string): The location to query`, `location` is the parameter name, `string` is the type, and the remainder is the description.
Supported types: `string`, `number`, `object`, `boolean`, `array`. Since v4.5.7, array subtypes are supported, e.g. `array[string]`.
> [!WARNING]
> **The `Args:` block is required and must be formatted correctly.**
>
> The `@filter.llm_tool` decorator generates the parameter schema by parsing the function's docstring — it does **not** read Python type annotations. If the docstring is missing an `Args:` block, or the format does not follow `param_name(type): description`, the generated schema will be empty. Any arguments passed by the LLM will be silently dropped, causing the function to fail with a missing-argument error.
>
> Additionally, passing `parameters=...` directly to the decorator is **not supported** and will be silently ignored. If you need manual control over the schema, use the `@dataclass` + `add_llm_tools()` approach above.
## Invoking Agents
> [!TIP]
@@ -257,7 +308,7 @@ curr_cid = await conv_mgr.get_curr_conversation_id(uid)
conversation = await conv_mgr.get_conversation(uid, curr_cid) # Conversation
```
::: details Conversation 类型定义
::: details Conversation Type Definition
```py
@dataclass
@@ -288,83 +339,83 @@ class Conversation:
#### `new_conversation`
- **Usage**
- **Usage**
Create a new conversation in the current session and automatically switch to it.
- **Arguments**
- `unified_msg_origin: str` – In the format `platform_name:message_type:session_id`
- `platform_id: str | None` – Platform identifier, defaults to parsing from `unified_msg_origin`
- `content: list[dict] | None` – Initial message history
- `title: str | None` – Conversation title
- **Arguments**
- `unified_msg_origin: str` – In the format `platform_name:message_type:session_id`
- `platform_id: str | None` – Platform identifier, defaults to parsing from `unified_msg_origin`
- `content: list[dict] | None` – Initial message history
- `title: str | None` – Conversation title
- `persona_id: str | None` – Associated persona ID
- **Returns**
- **Returns**
`str` – Newly generated UUID conversation ID
#### `switch_conversation`
- **Usage**
- **Usage**
Switch the session to a specified conversation.
- **Arguments**
- `unified_msg_origin: str`
- **Arguments**
- `unified_msg_origin: str`
- `conversation_id: str`
- **Returns**
- **Returns**
`None`
#### `delete_conversation`
- **Usage**
- **Usage**
Delete a conversation from the session; if `conversation_id` is `None`, deletes the current conversation.
- **Arguments**
- `unified_msg_origin: str`
- **Arguments**
- `unified_msg_origin: str`
- `conversation_id: str | None`
- **Returns**
- **Returns**
`None`
#### `get_curr_conversation_id`
- **Usage**
- **Usage**
Get the conversation ID currently in use by the session.
- **Arguments**
- **Arguments**
- `unified_msg_origin: str`
- **Returns**
- **Returns**
`str | None` – Current conversation ID, returns `None` if it doesn't exist
#### `get_conversation`
- **Usage**
- **Usage**
Get the complete object for a specified conversation; automatically creates it if it doesn't exist and `create_if_not_exists=True`.
- **Arguments**
- `unified_msg_origin: str`
- `conversation_id: str`
- **Arguments**
- `unified_msg_origin: str`
- `conversation_id: str`
- `create_if_not_exists: bool = False`
- **Returns**
- **Returns**
`Conversation | None`
#### `get_conversations`
- **Usage**
- **Usage**
Retrieve the complete list of conversations for a user or platform.
- **Arguments**
- `unified_msg_origin: str | None` – When `None`, does not filter by user
- **Arguments**
- `unified_msg_origin: str | None` – When `None`, does not filter by user
- `platform_id: str | None`
- **Returns**
- **Returns**
`List[Conversation]`
#### `update_conversation`
- **Usage**
- **Usage**
Update the title, history, or persona_id of a conversation.
- **Arguments**
- `unified_msg_origin: str`
- `conversation_id: str | None` – Uses the current conversation when `None`
- `history: list[dict] | None`
- `title: str | None`
- **Arguments**
- `unified_msg_origin: str`
- `conversation_id: str | None` – Uses the current conversation when `None`
- `history: list[dict] | None`
- `title: str | None`
- `persona_id: str | None`
- **Returns**
- **Returns**
`None`
## Persona Manager
`PersonaManager` is responsible for unified loading, caching, and providing CRUD interfaces for all Personas, while maintaining compatibility with the legacy persona format (v3) from before AstrBot 4.x.
`PersonaManager` is responsible for unified loading, caching, and providing CRUD interfaces for all Personas, while maintaining compatibility with the legacy persona format (v3) from before AstrBot 4.x.
During initialization, it automatically reads all personas from the database and generates v3-compatible data for seamless use with legacy code.
```py
@@ -386,59 +437,59 @@ persona_mgr = self.context.persona_manager
#### `get_all_personas`
- **Usage**
- **Usage**
Retrieve all personas from the database at once.
- **Returns**
- **Returns**
`list[Persona]` – Persona list, may be empty
#### `create_persona`
- **Usage**
- **Usage**
Create a new persona and immediately write it to the database; automatically refreshes the local cache upon success.
- **Arguments**
- `persona_id: str` – New persona ID (unique)
- `system_prompt: str` – System prompt
- `begin_dialogs: list[str]` – Optional, opening dialogs (even number of entries, alternating user/assistant)
- **Arguments**
- `persona_id: str` – New persona ID (unique)
- `system_prompt: str` – System prompt
- `begin_dialogs: list[str]` – Optional, opening dialogs (even number of entries, alternating user/assistant)
- `tools: list[str]` – Optional, list of allowed tools; `None`=all tools, `[]`=disable all
- **Returns**
- **Returns**
`Persona` – Newly created persona object
- **Raises**
- **Raises**
`ValueError` – If `persona_id` already exists
#### `update_persona`
- **Usage**
- **Usage**
Update any fields of an existing persona and synchronize to database and cache.
- **Arguments**
- `persona_id: str` – Persona ID to update
- `system_prompt: str` – Optional, new system prompt
- `begin_dialogs: list[str]` – Optional, new opening dialogs
- **Arguments**
- `persona_id: str` – Persona ID to update
- `system_prompt: str` – Optional, new system prompt
- `begin_dialogs: list[str]` – Optional, new opening dialogs
- `tools: list[str]` – Optional, new tool list; semantics same as `create_persona`
- **Returns**
- **Returns**
`Persona` – Updated persona object
- **Raises**
- **Raises**
`ValueError` – If `persona_id` doesn't exist
#### `delete_persona`
- **Usage**
- **Usage**
Delete the specified persona and clean up both database and cache.
- **Arguments**
- **Arguments**
- `persona_id: str` – Persona ID to delete
- **Raises**
- **Raises**
`ValueError` – If `persona_id` doesn't exist
#### `get_default_persona_v3`
- **Usage**
Get the default persona (v3 format) to use based on the current session configuration.
- **Usage**
Get the default persona (v3 format) to use based on the current session configuration.
Falls back to `DEFAULT_PERSONALITY` if configuration doesn't specify one or the specified persona doesn't exist.
- **Arguments**
- **Arguments**
- `umo: str | MessageSession | None` – Session identifier, used to read user-level configuration
- **Returns**
- **Returns**
`Personality` – Default persona object in v3 format
::: details Persona / Personality type definitions
::: details Persona / Personality Type Definition
```py
docs/en/dev/star/guides/listen-message-event.md
+7 -7
View File
@@ -1,4 +1,3 @@
# Handling Message Events
Event listeners can receive message content delivered by the platform and implement features such as commands, command groups, and event listening.
@@ -97,7 +96,7 @@ AstrBot will automatically parse command parameters for you.
```python
@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 -> Result is: 3
yield event.plain_result(f"Wow! The answer is {a + b}!")
```
@@ -108,7 +107,7 @@ Command groups help you organize commands.
```python
@filter.command_group("math")
def math(self):
def math():
pass
@math.command("add")
@@ -160,7 +159,7 @@ async def sub(self, event: AstrMessageEvent, a: int, b: int):
yield event.plain_result(f"Result is: {a - b}")
@calc.command("help")
def calc_help(self, event: AstrMessageEvent):
async def calc_help(self, event: AstrMessageEvent):
# /math calc help
yield event.plain_result("This is a calculator plugin with add and sub commands.")
```
@@ -173,7 +172,7 @@ You can add different aliases for commands or command groups:
```python
@filter.command("help", alias={'帮助', 'helpme'})
def help(self, event: AstrMessageEvent):
async def help(self, event: AstrMessageEvent):
yield event.plain_result("This is a calculator plugin with add and sub commands.")
```
@@ -209,7 +208,7 @@ async def on_aiocqhttp(self, event: AstrMessageEvent):
yield event.plain_result("Received a message")
```
In the current version, `PlatformAdapterType` includes `AIOCQHTTP`, `QQOFFICIAL`, `GEWECHAT`, and `ALL`.
In the current version, `PlatformAdapterType` supports the following values: `AIOCQHTTP`, `QQOFFICIAL`, `QQOFFICIAL_WEBHOOK`, `TELEGRAM`, `WECOM`, `WECOM_AI_BOT`, `LARK`, `DINGTALK`, `DISCORD`, `SLACK`, `KOOK`, `VOCECHAT`, `WEIXIN_OFFICIAL_ACCOUNT`, `SATORI`, `MISSKEY`, `LINE`, `MATRIX`, `WEIXIN_OC`, `MATTERMOST`, `WEBCHAT`, `ALL`.
#### Admin Commands
@@ -420,13 +419,14 @@ You can implement some message decoration here, such as converting to voice, con
```python
from astrbot.api.event import filter, AstrMessageEvent
import astrbot.api.message_components as Comp
@filter.on_decorating_result()
async def on_decorating_result(self, event: AstrMessageEvent):
result = event.get_result()
chain = result.chain
print(chain) # Print the message chain
chain.append(Plain("!")) # Add an exclamation mark at the end of the message chain
chain.append(Comp.Plain("!")) # Add an exclamation mark at the end of the message chain
```
> You cannot use yield to send messages here. This hook is only for decorating event.get_result().chain. If you need to send, please use the `event.send()` method directly.
docs/en/dev/star/guides/simple.md
-16
View File
@@ -40,19 +40,3 @@ Explanation:
All handler functions must be written within the plugin class. To keep content concise, in subsequent sections, we may omit the plugin class definition.
```
解释如下：
- 插件需要继承 `Star` 类。
- `Context` 类用于插件与 AstrBot Core 交互，可以由此调用 AstrBot Core 提供的各种 API。
- 具体的处理函数 `Handler` 在插件类中定义，如这里的 `helloworld` 函数。
- `AstrMessageEvent` 是 AstrBot 的消息事件对象，存储了消息发送者、消息内容等信息。
- `AstrBotMessage` 是 AstrBot 的消息对象，存储了消息平台下发的消息的具体内容。可以通过 `event.message_obj` 获取。
> [!TIP]
>
> `Handler` 一定需要在插件类中注册，前两个参数必须为 `self` 和 `event`。如果文件行数过长，可以将服务写在外部，然后在 `Handler` 中调用。
>
> 插件类所在的文件名需要命名为 `main.py`。
所有的处理函数都需写在插件类中。为了精简内容，在之后的章节中，我们可能会忽略插件类的定义。
docs/en/dev/star/plugin-new.md
+5
View File
@@ -102,8 +102,10 @@ The values in `support_platforms` must be keys from `ADAPTER_NAME_2_TYPE`. Curre
- `aiocqhttp`
- `qq_official`
- `qq_official_webhook`
- `telegram`
- `wecom`
- `wecom_ai_bot`
- `lark`
- `dingtalk`
- `discord`
@@ -111,9 +113,12 @@ The values in `support_platforms` must be keys from `ADAPTER_NAME_2_TYPE`. Curre
- `kook`
- `vocechat`
- `weixin_official_account`
- `weixin_oc`
- `satori`
- `misskey`
- `line`
- `matrix`
- `mattermost`
### Declare AstrBot Version Range (Optional)
docs/en/dev/star/plugin-publish.md
+11
View File
@@ -7,3 +7,14 @@ AstrBot uses GitHub to host plugins, so you'll need to push your plugin code to
You can submit your plugin by visiting the [AstrBot Plugin Marketplace](https://plugins.astrbot.app). Once on the website, click the `+` button in the bottom-right corner, fill in the basic information, author details, repository information, and other required fields. Then click the `Submit to GITHUB` button. You will be redirected to the AstrBot repository's Issue submission page. Please verify that all information is correct, then click the `Create` button to complete the plugin publication process.
![fill out the form](https://files.astrbot.app/docs/source/images/plugin-publish/image.png)
> ⚠️ **Size Limit**: The plugin zip package submitted to the marketplace **must not exceed 16MB**. If it exceeds this limit, the CI/CD pipeline will automatically reject the submission.
>
> To ensure your plugin passes review and publication smoothly, we recommend the following:
>
> - **Compress static assets**: Compress images, audio, and other resource files in your plugin to reduce their size.
> - **Clean up unnecessary files**: Avoid including directories like `.git`, `__pycache__`, `node_modules`, or development configuration files in your plugin repository. Add a `.gitignore` file to your repository root to exclude them.
> - **Optimize dependency size**: If your plugin depends on large libraries, consider trimming them down or importing only what is needed.
> - **Use `.gitattributes` or a release branch**: Reduce the zip package size by including only the files necessary for distribution.
>
> If your plugin truly cannot be compressed to under 16MB due to business requirements, please contact the maintainer to manually bypass this limit.
docs/en/faq.md
+71 -7
View File
@@ -6,17 +6,81 @@
Download `dist.zip` from the [release](https://github.com/AstrBotDevs/AstrBot/releases) page, extract it, and move it to `AstrBot/data`. If it still doesn't work, try restarting your computer (based on community feedback).
### First Login Account and Random Password
On first startup, the WebUI account is `astrbot` by default, and the default password is randomly generated (it is not a fixed hardcoded value). Check the startup logs and log in with the random initial password shown there:
```text
[00:27:40.590] [Core] [INFO] [dashboard.server:523]:
✨✨✨
AstrBot v4.24.3 WebUI is ready
➜ Local: http://localhost:6185
➜ Initial username: astrbot
➜ Initial password: UiYVpZxnW8k22IWqf0ru5pOy
➜ Change it after logging in
✨✨✨
Set dashboard.host in data/cmd_config.json to enable remote access.
```
`UiYVpZxnW8k22IWqf0ru5pOy` is the default password.
### Forgot Dashboard Password
If you forgot your AstrBot dashboard password, you can modify the `"dashboard"` field in the `AstrBot/data/cmd_config.json` configuration file, where `"username"` is your username and `"password"` is your password encrypted with MD5.
If you forgot your AstrBot dashboard password, find the `"dashboard"` field in `AstrBot/data/cmd_config.json`, for example:
To modify your account credentials, follow these steps:
```json
"dashboard": {
"enable": true,
"username": "astrbot",
"password": "81e0c3dxxxxxxxxxxx78862e78",
"pbkdf2_password": "pbkdf2_sha256$600000$1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"password_storage_upgraded": true,
"password_change_required": true,
"jwt_secret": "5e1b0280bcxxxxxxxxxxxxxxxxf4a",
"host": "127.0.0.1",
"port": 6185,
"disable_access_log": true,
"ssl": {
"enable": false,
"cert_file": "",
"key_file": "",
"ca_certs": ""
}
},
```
1. Modify the `"username"` field, keeping the `""` quotation marks. If you don't want to change the username, skip this step
2. Visit the website: [Online MD5 Generator](https://www.metools.info/code/c26.html)
3. Enter your new password in the input text box
4. Select MD5 encryption (32-bit), make sure to choose the 32-bit option
5. Paste the converted string into the configuration file, keeping the `""` quotation marks
Delete the `username`, `password`, `pbkdf2_password`, `password_storage_upgraded`, `password_change_required`, and `jwt_secret` fields (with their values), then save.
The segment should look like:
```json
"dashboard": {
"enable": true,
"host": "127.0.0.1",
"port": 6185,
"disable_access_log": true,
"ssl": {
"enable": false,
"cert_file": "",
"key_file": "",
"ca_certs": ""
}
},
```
After restart, AstrBot will automatically generate a random password with the fixed username `astrbot`; check the startup logs.
### Correct Password Cannot Log In After Upgrading AstrBot
If you are sure the dashboard password is correct but still cannot log in after upgrading AstrBot, the old WebUI static files may be incompatible with the newer backend.
Solution:
1. Stop AstrBot.
2. Delete the `dist` folder under AstrBot's `data` directory: `AstrBot/data/dist`.
3. Restart AstrBot.
After restart, AstrBot will reload or download WebUI files that match the current version.
## Bot Core Related
docs/en/platform/dingtalk.md
+15 -1
View File
@@ -16,6 +16,20 @@ Proactive message push: Supported.
## Create and Configure the App
DingTalk supports two setup methods: one-click QR creation in AstrBot, or manually creating an app in DingTalk Open Platform.
### Option 1: One-click QR Creation
AstrBot version requirement: >= v4.25.0.
Open AstrBot Dashboard -> `Bots` -> `+ Create Bot`, then select `DingTalk`.
Under `Creation Method`, select `One-click QR setup`, scan the QR code with the DingTalk mobile app, then create or bind a bot on the DingTalk authorization page. After creation succeeds, AstrBot automatically fills in `ClientID` and `ClientSecret`. Click `Save` to finish.
After QR creation succeeds, continue checking the event subscription, version release, and group installation steps below.
### Option 2: Manual Creation
Go to the [DingTalk Open Platform](https://open-dev.dingtalk.com/fe/app), then create an app:
![image](https://files.astrbot.app/docs/source/images/dingtalk/image-4.png)
@@ -36,7 +50,7 @@ Go to Credentials & Basic Information, then copy `ClientID` and `ClientSecret`.
Open AstrBot Dashboard -> `Bots` -> `+ Create Bot`, then create a DingTalk adapter.
Fill in `ClientID` and `ClientSecret`, then click Save. AstrBot will request authorization from DingTalk Open Platform automatically.
If you want AstrBot to create the app for you, select `One-click QR setup` and complete the scan. If you already created the app yourself, select `Manual setup`, fill in `ClientID` and `ClientSecret`, then click Save. AstrBot will request authorization from DingTalk Open Platform automatically.
Back in DingTalk Open Platform, open Event Subscriptions, select `Stream mode push`, and click Save. If successful, you will see a connected status.
docs/en/platform/lark.md
+31 -1
View File
@@ -20,6 +20,31 @@ The Lark client version must be >= 7.20. Lower versions only display the title a
## Creating a Bot
Lark supports two setup methods: one-click QR creation in AstrBot, or manually creating a custom enterprise app in the Lark Developer Console.
### Option 1: One-click QR Creation
AstrBot version requirement: >= 4.25.0.
Open the AstrBot management panel, click `Bots` in the left sidebar, click `+ Create Bot`, and select `lark`.
Under `Creation Method`, select `One-click QR Creation`, choose the China or international edition as needed, then scan the QR code with the Lark mobile app and confirm. After creation succeeds, AstrBot automatically fills in the app's `app_id`, `app_secret`, and domain configuration.
> [!IMPORTANT]
> After an app is created through QR scanning, group chats receive only messages that @ mention the bot or messages triggered by a wake prefix such as `/` by default. If you need the bot to receive all group messages, enable the additional permissions in the Lark Developer Console.
>
> Replace `<APP_ID>` in the URL below with your Lark app ID, then open it to jump to the permission enablement page:
>
> To find the App ID, go back to AstrBot's `Bots` page, find the Lark bot you just created, click `Edit`, and check the dialog that opens.
>
> ```text
> https://open.feishu.cn/app/<APP_ID>/auth?q=contact:contact.base:readonly,im:message.p2p_msg:readonly,im:message.group_at_msg:readonly,im:message:send,im:message,im:message:send_as_bot,im:resource:upload,im:resource,cardkit:card:write,im:message.group_at_msg:readonly,im:message.group_msg&op_from=openapi&token_type=tenant
> ```
After QR creation succeeds, continue checking the event subscription, permissions, version release, and group installation steps below.
### Option 2: Manual Creation
Navigate to the [Developer Console](https://open.feishu.cn/app) and create a custom enterprise application.
![Create Custom Enterprise Application](https://files.astrbot.app/docs/source/images/lark/image.png)
@@ -38,6 +63,7 @@ Click on "Credentials & Basic Info" to obtain your app_id and app_secret.
2. Click on `Bots` in the left sidebar
3. In the right panel, click `+ Create Bot`
4. Select `lark`
5. If you want AstrBot to create the app for you, select `One-click QR Creation` and complete the scan. If you already created the app yourself, select `Manual Creation`
Fill in the configuration fields as follows:
@@ -45,7 +71,6 @@ Fill in the configuration fields as follows:
- Enable: Check this option
- app_id: The app_id you obtained earlier
- app_secret: The app_secret you obtained earlier
- Bot name: Your Lark bot's name
For the domain field, if you're using Lark China, keep the default value. If you're using Lark International, set it to `https://open.larksuite.com`. If you're using a self-hosted enterprise Lark instance, enter your Lark instance's domain.
@@ -92,6 +117,11 @@ Next, click on "Permission Management," click "Enable Permissions," and enter `i
Enter `im:resource:upload,im:resource` again to enable image upload permissions.
If you want to use the bot in group chats, additionally enable `im:message.group_at_msg:readonly` and `im:message.group_msg`.
> [!TIP]
> Apps created through one-click QR creation are suitable for @ mentions and wake-prefix triggers by default. To receive every group message, make sure `im:message.group_msg` is enabled. You can also use the permission URL above to quickly open the corresponding page.
If you want to use streaming output, additionally enable `Create and update cards (cardkit:card:write)`.
The final set of permissions should look like this:
docs/en/platform/weixin_oc.md
+5 -6
View File
@@ -25,6 +25,8 @@ AstrBot supports connecting a personal WeChat account through the `Personal WeCh
2. Click `Bots` in the left sidebar.
3. Click `+ Create Bot` in the upper-right corner.
4. Select `Personal WeChat`.
5. The login QR code is shown directly. Scan it with WeChat on your phone and confirm the login inside WeChat.
6. After login succeeds, click `Save`.
## Configuration Notes
@@ -44,15 +46,12 @@ Leave the remaining options at their default values unless you explicitly know y
## QR Login
1. Fill in the configuration and click `Save`.
2. Return to the bot list. AstrBot will automatically request a login QR code from WeChat.
3. On the bot card, click `View QR Code` to open the QR dialog.
4. Scan it with WeChat on your phone, then confirm the login inside WeChat.
After you select `Personal WeChat`, AstrBot automatically requests a login QR code from WeChat and shows it directly in the create-bot dialog. Scan it with WeChat on your phone and confirm the login. When the QR area shows the login-success state, click `Save` to finish creating the bot.
After login succeeds, AstrBot will automatically persist the login state. On later restarts, if the session is still valid, you usually do not need to scan again.
After login succeeds and the bot is saved, AstrBot will automatically persist the login state. On later restarts, if the session is still valid, you usually do not need to scan again.
> [!NOTE]
> If the QR code expires, AstrBot will automatically request a new one. Please scan the refreshed QR code instead of the old one.
> If the QR code expires, close and reopen the create-bot dialog, or select `Personal WeChat` again to request a new QR code.
## Verification
docs/en/providers/302ai.md
+11 -11
View File
@@ -1,21 +1,21 @@
# 接入 302.AI
# Connect 302.AI
302.AI 是企业级 AI 应用平台，支持快捷接入全球各类 AI 模型。
[302.AI](https://302.ai) is an enterprise-grade AI application platform that provides quick access to a wide range of AI models worldwide.
## 使用
## Getting Started
点击[此链接](https://share.302.ai/rr1M3l) 注册账户。
Click [this link](https://share.302.ai/rr1M3l) to register an account.
注册完毕之后，点击[此链接](https://302.ai/apis/)选择需要接入的模型。
After registering, click [this link](https://302.ai/apis/) to select the model you want to use.
根据需求，进入[此链接](https://dash.302.ai/charge) 充值对应的金额。
If needed, visit [this link](https://dash.302.ai/charge) to top up your account balance.
## 接入
## Connect
打开 AstrBot 控制台 -> 服务提供商页面，点击新增提供商，找到并点击 `302.AI`(需要版本 >= 3.5.18)
Open the AstrBot dashboard → Service Providers page, click **Add Provider**, find and click `302.AI` (requires version >= 3.5.18).
修改 ID，并将 API Key 和模型名称填入对话框表单，点击保存，即可完成创建。
Set an ID, fill in the API Key and model name in the dialog form, then click **Save** to complete the setup.
## 使用
## Usage
对机器人输入 `/provider` 指令，将提供商切换到刚刚添加的 302.AI 提供商，即可使用。
Send the `/provider` command to the bot to switch to the 302.AI provider you just added.
docs/en/providers/ppio.md
+17 -19
View File
@@ -1,43 +1,41 @@
# 接入 PPIO 派欧云
# Connect PPIO Cloud
PPIO 派欧云是中国领先的独立分布式云计算服务商，您可以在派欧云上使用稳定、低价甚至免费的模型服务。
PPIO Cloud is a leading independent distributed cloud computing provider in China, offering stable, affordable, and even free model services.
## 准备
## Preparation
打开 [PPIO 派欧云官网](https://ppio.cn/user/register?invited_by=AIOONE)，并注册账户（通过此链接注册的账户将会获得 15 元人民币的代金券）。
Open the [PPIO Cloud website](https://ppio.cn/user/register?invited_by=AIOONE) and register an account (accounts registered through this link will receive a ¥15 voucher).
进入 [模型 API 服务](https://ppio.cn/model-api/console)，找到你想接入的模型。你可以通过筛选器选择不同厂商或者免费的模型。
Go to [Model API Service](https://ppio.cn/model-api/console) and find the model you want to use. You can filter by provider or select free models.
![image](https://files.astrbot.app/docs/source/images/ppio/image-1.png)
找到你想要接入的模型后，点击模型卡片，侧边会展开一个模型详情卡片，找到下方的 API 接入指南，如果您还没创建过 Key 可以点击创建。
Once you find the model, click its card to expand a detail panel on the right. Scroll down to the API integration guide — if you haven't created a key yet, click to create one.
![image](https://files.astrbot.app/docs/source/images/ppio/image-3.png)
打开 AstrBot 控制台 -> 服务提供商页面，点击新增提供商，找到并点击 `PPIO派欧云`(需要版本 >= 3.5.10，旧版本也可使用，见下文)。
Open the AstrBot dashboard → Service Providers page, click **Add Provider**, find and click `PPIO Cloud` (requires version >= 3.5.10; older versions are also supported, see below).
![image](https://files.astrbot.app/docs/source/images/ppio/image.png)
将 API Key 和模型名称填入对话框表单，点击保存，即可完成创建。
Fill in the API Key and model name in the dialog form, then click **Save** to complete the setup.
> [!TIP]
> 如果您是 AstrBot 旧版本（< 3.5.10）的用户，请打开 AstrBot 控制台 -> 服务提供商页面，点击新增提供商，找到 `OpenAI`，点击进入。
> 1. 将 ID 命名为 `ppio`（随意）
> 2. 然后将 `API Base URL` 设置为 `https://api.ppinfra.com/v3/openai`
> 3. 然后将 API Key 和模型名称填入对话框表单，点击保存，即可完成创建。
> If you are using an older version of AstrBot (< 3.5.10), open the AstrBot dashboard → Service Providers page, click **Add Provider**, find `OpenAI`, and click to enter.
> 1. Set the ID to `ppio` (any name works)
> 2. Set `API Base URL` to `https://api.ppinfra.com/v3/openai`
> 3. Fill in the API Key and model name in the dialog form, then click **Save** to complete the setup.
## Usage
## 使用
Send the `/provider` command to the bot to switch to the PPIO Cloud provider you just added.
对机器人输入 `/provider` 指令，将提供商切换到刚刚添加的 PPIO 派欧云提供商，即可使用。
## FAQ
## 常见问题
#### 显示 `400` 错误
#### `400` Error
```log
Error code: 400 - {'code': 400, 'message': '"auto" tool choice requires --enable-auto-tool-choice and --tool-call-parser to be set', 'type': 'BadRequestError'}
```
请暂时使用 `/tool off_all` 禁用所有的函数调用工具即可使用，或者换用其他模型。
Temporarily disable all function calling tools with `/tool off_all`, or switch to a different model.
docs/en/providers/provider-lmstudio.md
+18 -19
View File
@@ -1,38 +1,37 @@
# 接入 LM Studio 使用 DeepSeek-R1 等模型
# Connect LM Studio to Use DeepSeek-R1 and Other Models
LMStudio 允许在本地电脑上部署模型（需要电脑硬件配置符合要求）
LM Studio allows you to deploy models locally on your computer (hardware requirements must be met).
### 下载并安装 LMStudio
### Download and Install LM Studio
https://lmstudio.ai/download
<https://lmstudio.ai/download>
### 下载并运行模型
### Download and Run a Model
https://lmstudio.ai/models
<https://lmstudio.ai/models>
跟随 LMStudio 下载并运行想要的模型，如 deepseek-r1-qwen-7b:
Follow the LM Studio instructions to download and run your desired model, e.g. `deepseek-r1-qwen-7b`:
```bash
lms get deepseek-r1-qwen-7b
```
### 配置 AstrBot
### Configure AstrBot
在 AstrBot 上：
In AstrBot:
点击 配置->服务提供商配置->加号->openai
Go to **Configuration → Service Providers → + → OpenAI**
API Base URL 填写 `http://localhost:1234/v1`
Set `API Base URL` to `http://localhost:1234/v1`
API Key 填写 `lm-studio`
Set `API Key` to `lm-studio`
> 对于 Mac/Windows 使用 Docker Desktop 部署 AstrBot 部署的用户，API Base URL 请填写为 `http://host.docker.internal:1234/v1`。
> 对于 Linux 使用 Docker 部署 AstrBot 部署的用户，API Base URL 请填写为 `http://172.17.0.1:1234/v1`，或者将 `172.17.0.1` 替换为你的公网 IP IP（确保宿主机系统放行了 1234 端口）。
> For users deploying AstrBot via Docker Desktop on Mac or Windows, set `API Base URL` to `http://host.docker.internal:1234/v1`.
>
> For users deploying AstrBot via Docker on Linux, set `API Base URL` to `http://172.17.0.1:1234/v1`, or replace `172.17.0.1` with your server's public IP (make sure port 1234 is open on the host).
如果 LM Studio 使用了 Docker 部署，请确保 1234 端口已经映射到宿主机。
If LM Studio itself is deployed in Docker, ensure port 1234 is mapped to the host.
模型名填写上一步选好的
Set the model name to the one you selected in the previous step, then save the configuration.
保存配置即可。
> 输入 /provider 查看 AstrBot 配置的模型
> Run `/provider` to view the models configured in AstrBot.
docs/en/use/astrbot-agent-sandbox.md
+1 -1
View File
@@ -328,7 +328,7 @@ If you choose `Shipyard Neo`, the main configuration items are:
- If AstrBot can access Bay's `credentials.json`, you may leave it empty and let AstrBot auto-discover it
- `Shipyard Neo Profile`
- For example `python-default` or `browser-python`
- If not explicitly specified, AstrBot will try to choose a profile with richer capabilities, preferring one that includes the `browser` capability, and fall back to `python-default` if needed
- If left empty, AstrBot will try to choose a profile with richer capabilities, preferring one that includes the `browser` capability, and fall back to `python-default` if needed
- `Shipyard Neo Sandbox TTL`
- The upper lifetime limit of the sandbox, defaulting to 3600 seconds (1 hour)
docs/en/use/function-calling.md
+1 -1
View File
@@ -51,4 +51,4 @@ Below are some common tool calling demos:
## MCP
Please refer to this documentation: [AstrBot - MCP](/use/mcp).
Please refer to this documentation: [AstrBot - MCP](/en/use/mcp).
docs/en/use/mcp.md
+1 -1
View File
@@ -99,4 +99,4 @@ That's it.
Reference links:
1. Learn how to use MCP here: [Model Context Protocol](https://modelcontextprotocol.io/introduction)
2. Get commonly used MCP servers here: [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README-zh.md#what-is-mcp), [Model Context Protocol servers](https://github.com/modelcontextprotocol/servers), [MCP.so](https://mcp.so)
2. Get commonly used MCP servers here: [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers/blob/main/README.md#what-is-mcp), [Model Context Protocol servers](https://github.com/modelcontextprotocol/servers), [MCP.so](https://mcp.so)
docs/en/use/skills.md
+1 -1
View File
@@ -20,7 +20,7 @@ You can upload Skills with the following requirements:
1. The upload must be a `.zip` archive.
2. **After extraction, it must contain a single Skill folder. The folder name will be used as the identifier for the Skill in AstrBot—please name it using English characters.**
3. The Skill folder must include a file named `SKILL.md`, and its contents should preferably follow the Anthropic Skills specification. You can refer to Anthropic's documentation: https://code.claude.com/docs/zh-CN/skills
3. The Skill folder must include a file named `SKILL.md`, and its contents should preferably follow the Anthropic Skills specification. You can refer to Anthropic's documentation: https://code.claude.com/docs/en/skills
## Using Skills in AstrBot
docs/en/use/webui.md
+1 -1
View File
@@ -13,7 +13,7 @@ After starting AstrBot, you can access the admin panel by visiting `http://local
## Login
The default username and password are both `astrbot`.
For first-time login, AstrBot generates a random initial password and prints it in startup logs. Please read the startup log line containing the WebUI credential and use that password to log in (username is usually `astrbot`).
## ChatUI
docs/zh/deploy/astrbot/cli.md
+1 -1
View File
@@ -85,7 +85,7 @@ python main.py
> [!TIP]
> 如果你正在服务器上部署 AstrBot，需要将 `localhost` 替换为你的服务器 IP 地址。
>
> 默认用户名和密码是 `astrbot` 和 `astrbot`。
> 首次登录请使用启动日志中打印的随机初始密码（用户名通常为 `astrbot`）。登录后请立即修改密码。
接下来，你需要部署任何一个消息平台，才能够实现在消息平台上使用 AstrBot。
docs/zh/deploy/astrbot/compshare.md
+2 -2
View File
@@ -34,7 +34,7 @@ Both services started in the background.
![WebUI 界面](https://www-s.ucloud.cn/2025/07/7e9fc6edc1dfa916abc069f4cecc24cf_1753940381771.png)
使用用户名：astrbot 和密码 astrbot 进行登录。
首次登录时请使用启动日志内的随机初始密码（用户名通常是 astrbot），登录后请立即修改密码。
登录成功后，可以重新设置密码，并进入 AstrBot 的页面。
@@ -86,4 +86,4 @@ AstrBot 支持接入优云智算提供的模型 API。
## 更多功能
更多功能请参考 [AstrBot 官方文档](https://docs.astrbot.app)。
更多功能请参考 [AstrBot 官方文档](https://docs.astrbot.app)。
docs/zh/deploy/astrbot/docker.md
+1 -1
View File
@@ -98,7 +98,7 @@ sudo docker logs -f astrbot
> [!TIP]
> 由于 Docker 隔离了网络环境，所以不能使用 `localhost` 访问管理面板。
>
> 默认用户名和密码是 `astrbot` 和 `astrbot`。
> 首次登录请使用启动日志中打印的随机初始密码（用户名通常为 `astrbot`）。登录后请立即修改密码。
>
> 如果部署在云服务器上，需要在相应厂商控制台里放行对应端口。
docs/zh/deploy/astrbot/kubernetes.md
+1 -1
View File
@@ -194,4 +194,4 @@ image: m.daocloud.io/docker.io/soulter/astrbot:latest
部署并暴露服务后，您就可以通过相应的 IP 和端口访问 AstrBot 管理面板了。
> 默认用户名和密码是 `astrbot` 和 `astrbot`。
> 首次登录请使用启动日志中打印的随机初始密码（用户名通常为 `astrbot`）。登录后请立即修改密码。
docs/zh/deploy/astrbot/launcher.md
+2 -2
View File
@@ -64,7 +64,7 @@ MacOS 用户下载安装好后，可能会遇到 "已损坏，无法打开" 的
如果没有报错，你会看到一条日志显示类似 `🌈 管理面板已启动，可访问` 并附带了几条链接。打开其中一个链接即可访问 AstrBot 管理面板。
> [!TIP]
> 默认用户名和密码是 `astrbot` 和 `astrbot`。
> 首次登录请使用启动日志中打印的随机初始密码（用户名通常为 `astrbot`）。登录后请立即修改密码。
>
> **当管理面板打开时遇到 404 错误：**
> 在 [release](https://github.com/AstrBotDevs/AstrBot/releases) 页面下载dist.zip，解压拖到 AstrBot/data 下。还不行请重启电脑（来自群里的反馈）
@@ -98,4 +98,4 @@ windows 搜索 Python，打开文件位置：
**方法 2:**
重装 python，并且在安装时勾选 `Add Python to PATH`，然后重启电脑。
重装 python，并且在安装时勾选 `Add Python to PATH`，然后重启电脑。
docs/zh/dev/astrbot-config.md
+4 -4
View File
@@ -116,7 +116,7 @@ AstrBot 默认配置如下：
"dashboard": {
"enable": True,
"username": "astrbot",
"password": "77b90590a8945a7d36c963981a307dc9",
"password": "<your_password_md5>",
"jwt_secret": "",
"host": "0.0.0.0",
"port": 6185,
@@ -492,11 +492,11 @@ HTTP 代理。如 `http://localhost:7890`。
AstrBot WebUI 配置。
请不要随意修改 `password` 的值。它是一个经过 `md5` 编码的密码。请在控制面板修改密码。
请不要随意修改 `password` 的值。它是随机初始密码经过 `md5` 编码后的值。首次启动时请在日志中获取初始密码，并在控制面板中修改。
- `enable`: 是否启用 AstrBot WebUI。默认为 `true`。
- `username`: AstrBot WebUI 的用户名。默认为 `astrbot`。
- `password`: AstrBot WebUI 的密码。默认为 `astrbot` 的 `md5` 编码值。请勿直接修改，除非您知道自己在做什么。
- `username`: AstrBot WebUI 的用户名。
- `password`: AstrBot WebUI 的密码。首次启动会随机生成初始密码（已在日志中打印），这里保存的是该密码的 `md5` 值。请勿直接修改，除非您知道自己在做什么。
- `jwt_secret`: JWT 的密钥。AstrBot 会在初始化时随机生成。请勿修改，除非您知道自己在做什么。
- `host`: AstrBot WebUI 监听的地址。默认为 `0.0.0.0`。
- `port`: AstrBot WebUI 监听的端口。默认为 `6185`。
docs/zh/dev/star/guides/ai.md
+75 -60
View File
@@ -1,4 +1,3 @@
# AI
AstrBot 内置了对多种大语言模型（LLM）提供商的支持，并且提供了统一的接口，方便插件开发者调用各种 LLM 服务。
@@ -82,9 +81,18 @@ class MyPlugin(Star):
tool_mgr.func_list.append(BilibiliTool())
```
> [!WARNING]
> `context.register_llm_tool()` 已被弃用，请勿在新插件中使用。
>
> 如需通过该方法注册（旧插件兼容），`func_args` 必须是 **字典列表**，格式为：
> ```py
> func_args = [{"type": "string", "name": "arg_name", "description": "参数描述"}, ...]
> ```
> 传入字符串列表或其他格式会导致 `AttributeError: 'str' object has no attribute 'pop'`。
### 通过装饰器定义 Tool 和注册 Tool
除了上述的通过 `@dataclass` 定义 Tool 的方式之外，你也可以使用装饰器的方式注册 tool 到 AstrBot。如果请务必按照以下格式编写一个工具（包括函数注释，AstrBot 会解析该函数注释，请务必将注释格式写对）
除了上述的通过 `@dataclass` 定义 Tool 的方式之外，你也可以使用装饰器的方式注册 tool 到 AstrBot。请务必按照以下格式编写一个工具（包括函数注释，AstrBot 会解析该函数注释，请务必将注释格式写对）：
```py{3,4,5,6,7}
@filter.llm_tool(name="get_weather") # 如果 name 不填，将使用函数名
@@ -102,6 +110,13 @@ async def get_weather(self, event: AstrMessageEvent, location: str) -> MessageEv
支持的参数类型有 `string`, `number`, `object`, `boolean`, `array`。在 v4.5.7 之后，支持对 `array` 类型参数指定子类型，例如 `array[string]`。
> [!WARNING]
> **`Args:` 段是必须的，且格式不能写错。**
>
> `@filter.llm_tool` 装饰器通过解析函数的 docstring 来生成工具的参数 schema，**不会**读取函数签名中的类型注解。如果 docstring 缺少 `Args:` 段，或格式不符合 `参数名(类型): 描述` 的规范，框架生成的参数 schema 将为空，LLM 传入的参数会被静默丢弃，最终导致函数因缺少参数而报错。
>
> 此外，装饰器**不支持**通过 `parameters=...` 显式传入参数 schema，该写法会被忽略。如需手动控制 schema，请使用上方的 `@dataclass` + `add_llm_tools()` 方式。
## 调用 Agent
> [!TIP]
@@ -352,83 +367,83 @@ await conv_mgr.add_message_pair(
#### `new_conversation`
- __Usage__
- __Usage__
在当前会话中新建一条对话，并自动切换为该对话。
- __Arguments__
- `unified_msg_origin: str` – 形如 `platform_name:message_type:session_id`
- `platform_id: str | None` – 平台标识，默认从 `unified_msg_origin` 解析
- `content: list[dict] | None` – 初始历史消息
- `title: str | None` – 对话标题
- __Arguments__
- `unified_msg_origin: str` – 形如 `platform_name:message_type:session_id`
- `platform_id: str | None` – 平台标识，默认从 `unified_msg_origin` 解析
- `content: list[dict] | None` – 初始历史消息
- `title: str | None` – 对话标题
- `persona_id: str | None` – 绑定的 persona ID
- __Returns__
- __Returns__
`str` – 新生成的 UUID 对话 ID
#### `switch_conversation`
- __Usage__
- __Usage__
将会话切换到指定的对话。
- __Arguments__
- `unified_msg_origin: str`
- __Arguments__
- `unified_msg_origin: str`
- `conversation_id: str`
- __Returns__
- __Returns__
`None`
#### `delete_conversation`
- __Usage__
- __Usage__
删除会话中的某条对话；若 `conversation_id` 为 `None`，则删除当前对话。
- __Arguments__
- `unified_msg_origin: str`
- __Arguments__
- `unified_msg_origin: str`
- `conversation_id: str | None`
- __Returns__
- __Returns__
`None`
#### `get_curr_conversation_id`
- __Usage__
- __Usage__
获取当前会话正在使用的对话 ID。
- __Arguments__
- __Arguments__
- `unified_msg_origin: str`
- __Returns__
- __Returns__
`str | None` – 当前对话 ID，不存在时返回 `None`
#### `get_conversation`
- __Usage__
- __Usage__
获取指定对话的完整对象；若不存在且 `create_if_not_exists=True` 则自动创建。
- __Arguments__
- `unified_msg_origin: str`
- `conversation_id: str`
- __Arguments__
- `unified_msg_origin: str`
- `conversation_id: str`
- `create_if_not_exists: bool = False`
- __Returns__
- __Returns__
`Conversation | None`
#### `get_conversations`
- __Usage__
- __Usage__
拉取用户或平台下的全部对话列表。
- __Arguments__
- `unified_msg_origin: str | None` – 为 `None` 时不过滤用户
- __Arguments__
- `unified_msg_origin: str | None` – 为 `None` 时不过滤用户
- `platform_id: str | None`
- __Returns__
- __Returns__
`List[Conversation]`
#### `update_conversation`
- __Usage__
- __Usage__
更新对话的标题、历史记录或 persona_id。
- __Arguments__
- `unified_msg_origin: str`
- `conversation_id: str | None` – 为 `None` 时使用当前对话
- `history: list[dict] | None`
- `title: str | None`
- __Arguments__
- `unified_msg_origin: str`
- `conversation_id: str | None` – 为 `None` 时使用当前对话
- `history: list[dict] | None`
- `title: str | None`
- `persona_id: str | None`
- __Returns__
- __Returns__
`None`
## 人格设定管理器
`PersonaManager` 负责统一加载、缓存并提供所有人格（Persona）的增删改查接口，同时兼容 AstrBot 4.x 之前的旧版人格格式（v3）。
`PersonaManager` 负责统一加载、缓存并提供所有人格（Persona）的增删改查接口，同时兼容 AstrBot 4.x 之前的旧版人格格式（v3）。
初始化时会自动从数据库读取全部人格，并生成一份 v3 兼容数据，供旧代码无缝使用。
```py
@@ -450,56 +465,56 @@ persona_mgr = self.context.persona_manager
#### `get_all_personas`
- __Usage__
- __Usage__
一次性获取数据库中所有人格。
- __Returns__
- __Returns__
`list[Persona]` – 人格列表，可能为空
#### `create_persona`
- __Usage__
- __Usage__
新建人格并立即写入数据库，成功后自动刷新本地缓存。
- __Arguments__
- `persona_id: str` – 新人格 ID（唯一）
- `system_prompt: str` – 系统提示词
- `begin_dialogs: list[str]` – 可选，开场对话（偶数条，user/assistant 交替）
- __Arguments__
- `persona_id: str` – 新人格 ID（唯一）
- `system_prompt: str` – 系统提示词
- `begin_dialogs: list[str]` – 可选，开场对话（偶数条，user/assistant 交替）
- `tools: list[str]` – 可选，允许使用的工具列表；`None`=全部工具，`[]`=禁用全部
- __Returns__
- __Returns__
`Persona` – 新建后的人格对象
- __Raises__
- __Raises__
`ValueError` – 若 `persona_id` 已存在
#### `update_persona`
- __Usage__
- __Usage__
更新现有人格的任意字段，并同步到数据库与缓存。
- __Arguments__
- `persona_id: str` – 待更新的人格 ID
- `system_prompt: str` – 可选，新的系统提示词
- `begin_dialogs: list[str]` – 可选，新的开场对话
- __Arguments__
- `persona_id: str` – 待更新的人格 ID
- `system_prompt: str` – 可选，新的系统提示词
- `begin_dialogs: list[str]` – 可选，新的开场对话
- `tools: list[str]` – 可选，新的工具列表；语义同 `create_persona`
- __Returns__
- __Returns__
`Persona` – 更新后的人格对象
- __Raises__
- __Raises__
`ValueError` – 若 `persona_id` 不存在
#### `delete_persona`
- __Usage__
- __Usage__
删除指定人格，同时清理数据库与缓存。
- __Arguments__
- __Arguments__
- `persona_id: str` – 待删除的人格 ID
- __Raises__
- __Raises__
`ValueError` – 若 `persona_id` 不存在
#### `get_default_persona_v3`
- __Usage__
根据当前会话配置，获取应使用的默认人格（v3 格式）。
- __Usage__
根据当前会话配置，获取应使用的默认人格（v3 格式）。
若配置未指定或指定的人格不存在，则回退到 `DEFAULT_PERSONALITY`。
- __Arguments__
- __Arguments__
- `umo: str | MessageSession | None` – 会话标识，用于读取用户级配置
- __Returns__
- __Returns__
`Personality` – v3 格式的默认人格对象
::: details Persona / Personality 类型定义
docs/zh/dev/star/guides/listen-message-event.md
+8 -8
View File
@@ -1,4 +1,3 @@
# 处理消息事件
事件监听器可以收到平台下发的消息内容，可以实现指令、指令组、事件监听等功能。
@@ -97,9 +96,9 @@ AstrBot 会自动帮你解析指令的参数。
```python
@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"Wow! The anwser is {a + b}!")
yield event.plain_result(f"Wow! The answer is {a + b}!")
```
## 指令组
@@ -108,7 +107,7 @@ def add(self, event: AstrMessageEvent, a: int, b: int):
```python
@filter.command_group("math")
def math(self):
def math():
pass
@math.command("add")
@@ -160,7 +159,7 @@ async def sub(self, event: AstrMessageEvent, a: int, b: int):
yield event.plain_result(f"结果是: {a - b}")
@calc.command("help")
def calc_help(self, event: AstrMessageEvent):
async def calc_help(self, event: AstrMessageEvent):
# /math calc help
yield event.plain_result("这是一个计算器插件，拥有 add, sub 指令。")
```
@@ -173,7 +172,7 @@ def calc_help(self, event: AstrMessageEvent):
```python
@filter.command("help", alias={'帮助', 'helpme'})
def help(self, event: AstrMessageEvent):
async def help(self, event: AstrMessageEvent):
yield event.plain_result("这是一个计算器插件，拥有 add, sub 指令。")
```
@@ -209,7 +208,7 @@ async def on_aiocqhttp(self, event: AstrMessageEvent):
yield event.plain_result("收到了一条信息")
```
当前版本下，`PlatformAdapterType` 有 `AIOCQHTTP`, `QQOFFICIAL`, `GEWECHAT`, `ALL`。
当前版本下，`PlatformAdapterType` 支持以下值：`AIOCQHTTP`、`QQOFFICIAL`、`QQOFFICIAL_WEBHOOK`、`TELEGRAM`、`WECOM`、`WECOM_AI_BOT`、`LARK`、`DINGTALK`、`DISCORD`、`SLACK`、`KOOK`、`VOCECHAT`、`WEIXIN_OFFICIAL_ACCOUNT`、`SATORI`、`MISSKEY`、`LINE`、`MATRIX`、`WEIXIN_OC`、`MATTERMOST`、`WEBCHAT`、`ALL`。
#### 管理员指令
@@ -437,13 +436,14 @@ async def on_agent_done(self, event: AstrMessageEvent, run_context: ContextWrapp
```python
from astrbot.api.event import filter, AstrMessageEvent
import astrbot.api.message_components as Comp
@filter.on_decorating_result()
async def on_decorating_result(self, event: AstrMessageEvent):
result = event.get_result()
chain = result.chain
print(chain) # 打印消息链
chain.append(Plain("!")) # 在消息链的最后添加一个感叹号
chain.append(Comp.Plain("!")) # 在消息链的最后添加一个感叹号
```
> 这里不能使用 yield 来发送消息。这个钩子只是用来装饰 event.get_result().chain 的。如需发送，请直接使用 `event.send()` 方法。
docs/zh/dev/star/guides/simple.md
+1 -1
View File
@@ -4,7 +4,7 @@
```python
from astrbot.api.event import filter, AstrMessageEvent, MessageEventResult
from astrbot.api.star import Context, Star, register
from astrbot.api.star import Context, Star
from astrbot.api import logger # 使用 astrbot 提供的 logger 接口
class MyPlugin(Star):
docs/zh/dev/star/plugin-new.md
+5
View File
@@ -104,8 +104,10 @@ support_platforms:
- `aiocqhttp`
- `qq_official`
- `qq_official_webhook`
- `telegram`
- `wecom`
- `wecom_ai_bot`
- `lark`
- `dingtalk`
- `discord`
@@ -113,9 +115,12 @@ support_platforms:
- `kook`
- `vocechat`
- `weixin_official_account`
- `weixin_oc`
- `satori`
- `misskey`
- `line`
- `matrix`
- `mattermost`
### 声明 AstrBot 版本范围（Optional）
docs/zh/dev/star/plugin-publish.md
+11
View File
@@ -7,3 +7,14 @@ AstrBot 使用 GitHub 托管插件，因此你需要先将插件代码推送到
你可以前往 [AstrBot 插件市场](https://plugins.astrbot.app) 提交你的插件。进入该网站后，点击右下角的 `+` 按钮，填写好基本信息、作者信息、仓库信息等内容后，点击 `提交到 GITHUB` 按钮，你将会被导航到 AstrBot 仓库的 Issue 提交页面，请确认信息无误后点击 `Create` 按钮提交，即可完成插件发布。
![fill out the form](https://files.astrbot.app/docs/source/images/plugin-publish/image.png)
> ⚠️ **大小限制**：发布到插件市场的插件压缩包（zip）大小**不得超过 16MB**。如果超过此限制，CI/CD 流水线将自动拒绝该发布请求。
>
> 为确保你的插件能顺利通过审核和发布，建议采取以下措施：
>
> - **压缩图片等静态资源**：对插件中的图片、音频等资源文件进行压缩，减小体积。
> - **清理不必要的文件**：避免将 `.git` 目录、`__pycache__`、`node_modules`、开发用配置文件等非必需文件提交到插件仓库中。建议在仓库根目录添加 `.gitignore` 来排除它们。
> - **优化依赖体积**：如果插件包含体积较大的依赖库，可考虑精简或按需引入。
> - **使用 `.gitattributes` 或发布分支**：通过只包含发布所需文件的策略来减小 zip 包体积。
>
> 如果插件确实因业务需要无法压缩到 16MB 以内，可以联系维护者手动 bypass 此限制。
docs/zh/faq.md
+72 -7
View File
@@ -6,17 +6,82 @@
在 [release](https://github.com/AstrBotDevs/AstrBot/releases) 页面下载 `dist.zip`，解压拖到 `AstrBot/data` 下。还不行请重启电脑（来自群里的反馈）
### 首次登录的默认账号和随机密码
首次启动时，WebUI 的默认账号为 `astrbot`，默认密码会随机生成，不会写死为固定值。请在启动日志中查找以下内容并使用日志中的随机初始密码登录：
```text
[00:27:40.590] [Core] [INFO] [dashboard.server:523]:
✨✨✨
AstrBot v4.24.3 WebUI is ready
➜ Local: http://localhost:6185
➜ Initial username: astrbot
➜ Initial password: UiYVpZxnW8k22IWqf0ru5pOy
➜ Change it after logging in
✨✨✨
Set dashboard.host in data/cmd_config.json to enable remote access.
```
其中的 `UiYVpZxnW8k22IWqf0ru5pOy` 就是默认密码。在使用默认密码登录后，会自动进入设置账户环节。
### 管理面板的密码忘记了
如果你忘记了 AstrBot 管理面板的密码，你可以在 `AstrBot/data/cmd_config.json` 配置文件中找到 `"dashboard"` 字段进行修改，其中 `"username"` 是你的用户名，`"password"` 是你的密码（经过 MD5 加密）。
如果你忘记了 AstrBot 管理面板的密码，你可以在 `AstrBot/data/cmd_config.json` 配置文件中找到 `"dashboard"` 字段，如下：
如果想要修改账号密码，你可以这样做：
```json
"dashboard": {
"enable": true,
"username": "astrbot",
"password": "81e0c3dxxxxxxxxxxx78862e78",
"pbkdf2_password": "pbkdf2_sha256$600000$1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"password_storage_upgraded": true,
"password_change_required": true,
"jwt_secret": "5e1b0280bcxxxxxxxxxxxxxxxxf4a",
"host": "127.0.0.1",
"port": 6185,
"disable_access_log": true,
"ssl": {
"enable": false,
"cert_file": "",
"key_file": "",
"ca_certs": ""
}
},
```
1. 修改 `"username"` 字段，注意保留 `""`；如果不想修改用户名，可以不修改
2. 进入网站：[在线 MD5 生成](https://www.metools.info/code/c26.html)
3. 在转换前文本框输入你的新密码
4. 选择 MD5 加密（32 位），请确认选择 32 位选项
5. 将转换后的字符粘贴至配置文件，注意保留 `""`, 且字母使用小写
删除 `username`, `password`, `pbkdf2_password`, `password_storage_upgraded`, `password_change_required`, `jwt_secret` 五个字段（连同值一起），然后保存。上述片段修改类似如下：
```json
"dashboard": {
"enable": true,
"host": "127.0.0.1",
"port": 6185,
"disable_access_log": true,
"ssl": {
"enable": false,
"cert_file": "",
"key_file": "",
"ca_certs": ""
}
},
```
重启后 AstrBot 将会自动生成随机的密码以及固定的用户名 `astrbot`，请在日志查看。
### 升级 AstrBot 后密码正确但无法登录
如果你确认管理面板密码正确，但升级 AstrBot 后仍然无法登录，可能是旧版 WebUI 静态文件缓存与新版后端不兼容。
解决方案：
1. 停止 AstrBot。
2. 删除 AstrBot 的 `data` 目录下的 `dist` 文件夹，即 `AstrBot/data/dist`。
3. 重新启动 AstrBot。
重启后，AstrBot 会重新加载或下载匹配当前版本的 WebUI 文件。
## AstrBot 使用相关
docs/zh/platform/dingtalk.md
+15 -1
View File
@@ -16,6 +16,20 @@
## 创建和配置应用
钉钉支持两种创建方式：在 AstrBot 中扫码一键创建，或在钉钉开放平台手动创建应用。
### 方式一：扫码一键创建
需要 AstrBot 版本 >= v4.25.0。
打开 AstrBot 管理面板 -> `机器人` -> `+ 创建机器人`，选择 `钉钉(DingTalk)`。
在 `选择创建方式` 中选择 `扫码一键创建`，使用手机钉钉扫描页面中的二维码，并在钉钉页面中创建或绑定机器人。创建成功后，AstrBot 会自动写入 `ClientID` 和 `ClientSecret`，此时点击 `保存` 即可。
扫码创建完成后，仍建议检查后文的事件订阅、版本发布和拉入群组步骤。
### 方式二：手动创建
前往 [钉钉开放平台](https://open-dev.dingtalk.com/fe/app)，点击创建应用：
![image](https://files.astrbot.app/docs/source/images/dingtalk/image-4.png)
@@ -36,7 +50,7 @@
打开 AstrBot 管理面板 -> `机器人` -> `+ 创建机器人`，创建一个钉钉适配器。
将刚刚复制的 `ClientID` 和 `ClientSecret` 填入，点击保存，AstrBot 将会自动向钉钉开放平台请求。
如果使用扫码一键创建，选择 `扫码一键创建` 并完成扫码；如果使用自己创建的钉钉应用，选择 `手动创建`，将刚刚复制的 `ClientID` 和 `ClientSecret` 填入。点击保存后，AstrBot 将会自动向钉钉开放平台请求。
回到钉钉开放平台，点击事件订阅，选择 `Stream 模式推送`，点击保存，如果没有意外情况，将会看到 连接接入成功 字样。
docs/zh/platform/lark.md
+29 -1
View File
@@ -20,6 +20,31 @@
## 创建机器人
飞书（Lark）支持两种创建方式：在 AstrBot 中扫码一键创建，或在飞书开发者后台手动创建企业自建应用。
### 方式一：扫码一键创建
需要版本 >4.25.0。
进入 AstrBot 管理面板，点击左边栏 `机器人`，然后点击 `+ 创建机器人`，选择 `lark(飞书)`。
在 `选择创建方式` 中选择 `扫码一键创建`，按需选择国内版或海外版，然后使用手机飞书扫描页面中的二维码并确认。创建成功后，AstrBot 会自动写入该应用的 `app_id`、`app_secret` 和域名配置。
> [!IMPORTANT]
> 通过扫码方式创建后，群聊下默认仅会接收 @ 机器人和通过唤醒前缀（例如 `/`）触发的消息。如果你希望机器人接收群聊中的所有消息，需要前往飞书开发者后台为应用开通额外权限。
>
> 可以将下面链接中的 `<APP_ID>` 替换为你的飞书应用 App ID 后打开，一键进入权限开通页：
>
> App ID 获取方式：回到 AstrBot 的 `机器人` 页，找到刚刚创建的飞书机器人，点击 `编辑`，弹出的对话框中可以看到 App ID。
>
> ```text
> https://open.feishu.cn/app/<APP_ID>/auth?q=contact:contact.base:readonly,im:message.p2p_msg:readonly,im:message.group_at_msg:readonly,im:message:send,im:message,im:message:send_as_bot,im:resource:upload,im:resource,cardkit:card:write,im:message.group_at_msg:readonly,im:message.group_msg&op_from=openapi&token_type=tenant
> ```
扫码创建完成后，建议继续检查后文的事件订阅、权限、版本发布和拉入群组步骤。
### 方式二：手动创建
前往 [开发者后台](https://open.feishu.cn/app) ，创建企业自建应用。
![创建企业自建应用](https://files.astrbot.app/docs/source/images/lark/image.png)
@@ -38,6 +63,7 @@
2. 点击左边栏 `机器人`
3. 然后在右边的界面中，点击 `+ 创建机器人`
4. 选择 `lark(飞书)`
5. 如果使用扫码一键创建，选择 `扫码一键创建` 并完成扫码；如果使用自己创建的企业自建应用，选择 `手动创建`
弹出的配置项填写：
@@ -45,7 +71,6 @@
- 启用(enable): 勾选。
- app_id: 获取的 app_id
- app_secret: 获取的 app_secret
- 飞书机器人的名字
对于 domain，如果您使用国内版飞书，保持默认即可；如果您正在用国际版飞书，请设置为 `https://open.larksuite.com`；如果您使用企业自部署飞书，请填写您的飞书实例的域名。
@@ -94,6 +119,9 @@
如果需要在群聊里使用，请额外开通 `im:message.group_at_msg:readonly` 和 `im:message.group_msg` 权限。
> [!TIP]
> 扫码一键创建的应用默认适合 @ 机器人和唤醒前缀触发。如果要接收群聊所有消息，请确认已经开通 `im:message.group_msg`。你也可以使用上文提供的权限开通链接快速进入对应页面。
如果需要使用流式输出，请额外开通 `创建与更新卡片(cardkit:card:write)` 权限。
最终开通的权限如下图：
docs/zh/platform/weixin_oc.md
+5 -10
View File
@@ -23,6 +23,8 @@ AstrBot 支持通过 `个人微信` 适配器接入微信个人号。该适配
2. 点击左侧栏 `机器人`。
3. 点击右上角 `+ 创建机器人`。
4. 选择 `个人微信`。
5. 页面会直接显示登录二维码，使用手机微信扫码，并在微信内确认登录。
6. 登录成功后点击 `保存`。
## 配置项说明
@@ -42,18 +44,12 @@ AstrBot 支持通过 `个人微信` 适配器接入微信个人号。该适配
## 扫码登录
1. 填好配置后点击 `保存`。
2. 返回机器人列表，AstrBot 会自动向微信接口申请登录二维码。
3. 在**机器人卡片**中点击 “查看二维码” 按钮，会弹出二维码对话框。（点击保存之后可能需要等 5 到 10 秒左右才会出现这个按钮）
4. 使用手机微信扫码，并在微信内确认登录。
选择 `个人微信` 后，AstrBot 会自动向微信接口申请登录二维码，并直接显示在创建机器人弹窗中。使用手机微信扫码确认后，二维码会显示登录成功状态，此时点击 `保存` 即可完成创建。
![微信二维码入口](weixin_qr_entry.png)
登录成功后，AstrBot 会自动保存登录态。后续重启时，如果登录态仍有效，通常不需要再次扫码。
登录成功并保存后，AstrBot 会自动保存登录态。后续重启时，如果登录态仍有效，通常不需要再次扫码。
> [!NOTE]
> 1. 如果二维码过期，AstrBot 会自动重新申请新的二维码。刷新后请使用新的二维码重新扫码。
> 2. 如果 WebUI 没看到 “查看二维码” 按钮，可以前往终端或者 WebUI 控制台，找到 `请使用手机微信扫码登录，二维码有效期 5 分钟，过期后会自动刷新。` 对应的日志，附近会显示二维码扫码链接和终端直接输出的二维码，直选择一种方式扫码即可。
> 如果二维码过期，请关闭并重新打开创建机器人弹窗，或重新选择 `个人微信` 以获取新的二维码。
## 验证
@@ -77,4 +73,3 @@ AstrBot 支持通过 `个人微信` 适配器接入微信个人号。该适配
- 该适配器通过扫码登录个人微信，接入方式与微信公众号、企业微信不同。
- 不需要配置公网回调地址，也不需要开启统一 Webhook 模式。
docs/zh/use/astrbot-agent-sandbox.md
+1 -1
View File
@@ -434,7 +434,7 @@ docker pull soulter/shipyard-ship:latest
- 如果是官方联合部署，且 AstrBot 能访问 Bay 的 `credentials.json`，可以留空自动发现
- `Shipyard Neo Profile`
- 例如 `python-default`、`browser-python`
- 如果未手动指定，AstrBot 会优先尝试选择能力更完整、且优先带有 `browser` capability 的 profile，失败时再回退到 `python-default`
- 如果留空，AstrBot 会优先尝试选择能力更完整、且优先带有 `browser` capability 的 profile，失败时再回退到 `python-default`
- `Shipyard Neo Sandbox TTL`
- sandbox 生命周期上限，默认值为 3600 秒（1 小时）
docs/zh/use/knowledge-base.md
+1 -1
View File
@@ -55,6 +55,6 @@ AstrBot 支持多知识库管理。在聊天时，您可以**自由指定知识
1. 打开 [硅基流动官网](https://cloud.siliconflow.cn/i/zMCYMSt2)，注册账户并完成实名认证。
2. 打开 [API 密钥](https://cloud.siliconflow.cn/me/account/ak)。
5. 填写 AstrBot OpenAI Embedding 模型提供商配置：
1. API Key 为刚刚申请的 PPIO 的 API Key
1. API Key 为刚刚申请的硅基流动的 API Key
2. embedding api base 填写 `https://api.siliconflow.cn/v1`
3. model 填写你选择的模型，此例子中为 `BAAI/bge-m3`。
docs/zh/use/webui.md
+1 -1
View File
@@ -13,7 +13,7 @@ AstrBot 管理面板具有管理插件、查看日志、可视化配置、查看
## 登录
默认用户名和密码是 `astrbot` 和 `astrbot`。
新用户首次登录时，AstrBot 会生成一个随机初始密码并写入启动日志。请先在启动日志中查找并使用该密码登录（用户名通常为 `astrbot`），登录后请立即修改密码。
## ChatUI