plugins/            # PHP 插件
└── <作者>/<插件名>/
    ├── main.php            # 入口（必须）
    ├── metadata.json       # 元数据（必须）
    └── _conf_schema.json   # 配置 schema（可选，后台自动渲染表单）

plugins_py/         # Python 插件（AstrBot 原生写法）
└── <作者>/<插件名>/
    ├── main.py             # 入口（必须）
    ├── metadata.json       # 元数据（必须）
    └── _conf_schema.json   # 配置 schema（可选）

{
  "name": "HelloWorld",
  "desc": "打招呼示例插件",
  "version": "1.0.0",
  "author": "XZQQ",
  "repo": "https://github.com/your/repo"
}

{
  "reply_prefix": { "type": "string", "description": "回复前缀", "default": "【XZCLOUD】" },
  "max_len":      { "type": "int",    "description": "最大长度", "default": 100 },
  "enabled_extra":{ "type": "bool",   "description": "附加功能", "default": true }
}

<?php
declare(strict_types=1);

use XZQQ\Event\MessageChain;
use XZQQ\Event\MessageEvent;
use XZQQ\Plugin\Filter;
use XZQQ\Plugin\PluginBase;

return new class extends PluginBase {

    #[Filter\Command('hello', alias: ['hi', '你好'],
        description: '打招呼',
        usage: '/hello [名字]')]
    public function onHello(MessageEvent $event): MessageChain
    {
        $name = $event->arg('name', '世界');       // 带参指令自动注入
        return MessageChain::plain($this->config('reply_prefix', '【XZCLOUD】') . " 你好，{$name}！");
    }

    #[Filter\Command('dice')]
    public function onDice(MessageEvent $event): MessageChain
    {
        return MessageChain::plain('🎲 你掷出了 ' . random_int(1, 6) . ' 点');
    }

    #[Filter\Command('admin', permission: 'admin')]
    #[Filter\PermissionType('admin')]
    public function onAdmin(MessageEvent $event): MessageChain
    {
        return MessageChain::plain('管理员专属指令');
    }

    #[Filter\Regex('/天气|下雨|气温/u')]
    public function onWeather(MessageEvent $event): MessageChain
    {
        return MessageChain::plain('今天晴，25℃');
    }

    #[Filter\EventMessageType('GROUP_MESSAGE')]
    public function onGroup(MessageEvent $event): MessageChain
    {
        if (!$event->isAtBot()) return MessageChain::empty();  // 未@不处理
        return MessageChain::at($event->senderId)->plain(' 在的');
    }
};

MessageChain::plain('文本');
MessageChain::image($url, $name);
MessageChain::video($url, $name);
MessageChain::record($url);                 // 语音
MessageChain::file($url, $name);
MessageChain::face(123);                    // QQ 表情 ID
MessageChain::at($userId);
MessageChain::atAll();
MessageChain::reply($messageId);
MessageChain::empty();                      // 不回复

from astrbot.api import star
from astrbot.api.event import filter, AstrMessageEvent

@star.register(name="helloworld_py", desc="打招呼示例", version="1.0.0", author="XZQQ")
class Main(star.Star):
    '''插件主类：类名建议叫 Main；可带 (context) 形参接收上下文'''

    def __init__(self, context):
        super().__init__(context)
        self.prefix = self.context.get_config().get("reply_prefix", "【XZCLOUD】")

    @filter.command("hello", alias={"你好", "hi"})
    async def hello(self, event: AstrMessageEvent, name: str = "世界"):
        '''带参指令：name 自动从指令参数注入；默认值支持'''
        yield event.plain_result(f"{self.prefix} 你好，{name}！")

    @filter.command("ping")
    async def ping(self, event: AstrMessageEvent):
        event.stop_event()            # 阻止后续插件处理
        yield event.plain_result("pong")

    @filter.regex(r"^(?:今天|明天)?天气.*")
    async def weather(self, event: AstrMessageEvent):
        yield event.plain_result("今天晴，25℃")

    @filter.permission_type(filter.PermissionType.ADMIN)
    @filter.command("pyinfo")
    async def pyinfo(self, event: AstrMessageEvent):
        yield event.plain_result("管理员信息")

    async def initialize(self):   # 生命周期：加载完成后调用
        pass

    async def terminate(self):    # 生命周期：卸载/停用时调用
        pass

cd bridge
python3 astrbot_bridge.py --selftest      # 本地自检：强制加载插件并回放 3 条测试消息
python3 astrbot_bridge.py --verbose       # 前台运行并打印收发帧