Sandbox（模拟环境）

网页访问的模拟聊天环境：在浏览器里模拟群聊 / 私聊场景发送消息，消息走完整的插件处理链路，机器人回复实时显示在网页上。适合没有真实平台账号时调试插件、验证模板标签、测试多平台能力降级。

适配器类型："sandbox"　源码：src/adapter/sandbox/

启动后本框架起一个本地网页服务（默认 8800 端口），浏览器打开即可使用。纯内存模拟，零外部依赖，重启即清空历史。

说明

特点

• 零外部依赖，无需真实平台账号
• 网页界面模拟群聊/私聊，消息走完整插件处理链路
• 支持多用户身份切换（User1 / User2）
• 按会话粒度上报能力集，可测试内核能力降级

原理

• 接收：网页前端 POST 消息到本地 HTTP 服务，转为框架事件派发
• 发送：插件调用 send API 后，消息写入对应会话的消息流，前端轮询刷新
• 能力：群聊上报全消息段 + 群管理能力，私聊上报全消息段无群管理能力

前提

• 无特殊前提，启动后浏览器访问本地端口即可

安装

适配器安装

van adapter install sandbox

依赖库

无额外依赖（纯 Node.js 内置 HTTP）。

配置

{
  "botId": "Sandbox",
  "type": "sandbox",
  "port": 8800,
  "selfName": "沙盒机器人",
  "enable": true
}

配置项	必填	说明
port	可选	网页服务端口，默认 8800
selfName	可选	机器人在网页上显示的昵称，默认 Bot
selfId	可选	机器人在场景中的协议 ID，默认 botId

模拟用户的消息 userId 不能与 selfId 相同（会被内核 ignoreSelf 忽略）。

接收事件

• 群聊消息 → group_message（含群号 + 模拟成员 userId）
• 私聊消息 → private_message

事件照常走内核管道：分配 traceId、ID 字符串化、填充会话能力集、跑中间件再派发插件，与真实平台完全一致。

网页使用

启动后访问 http://127.0.0.1:8800，界面固定三个会话：

• 群聊 · 10001、群聊 · 10002：两个模拟群聊
• 私聊：与机器人的单聊

右上角可切换身份 User1 / User2，当前会话的所有消息都以该身份发出。

• 消息区：用户消息与机器人回复实时显示
• 输入框：Enter 发送、Shift+Enter 换行
• 首次测试建议先发 #设置主人号 User1 设置主人，再发指令查看回复

页面每 1 秒轮询一次服务端消息流。

API 调用

// 发群消息
await bot.callApi("send_group_msg", { group_id: "10001", message: "你好" })

// 发私聊
await bot.callApi("send_private_msg", { user_id: "10086", message: "你好" })

// 自动判断
await bot.callApi("send_msg", { group_id: "10001", message: "你好" })

message 支持字符串或消息段数组；图片 / 视频 / markdown / 按钮等段会渲染成对应占位文本显示在网页上。

会话能力

• 群聊：全消息段 + canMuteMember / canKickMember
• 私聊：全消息段，无 canMuteMember / canKickMember

常见问题

• 机器人不回复：检查插件逻辑（如 keyword 词库匹配、主人指令）。首次测试先发 #设置主人号 User1。
• 消息历史丢失：消息历史存内存，框架重启即清空，属正常行为。
• 页面不刷新：确认端口未被占用，浏览器访问的是配置的 port。

相关项目

无外部参考项目（内置模拟适配器）。