Merge pull request #62 from langbot-app/feat/new-plugin

Feat/new plugin
2026-11-01 13:25:18 +08:00 · 2025-09-16 12:35:23 +08:00
parent 61eca6f343
commit 5a3cd5fcb1
59 changed files with 3246 additions and 1390 deletions
@@ -0,0 +1,211 @@
+# 组件：命令
+
+命令组件由用户通过`!`（或其他已设置的前缀）开头的命令消息触发。如下是命令`!help`的触发示例：
+
+<img width="600" src="/assets/image/zh/plugin/dev/components/command_use.png" />
+
+## 添加命令组件
+
+单个插件中能添加任意数量的命令，请在插件目录执行命令`lbp comp Command`，并根据提示输入命令的配置。
+
+```bash
+➜  HelloPlugin > lbp comp Command
+Generating component Command...
+Command name: info
+Command description: Show information of the query
+Component Command generated successfully.
+组件 Command 生成成功。
+```
+
+现在即会在`components/commands/`目录下生成`info.yaml`和`info.py`文件，`.yaml`定义了`!info`命令的基础信息，`.py`是该命令的处理程序：
+
+```bash
+➜  HelloPlugin > tree
+...
+├── components
+│   ├── __init__.py
+│   ├── commands
+│   │   ├── __init__.py
+│   │   ├── info.py
+│   │   └── info.yaml
+...
+```
+
+## 清单文件：命令组件
+
+```yaml
+apiVersion: v1  # 请勿修改
+kind: Command  # 请勿修改
+metadata:
+  name: info  # 命令名称，在使用时，用户会通过 !info 触发该命令
+  label:  # 命令显示名称，用于显示在 LangBot 的 UI 上，支持多语言
+    en_US: Info
+    zh_Hans: Info
+  description:  # 命令描述，用于显示在 LangBot 的 UI 上，支持多语言。可选。
+    en_US: 'Show information of the query'
+    zh_Hans: '发送此次消息的详细信息'
+spec:
+execution:
+  python:
+    path: info.py  # 命令处理程序，请勿修改
+    attr: Info  # 命令处理程序的类名，与 info.py 中的类名一致
+```
+
+## 插件处理
+
+默认会生成如下代码(components/command/<命令名称>.py)，您需要在`Info`类的`initialize`方法中注册并实现子命令的处理逻辑。
+
+```python
+# Auto generated by LangBot Plugin SDK.
+# Please refer to https://docs.langbot.app/en/plugin/dev/tutor.html for more details.
+from __future__ import annotations
+
+from typing import Any, AsyncGenerator
+
+from langbot_plugin.api.definition.components.command.command import Command, Subcommand
+from langbot_plugin.api.entities.builtin.command.context import ExecuteContext, CommandReturn
+
+
+class Info(Command):
+    
+    async def initialize(self):
+        await super().initialize()
+        
+        "Fill with your code here"
+```
+
+添加子命令：
+
+```python
+...
+class Info(Command):
+    
+    async def initialize(self):
+        await super().initialize()
+        
+        @self.subcommand(
+            name="",  # 空字符串表示根命令
+            help="Show information of the query", # 命令帮助信息
+            usage="info", # 命令使用示例，显示在命令帮助信息中
+            aliases=["i"], # 命令别名
+        )
+        async def send(self, context: ExecuteContext) -> AsyncGenerator[CommandReturn, None]:
+            print(context)
+
+            reply_text = f"Query ID: {context.query_id}\n"
+            reply_text += f"command: {context.command}\n"
+            reply_text += f"command_text: {context.command_text}\n"
+            reply_text += f"params: {context.params}\n"
+            reply_text += f"crt_params: {context.crt_params}\n"
+            reply_text += f"privilege: {context.privilege}\n"
+            reply_text += f"session: {context.session.launcher_type.value}_{context.session.launcher_id}\n"
+            
+            yield CommandReturn(
+                text=reply_text,
+            )
+
+        @self.subcommand(
+            name="field",
+            help="Show information of the field",
+            usage="info field",
+            aliases=["f"],
+        )
+        async def field(self, context: ExecuteContext) -> AsyncGenerator[CommandReturn, None]:
+            print(context)
+
+            field_name = context.crt_params[0]
+            field_value = getattr(context, field_name)
+
+            yield CommandReturn(
+                text=f"{field_name}: {field_value}",
+            )
+```
+
+该代码中，`send`函数通过装饰器`@self.subcommand`注册为子命令，并在其中打印了命令的上下文（ExecuteContext）信息并拼接成一条回复消息。
+
+### 子命令注册
+
+`name` 为子命令名称，留空表示处理主命令。不为空则匹配第二个参数为命令，例如：
+
+- `!info` 匹配 name="" 的子命令
+- `!info field` 匹配 name="field" 的子命令
+- `!info field value` 匹配 name="field" 的子命令，`value` 为子命令参数
+
+子命令函数中，可通过 `context` 变量读取到命令参数。
+
+上述命令效果如图：
+
+<img width="600" src="/assets/image/zh/plugin/dev/components/info_command_demo.png" />
+
+### 命令上下文
+
+```python
+
+class ExecuteContext(pydantic.BaseModel):
+    """单次命令执行上下文"""
+
+    query_id: int
+    """请求ID"""
+
+    session: provider_session.Session
+    """本次消息所属的会话对象"""
+
+    command_text: str
+    """命令完整文本"""
+
+    command: str
+    """命令名称"""
+
+    crt_command: str
+    """当前命令
+    
+    多级命令中crt_command为当前命令，command为根命令。
+    例如：!plugin on Webwlkr
+    处理到plugin时，command为plugin，crt_command为plugin
+    处理到on时，command为plugin，crt_command为on
+    """
+
+    params: list[str]
+    """命令参数
+    
+    整个命令以空格分割后的参数列表
+    """
+
+    crt_params: list[str]
+    """当前命令参数
+
+    多级命令中crt_params为当前命令参数，params为根命令参数。
+    例如：!plugin on Webwlkr
+    处理到plugin时，params为['on', 'Webwlkr']，crt_params为['on', 'Webwlkr']
+    处理到on时，params为['on', 'Webwlkr']，crt_params为['Webwlkr']
+    """
+
+    privilege: int
+    """会话权限级别"""
+
+    ...
+```
+
+### 命令返回值
+
+命令返回值(CommandReturn)目前支持返回文本（text）和图片（image_url，图片链接）、错误（error）。
+
+```python
+yield CommandReturn(
+    text=reply_text,
+)
+
+yield CommandReturn(
+    image_url=image_url,
+)
+```
+
+命令处理支持返回多条消息，故请使用`yield`语句返回消息。
+
+具体的返回值请参考`CommandReturn`的定义：[langbot_plugin.api.entities.builtin.command.context.CommandReturn](https://github.com/langbot-app/langbot-plugin-sdk/tree/main/src/langbot_plugin/api/entities/builtin/command/context.py)
+
+## 接下来做什么
+
+您已经了解了命令注册和命令执行的基本信息，接下来可以：
+
+- 查看[插件通用 API](/zh/plugin/dev/apis/common)