README.md

🚀 TeleBox

稳定可靠的 Telegram UserBot 框架

TypeScript 全栈 · 插件热加载 · 一键扩展 · 可与 TeleBox-Next 无缝切换

📖 快速开始 · 🔌 插件生态 · 🛠️ 开发指南 · 📋 安装

---

✨ 为什么选择 TeleBox

📦 插件即扩展 🔄 动态加载 安装、卸载、更新插件，按需热重载 🏷️ 别名系统 把常用命令映射成你习惯的短指令 👂 消息 / 事件监听 不只是命令：可做自动回复、统计、定时任务

🛡️ 开箱即用 🌐 远程插件商店 .tpm 一键搜索 / 安装 / 批量更新 👑 权限体系 sudo / sure，把能力安全分享给协作者 🔀 版本切换 .switch go 在 TeleBox 与 Next 之间直切，会话与插件配置一并迁移

⚡ 生产就绪 ♻️ Generation 生命周期 重载可中止、可清理，避免资源泄漏 ⬆️ 自动更新 主仓 + 插件可自动拉取，重启后补齐状态 🔧 一键修复 .autofix：清重名插件 → 硬同步代码 → 重启 → 更新插件

🏗️ 项目结构

📁 点击展开项目结构

📦 TeleBox/
├── 🎯 src/
│   ├── 🚪 index.ts              # 入口
│   ├── 🔌 plugin/               # 内置系统插件（24 个）
│   │   ├── help.ts · tpm.ts · update.ts · switch.ts · autofix.ts
│   │   ├── status.ts · ping.ts · reload.ts · health.ts · exec.ts · sudo.ts
│   │   └── …
│   ├── 🛠️ utils/                # 运行时 / 插件管理 / 会话 / 日志
│   └── 🪝 hook/                 # 客户端补丁与类型增强
├── 🔌 plugins/                  # 用户插件目录（.tpm 安装到这里）
├── 📁 assets/                   # 运行时数据与资源
├── 📂 temp/ · logs/
├── ⚙️ package.json · tsconfig.json
└── 📋 INSTALL.md · TELEBOX_DEVELOPMENT.md

🧩 插件抽象（开发者）

abstract class Plugin {
  abstract description:
    | string
    | ((...args: any[]) => string | void)
    | ((...args: any[]) => Promise<string | void>);

  abstract cmdHandlers: Record<
    string,
    (msg: Api.Message, trigger?: Api.Message) => Promise<void>
  >;

  listenMessageHandler?: (msg: Api.Message) => Promise<void>;
  eventHandlers?: Array<{ event?: any; handler: (event: any) => Promise<void> }>;
  cronTasks?: Record<string, {
    cron: string;
    description: string;
    handler: (client: TelegramClient) => Promise<void>;
  }>;
}

默认命令前缀：. 。 $ · 开发模式（npm run dev）：! ！
完整规范见 TELEBOX_DEVELOPMENT.md

🔌 插件生态

🎯 内置插件

插件	命令	说明
help	help, h	帮助与命令列表
tpm	tpm	插件管理器：搜索 / 安装 / 卸载 / 更新 / 上传
update	update	拉取主仓最新代码并安装依赖
switch	switch	TeleBox ↔ Next 版本切换（会话转换 + 配置迁移）
autofix	autofix	一键修复：清重名插件 → 硬同步 → 重启 → 更新插件
reload	reload, exit, restart, pmr	插件重载 / 退出 / PM2 重启
health	health, memory	内存守护：看占用、开自动保护，偏高时尽量不打断任务再清理
status	status, sysinfo	运行状态与系统信息
version	version, ver	版本号与更新状态
ping	ping	API / 目标 / DC 延迟探测（TCP 优先）
debug	id, entity, msg, echo	对话 / 实体 / 消息调试
sudo	sudo	管理员授权
sure	sure	授权他人以 bot 身份发送（支持重定向）
exec	exec	安全执行 Shell 命令
alias	alias	命令别名 / 重命名
prefix	prefix	命令前缀管理
bf	bf, hf	备份工具
sendlog	sendlog, logs, log	发送日志文件
loglevel	loglevel	日志级别
re	re	消息复读
save	save	会话 / 配置保存相关
leech	leech	历史消息抓取与归档
agent	agent	内置 Agent 能力
kitt	kitt	高级触发器：匹配 → 执行（系统插件）

🌟 扩展插件

官方插件仓库提供 100+ 社区插件，安装、更新、卸载都走 TPM：

操作	命令
搜索	.tpm search / .tpm s
安装	.tpm i <名> · .tpm i a b c · .tpm i all
从文件装	回复 .ts 文件 + .tpm install
卸载	.tpm rm <名> · .tpm rm all
更新	.tpm update / .tpm ua
列表	.tpm ls · .tpm lv
上传	.tpm ul <名>

🛠️ 技术栈

领域	选型	版本
运行时	Node.js	24.x
语言	TypeScript	^5.9.2
Telegram	Teleproto	^1.228.2
数据库	better-sqlite3 · lowdb	^12.2.0 · ^7.0.1
运行	tsx	^4.22.4
HTTP / 图像 / 工具	axios · sharp · lodash · cron	见 package.json

🚀 快速开始

git clone https://github.com/TeleBoxOrg/TeleBox.git ~/telebox
cd ~/telebox && npm install && npm start
# 生产环境建议：pm2 start "npm start" --name telebox

常用命令

场景	示例
帮助	.help · .help tpm
装插件	.tpm i weather
查延迟	.ping · .ping 1.1.1.1
系统状态	.status
更新主仓	.update
切到 Next	.switch go
一键修复	.autofix

npm run dev   # 开发模式，前缀改为 ! / ！

🔗 相关链接

📄 许可证

本项目采用 LGPL-2.1 开源

---

TeleBox — 把 Telegram UserBot 做成可维护的工程

_{Made with ❤️ by TeleBox Team}