fraq-plugin-onebot-server

将 Fraq 当前连接的 Milky 协议端转换为 OneBot 11 HTTP、WebSocket 和 HTTP POST 服务。

安装

pnpm add fraq-plugin-onebot-server

需要 Node.js 22+，@fraqjs/fraq 由宿主项目提供。

使用

在现有 Fraq Context 启动前安装插件：

import OneBotServerPlugin from 'fraq-plugin-onebot-server';

ctx.install(OneBotServerPlugin, {
  host: '0.0.0.0',
  port: 5700,
  accessToken: process.env.ONEBOT_ACCESS_TOKEN,
  eventMessageFormat: 'array',
  heartbeatIntervalMs: 15_000,
});

默认端点：

• HTTP API：GET/POST /:action
• WebSocket API：/api
• WebSocket Event：/event
• Universal WebSocket：/

只使用反向 WebSocket：

ctx.install(OneBotServerPlugin, {
  http: false,
  forwardWebSocket: false,
  reverseWebSocket: {
    url: 'ws://127.0.0.1:2536/OneBotv11',
    useUniversalClient: true,
    reconnectIntervalMs: 3_000,
  },
});

能力

• 全部 38 个 OneBot 11 标准 action 和 .handle_quick_operation
• LLOneBot/go-cqhttp 扩展，dispatcher 共注册 123 个 action
• 正向/反向 WebSocket、HTTP API、HTTP POST 签名和快速操作
• CQ 码、消息段、合并转发、历史消息和已读标记
• 表情回应、戳一戳、群精华、群公告和请求通知
• 群文件、私聊文件、媒体缓存和 ffmpeg 语音转换
• 持久化 OneBot message_id 映射

Milky 没有等价能力的 action 会返回明确失败，不会伪造成功。fetch_emoji_like 只能查询插件启动后观察到的表情事件；set_group_file_forever 需要 Milky 1.3。

完整 action 状态和实机结果见 LIVE_TEST.md。

常用配置

| 配置 | 默认值 | 说明 | | --- | --- | --- | | host | 127.0.0.1 | HTTP/WebSocket 监听地址 | | port | 5700 | HTTP/WebSocket 监听端口 | | accessToken | 无 | OneBot 访问令牌 | | http | true | 启用 HTTP API | | forwardWebSocket | true | 启用正向 WebSocket | | reverseWebSocket | 无 | 反向 WebSocket 配置 | | eventMessageFormat | array | array 或 string | | heartbeatIntervalMs | false | 心跳间隔，单位毫秒 | | storageDirectory | .fraq/onebot-server | 消息映射和媒体缓存目录 | | credentialTimeoutMs | 3000 | Cookie/CSRF 预热请求超时 |

开发

pnpm install
pnpm test
pnpm typecheck
pnpm check
pnpm build

许可证

MIT