Files
matrix-bot/README.md
T
eskima 0a3843630a feat: use native Matrix Power Level to control check-in immunity and cross-room syncing
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.
2026-06-08 02:49:08 +08:00

145 lines
8.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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()`,在 `AppModule` import 其 module。
## 快速开始(本地)
```bash
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 部署
```bash
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)变化以及人员离开事件**。
1. **权限联动**:管理员只需在客户端(如 Element)的签到房间设置里,点开用户头像修改权限等级,机器人就会自动将该用户跨群调配到不同的工作房或小黑屋中。
2. **踢出联动**:如果某个用户主动退出了签到房,或者因为长期不打卡被签到机器人踢出了签到房,该机器人也会立即将其视为“失去大本营身份”,自动将其从所有工作房踢出,并丢进失联房。
| 原生权限分 | 内部级别 | 默认自动执行的操作 |
|---|---|---|
| `≥ 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)
1. 新建 `src/bots/notify/notify.bot.ts`,`implements RoomBot`,类上加 `@RegisterBot()`。
2. 新建 `notify.module.ts`,`providers: [NotifyBot]`。
3. `AppModule` 的 imports 里加 `NotifyModule`。
4. `config/bots.yaml` 增加一条 `{ name: notify, account: main, rooms: [...] }`。