一个能直接运行的计数插件,用来起步写自己的 LenBot 插件。
- 在 GitHub 上点 Use this template 生成自己的仓库。
- 改
plugin.toml里的name、authors、version和license。 - 把命令和工具改成自己的名字,避免和别的插件重名。
/计数:读当前群的计数。计数加一:按配置里的step增加。/计数清零:清零。- 工具
counter_read:返回当前群的计数 JSON。 - 工具
counter_card:后台生成计数说明后自行发送;需要宿主配置模型。
计数按群分开存,更新插件源码后保留。
uv run --no-sync pytest -q tests测试用宿主提供的 PluginTest 模拟消息和配置,直接在本仓库运行。可在 scenes 中传入不同平台的场景 ID 验证模拟消息,例如 PluginTest(package, scenes=("telegram:group:-1001234",))。CI 调用 LenBot 提供的可复用工作流,默认用宿主 master 跑测试和打包检查;需要固定宿主版本时在 .github/workflows/ci.yml 里传 host_ref。
- 改
plugin.toml的版本号并提交。 - 打
v*标签,工作流会生成 ZIP 并挂到 GitHub Release。
用户可以在面板里填仓库地址用 Git 安装,也可以导入 Release 里的 ZIP。配置或数据格式有变化时写在 README 里;回退源码时,已经存下的数据保持原样。
接口、生命周期和配置说明见宿主仓库的 developer/plugins-v1.md。
模板采用 GPL-3.0-only。LenBot 宿主采用 AGPL-3.0-only,插件和宿主运行在同一个进程里,推荐插件也使用 GPL-3.0;改用其他许可证前请确认它与 GPLv3/AGPLv3 兼容。
工具采用接口 1 的显式简介、Field 参数说明与 prompts/tools.md 共享指南,返回原生 JSON 或文本。用 PluginTest.preview_tools() 查看模型说明、参数与可用性;测试里模型服务默认关闭。兼容和更新事项见 CHANGELOG。
CI 调用 LenBot 的可复用工作流,跟随宿主 master 测试。catalog-entry.json 记录目录条目的安装来源。
本机生成 ZIP(LenBot 仓库与本仓库放在同一目录下):uv run --no-project --python 3.13 python ../LenBot/scripts/package_plugin.py . /tmp/plugin.zip。打包取 Git 已跟踪的运行源码和资源,新增文件需先加入 Git。
本模板保留两个工具:counter_read 查询 JSON;counter_card 开始后台生成并自行发送。两种结果语义不同,所以分别暴露。不要为每个 HTTP 端点、列表页、详情页或随机选项再加一个工具。
同一能力需要多种操作时,可用 request: Annotated[SearchRequest | ReadRequest, Field(discriminator="action")];各 Request 继承配置 ConfigDict(strict=True, extra="forbid") 的 BaseModel,并分别声明 action: Literal["search"]/Literal["read"] 和所需字段。列表、详情使用同一工具;查询和真实发送/账号写入保持清楚的边界。不要堆一组互斥可选参数。
用 PluginTest.preview_tools() 核对实际工具数、发现目录、共享指南与每个操作的 schema。工具数量和 schema 大小分开核对,检查目录和真实加载内容;已有生成 title 在模型参数中去掉,Field 的说明、示例和约束保留。
清单声明 send、generate、events。这些权限约束宿主提供的能力,插件自行执行的 Python 与网络访问不受其约束。插件运行在宿主进程中,当前功能使用工具或后台协程,isolation = "inline"。