Files
matrix-bot/README.md
T

156 lines
11 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.
# Matrix 插件机器人
[English](README.en.md)
基于 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:
```sh
docker compose up -d --build
```
本地直接使用 Node/Nest 启动时,需要先安装依赖、生成 Prisma 客户端、初始化专用数据库并构建,同时将所需变量导出到进程环境。`.env` 由 Docker Compose 读取;直接启动应用不会自动把该文件全部导入环境。
`DRY_RUN=true` 只抑制 Matrix 传输,仍会初始化数据库、运行旧数据迁移并注册定时任务。验证代码请使用下面的隔离测试,不要把 dry-run 当作完全只读检查。
持久化内容包括:
- `./data`:应用数据库、插件数据和启停状态。
- `matrix-crypto` 卷:Matrix 登录会话、设备凭据及加密状态。
- `./config`:只读挂载的运行配置。
- `./plugins`:只读挂载的外部插件目录。
升级前应一致备份应用数据及会话加密数据。每套账号及数据库部署只运行一个活动进程;每个房间的命令、事件、定时任务和插件启停在进程内串行协调。数据库额外保证每日签到唯一,但暂不支持多个副本共同执行同一套定时任务及确认操作。
## 测试与扩展
```sh
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` 日志级别下解析新建数据库错误的问题。初始化失败时清理步骤也不会继续访问未创建的数据库对象。
新插件无需修改应用模块、消息分发或会话管理代码。放入已配置目录并重启发现后,就能通过插件命令启用。已安装插件的启停无需重启;插件代码热替换和不可信代码沙箱暂未提供。
- [升级与旧数据迁移](docs/UPGRADE.md)
- [插件 API 与开发说明](docs/PLUGINS.md)
- [可运行的外部插件示例](examples/greeting.plugin.js)
目前内置签到和成员管理,RSS 订阅可在此接口上独立扩展,尚未内置 RSS 拉取和解析功能。