11 KiB
Matrix 插件机器人
基于 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 拉取和解析功能。