2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00
2026-06-04 15:45:20 +08:00

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。

快速开始(本地)

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
!level set <用户ID> <等级> 设置等级(等级支持中文「黄金」或英文 gold)🔒 管理员
!level raise <用户ID> 提升一级 🔒 管理员
!level super <用户ID> 赋予超级管理(免统计/免踢)🔒 管理员
!level clear <用户ID> 清除等级为青铜 🔒 管理员
!reset 重置所有人当日签到状态 🔒 管理员
!test daily|monthly 手动触发日报/月报(运维测试用)🔒 管理员
!echo <文本> / !ping / !help 杂项

等级:超级管理 / 青铜 / 白银 / 黄金 / 铂金 / 钻石(内部存英文 key,仅展示转中文)。

🔒 管理员命令权限:level / reset / test 仅 房间内 power level ≥ adminPowerLevel(默认 100) 或在 config.admins 白名单中的用户可调用,其他人发送会被拒绝。这是信任根 —— DB 里的「超级管理」 等级只表示免统计/免踢,不等于命令权限。power level 在 Element 的「房间设置 → 权限」里给成员调整 (100=管理员、50=版主);admins 留空即纯按 power level 判定,无需写死名单。

定时任务

  • 每日 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 之外的补充,可留空)

新增一个机器人(例: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: [...] }。
S
Description
No description provided
Readme
316 KiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 93.5%
JavaScript 5.6%
Dockerfile 0.7%
Shell 0.2%