diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index cad68ec06b..458bc8dabe 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -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" }, ], }, diff --git a/docs/en/dev/plugin-platform-adapter.md b/docs/en/dev/plugin-platform-adapter.md index 8e65528e23..4772b6e180 100644 --- a/docs/en/dev/plugin-platform-adapter.md +++ b/docs/en/dev/plugin-platform-adapter.md @@ -2,23 +2,23 @@ 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 @@ -29,7 +29,7 @@ class FakeClient(): await asyncio.sleep(5) await getattr(self, 'on_message_received')({ 'bot_id': '123', - 'content': '新消息', + 'content': 'new message', 'username': 'zhangsan', 'userid': '123', 'message_id': 'asdhoashd', @@ -37,28 +37,28 @@ class FakeClient(): }) 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 + abm = await self.convert_message(data=data) # Convert to AstrBotMessage await self.handle_msg(abm) - # 初始化 FakeClient + # 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 @@ -138,13 +139,13 @@ class FakePlatformEvent(AstrMessageEvent): 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) -有任何疑问欢迎加群询问~ \ No newline at end of file +If you have any questions, feel free to join the community group and ask~ diff --git a/docs/en/dev/star/guides/ai.md b/docs/en/dev/star/guides/ai.md index 361ac55c46..8e09da1340 100644 --- a/docs/en/dev/star/guides/ai.md +++ b/docs/en/dev/star/guides/ai.md @@ -257,7 +257,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 @@ -438,7 +438,7 @@ persona_mgr = self.context.persona_manager - **Returns** `Personality` – Default persona object in v3 format -::: details Persona / Personality 类型定义 +::: details Persona / Personality Type Definition ```py diff --git a/docs/en/dev/star/guides/simple.md b/docs/en/dev/star/guides/simple.md index f2dc11be95..d7ed40f957 100644 --- a/docs/en/dev/star/guides/simple.md +++ b/docs/en/dev/star/guides/simple.md @@ -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`。 - -所有的处理函数都需写在插件类中。为了精简内容,在之后的章节中,我们可能会忽略插件类的定义。 diff --git a/docs/en/providers/302ai.md b/docs/en/providers/302ai.md index 50a3abe775..8685e3b055 100644 --- a/docs/en/providers/302ai.md +++ b/docs/en/providers/302ai.md @@ -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. diff --git a/docs/en/providers/ppio.md b/docs/en/providers/ppio.md index fceb61dd10..db9ed03b40 100644 --- a/docs/en/providers/ppio.md +++ b/docs/en/providers/ppio.md @@ -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` 禁用所有的函数调用工具即可使用,或者换用其他模型。 \ No newline at end of file +Temporarily disable all function calling tools with `/tool off_all`, or switch to a different model. diff --git a/docs/en/providers/provider-lmstudio.md b/docs/en/providers/provider-lmstudio.md index 969f7d7c89..4c0d99a7c3 100644 --- a/docs/en/providers/provider-lmstudio.md +++ b/docs/en/providers/provider-lmstudio.md @@ -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 + -### 下载并运行模型 +### Download and Run a Model -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 配置的模型 \ No newline at end of file +> Run `/provider` to view the models configured in AstrBot. diff --git a/docs/en/use/function-calling.md b/docs/en/use/function-calling.md index 1526cbab90..2208ddd113 100644 --- a/docs/en/use/function-calling.md +++ b/docs/en/use/function-calling.md @@ -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). diff --git a/docs/en/use/mcp.md b/docs/en/use/mcp.md index 1681d31325..a2b95f5622 100644 --- a/docs/en/use/mcp.md +++ b/docs/en/use/mcp.md @@ -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) diff --git a/docs/en/use/skills.md b/docs/en/use/skills.md index a57a5b12ce..4221cc047a 100644 --- a/docs/en/use/skills.md +++ b/docs/en/use/skills.md @@ -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