ErisPulse PlatformFeatures 文档

基线协议：OneBot12

本文档为平台特定功能指南，包含：

• 各适配器支持的Send方法链式调用示例
• 平台特有的事件/消息格式说明

通用使用方法请参考：

• 基础概念
• 事件转换标准
• API响应规范

平台特定功能

此部分由各适配器开发者维护，用于说明该适配器与 OneBot12 标准的差异和扩展功能。请参考以下各平台的详细文档：

• 维护说明

• 云湖平台特性

• 云湖用户平台特性

• Telegram平台特性

• OneBot11平台特性

• OneBot12平台特性

• 邮件平台特性

• Kook(开黑啦)平台特性

• Matrix平台特性

• QQ官方机器人平台特性

• 花枫咖啡馆

• Discord

• Webhook协议桥

• 微信公众号

此外还有 sandbox 适配器，但此适配器无需维护平台特性文档

通用接口

Send 链式调用

所有适配器都支持以下标准调用方式：

注意： 文档中的 {AdapterName} 需替换为实际适配器名称（如 yunhu、telegram、onebot11、email 等）。

1. 指定类型和ID: To(type,id).Func()

   # 获取适配器实例
   my_adapter = adapter.get("{AdapterName}")
   
   # 发送消息
   await my_adapter.Send.To("user", "U1001").Text("Hello")
   
   # 例如：
   yunhu = adapter.get("yunhu")
   await yunhu.Send.To("user", "U1001").Text("Hello")
   

2. 仅指定ID: To(id).Func()

   my_adapter = adapter.get("{AdapterName}")
   await my_adapter.Send.To("U1001").Text("Hello")
   
   # 例如：
   telegram = adapter.get("telegram")
   await telegram.Send.To("U1001").Text("Hello")
   

3. 指定发送账号: Using(account_id)

   my_adapter = adapter.get("{AdapterName}")
   await my_adapter.Send.Using("bot1").To("U1001").Text("Hello")
   
   # 例如：
   onebot11 = adapter.get("onebot11")
   await onebot11.Send.Using("bot1").To("U1001").Text("Hello")
   

4. 直接调用: Func()

   my_adapter = adapter.get("{AdapterName}")
   await my_adapter.Send.Text("Broadcast message")
   
   # 例如：
   email = adapter.get("email")
   await email.Send.Text("Broadcast message")
   

异步发送与结果处理

Send DSL 的方法返回 asyncio.Task 对象，这意味着您可以选择是否立即等待结果：

# 获取适配器实例
my_adapter = adapter.get("{AdapterName}")

# 不等待结果，消息在后台发送
task = my_adapter.Send.To("user", "123").Text("Hello")

# 如果需要获取发送结果，稍后可以等待
result = await task

发送规则装饰器

在实际开发中，经常需要：发送成功后才执行后续逻辑、失败自动重试、超时取消、发送进度监控等。Send DSL 内置了一套发送规则装饰器，通过链式方法附加规则：

yunhu = adapter.get("yunhu")

# 发送成功后才扣积分
await (yunhu.Send.To("user", "123")
       .Hook(lambda r: deduct_points("123"))
       .Text("消费成功"))

# 失败重试 + 超时取消 + 进度监控
def on_progress(ctx):
    print(f"阶段: {ctx.stage}, 尝试: {ctx.attempt + 1}/{ctx.max_attempts}")

task = (yunhu.Send.To("user", "123")
        .Retry(3)              # 最多重试 3 次
        .Timeout(10)           # 每次超时 10 秒
        .OnProgress(on_progress)
        .OnError(lambda ctx: notify_admin(ctx.error))
        .Text("重要通知"))

规则方法返回 self，必须放在发送方法（Text/Image 等）之前调用。SendContext 包含 stage（pending/sending/retrying/success/failed/timeout）、attempt、elapsed、error、result 等字段，便于监控。

批量构建模式（Build）

一条链路中构建多个发送方法，最后统一执行。适用于“一口气发多条消息”的场景：

yunhu = adapter.get("yunhu")

# 构建多条消息，统一发送
results = await (yunhu.Send.To("user", "123")
                .Build()                     # 进入构建模式
                .Text("通知一")
                .Image("pic.jpg")
                .Text("通知二")
                .send_all())                 # 统一执行
# results = [Text结果, Image结果, Text结果]

.send_all() 默认并行执行（并发发送，效率高）。需要保证消息到达顺序时调用 .Sequential() 串行执行：

# 串行执行（保证顺序）+ 失败重试
await (yunhu.Send.To("group", "456")
       .Build()
       .Sequential()                # 按顺序依次发送
       .Retry(2)                     # 失败的条目各自重试
       .Text("第一条").Text("第二条")
       .send_all())

批量执行采用失败继续策略：某条失败不会中断其他条，失败的条目自动重试。批量也支持整批的 Hook（全部成功后触发）、OnError（有失败时触发）、OnProgress（进度回调）。

更详细的规则与批量构建说明请参考 SendDSL 详解。

事件监听

有三种事件监听方式：

1. 平台原生事件监听：

   from ErisPulse.Core import adapter, logger
   
   @adapter.on("event_type", raw=True, platform="{AdapterName}")
   async def handler(data):
       logger.info(f"收到{AdapterName}原生事件: {data}")
   

2. OneBot12标准事件监听：

   from ErisPulse.Core import adapter, logger
   
   # 监听OneBot12标准事件
   @adapter.on("event_type")
   async def handler(data):
       logger.info(f"收到标准事件: {data}")
   
   # 监听特定平台的标准事件
   @adapter.on("event_type", platform="{AdapterName}")
   async def handler(data):
       logger.info(f"收到{AdapterName}标准事件: {data}")
   

3. Event模块监听： Event的事件基于 adapter.on() 函数，因此Event提供的事件格式是一个OneBot12标准事件

   from ErisPulse.Core.Event import message, notice, request, command
   
   message.on_message()(message_handler)
   notice.on_notice()(notice_handler)
   request.on_request()(request_handler)
   command("hello", help="发送问候消息", usage="hello")(command_handler)
   
   async def message_handler(event):
       logger.info(f"收到消息: {event}")
   async def notice_handler(event):
       logger.info(f"收到通知: {event}")
   async def request_handler(event):
       logger.info(f"收到请求: {event}")
   async def command_handler(event):
       logger.info(f"收到命令: {event}")
   

其中，最推荐的是使用 Event 模块进行事件处理，因为 Event 模块提供了丰富的事件类型，以及丰富的事件处理方法。

标准格式

为方便参考，这里给出了简单的事件格式，如果需要详细信息，请参考上方的链接。

注意： 以下格式为基础 OneBot12 标准格式，各适配器可能在此基础上有扩展字段。具体请参考各适配器的特定功能说明。

标准事件格式

所有适配器必须实现的事件转换格式：

{
  "id": "event_123",
  "time": 1752241220,
  "type": "message",
  "detail_type": "group",
  "platform": "example_platform",
  "self": {"platform": "example_platform", "user_id": "bot_123"},
  "message_id": "msg_abc",
  "message": [
    {"type": "text", "data": {"text": "你好"}}
  ],
  "alt_message": "你好",
  "user_id": "user_456",
  "user_nickname": "ExampleUser",
  "group_id": "group_789"
}

标准响应格式

消息发送成功

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "message_id": "1234",
    "time": 1632847927.599013
  },
  "message_id": "1234",
  "message": "",
  "echo": "1234",
  "{platform}_raw": {...}
}

消息发送失败

{
  "status": "failed",
  "retcode": 10003,
  "data": null,
  "message_id": "",
  "message": "缺少必要参数",
  "echo": "1234",
  "{platform}_raw": {...}
}

参考链接

ErisPulse 项目：

• 主库
• Yunhu 适配器库
• Telegram 适配器库
• OneBot 适配器库

相关官方文档：

• OneBot V11 协议文档
• Telegram Bot API 官方文档
• 云湖官方文档

参与贡献

我们欢迎更多开发者参与编写和维护适配器文档！请按照以下步骤提交贡献：

1. Fork ErisPuls 仓库。
2. 在 docs/platform-features/ 目录下创建一个 Markdown 文件，并命名格式为 <平台名称>.md。
3. 在本 README.md 文件中添加对您贡献的适配器的链接以及相关官方文档。
4. 提交 Pull Request。

感谢您的支持！