🚀 TeleBox

现代化 Telegram Bot 开发框架

基于 Node.js 和 TypeScript 构建，提供强大的插件系统和丰富的功能模块

📖 快速开始 • 🔌 插件生态 • 🛠️ 开发指南 • 📚 文档

---

✨ 核心特性

📦 模块化插件架构 🔄 动态插件加载 支持热重载，无需重启即可更新插件 🏷️ 命令别名系统 灵活的命令重定向和自定义别名 🎯 多命令支持 单个插件可注册多个命令和子命令 👂 消息监听器 支持全局消息监听和事件处理

🔧 内置功能模块 ⚙️ 系统管理 进程管理、系统信息监控、日志查看 🛡️ 权限控制 sudo 权限分配和用户管理 🌐 远程插件 在线插件商店，一键安装/卸载 💻 Shell 执行 安全的命令行执行环境 🔍 信息查询 用户、群组、频道详细信息获取

⚡ 高性能设计 🔒 TypeScript 类型安全，开发体验优秀 🚀 异步架构 基于 Promise 的非阻塞设计 🛠️ 错误处理 完善的异常捕获和恢复机制 💾 内存优化 智能缓存和资源管理

🏗️ 项目结构

📁 点击展开项目结构

📦 TeleBox/
├── 🎯 src/                     # 核心源代码
│   ├── 🚪 index.ts            # 应用入口点
│   ├── 🔌 plugin/             # 内置插件目录
│   │   ├── 📖 help.ts         # 帮助系统
│   │   ├── 📦 npm.ts          # 插件管理器
│   │   ├── 🆔 id.ts           # 信息查询
│   │   ├── 👑 sudo.ts         # 权限管理
│   │   ├── 💻 exec.ts         # Shell 执行
│   │   ├── 🏓 ping.ts         # 网络测试
│   │   ├── 📊 sysinfo.ts      # 系统信息
│   │   └── 🔧 ...             # 其他内置插件
│   └── 🛠️ utils/              # 工具库
│       ├── ⚙️ pluginManager.ts     # 插件管理核心
│       ├── 🔗 entityHelpers.ts     # Telegram 实体处理
│       ├── 🔐 loginManager.ts      # 登录管理
│       ├── 💬 conversation.ts      # 对话管理
│       └── 🧰 ...                  # 其他工具
├── 🔌 plugins/                # 用户插件目录
├── 📁 assets/                 # 静态资源
├── 💾 my_session/             # 会话文件
├── 📂 temp/                   # 临时文件
├── ⚙️ package.json            # 项目配置
├── 📝 tsconfig.json           # TypeScript 配置
└── 📋 INSTALL.md              # 安装文档

🧩 核心组件

🔧 插件系统架构

// 🎨 优雅的插件接口设计
interface Plugin {
  command: string[];                                    // 🏷️ 命令列表
  description?: string;                                 // 📝 功能描述
  cmdHandler: (msg: Api.Message) => Promise<void>;     // ⚡ 命令处理器
  listenMessageHandler?: (msg: Api.Message) => Promise<void>; // 👂 消息监听器
}

🎮 命令系统 🔤 多前缀支持 支持 . 。 $ 等多种命令前缀 🧪 开发模式 开发环境使用 ! ！ 前缀 🧠 智能解析 自动识别命令和参数 💬 错误处理 友好的错误提示和帮助信息

🛡️ 权限管理 👑 sudo 系统 分级权限控制 📋 用户白名单 灵活的访问控制 🔒 安全执行 受限的 shell 命令执行 🔐 会话管理 安全的登录和认证机制

🔌 插件生态

🎯 内置插件

🔌 插件	⌨️ 命令	📋 功能描述
📖 help	h, help, ?	🎯 帮助系统和命令列表
📦 npm	npm	🔧 插件管理器（安装/卸载/搜索）
🆔 id	id	🔍 获取用户/群组/频道详细信息
👑 sudo	sudo	🛡️ 权限管理和用户授权
💻 exec	exec	🔒 安全的 Shell 命令执行
🏓 ping	ping	🌐 网络连接测试
📊 sysinfo	sysinfo	📈 系统信息监控
🏷️ alias	alias	🔄 命令别名管理
🔄 update	update	⬆️ 系统更新管理

🌟 扩展插件

🎪 丰富的插件生态系统

🔍 查看可用插件 → .npm search
📥 安装插件 → .npm i <插件名>
🗑️ 卸载插件 → .npm rm <插件名>
📤 上传插件 → .npm upload <插件名>

🛠️ 技术栈

🏗️ 技术领域	🔧 技术选型	📊 版本
🚀 运行时	Node.js	20.x
💎 开发语言	TypeScript	5.9.2
📡 Telegram 库	GramJS	2.26.22
💾 数据库	better-sqlite3	12.2.0
⚡ 构建工具	tsx + tsconfig-paths	latest
🌐 HTTP 客户端	axios	1.11.0
🖼️ 图像处理	sharp	0.34.3
⏰ 任务调度	node-schedule	2.1.1
🧰 工具库	lodash	4.17.21

🚀 快速开始

📥 安装部署

💡 基本命令

🔍 信息查询 .help # 📖 查看所有命令 .help <命令> # 📝 查看特定命令帮助 .id # 🆔 获取当前聊天信息

🔧 插件管理 .npm search # 🔍 查看远程插件列表 .npm i <插件名> # 📥 安装插件 .sudo add <用户> # 👑 添加 sudo 权限

🧪 开发模式

# 🚀 启动开发模式
NODE_ENV=development npm run dev

💡 开发模式下使用 ! 和 ！ 作为命令前缀

📚 相关链接

📄 许可证

本项目采用 LGPL-2.1 许可证开源

---

🎯 TeleBox

让 Telegram Bot 开发更简单、更强大

_{Made with ❤️ by TeleBox Team}