模块插件开发
本指南根据 TGBotPress 仓库当前 SDK、插件目录和官方开发文档整理。开发前请核对目标版本的源码和测试;项目仍在迭代。
当前能力与限制
项目提供 SDK 类型、内置模块、生命周期管理和 ETS 市场展示信息提交入口。宿主目前以静态注册为主:定义 manifest、打包或提交市场信息,都不会让任意第三方插件自动安装运行。前端动态路由、第三方代码隔离、多实例制品同步和线上回滚仍需实现或验收。
当前远程安装信任策略要求插件 ID 已在内置目录中、包名为 @tgbotpress/plugin-<id>;GitHub Packages 包还需要 SHA-512 完整性信息。后台远程安装按钮目前禁用。第三方代码运行时具有宿主进程权限,--ignore-scripts 和权限声明都不能替代隔离。
开发前准备
- 确定目标宿主版本、模块功能、数据所有权、插件依赖和现有行为。
- 阅读 SDK 类型、插件目录和宿主注册,参考 groups 与 cloneproxy。
- 追踪涉及的菜单、API、权限、数据库、worker 和 Telegram 更新。准备隔离 PostgreSQL 和模拟外部服务,避免使用生产数据或真实资金。
- 需要 Agent 辅助时,可使用后台提供的开发 Skill。
创建插件包
插件通常采用 ESM npm 包,通过 exports 明确暴露 JavaScript 和类型入口。例如:
plugin-example/
├── package.json
└── src/
├── index.js
└── index.d.ts{
"name": "@example/plugin-example",
"version": "0.1.0",
"type": "module",
"exports": {
".": { "types": "./src/index.d.ts", "import": "./src/index.js" }
},
"files": ["src"],
"peerDependencies": { "@tgbotpress/plugin-sdk": "^0.1.0" }
}示例包名仅展示结构,不符合当前官方包安装信任策略。发布前确认 SDK 版本、目标 registry 的可用性以及包读取权限,并为公开入口提供相应类型声明。
定义 manifest 和入口
export const manifest = {
id: 'example',
version: '0.1.0',
hostRange: '>=1.0.0 <2.0.0',
sdkVersion: '0.1.0',
name: '示例插件',
dependencies: [],
menuRoutes: [],
apiRoutes: [],
tasks: [],
drainTasks: [],
configTypes: [],
}
export const plugin = { manifest }id、version、hostRange、sdkVersion 和 name 是必填字段;还可声明 description、插件依赖、菜单、API、任务和排空任务。configTypes 可包含 command、keyboard、keyreply、keyreply_keyboard。插件依赖写在 manifest,npm 依赖写在 package.json。
plugin 可选实现 activate(host) 和 deactivate(host)。当前 PluginHost 提供 manifest、状态查询、状态转换和日志接口;不要假设它已提供数据库或 Telegram 客户端。业务所需能力需要设计受控的宿主适配接口,避免直接依赖宿主私有代码。
接入宿主
声明不会自动注册功能,需根据目标版本显式接线并追踪实际调用:
| 能力 | 源码入口 | 重点 |
|---|---|---|
| 模块注册 | src/plugins/catalog.ts、src/plugins/registry.server.ts | ID、依赖、生命周期与实际实现一致 |
| 后台导航 | src/lib/plugin-navigation.ts、src/config/admin-navigation.ts | 菜单权限和插件状态 |
| HTTP API | src/routes/、src/server/ | 服务端身份、角色、来源、参数及插件状态校验 |
| 后台任务 | src/server/platform-worker.server.ts、src/worker/ | 租约、并发、幂等、停用及排空 |
| 机器人配置 | src/plugins/plugin-config-links.server.ts | 自动或人工归属、共享配置和恢复 |
| 数据迁移 | migrations/ | 版本兼容、备份、失败恢复与数据保留 |
隐藏菜单不能代替 API 鉴权。涉及 Telegram、支付、钱包和订单时,要明确事务边界、外部副作用、重复事件和失败重试,避免重复扣款或发放。
生命周期与数据
active:允许接受新业务。draining:停止不应继续接收的新业务,并按模块约定处理在途任务。uninstalled:逻辑卸载,不等同于删除代码或数据。
操作包括 install、disable、resume 和 uninstall;具体转换规则见 src/plugins/lifecycle-policy.ts。卸载前检查依赖、运行任务和未完成业务,默认保留业务数据。涉及资金或链上任务时,应明确停用后如何履行已有义务。
测试与打包
- 在隔离环境验证正常、失败、重复执行、并发、重启和恢复路径;模拟 Telegram、支付和链上服务。
- 从仓库根目录运行
npm run typecheck、相关测试及npm run build;集成测试按对应测试文件配置隔离数据库。 - 在插件目录执行
npm pack --dry-run检查包内容,再执行npm pack,在干净项目中安装产物及必要的 peer dependencies,验证公开 JavaScript 和类型入口。 - 在真实宿主入口验证有权限和无权限访问、菜单、API、任务、启停、排空、依赖及回滚。修改 TypeScript 后,确保包内 JavaScript 和声明文件与源码一致。
- 检查包和日志中没有 token、私钥及其他凭据。分别记录打包、宿主集成、远程发布、市场上架和实际安装的结果。
提交市场展示
超级管理员在后台插件市场的「开发模块」中选择「公开上架模块插件」,先登录 ETS,再填写名称、介绍、npm 安装命令及可选图片。当前表单接受 npm install 或 npm i、包名及可选完整版本号;图片支持 PNG、JPEG、WebP,最大 200 KB。
ETS 接受展示信息、npm 包发布以及宿主安装是独立步骤。先确认包已在目标 registry 发布且可被目标用户读取,再提交展示信息;外部服务的接受和审核结果以实际接口为准。