插件

本指南介绍如何使用 @hookimpl 构建 Bub 插件。

导入与基本结构

使用 Bub 导出的标记：

from bub import hookimpl

在插件对象上实现 hook：

from __future__ import annotations

from bub import hookimpl


class MyPlugin:
    @hookimpl
    def build_prompt(self, message, session_id, state):
        return "custom prompt"

my_plugin = MyPlugin()

通过 Entry Point 注册插件

在 pyproject.toml 中暴露你的插件：

[project.entry-points."bub"]
my_plugin = "my_package.plugin:my_plugin"

BubFramework.load_hooks() 先加载内置插件，然后加载 group="bub" 中的 entry point。

通过导入模块暴露工具

工具通过 @tool 装饰器的导入时副作用注册。 你的插件必须在 agent 开始使用工具之前导入包含 @tool 定义的模块。

示例：

from __future__ import annotations

from bub import hookimpl

from . import tools  # noqa: F401


class MyPlugin:
    @hookimpl
    def system_prompt(self, prompt, state):
        return "extension prompt"

如果缺少该导入，工具模块不会执行，bub.tools.REGISTRY 中不会插入任何内容，工具也不会对 agent 或 CLI 补全可用。

在扩展包中发布技能

扩展包也可以通过在发行版中包含顶层 skills/ 目录来发布技能。

示例布局：

my-extension/
├─ src/
│  ├─ my_extension/
│  │  └─ plugin.py
│  └─ skills/
│     └─ my-skill/
│        └─ SKILL.md
└─ pyproject.toml

配置你的构建后端以将 skills/ 目录包含在包数据中。例如使用 pdm-backend：

[tool.pdm.build]
includes = ["src/"]

在运行时，Bub 从 <site-packages>/skills 发现内置技能，因此位于该位置的打包技能会被自动加载。 这些技能遵循正常的优先级规则，仍可被工作区（.agents/skills）或用户级（~/.agents/skills）技能覆盖。