TeleBot

基于 Bun 和 grammY 构建的插件式可扩展 Telegram Bot 框架。用简洁的 TypeScript 类编写插件，丢进 plugins/ 目录，热重载即可生效 —— 无需重启。

特性

• 插件架构 — 一切皆插件。内置命令（start、help、admin、插件管理器）与用户插件的构建方式完全相同。
• 热重载 — 通过 /reload 或插件管理器在运行时增删改插件。基于代际（generation）的优雅生命周期：旧代排空请求，新代无缝接管。
• 插件市场 — /plugin search、/plugin install、/plugin update — 从远程索引、直接 URL 或回复 .ts 文件安装插件。
• 依赖解析 — 插件声明依赖及 semver 版本范围（如 storage@>=1.0.0）。拓扑排序保证加载顺序，循环依赖检测防止死锁。
• 对话引擎 — 多步有状态对话，支持超时处理、取消操作和逐步流程控制。
• 配置界面 — 插件可声明配置结构，在 Telegram 内通过内联键盘让管理员直接修改设置。
• 定时任务 — 插件可注册 cron 定时任务，生命周期与 bot 代际绑定。
• 权限体系 — 三级权限（0=公开, 1=信任用户, 2=管理员），命令可设置最低权限要求。
• 频率限制 — 每用户请求限流，可配置时间窗口和最大请求数。
• 群组认证 — 白名单模式：仅允许已授权的群组使用 bot。
• 命令别名 — 为任意已注册命令创建快捷方式。
• 会话存储 — SQLite 持久化会话，支持 TTL 自动过期。
• 中间件链 — 错误边界 → 日志 → 限流 → 认证 → 回调处理 → 对话 → 配置输入 → 命令路由。
• 优雅关闭 — 退出前排空活跃请求、释放资源、刷写插件数据。
• 开箱即用 Docker — docker compose up -d 即可运行。

技术栈

组件	技术
运行时	Bun
Bot 框架	grammY
数据库	SQLite（Bun 内置）
数据迁移	Drizzle ORM
校验	Zod
日志	Pino
定时任务	自研 cron 解析器 + 定时调度

快速开始

环境要求

• Bun >= 1.0
• 从 @BotFather 获取的 Telegram bot token

安装步骤

git clone https://github.com/your-org/telebot.git
cd telebot

# 安装依赖
bun install

# 复制并编辑环境变量
cp .env.example .env
# 编辑 .env — 至少设置 BOT_TOKEN 和 ADMIN_IDS

# 开发模式启动（监听文件变更）
bun dev

环境变量

变量	必填	默认值	说明
BOT_TOKEN	是	—	从 @BotFather 获取的 Telegram bot token
ADMIN_IDS	是	—	逗号分隔的管理员用户 ID
LOG_LEVEL	否	info	日志级别：debug、info、warn、error
RATE_LIMIT_MAX	否	30	窗口内最大请求数
RATE_LIMIT_WINDOW	否	60	限流窗口（秒）
CHAT_MODE	否	all	聊天模式：all（全部）或 whitelist（白名单）
PLUGIN_INDEX_URL	否	—	插件市场 JSON 地址
PLUGIN_ALLOWED_ORIGINS	否	—	逗号分隔的允许插件来源域名
DB_PATH	否	assets/telebot.db	SQLite 数据库路径

Docker 部署

# 创建 .env，填写 BOT_TOKEN 和 ADMIN_IDS
cp .env.example .env

# 启动
docker compose up -d

# 查看日志
docker compose logs -f

assets/ 和 plugins/ 目录通过 volume 挂载 —— 插件和数据在容器重启后不会丢失。

插件系统

插件是继承 Plugin 基类的 TypeScript 类。将 .ts 文件放入 plugins/ 目录后重载即可。

import { Plugin } from "../src/plugin/base.ts";
import type { CommandHandler } from "../src/types/plugin.ts";

export default class HelloPlugin extends Plugin {
  name = "hello";
  version = "1.0.0";
  description = "一个友好的问候插件";

  commands: Record<string, CommandHandler> = {
    hello: async (ctx) => {
      await ctx.reply(`你好，${ctx.from?.first_name || "朋友"}！`);
    },
  };
}

完整插件开发教程请见 PLUGIN_DEV_GUIDE.md。

内置命令

命令	权限	说明
/start	公开	欢迎消息
/help	公开	列出所有可用命令
/ping	公开	在线检测
/plugin install|uninstall|list|search|update	管理员	插件管理器
/admin status|reload|stop	管理员	管理面板
/allowchat / /blockchat / /listchats	管理员	群组白名单管理
/allowuser / /listusers	管理员	用户权限管理
/alias set|del|list	管理员	命令别名管理
/reload	管理员	热重载所有插件

目录结构

src/
├── index.ts              # 入口
├── config/               # 环境配置 + schema
├── core/                 # 运行时、bot、会话、对话、启动检查
│   └── middleware/        # 认证、日志、限流、错误边界
├── plugin/               # Plugin 基类、管理器、注册表、校验器、上下文
├── commands/             # 内置命令插件（start/help/admin/plugin/reload/alias/ping）
│   └── services/          # PluginInstaller 服务
├── db/                   # 数据库连接、迁移、插件数据存储
├── types/                # TypeScript 类型定义
└── utils/                # 日志、cron、熔断器、重试、安全 Telegram、重启通知

项目脚本

脚本	说明
bun dev	开发模式启动（热重载）
bun start	生产模式启动
bun run typecheck	TypeScript 类型检查
bun test	运行测试
bun run db:generate	生成 Drizzle 迁移
bun run db:migrate	执行待处理的迁移
bun run lint	代码检查

License

MIT