koishi-plugin-msg-router

这是一个用于 Koishi 的消息转发插件。它把你配置好的指令转发到外部 OneBot v11 WebSocket 后端，再把后端返回内容回传给用户。

主要用途

• 把某些 Koishi 指令交给外部后端程序处理
• 支持正向 WS 和反向 WS 两种模式
• 后端可通过 WebSocket 常驻连接接收请求
• 支持令牌鉴权，token 可留空
• 支持可选的 HMAC 签名
• 支持断线重连、心跳保活、超时控制、并发控制

控制台配置说明

总开关

• debug：是否输出调试信息

正向 WS 路由列表

这张表用于“插件主动连接后端”的场景。

• name：路由名称
• enabled：是否启用
• mode：固定为 client
• endpoint：OneBot v11 WebSocket 地址
• token：后端鉴权令牌，可不填
• secret：HMAC 签名密钥，可不填
• commands：触发这条路由的 Koishi 指令
• action：发送给后端的 action 名称
• timeout：单次请求等待时间，单位毫秒
• heartbeatInterval：发送 ping 的间隔，单位毫秒
• reconnectInterval：断线后的重连间隔，单位毫秒
• maxConcurrency：同时允许的请求数量

反向 WS 路由列表

这张表用于“插件监听，后端主动连进来”的场景。

• name：路由名称
• enabled：是否启用
• mode：固定为 server
• listenHost：监听主机
• listenPort：监听端口
• token：后端鉴权令牌，可不填
• secret：HMAC 签名密钥，可不填
• commands：触发这条路由的 Koishi 指令
• action：发送给后端的 action 名称
• timeout：单次请求等待时间，单位毫秒
• heartbeatInterval：发送 ping 的间隔，单位毫秒
• reconnectInterval：断线后的重连间隔，单位毫秒
• maxConcurrency：同时允许的请求数量

推荐配置示例

{
  "debug": false,
  "clientRoutes": [
    {
      "name": "AI 后端",
      "enabled": true,
      "mode": "client",
      "endpoint": "ws://127.0.0.1:8080",
      "token": "",
      "secret": "",
      "commands": ["ask", "translate", "summarize"],
      "action": "msg_router.forward_command",
      "timeout": 10000,
      "heartbeatInterval": 30000,
      "reconnectInterval": 5000,
      "maxConcurrency": 16
    }
  ],
  "serverRoutes": [
    {
      "name": "反向后端",
      "enabled": true,
      "mode": "server",
      "listenHost": "127.0.0.1",
      "listenPort": 8080,
      "token": "",
      "secret": "",
      "commands": ["reply", "summarize"],
      "action": "msg_router.forward_command",
      "timeout": 10000,
      "heartbeatInterval": 30000,
      "reconnectInterval": 5000,
      "maxConcurrency": 16
    }
  ]
}

模式说明

• client 模式：插件主动连接后端
• server 模式：插件自己监听，等待后端连接
• server 模式下，如果后端还没连上来，命令会等待到超时为止

协议约定

插件向后端发送带 action / echo 外壳的请求，其中 params 使用 OneBot v11 的标准消息事件结构。当前只把文本内容封装为 message 段：

{
  "action": "msg_router.forward_command",
  "params": {
    "time": 1710000000,
    "self_id": 123456789,
    "post_type": "message",
    "message_type": "group",
    "sub_type": "normal",
    "message_id": 10001,
    "user_id": 123456,
    "group_id": 654321,
    "message": [
      {
        "type": "text",
        "data": {
          "text": "hello"
        }
      }
    ],
    "raw_message": "hello",
    "font": 0,
    "sender": {
      "user_id": 123456,
      "nickname": "Alice"
    }
  },
  "auth": {
    "algorithm": "hmac-sha256",
    "signature": "hex-string",
    "timestamp": 1710000000000
  },
  "echo": "uuid"
}

后端响应示例：

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "text": "reply text"
  },
  "echo": "uuid"
}

如果 data.text、data.message 或 data.reply 存在，插件会直接把它返回给用户。data.message 支持 OneBot 风格的文本段数组。

兼容说明

• token 是可选项，不填时不会附加 Authorization 头
• secret 也是可选项，不填时不会生成 auth
• 如果后端没有返回可显示内容，插件会保持静默
• 请求超时只会记录警告，不会把命令直接抛成错误
• 同名指令不建议在多个路由里重复配置