Add room-scoped Matrix plugins and bilingual configuration commands

This commit is contained in:
Matrix Bot Project committed 2026-11-20 23:29:33 +08:00
1 parent 061bfbd12a
commit f4f30c3b5c
75 files changed
+2559 -1975

No files matched your search

+142 -131
View File
@@ -1,144 +1,155 @@
# daily-bot-nest
# Matrix 插件机器人
多房间 Matrix 机器人平台(NestJS 重构版)。每个房间机器人是一个**自包含的功能模块**,
可**共享账号**或使用**独立 Matrix 账号**;新增机器人只需加一个目录,核心代码不动。
[English](README.en.md)
## 架构
基于 NestJS / TypeScript 的多账号、多房间插件平台。核心统一处理 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(命令 + 日报定时)
内置插件:
- **签到 `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:
```sh
docker compose up -d --build
```
### 设计要点
- **账号可共享/独立**: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。
本地直接使用 Node/Nest 启动时,需要先安装依赖、生成 Prisma 客户端、初始化专用数据库并构建,同时将所需变量导出到进程环境。`.env` 由 Docker Compose 读取;直接启动应用不会自动把该文件全部导入环境。
## 快速开始(本地)
`DRY_RUN=true` 只抑制 Matrix 传输,仍会初始化数据库、运行旧数据迁移并注册定时任务。验证代码请使用下面的隔离测试,不要把 dry-run 当作完全只读检查。
```bash
cp .env.example .env # 配置 DATABASE_URL / DRY_RUN / 各账号密码
cp config/bots.example.yaml config/bots.yaml # 复制配置模板,填写真实房间 ID 与账号
npm install
持久化内容包括:
- `./data`:应用数据库、插件数据和启停状态。
- `matrix-crypto` 卷:Matrix 登录会话、设备凭据及加密状态。
- `./config`:只读挂载的运行配置。
- `./plugins`:只读挂载的外部插件目录。
升级前应一致备份应用数据及会话加密数据。每套账号及数据库部署只运行一个活动进程;每个房间的命令、事件、定时任务和插件启停在进程内串行协调。数据库额外保证每日签到唯一,但暂不支持多个副本共同执行同一套定时任务及确认操作。
## 测试与扩展
```sh
npm ci
npm run prisma:generate
npm run prisma:push # 初始化数据库表
npm test # 跑单元测试
npm run test:integration # 跑集成测试(使用临时 SQLite,自动清理)
DRY_RUN=true npm run start # 不连 Matrix 的装配验证(打印路由表)
npm run typecheck
npm run build
npm run test:all
```
> **注意**:`config/bots.yaml` 包含真实凭据,已加入 `.gitignore` 不会被提交。
> 首次克隆后必须先从 `bots.example.yaml` 复制并填写,否则启动时会报错提示。
测试使用模拟 Matrix、被拦截的网络接口及独立临时 SQLite 数据库,不读取运行配置。测试中的 Prisma CLI 子进程固定使用 `RUST_LOG=info`,绕过 Prisma 5.22 在 `warn` 日志级别下解析新建数据库错误的问题。初始化失败时清理步骤也不会继续访问未创建的数据库对象。
真实运行:把 `.env` 里 `DRY_RUN` 设为 false,并填好 `config/bots.yaml` 的房间与各账号密码。
新插件无需修改应用模块、消息分发或会话管理代码。放入已配置目录并重启发现后,就能通过插件命令启用。已安装插件的启停无需重启;插件代码热替换和不可信代码沙箱暂未提供。
## Docker 部署
- [升级与旧数据迁移](docs/UPGRADE.md)
- [插件 API 与开发说明](docs/PLUGINS.md)
- [可运行的外部插件示例](examples/greeting.plugin.js)
```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: [...] }`。
目前内置签到和成员管理,RSS 订阅可在此接口上独立扩展,尚未内置 RSS 拉取和解析功能。