打包与分发

当你基于 Bub 构建了自定义工具、通道插件、特定工作流技能，甚至想要打造专属的定制 CLI 时，可以将它们打包为标准的 Python 发行包（Wheel），发布至 PyPI 或私有镜像源供团队与用户安装。

在 Bub 架构中，打包分发通常对应三种场景：

分发形态	交付物	适用场景
扩展能力包	插件入口点 + 技能命名空间	为现有 Bub 生态贡献自定义工具、生命周期服务或专业技能
专属业务 CLI	自定义命令行脚本（如 `my-bub`）	包装 Bub 为特定业务场景的专属 Agent，固定工作区或封装默认配置
一体化套件	自有命令 + 插件 + 技能（All-in-One）	一键交付完整的垂直领域智能体，用户安装即可直接使用

发布自有命令

发行包可以提供自己的命令名，并在内部调用 Bub 的 CLI 入口。通过这种方式，你可以为 Agent 打造专属品牌或固化默认行为：

# src/my_bub/cli.py
from pathlib import Path
import os
from bub.__main__ import main as bub_main


def main() -> None:
    # 可选：固化默认工作区。Bub 的工作区默认取当前目录，没有对应的 BUB_* 环境变量，
    # 因此在调用 bub_main() 之前先切换目录；用户传入的 --workspace 仍可覆盖它。
    if workspace := os.getenv("MY_BUB_WORKSPACE"):
        os.chdir(Path(workspace).expanduser())

    # 调用 Bub 核心 CLI 调度器，自动支持 chat, run, gateway 等完整子命令
    bub_main()

在 pyproject.toml 中通过 [project.scripts] 注册命令：

[project.scripts]
my-bub = "my_bub.cli:main"

用户安装后，即可直接运行 my-bub chat、my-bub gateway 或 my-bub run。Bub 的 Typer CLI 会自动挂载所有原生子命令并支持 --workspace 等标准参数。

分发插件与技能

一个 Wheel 发行包可以同时提供插件入口点、标准技能命名空间包以及自定义 CLI 命令：

文件夹my-bub/
- pyproject.toml
- 文件夹src/
  - 文件夹my_bub/
    __init__.py
    cli.py # 自有 CLI 入口
    plugin.py # 插件与 Hook 实现
    tools.py # 自定义工具
  - 文件夹skills/ # 技能命名空间包（切勿放置 __init__.py）
    文件夹repo-reviewer/
    SKILL.md
    文件夹references/
    guidelines.md

配置 pyproject.toml

在 pyproject.toml 中配置入口点与 Hatch 构建包含规则：

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-bub"
version = "0.1.0"
description = "My Custom Bub Agent Distribution"
requires-python = ">=3.12"
dependencies = [
    "bub[app]>=0.6.0",         # 必须声明 app 依赖以支持 CLI、插件装载与技能
]

[project.scripts]
my-bub = "my_bub.cli:main"

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

[tool.hatch.build.targets.wheel]
packages = ["src/my_bub", "src/skills"]

配置要点

依赖声明：务必声明 bub[app]。自 0.6.0 起，核心包 bub 仅包含轻量内核，CLI、插件装载与技能运行时均由 app 额外依赖提供，遵循 0.6 迁移说明中的包结构调整。插件所依赖的三方库（如 httpx、pydantic 等）也应一并声明在发行包的 dependencies 中。
入口点格式：插件入口点组必须为 "bub"，具体语法参见插件注册规则。
打包包含范围：在 [tool.hatch.build.targets.wheel] 的 packages 中明确包含 "src/skills"，确保技能资产随 Wheel 打包并正确安装至环境中的 site-packages/skills/。

构建与分发

推荐使用 uv 快速构建标准的 Wheel 和源码包：

uv build

构建完成后，产物将生成在 dist/ 目录下（如 my_bub-0.1.0-py3-none-any.whl）。你可以将其发布至 PyPI，或在组织内部通过私有源分发。

对于下游用户：

作为全局 CLI 安装：推荐使用 uv tool install my-bub；
作为受管插件安装：若需要将该包安装至 Bub 管理的独立项目或容器环境中，使用 bub install。

发布前验证

发布到公开或生产环境前，务必在全新的虚拟环境中完成验证。

创建独立环境并安装 Wheel：
```
uv venv .test-env && source .test-env/bin/activate
uv pip install dist/*.whl
```
务必从打包生成的 wheel 安装，而不是直接在开发源码目录下运行。
验证插件与 Hooks 加载：
```
my-bub hooks
```
检查终端输出中是否正确列出了你的插件标识，确认入口点加载成功且没有弃用警告或导入异常。
验证技能发现：
```
my-bub run ",skill"
```
确认分发的技能（如 repo-reviewer）出现在已发现列表中，并使用 my-bub run ",skill name=repo-reviewer" 检查变量插值与正文展开是否正常。
验证自有命令与交互链路：
```
my-bub run "测试模型与自定义工具调用"
my-bub chat
```
验证模型交互、自定义工具执行、内部命令调度以及会话历史持久化。
验证网关与宿主集成（如适用）：若该发行包提供了渠道扩展或被宿主系统集成，按部署与复用 Bub 应用接入宿主服务，验证并发、关闭流和退出清理。