1. Added RoomManagerBot for cross-room permission and leave syncing based on native power levels. 3. Added invite() to MatrixSession and added onMemberLeave/onPowerLevel hooks to Dispatcher. 4. Updated README and example configs.
daily-bot-nest
多房间 Matrix 机器人平台(NestJS 重构版)。每个房间机器人是一个自包含的功能模块, 可共享账号或使用独立 Matrix 账号;新增机器人只需加一个目录,核心代码不动。
架构
src/
├─ config/ 加载 + 校验 bots.yaml(zod),支持 env(VAR) 引用
├─ core/
│ ├─ matrix/ SessionManager(账号去重) + MatrixSession(归一化事件 + 出站)
│ ├─ bot/ RoomBot 契约 / BotContext / BotRegistry(DiscoveryService 自动发现)
│ │ Dispatcher(按 account:roomId 路由) / BotPlatform(总装配)
│ ├─ command/ 命令解析(! 前缀,移植自 Rust 版)
│ ├─ scheduler/ cron 注册
│ └─ db/ Prisma + BotStore(按 bot 名隔离的 KV)
└─ bots/
└─ checkin/ 示例:签到 bot(命令 + 日报定时)
设计要点
- 账号可共享/独立:bot 在配置里声明
account。多个 bot 同 account ⇒ 只建一个 client(共享);不同 account ⇒ 独立身份。由SessionManager去重。 - 路由:消息归一化后带
{account, roomId},Dispatcher用account:roomId查BotRegistry找到对应 bot,调其钩子。 - 隔离:每个 bot 通过
BotContext.db拿到按自身名字 scope 的BotStore,数据互不串。 - 可测试:bot 只依赖
BotContext接口,单测 mock 即可,无需真连 Matrix。 - 可扩展:新增 bot = 新建
bots/xxx/,类上加@RegisterBot(),在AppModuleimport 其 module。
快速开始(本地)
cp .env.example .env # 配置 DATABASE_URL / DRY_RUN / 各账号密码
cp config/bots.example.yaml config/bots.yaml # 复制配置模板,填写真实房间 ID 与账号
npm install
npm run prisma:generate
npm run prisma:push # 初始化数据库表
npm test # 跑单元测试
npm run test:integration # 跑集成测试(使用临时 SQLite,自动清理)
DRY_RUN=true npm run start # 不连 Matrix 的装配验证(打印路由表)
注意:
config/bots.yaml包含真实凭据,已加入.gitignore不会被提交。 首次克隆后必须先从bots.example.yaml复制并填写,否则启动时会报错提示。
真实运行:把 .env 里 DRY_RUN 设为 false,并填好 config/bots.yaml 的房间与各账号密码。
Docker 部署
cp .env.example .env # 填好各账号密码与 DRY_RUN;DATABASE_URL 由 compose 覆盖
cp config/bots.example.yaml config/bots.yaml # 复制模板后填写真实房间 ID 与账号
# 编辑 config/bots.yaml,填入真实房间 ID 与 homeServer 等信息
docker compose up -d --build # 构建并后台启动
docker compose logs -f # 看日志
- 启动时
docker-entrypoint.sh会自动prisma db push建表(幂等)。 - SQLite 数据落在与
docker-compose.yml同级的./data/本地目录(bind mount 到/app/data),容器重建不丢数据。该目录已在.gitignore/.dockerignore中排除 (仅保留.gitkeep占位),不会被提交或打进镜像。 config/以只读方式挂载;改完配置docker compose restart即生效。DRY_RUN现由.env控制(不再被 compose 写死)。真实运行设DRY_RUN=false。- 切 Postgres:改
prisma/schema.prisma的 provider 为postgresql, 并把 compose 里DATABASE_URL指向 Postgres 连接串即可。
排错
容器反复重启 / 日志不断打印登录
根因通常是 Matrix 用户名或密码错误:登录返回 M_FORBIDDEN [403],进程退出,
被 compose restart: on-failure 拉起后再次失败,形成循环。处理:
- 核对
.env的账号密码、config/bots.yaml的userId/homeServer; - 程序已对凭据类错误延迟 30 秒再退出,以避免高频登录被 homeserver 限流/封禁;
- 本地仅想验证装配,可在
.env设DRY_RUN=true跳过真实登录。
控制方式
- 配置:
config/bots.yaml决定哪些 bot、用什么账号、管哪些房间。改后重启生效。 - 房间内命令:管理员直接在 Matrix 房间发
!命令。 - 无需前端;REST 管理 API 为将来预留(当前未实现)。
签到 bot 命令
| 命令 | 说明 |
|---|---|
!checkin 或 直接发「签到」 |
今日签到(全角「!签到」也可) |
!list <用户ID|all> [--raw] |
查询签到状态,--raw 输出 JSON |
!reset |
重置所有人当日签到状态 🔒 管理员 |
!test daily|monthly |
手动触发日报/月报(运维测试用)🔒 管理员 |
!echo <文本> / !ping / !help |
杂项 |
签到等级(青铜 / 白银 / 黄金 / 铂金 / 钻石)将根据用户的累计签到次数纯自动升级,仅作趣味展示。
🔒 管理员权限与免死特权:
reset/test等管理命令仅 房间内 power level ≥adminPowerLevel(默认 100) 或在config.admins白名单中的用户可调用。 同时,只要用户的原生权限分达到了管理员级别,就会在每天凌晨的清理逻辑中被自动“免死”(即使长期不签到也不会被踢)。 所有权限调整请直接在 Element 客户端的「房间设置 → 权限」里通过原生 UI 操作,无需手动输入命令。
定时任务
- 每日 03:00:生成签到日报(按今日未签到 / ≥7 / ≥14 / ≥30 天 / 从未签到分桶),
发到
mainRoom;若autoKick: true,踢出未签到 ≥kickDays天的用户 (尊重whitelist与超级管理),然后重置当日签到。 - 每月 1 日 00:05:生成月度签到排行,发到
mainRoom,重置月度计数。
checkin 配置项(config/bots.yaml 的 config)
| 字段 | 默认 | 说明 |
|---|---|---|
mainRoom |
第一个房间 | 日报/月报发送的房间 |
kickDays |
30 | 自动踢人的未签到天数阈值 |
autoKick |
false | 是否在日报后自动踢人 |
whitelist |
[] | 永不踢出的用户列表 |
adminPowerLevel |
100 | 房间内 power level ≥ 此值即视为管理员(100=管理员、50=版主) |
admins |
[] | 额外管理员白名单(power level 之外的补充,可留空) |
权限同步机器人 (Room Manager)
该机器人不靠命令驱动,而是监听 Matrix 原生的权限分(Power Level)变化以及人员离开事件。
- 权限联动:管理员只需在客户端(如 Element)的签到房间设置里,点开用户头像修改权限等级,机器人就会自动将该用户跨群调配到不同的工作房或小黑屋中。
- 踢出联动:如果某个用户主动退出了签到房,或者因为长期不打卡被签到机器人踢出了签到房,该机器人也会立即将其视为“失去大本营身份”,自动将其从所有工作房踢出,并丢进失联房。
| 原生权限分 | 内部级别 | 默认自动执行的操作 |
|---|---|---|
≥ levelA |
最高权限 (如版主 50) | 邀请进工作房1,邀请进工作房2 |
== levelB |
中等权限 (如默认 0) | 从工作房1踢出,邀请进工作房2 |
≤ levelC |
最低权限 (如受限 -1) | 从工作房1、2踢出,邀请进失联房 |
room-manager 配置项(config/bots.yaml 的 config)
| 字段 | 说明 |
|---|---|
workRoom1 |
高级工作群 ID(最高权限才能进) |
workRoom2 |
普通工作群 ID(中高权限能进) |
lostRoom |
失联小黑屋 ID(最低权限进入) |
levelA |
最高权限的分数阈值,默认为 50 |
levelB |
中等权限的分数,默认为 0 |
levelC |
最低权限的分数阈值,默认为 -1 |
注意:
room-manager机器人的rooms数组中,应当只填写“签到/管理房”的 ID。机器人只会在这个房间里当“保安”监听原生权限变化,然后往外执行踢/拉操作。
新增一个机器人(例:notify)
- 新建
src/bots/notify/notify.bot.ts,implements RoomBot,类上加@RegisterBot()。 - 新建
notify.module.ts,providers: [NotifyBot]。 AppModule的 imports 里加NotifyModule。config/bots.yaml增加一条{ name: notify, account: main, rooms: [...] }。