Files

11 KiB
Raw Permalink Blame History

Matrix 插件机器人

English

基于 NestJS / TypeScript 的多账号、多房间插件平台。核心统一处理 Matrix 登录、加密、消息分发、权限、中英文命令、定时任务和存储。已安装插件可以在群内启停,不需要重启机器人。

内置插件:

  • 签到 checkin:按业务日期签到、查询统计、可选的长期未签到成员清理。
  • 成员管理 room-manager:独立业务身份、可选的 Matrix 权限映射及跨群成员同步。

管理与使用

所有命令支持 !、! 和 / 前缀。部分 Matrix 客户端会拦截斜杠命令,遇到这种情况使用 !。英文命令不区分大小写,中英文别名执行同一个处理函数。默认回复中文,可由管理员用 !语言 英文 切换;配置及语言设置按房间隔离。

英文半角 ! 和中文全角 ! 可以互换,与命令使用中文还是英文无关。每行四种写法效果相同,任选一条发送即可。

操作 半角 + 中文 全角 + 中文 半角 + 英文 全角 + 英文
签到 !签到 !签到 !checkin !checkin
查自己的签到记录 !查询 !查询 !list !list
查看帮助 !帮助 !帮助 !help !help

单独发送 签到 或 帮助 也可以。查询请带前缀。

管理员指房间 admins 名单中的用户,或原生 Matrix 权限分达到 adminPowerLevel 的用户(默认 100)。读取权限失败时拒绝管理操作。业务身份不会赋予 Matrix 管理权限。

平台命令

中文 English 权限与效果
!帮助 或 帮助 !help 显示当前已启用功能中有权使用的命令
!在线 !ping 回复 pong
!复述 <文本> !echo <text> 复述文本
!插件 列表 / !插件 状态 !plugin list / !plugin status 查看插件状态;错误详情仅管理员可见
!插件 启用 <名称> !plugin enable <name> 管理员;启用当前房间的插件
!插件 停用 <名称> / !插件 禁用 <名称> !plugin disable <name> 管理员;停止插件并保留数据
!语言 中文 / !语言 英文 !language zh-CN / !language en 管理员;保存房间回复语言
!操作记录 !audit 管理员;查看最近 10 条操作,房间最多保留 200 条

插件名称可用 签到 / checkin、成员管理 / 权限同步 / room-manager。即使所有业务插件均停用,平台管理命令仍然可用。

管理员可用 /config(!配置)查看当前房间 ID、语言、时区和报表设置。!配置 语言 英文 立即生效;!配置 报表 关 在签到插件下次启动时生效。

如果配置给一个无域名的房间 ID 误加了 :域名,可在实际房间发送 !配置 查看提示,再发 !配置 绑定。只有该房间配置的 admins 成员可执行绑定恢复,名单内账号在任何原生权限分下均可操作。机器人必须已加入该房间,没有加入旧 ID 对应的房间,且候选房间必须唯一。绑定保存到数据库,保留原配置和数据范围,服务下次启动时使用正确的 ID。此命令需要机器人能够读到消息;缺失的历史解密密钥需要单独处理。

签到命令

中文 English 权限与效果
签到 或 !签到 !checkin 普通成员;当日签到
!查询 !list 普通成员;查询自己的签到摘要
!查询 <用户ID> / !查询 全部 !list <userId> / !list all 查询其他人或全部记录需要管理员权限
!查询 [用户ID] --原始 !list [userId] --raw 管理员;返回 JSON 摘要,也可指定全部 / all
!日报 [YYYY-MM-DD] !report daily [YYYY-MM-DD] 管理员;只读查询,不重置、不踢人
!月报 [YYYY-MM] !report monthly [YYYY-MM] 管理员;只读查询,不清零
!清理 预览 !cleanup preview 管理员;预览长期未签到候选人
!清理 确认 <确认码> !cleanup confirm <token> 管理员;重新校验后执行预览过的名单

签到按“账号、房间、用户、业务日期”唯一记录。业务日期以配置的 timeZone 为准,默认北京时间;午夜即可开始新一天签到,不依赖日报执行。重复发送、切换中英文或重复查询报表都不会增加次数。

等级按累计已知签到次数计算:青铜 1–7、白银 8–14、黄金 15–29、铂金 30–44、钻石 45 次及以上。它只用于展示,不决定群权限。旧数据缺少完整历史时不会虚构累计次数,详见升级说明。

自动日报在配置时区的每天 03:00 统计前一天,月报在每月 1 日 00:05 统计上月。插件每分钟检查一次到期任务,并保存发送进度。停机后补发最新一期及补发范围说明,不连续刷出所有漏发报表;历史日期仍可查询。首次启用只建立进度,不补发此前报表。

报表不删除签到记录。日报的成员名单依据当前群成员,不是历史成员快照。发送消息与保存进度并非原子操作,若进程在两者之间退出,恢复后可能重复发送通知,但不会重复记签到或清零统计。

成员管理命令

以下命令均要求管理员权限。

中文 English 效果
!成员管理 状态 !access status 查看模式与各项自动操作开关
!身份 设置 <用户ID> 核心/普通/受限 !role set <userId> core/member/restricted 预览业务身份变更;角色参数只填写其中一个值
!成员管理 预览 [用户ID] / !成员管理 核对 [用户ID] !access preview [userId] / !access reconcile [userId] 预览状态差异,不执行成员操作
!成员管理 确认 <确认码> !access confirm <token> 重新校验后执行预览中的操作

默认采用独立业务身份,不通过提升原生权限来分配工作群:

身份 目标成员状态
核心 / core 邀请进入工作群 1、2,从失联群移出
普通 / member 从工作群 1 移出,邀请进入工作群 2,从失联群移出
受限 / restricted 从工作群 1、2 移出,邀请进入失联群

邀请仍需成员接受。机器人需要在目标群中具备相应权限。机器人自身不会被清理或同步;原生管理员不会被成员同步移除。

确认码只对发起预览的管理员、当前房间和当前插件有效,五分钟后过期且只能使用一次。新的同类预览替换旧预览,重新启用插件会使旧确认码失效。执行前会检查成员状态、权限和预览是否仍适用,不会把新出现的操作加入原预览名单。

自动操作开关

所有成员变更自动化默认关闭,各开关互相独立。

配置 作用
checkin.cleanupEnabled 允许通过预览和确认进行未签到清理
checkin.autoCleanup 额外允许每天 03:00 后自动清理;必须同时开启 cleanupEnabled
room-manager.syncOnJoin 加入管理群时按规则同步
room-manager.syncOnLeave 离开管理群时移出工作群并邀请进入失联群
room-manager.syncPowerChanges 按原生权限变化同步;仅 matrix 模式可用
room-manager.autoReconcile 启用时及每 15 分钟按当前状态重新核对

自动清理不会在签到插件的启用钩子中执行;如果明确开启了自动清理且任务到期,后续定时检查可能执行它。豁免名单、管理员、机器人自身、当天已签到和从未有过已知签到记录的成员不会成为清理对象。权限读取失败会跳过并记录。

成员管理的自动核对可以补偿已观察到成员的漏处理事件;与离群联动共同开启时,也能处理停机期间这些成员的离群。没有被当前版本观察过的历史成员无法凭空恢复。关闭签到清理不会关闭成员管理的离群或权限联动。

可选 mode: matrix 使用原生权限映射:分数达到 A 为核心,B 至 A 之间为普通,达到或低于 C 为受限;C 与 B 之间只从失联群移出。必须满足 levelA > levelB > levelC。改变原生权限仍会影响该用户在控制群的管理能力;只想改变工作群准入时使用默认 business 模式。

旧 !reset、!test ...、!level ... 仅回复停用说明,不再重置数据、清理成员或手动修改签到等级。

部署配置

复制 .env.example 为 .env,复制 config/bots.example.yaml 为 config/bots.yaml,填写部署使用的账号及房间信息。机器人应事先加入管理群和所需目标群。配置支持多个账号、多个房间;每个插件实例的数据按账号和房间隔离。

运行时保存的插件启停状态和回复语言优先于配置中的初始默认值。插件规则、管理员名单、房间及时间设置仍由服务器配置管理,修改后重启生效。聊天命令不会下载安装代码,也不会修改服务器文件。

以下命令会启动服务,DRY_RUN=false 时连接真实 Matrix:

docker compose up -d --build

本地直接使用 Node/Nest 启动时,需要先安装依赖、生成 Prisma 客户端、初始化专用数据库并构建,同时将所需变量导出到进程环境。.env 由 Docker Compose 读取;直接启动应用不会自动把该文件全部导入环境。

DRY_RUN=true 只抑制 Matrix 传输,仍会初始化数据库、运行旧数据迁移并注册定时任务。验证代码请使用下面的隔离测试,不要把 dry-run 当作完全只读检查。

持久化内容包括:

  • ./data:应用数据库、插件数据和启停状态。
  • matrix-crypto 卷:Matrix 登录会话、设备凭据及加密状态。
  • ./config:只读挂载的运行配置。
  • ./plugins:只读挂载的外部插件目录。

升级前应一致备份应用数据及会话加密数据。每套账号及数据库部署只运行一个活动进程;每个房间的命令、事件、定时任务和插件启停在进程内串行协调。数据库额外保证每日签到唯一,但暂不支持多个副本共同执行同一套定时任务及确认操作。

测试与扩展

npm ci
npm run prisma:generate
npm run typecheck
npm run build
npm run test:all

测试使用模拟 Matrix、被拦截的网络接口及独立临时 SQLite 数据库,不读取运行配置。测试中的 Prisma CLI 子进程固定使用 RUST_LOG=info,绕过 Prisma 5.22 在 warn 日志级别下解析新建数据库错误的问题。初始化失败时清理步骤也不会继续访问未创建的数据库对象。

新插件无需修改应用模块、消息分发或会话管理代码。放入已配置目录并重启发现后,就能通过插件命令启用。已安装插件的启停无需重启;插件代码热替换和不可信代码沙箱暂未提供。

目前内置签到和成员管理,RSS 订阅可在此接口上独立扩展,尚未内置 RSS 拉取和解析功能。