核心概念

Beadbox 将 bd CLI 背后的数据模型可视化。以下六个概念涵盖了你在仪表盘中看到的一切。

工作区

工作区是一个包含 .beads/ 文件夹的项目目录。数据库后端可以是 SQLite（旧版）或 Dolt。每个工作区独立追踪自己的问题集，与其他项目互不干扰。

Beadbox 通过 ~/.beadbox/registry.json 注册表、跟踪上次活跃工作区的 cookie，以及扫描当前工作目录中的 .beads/ 文件夹来检测工作区。使用顶部栏的选择器在工作区之间切换。

在嵌入模式下，所有数据保留在本地，无需账号或云依赖。工作区可以选择性地连接远程 Dolt 服务器以实现多用户写入，从而支持 push 和 pull 同步。

bead 是工作的基本单位，相当于一个问题、任务或工单。每个 bead 包含：

由 bd CLI 分配的唯一 ID（例如 bb-a3f2），由工作区前缀和 base32 编码后缀组成
标题和可选描述（支持 markdown）
状态：open、in_progress、blocked、deferred、ready_for_qa、qa_passed、ready_to_ship 或 closed
优先级：P0（紧急）到 P4（待办）
类型：task、bug、feature、epic、chore 或 decision（核心类型）。molecule 和 gate 等自定义类型可按工作区配置。
可选的负责人

用 bd create 创建 bead，用 bd show 查看。在 Beadbox 中，点击树中的任意 bead 打开详情面板。

epic 是有子项的 bead。它将相关工作分组并跟踪整体进度。在树状视图中，epic 根据已关闭子项的数量显示进度条。

传递 --parent 来创建子项：

bd create --title="Subtask" --type=task --parent=EPIC-ID

Epic 可以嵌套。epic 的子项本身也可以是拥有自己子项的 epic。树状视图通过展开/折叠控件渲染这种层级结构。

一个 bead 可以阻塞其他 bead。当 bead A 阻塞 bead B 时，B 在 A 关闭之前无法推进。依赖关系在树状视图中以阻塞标记显示，在详情面板中以依赖列表显示。

用 bd dep 设置依赖关系：

bd dep BEAD-A --blocks BEAD-B

Beadbox 绘制依赖图，让你一眼看出哪些 bead 正在阻碍进度。

每个 bead 都有评论线程。评论是 agent 和人类就 bead 进行沟通的方式：发布实现前的计划、报告完成情况、标记阻塞项、提供 QA 验证步骤。

从 CLI 添加评论：

bd comments add BEAD-ID --author agent-name "PLAN: ..."
bd comments add BEAD-ID --author agent-name "DONE: ..."

在 Beadbox 中，评论以 markdown 形式按时间顺序显示在详情面板中。

每个 bead 遵循以下生命周期：

每种状态在 Beadbox 中都有独特的颜色标记。过滤栏支持按状态显示或隐藏 bead。Activity Dashboard 使用这些状态将 bead 按 pipeline 阶段分组。