内容
# Beadhive (`bh`)
`bh` 是一个用于管理多个仓库中的 **beads** 问题跟踪的单一命令行界面。每个仓库都是其自己的 beads 数据库（一个 **hive**），具有短而稳定的前缀；`bh` 可以将其纳入管理，保持其标签一致，跨一个或多个仓库运行 `bd`/`git`，并聚合每个 hive 的信息到一个跨仓库的视图中 — 甚至可以查看那些代码未被检查出的 hive。
它是在 `bd`、`git`、`git-workspace`、`dolt` 和 `docker` 之上的一层薄薄的编排层：`bh` 编码了约定、注册表、验证和路由。配置和运行时状态存放在 `~/.beadhive/` 下；**不会有问题数据存储在那里** — 每个 hive 的问题都存放在该仓库自己的 git 远程仓库的 `refs/dolt/data` 下。
`bh` 是 **Beadhive** 伞形工作空间的命令行界面 — **AGF**（Agentic Git Flow）的集成平面驱动程序，AGF 是一个抽象的、与跟踪器无关的过程。**Beadflow** 是该过程在 beads 上的实现：此仓库的具体实现，在命名层下具有不变的行为。有关该过程，请参阅 [docs/AGF.md](docs/AGF.md)；有关命名决策记录，请参阅 [docs/design/limn-naming-strategy-adr.md](docs/design/limn-naming-strategy-adr.md)。
此仓库是命令行界面的源代码（Python 包 `beadhive` 在 PyPI 上，命令 `bh`）。
## 安装
**代理：** 将您的代理指向 [`INSTALL.md`](INSTALL.md) — 首选安装路径。它携带了一个结构化的 `install:` frontmatter 块（代理读取它，披露计划，并在每个命令之前询问）以及任何代理或人类都可以遵循的纯文本备用方案。
**手动**（选择一个）：
```sh
uv tool install 'beadhive[otel]' # PyPI（推荐 — 预构建的轮子，几秒钟）
pipx install 'beadhive[otel]' # PyPI 替代方案
brew install beadhive/tap/beadhive # Homebrew（较慢 — 从源代码构建本地依赖项）
```
然后搭建配置文件：
```sh
bh config init # 将 config.yaml 和模板写入 ~/.beadhive/
```
**可选（Claude Code）：** `bh` claude-plugin 提供 AGF 座位代理定义和角色技能；`bh mcp install` 在用户范围内连接 MCP 服务器：
```sh
claude plugin marketplace add beadhive/claude-plugin
claude plugin install bh@beadhive
bh mcp install
```
## 文档
刚开始使用 `bh`？从 [`**docs/ONBOARDING.md**`](docs/ONBOARDING.md) 开始 — 从全新 Mac 到配置的 AGF 工作空间和注册的 hive 的端到端指南。
其他所有内容 — 设计和推理、配置、完整的命令表面和每个组件 — 都从 [`**docs/OVERVIEW.md**`](docs/OVERVIEW.md) 开始。
## 开发
```sh
just bootstrap # brew bundle + mise install + uv sync （每台机器一次）
just install # uv tool install --force '.[otel]' → ~/.local/bin/bh
just lint # ruff check
just fmt # ruff format
just test # pytest
just build # uv build
```
