NcatBot 文档

外观

多平台开发指南

约 1070 字大约 4 分钟

2026-03-19

NcatBot 5.2 起支持跨平台运行 — 通过 Adapter/Platform/Trait 三层抽象实现多平台统一开发。

Quick Reference

核心三层抽象

层说明
Platform适配器的 platform 标识（如 "qq"），用于事件路由、API 注入、Handler 过滤
API Trait跨平台 API 能力协议：IMessaging（消息）、IGroupManage（群管理）、IQuery（查询）、IFileTransfer（文件）
事件 Trait事件实体通用能力：Replyable、Deletable、GroupScoped、Kickable、Bannable、HasSender、Approvable

多平台 API 访问

操作调用方式
QQ 平台 APIself.api.qq.messaging.* / self.api.qq.manage.* 等
GitHub 平台 APIself.api.github.create_issue() / self.api.github.merge_pr() 等
查看已注册平台self.api.platforms → Dict[str, IAPIClient]

平台过滤

所有装饰器支持 platform 参数限定事件来源：

示例说明
@registrar.on_group_command("hello", platform="qq")仅 QQ 群命令
@registrar.on_message(platform="qq")仅 QQ 消息
@registrar.on_notice()所有平台通知（不设 platform）

跨平台插件编写

使用 Trait 协议检查事件能力：isinstance(event, Replyable) → 可调用 event.reply()。

核心概念

平台 (Platform)

每个适配器有一个 platform 标识符（如 "qq"、"telegram"），用于：

  • 事件路由：event.platform 区分事件来源
  • API 注入：HandlerDispatcher 自动为事件实体注入对应平台的 API
  • Handler 过滤：@bot.on("message", platform="qq") 仅接收 QQ 消息

Trait 协议

跨平台 API 按功能拆分为 Trait 协议（api/traits/）：

Trait功能
IMessaging发送/撤回消息、转发
IGroupManage群管理（踢人、禁言、设管理）
IQuery信息查询（好友列表、群信息）
IFileTransfer文件上传/下载

事件实体也有 Trait 协议（event/traits.py）：

Trait功能
Replyable可回复（reply(), send()）
Deletable可撤回（delete()）
HasSender有发送者信息
GroupScoped群相关（有 group_id）
Kickable可踢出群成员
Bannable可禁言

多平台运行

单个 BotClient 可同时运行多个适配器，共享插件和服务：

from ncatbot.app import BotClient
from ncatbot.adapter import NapCatAdapter
from ncatbot.adapter.github import GitHubAdapter

bot = BotClient(adapters=[
    NapCatAdapter(),           # platform="qq"
    GitHubAdapter(),           # platform="github"
    # TelegramAdapter(),       # platform="telegram" (未来)
])
bot.run()

单平台用法（默认）

对于只使用 QQ 的场景，用法与 5.0 完全相同：

from ncatbot.app import BotClient

bot = BotClient()  # 默认 NapCatAdapter

@bot.on("message.group")
async def on_msg(event):
    await event.reply("hello")

bot.run()

多平台 API 访问

plugin.api（BotAPIClient）是多平台门面，提供三种访问方式：

# 方式 1: 直接属性访问（推荐，有类型提示）
await self.api.qq.messaging.send_group_msg(group_id, message)
await self.api.bilibili.send_danmu(room_id, text)
await self.api.github.create_issue_comment(repo, issue_number, body)

# 方式 2: 动态平台访问（按名称获取）
client = self.api.platform("qq")        # → IQQAPIClient
await client.messaging.send_group_msg(group_id, message)

# 方式 3: 查看已注册的平台
print(self.api.platforms)  # {"qq": <IQQAPIClient>, "bilibili": ..., "github": ...}

选择建议：

方式适用场景
api.qq.* / api.bilibili.*平台确定、需要 IDE 自动补全
api.platform(name)平台名来自变量或运行时动态决定
api.platforms遍历/列出所有已注册平台

平台过滤

通过 platform 参数限定 handler 只接收特定平台的事件：

@bot.on("message.group", platform="qq")
async def qq_only(event):
    """仅处理 QQ 群消息"""
    await event.reply("QQ!")

@bot.on("message")
async def all_platforms(event):
    """处理所有平台的消息"""
    print(f"来自 {event.platform} 的消息")

所有便捷装饰器都支持 platform 参数：

@bot.on_group_message(platform="qq")
@bot.on_command("/help", platform="qq")
@bot.on_notice(platform="qq")

编写跨平台插件

使用 Trait 协议编写跨平台逻辑：

from ncatbot.event import Replyable, GroupScoped

@bot.on("message")
async def cross_platform(event):
    if isinstance(event, Replyable):
        await event.reply("hello from any platform!")

    if isinstance(event, GroupScoped):
        print(f"群 {event.group_id} 的消息")

参考

实战案例

GitHub ↔ QQ 双向桥接

examples/cross_platform/03_github_qq_bridge/ 展示了一个完整的跨平台双向桥接机器人：

  • GitHub → QQ：Issue/PR/Push/Comment 事件自动转发到指定 QQ 群
  • QQ → GitHub：在 QQ 群中引用(reply)通知消息，回复内容自动作为 GitHub Issue Comment 发送
  • 消息映射追踪：维护 QQ 消息 ID ↔ GitHub Issue 的映射表，支持 reply 反向关联

核心技术点：

  • 同时使用 registrar.github.* 和 registrar.qq.* 平台子注册器
  • 通过 self.api.qq.* 和 self.api.github.* 访问多平台 API
  • ConfigMixin 读取桥接群号和仓库名，避免硬编码
  • HasSender Trait 统一获取 GitHub/QQ 事件的发送者信息

⚠️ 本示例依赖开发中的 GitHub Adapter，API 可能变动。

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025 NcatBot