fraq-plugin-botweb

基于 fraq（@fraqjs/fraq）的 Web 聊天面板插件：在浏览器里以 Bot 身份查看好友/群会话、收发消息。仅适配 milky 协议（fraq 本身就是 Milky Bot 框架）。

• 页面与接口统一挂在 @fraqjs/plugin-webui-gateway 上：/webui/botweb/（SPA）+ /webui/botweb/api/*（REST + WS），鉴权由网关统一管理（单口令 + 签名 Cookie 会话，登录页为网关自带）
• HTTP 服务来自 @fraqjs/plugin-hono（所有插件共享同一个 Hono 应用/端口）
• 前端：React 19 + Vite 6 + Tailwind v4 + HeroUI v3，构建产物输出到 dist/webui 随包发布

安装与使用

pnpm add fraq-plugin-botweb @fraqjs/plugin-hono @fraqjs/plugin-webui-gateway

在入口中按顺序安装（hono → webui-gateway → botweb）：

import { Context } from '@fraqjs/fraq'
import HonoPlugin from '@fraqjs/plugin-hono'
import WebuiGatewayPlugin from '@fraqjs/plugin-webui-gateway'
import BotwebPlugin from 'fraq-plugin-botweb'

const ctx = Context.fromUrl('http://127.0.0.1:7003/', { accessToken: 'milky令牌' })
ctx.install(HonoPlugin, { port: 4649 })
ctx.install(WebuiGatewayPlugin, { accessToken: 'WebUI登录口令' })
ctx.install(BotwebPlugin)
await ctx.start()

访问 http://127.0.0.1:4649/webui/botweb/，用 webui-gateway 的口令登录。

使用 fraq CLI（fraq.yml）时等价配置：

milky:
  url: http://127.0.0.1:7003/
  accessToken: milky令牌
plugins:
  fraqjs/plugin-hono:
    port: 4649
  fraqjs/plugin-webui-gateway:
    accessToken: WebUI登录口令
  fraq-plugin-botweb: {}

注意：@fraqjs/plugin-webui-gateway 目前为 0.1.0（peer 声明 @fraqjs/fraq: ^0.14.0），本插件按 fraq 0.14.x 开发验证。

功能

• 好友/群会话列表、消息收发（文本/QQ 表情/图片/语音/视频/文件/@/引用/JSON 卡片/markdown 渲染）
• 历史消息分页（milky get_history_messages，好友/群统一，单页上限 30 条）
• 实时推送（WS）：新消息、撤回标记、戳一戳、群表情回应（±1 聚合）、会话资料增量
• 戳一戳、踢出群成员、群消息贴/取消表情回应（仅群聊）
• QQ 小黄脸本地图源（resources/faces，随构建拷入 dist/webui/faces）、Apple emoji 图片渲染
• 消息「原始事件」查看（milky get_message 原样返回）、文件下载（临时链接 302 跳转）

开发

pnpm install
cp .env.example .env   # 配置 milky 地址 URL / TOKEN、面板口令 WEBUI_TOKEN、端口 PORT
pnpm build             # tsdown（dist/*.mjs）+ vite（dist/webui），显式顺序
pnpm dev               # tsx test/smoke.ts，连接 .env 里的 milky 服务器起测试服务
pnpm typecheck         # 后端 + 前端 tsc --noEmit

前端热更调试：pnpm exec vite web（:5173，/webui 代理到 4649，含 WS）。

许可证

MIT