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.
145 lines
8.0 KiB
Markdown
145 lines
8.0 KiB
Markdown
# 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: [...] }`。
|