Skip to content

模块插件开发 ​

本指南根据 TGBotPress 仓库当前 SDK、插件目录和官方开发文档整理。开发前请核对目标版本的源码和测试;项目仍在迭代。

当前能力与限制 ​

项目提供 SDK 类型、内置模块、生命周期管理和 ETS 市场展示信息提交入口。宿主目前以静态注册为主:定义 manifest、打包或提交市场信息,都不会让任意第三方插件自动安装运行。前端动态路由、第三方代码隔离、多实例制品同步和线上回滚仍需实现或验收。

当前远程安装信任策略要求插件 ID 已在内置目录中、包名为 @tgbotpress/plugin-<id>;GitHub Packages 包还需要 SHA-512 完整性信息。后台远程安装按钮目前禁用。第三方代码运行时具有宿主进程权限,--ignore-scripts 和权限声明都不能替代隔离。

开发前准备 ​

  1. 确定目标宿主版本、模块功能、数据所有权、插件依赖和现有行为。
  2. 阅读 SDK 类型、插件目录和宿主注册,参考 groups 与 cloneproxy。
  3. 追踪涉及的菜单、API、权限、数据库、worker 和 Telegram 更新。准备隔离 PostgreSQL 和模拟外部服务,避免使用生产数据或真实资金。
  4. 需要 Agent 辅助时,可使用后台提供的开发 Skill。

创建插件包 ​

插件通常采用 ESM npm 包,通过 exports 明确暴露 JavaScript 和类型入口。例如:

text
plugin-example/
├── package.json
└── src/
    ├── index.js
    └── index.d.ts
json
{
  "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 和入口 ​

js
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.tsID、依赖、生命周期与实际实现一致
后台导航src/lib/plugin-navigation.ts、src/config/admin-navigation.ts菜单权限和插件状态
HTTP APIsrc/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。卸载前检查依赖、运行任务和未完成业务,默认保留业务数据。涉及资金或链上任务时,应明确停用后如何履行已有义务。

测试与打包 ​

  1. 在隔离环境验证正常、失败、重复执行、并发、重启和恢复路径;模拟 Telegram、支付和链上服务。
  2. 从仓库根目录运行 npm run typecheck、相关测试及 npm run build;集成测试按对应测试文件配置隔离数据库。
  3. 在插件目录执行 npm pack --dry-run 检查包内容,再执行 npm pack,在干净项目中安装产物及必要的 peer dependencies,验证公开 JavaScript 和类型入口。
  4. 在真实宿主入口验证有权限和无权限访问、菜单、API、任务、启停、排空、依赖及回滚。修改 TypeScript 后,确保包内 JavaScript 和声明文件与源码一致。
  5. 检查包和日志中没有 token、私钥及其他凭据。分别记录打包、宿主集成、远程发布、市场上架和实际安装的结果。

提交市场展示 ​

超级管理员在后台插件市场的「开发模块」中选择「公开上架模块插件」,先登录 ETS,再填写名称、介绍、npm 安装命令及可选图片。当前表单接受 npm install 或 npm i、包名及可选完整版本号;图片支持 PNG、JPEG、WebP,最大 200 KB。

ETS 接受展示信息、npm 包发布以及宿主安装是独立步骤。先确认包已在目标 registry 发布且可被目标用户读取,再提交展示信息;外部服务的接受和审核结果以实际接口为准。

Released under the MIT License.