ErisPulse ErisPulse
在交互式文档中心打开 →
本页章节
本文为静态镜像,内容以交互版为准 在交互式文档中心打开 →

Sandbox 平台特性文档

SandboxAdapter 是 ErisPulse 内置的沙盒适配器,用于本地开发与模块调试——无需真实平台即可模拟消息收发。


文档信息

  • 对应模块版本: 4.2.3
  • 维护者: ErisPulse
  • 最后更新: 2026-11-10

基本信息

  • 平台简介:本地沙盒环境,提供虚拟用户/群组、Web 调试面板与消息持久化
  • 适配器名称:SandboxAdapter
  • 平台标识:sandbox
  • 单账户设计(本地调试场景)
  • 框架要求:软依赖 ErisPulse>=2.7.1(运行时检测提示,不强制)

v5 范式更新(4.1.0)

  • Api DSL 最小集:get_self_info / get_status / get_version / get_supported_actions
  • spawn_background 任务归属:心跳任务改用 runtime.spawn_background
  • 框架软依赖:运行时检测 ErisPulse>=2.7.1 并提示
  • 导入路径更新至 Core.Bases(BaseConfig)

标准化对齐(4.2.3)

响应结构与错误码遵循 API 响应规范。

HTML 发送方法

  • .Html(html: str):发送 HTML 消息(经 html 通道渲染到 Web 面板)
  • .HTML(html: str):.Html() 的别名(与标准 Send 方法命名保持一致)

元动作(已标准)

标准元动作返回标准响应:

动作 data 内容
get_self_info user_id(配置的 self_id)/ user_name(sandbox)
get_status good(运行状态)/ bots(账户列表)
get_version impl(ErisPulse-SandboxAdapter)/ version / onebot_version
get_supported_actions 支持的动作名列表
from ErisPulse import sdk
sandbox = sdk.adapter.get("sandbox")

result = await sandbox.Api.get_self_info()   # 沙盒机器人身份
result = await sandbox.Api.get_status()
result = await sandbox.Api.get_version()
result = await sandbox.Api.get_supported_actions()

请求事件处理(Request stub)

沙盒会合成 type="request" 事件(好友/群申请,request_id 透传自模拟事件),模块可用标准方式审批(完整规范见 请求操作规范):

from ErisPulse.Core.Event import request

@request.on_friend_request()
async def handle_friend_request(event):
    await event.approve()   # 或 event.reject()

适配器侧 Request DSL 为模拟桩:accept() / reject() 校验 request_id(缺失时返回标准错误 retcode=34001,属于请求操作族错误码),校验通过后模拟审批成功返回标准成功响应,便于下游联调 approve() / reject() 流程。

错误码规范

retcode 含义 说明
0 成功 —
10002 不支持 平台无对应能力
10003 参数错误 缺少或无效参数
10006 无效消息段数据 MergeForward 节点无有效文本内容
34001 请求不存在 Request.accept()/reject() 缺少 request_id(请求操作族)

配置说明

[Sandbox]
self_id = "sandbox_bot"  # 沙盒机器人ID
enable = true            # 是否启用

使用说明

  • 沙盒提供虚拟用户与群组,模块可像真实平台一样收发消息
  • Web 调试面板可手动发送消息触发模块处理逻辑
  • 消息数据持久化存储(sdk.storage),重启后可恢复

支持的消息发送类型

所有发送方法均通过链式语法实现,例如:

from ErisPulse import sdk
sandbox = sdk.adapter.get("sandbox")

await sandbox.Send.To("private", "user1").Text("Hello")
await sandbox.Send.To("group", "group1").Markdown("**加粗**")

支持的发送类型包括:

方法 说明
.Text(text) 发送文本消息
.Image(file, summary=None) 发送图片
.Face(face_id) 发送表情
.Record(file, magic=False) 发送语音
.Voice(file) 发送语音(audio 通道)
.Video(file) 发送视频
.File(file, filename=None) 发送文件
.Html(html) / .HTML(html) 发送 HTML 消息(后者为别名)
.Markdown(markdown) 发送 Markdown 消息
.Json(json_data) 发送 JSON 卡片消息
.Xml(xml_data) 发送 XML 卡片消息
.Music(platform, id, title=None) 发送音乐消息
.Share(url, title, content=None, image=None) 发送链接分享
.Location(lat, lon, title=None, content=None) 发送位置消息
.Dice() 发送骰子
.Rps() 发送猜拳
.Poke(user_id, type="poke") 戳一戳
.Recall(message_id) 模拟撤回消息
.MergeForward(nodes, title="合并聊天记录") 发送合并转发消息(渲染为 <details> 折叠 HTML 卡片,html 通道发出),用于验证模块的合并转发逻辑
.Raw_ob12(message) 发送 OneBot12 原始消息段(纯 node 列表自动路由合并转发,混合列表 node 段降级为纯文本)

At / AtAll / Reply 修饰器由框架 SendDSL 基类提供。