✨ nonebot-plugin-template ✨

Important

收藏项目 以便创建插件仓库～⭐️

🎉 快速开始

1. 点击 创建仓库
2. ⚠️ 重要: 前往仓库 Settings -> Actions -> General -> 最下方 Workflow permissions, 勾选 Read and write permissions，然后点击 Save 按钮
3. 在 Add file 菜单中选择 Create new file, 在新文件名处输入LICENSE, 此时在右侧会出现一个 Choose a license template 按钮, 点击此按钮选择开源协议模板, 然后在最下方提交新文件到主分支(这会触发一个工作流，生成新的 README，并修改 pyproject.toml 等文件中的插件名称)

🧰 本地开发环境

• 依赖管理：uv（自动创建虚拟环境）
• 任务编排：just
• 代码质量：ruff（格式化 + 静态检查）、basedpyright（类型检查）
• 测试：pytest + pytest-xdist（并行）+ pytest-cov
• 提交规范：commitizen、pre-commit / prek
• 变更日志：git-cliff

安装依赖

uv sync --all-groups -p 3.12

常用命令

just test      # 单元测试（含覆盖率，自动并行）
just lint      # 代码检查 + 格式化（ruff check/format）
just check     # 类型检查（basedpyright）
just hooks     # 安装 pre-commit / prek 钩子
just update    # 更新钩子版本（prek autoupdate）
just changelog # 生成最新 changelog（git-cliff）
just bump      # 根据 commit 自动升版本并更新锁文件（cz + uv lock）

Note

模板库中自带了一个 Release 工作流, 你可以使用此工作流发布你的插件到 PyPI

配置 PyPI Trusted Publisher

配置文档: https://docs.pypi.org/trusted-publishers/adding-a-publisher/

• PyPI Project Name: nonebot-plugin-template
• Owner: Your GitHub username
• Repository name: nonebot-plugin-template
• Workflow name: release.yml
• Environment name: release

使用 Commitizen 更新版本号，并触发 Release 工作流 (推荐)

确保已安装 just，然后执行：

just bump

该操作会：

1. 根据 conventional commits 自动确定版本号
2. 更新 pyproject.toml 中的版本号和 CHANGELOG.md
3. 更新 uv.lock 中的版本号
4. 创建一个带 v* tag 的提交

也可以手动指定版本递增：uv run cz bump --increment patch/minor/major

接下来推送提交和 tag：

git push origin main --tags

触发 Release 工作流 (手动)

更新版本号

uv version --bump patch

possible values: major, minor, patch, stable, alpha, beta, rc, post, dev

提交并推送...

从本地推送任意 tag 即可触发。

创建 tag:

git tag v*

推送本地所有 tag:

git push origin --tags

Important

不会使用 uv ？

不会看文档去

安装 uv

windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

curl:

curl -LsSf https://astral.sh/uv/install.sh | sh

pipx:

pipx install uv

安装所有依赖(自动创建 venv 虚拟环境, -p 指定 python 版本):

uv sync --all-groups -p 3.12

添加其他依赖, 例如 koishi(bushi

uv add koishi

uv 文档

Note

pre-commit / prek 使用方法

提交前检查

安装 pre-commit

uv tool install pre-commit

或安装 prek (推荐)

On Linux / macOS:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/j178/prek/releases/download/v0.2.13/prek-installer.sh | sh

On Windows:

powershell -ExecutionPolicy ByPass -c "irm https://github.com/j178/prek/releases/download/v0.2.13/prek-installer.ps1 | iex"

安装钩子

pre-commit install

prek install

添加到暂存区

git add <待提交文件>

仓库地址:

• prek