fraq-plugin-maa

通过 Fraq 聊天命令和类型化 Service API 使用 MAA 远程控制协议。插件支持预登记多台设备、SQLite 持久化、运行时切换当前设备、危险操作确认，以及将任务结果和截图发送到固定 QQ 群。

运行要求

• Node.js >=22.13
• @fraqjs/fraq ^0.14.0
• @fraqjs/plugin-hono ^0.2.1
• @fraqjs/plugin-kysely ^0.3.0
• 一个可用的 Milky 协议端

本插件实现的是 MAA 的两个 HTTP POST 端点，不会直接连接 MAA，也不使用 WebSocket。公网部署必须通过 HTTPS 反向代理暴露 Hono 服务。

配置

在 fraq.yml 中同时安装 Hono、Kysely 和本插件。Fraq CLI 中的 maa 对应 npm 包 fraq-plugin-maa。

configVersion: 1
fraqVersion: 0.14.0

milky:
  url: http://127.0.0.1:30001/

plugins:
  fraqjs/hono:
    host: 127.0.0.1
    port: 4649

  fraqjs/kysely:
    sqliteUrl: file:./fraq.db

  maa:
    controllerQq: 123456789
    notificationGroup: 987654321
    defaultDevice: desktop
    devices:
      - alias: desktop
        deviceId: 0123456789abcdef0123456789abcdef
        userToken: ${{ text:secrets/maa-desktop-token.txt }}
      - alias: server
        deviceId: fedcba9876543210fedcba9876543210
        userToken: ${{ text:secrets/maa-server-token.txt }}
    routePrefix: /maa
    reportBodyLimitBytes: 67108864
    confirmationTtlMs: 300000
    taskRetentionDays: 30
    maxOutstandingTasks: 100

activation:
  default: mention
  overrides:
    - match:
        plugin: maa
      rule: { type: prefix, prefix: / }

userToken 每台设备必须不同且至少 16 字符。推荐使用 32 字节随机值并通过 ${{ text:... }} 引用密钥文件，避免直接提交到配置仓库。

MAA 设置

为每台设备填写以下远程控制设置：

• 用户标识符：该设备配置中的 userToken
• 设备标识符：必须与配置中的 deviceId 完全一致
• 获取任务端点：https://你的域名/maa/getTask
• 汇报任务端点：https://你的域名/maa/reportStatus

反向代理的请求体限制不能小于 reportBodyLimitBytes。MAA 截图经过 Base64 编码后可能达到数十 MB。MAA 重新生成设备标识符后，需要同步修改插件配置并重启 Fraq。

命令

所有命令只接受 controllerQq 发出的好友或群消息。即时响应回到原会话，MAA 回报的最终结果统一发送到 notificationGroup。

| 命令 | 说明 | | --- | --- | | maa device list | 列出设备和在线状态 | | maa device current | 查看当前设备 | | maa device use <别名> | 切换并持久化当前设备 | | maa start [模式] | 执行一键长草或子任务 | | maa screenshot [now/queued] | 立即截图或排队截图 | | maa stop | 请求停止当前任务 | | maa status | 通过心跳查询运行状态 | | maa gacha <once/ten> | 创建牛牛抽卡确认 | | maa set connection <地址> | 创建连接地址修改确认 | | maa set stage <关卡> | 创建首选关卡修改确认 | | maa confirm <任务前缀> <确认码> | 确认危险任务 | | maa tasks | 查看当前设备最近 20 个任务 | | maa cancel <任务前缀> | 取消待确认或尚未下发的任务 |

maa start 的模式包括 all、base、wakeup、combat、recruiting、mall、mission、roguelike 和 reclamation。

Service API

插件导出 MaaRemoteService，其他 fraq 插件可以声明依赖并复用同一设备配置和持久化队列：

import { definePlugin } from '@fraqjs/fraq';
import { MaaRemoteService } from 'fraq-plugin-maa';

export default definePlugin({
  name: 'maa-scheduler',
  inject: { maa: MaaRemoteService },
  apply(ctx) {
    ctx.interval(60_000, async () => {
      await ctx.maa.enqueue({ type: 'HeartBeat' });
    });
  },
});

公开方法包括：

• enqueue(input, options?)：下发任务；options.device 可以指定非当前设备。
• listDevices()、getDefaultDevice()、setDefaultDevice(reference)：查询或切换设备。
• listTasks(options?)、cancelTask(reference, options?)：查询或取消任务。
• prepareDangerousTask(input)、confirmTask(reference, code)：使用一次性确认流程。

设置修改和抽卡属于危险任务。可信插件如果不走确认流程，调用 enqueue 时必须显式传入 { allowDangerous: true }。

投递语义与安全

• 未回报的任务会在每次轮询中重复返回相同 ID，由 MAA 负责去重，语义为至少一次投递。
• MAA 在执行过程中重启可能丢失自己的去重记录，远程控制协议无法完全避免任务再次执行。
• 已经下发到 MAA 的任务不能可靠撤回，maa cancel 只允许取消待确认或尚未下发的任务。
• 相同回报可以安全重试；插件只更新和通知一次。通知失败会持久化并指数退避重试最多 24 小时。
• 无效的 deviceId + userToken 一律返回 401，不会自动登记未知设备。
• Hono 默认只监听 127.0.0.1。不要在公网使用明文 HTTP，也不要在聊天、日志或仓库中公开设备密钥。

协议基线为 MAA dev-v2 的远程控制协议和 Fraq 0.14.0。

测试

Mock 测试使用 @fraqjs/plugin-mock 注入消息并拦截 Milky API，不需要运行真实协议端：

pnpm test

冒烟测试会连接真实 Milky，并在本机启动 MAA HTTP 服务。先配置环境变量，再运行：

$env:MILKY_URL = 'http://127.0.0.1:3000'
$env:MILKY_ACCESS_TOKEN = 'your-milky-token'
$env:MAA_CONTROLLER_QQ = '10001'
$env:MAA_NOTIFICATION_GROUP = '20001'
$env:MAA_DEVICE_ID = 'your-maa-device-id'
$env:MAA_USER_TOKEN = 'your-maa-user-token'
pnpm smoke

可选变量包括 MAA_DEVICE_ALIAS、MAA_HTTP_HOST、MAA_HTTP_PORT 和 MAA_SQLITE_URL。启动后用控制者 QQ 发送 maa status，并让对应 MAA 实例访问输出的 /maa 地址；按 Ctrl+C 停止。

开发

pnpm install
pnpm check
pnpm test
pnpm lint
pnpm build