fix(docs):多份文档汉译英并整理 (#8001)

* docs(en): translate plugin-platform-adapter.md from Chinese to English * docs(en): translate plugin-platform-adapter.md from Chinese to English * Update ppio.md * Update provider-lmstudio.md * Update function-calling.md * Update skills.md * Update ai.md * Update simple.md * Update mcp.md * Update config.mjs kook * fix(docs): fix MessageSesion import path in platform adapter example Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
2026-07-15 17:30:13 +08:00 · 2026-05-09 22:17:47 +08:00
parent 4bcaaab44f
commit bd9aade842
10 changed files with 102 additions and 120 deletions
--- 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" },
                ],
              },
--- 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)


-有任何疑问欢迎加群询问~
+If you have any questions, feel free to join the community group and ask~
--- 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

--- 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`。
-
-所有的处理函数都需写在插件类中。为了精简内容，在之后的章节中，我们可能会忽略插件类的定义。
--- 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.
--- 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` 禁用所有的函数调用工具即可使用，或者换用其他模型。
+Temporarily disable all function calling tools with `/tool off_all`, or switch to a different model.
--- 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
+<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.
--- 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).
--- 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)
--- 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