beads

Beads（bd）是一个专为 AI 智能体设计的分布式任务管理系统。它能为智能体提供“长期记忆”，并以结构化的方式规划、跟踪和执行复杂工作流，从而避免上下文丢失。Beads 使用 Git 作为数据库，任务会随代码一起被版本化、分支和合并。

安装

如果找不到 bd，可以使用以下任一方式为用户安装（如不确定请先征得许可）：

npm（推荐）：

npm install -g @beads/bd

Homebrew：

brew install steveyegge/beads/bd

Go：

go install github.com/steveyegge/beads/cmd/bd@latest

初始化

在仓库中使用 Beads 之前，必须先初始化。

初始化：

bd init

如果希望在本地使用 Beads 而不把 .beads 目录提交到远程仓库（适合个人跟踪），可使用：

bd init --stealth

安装钩子（对智能体至关重要）：

bd hooks install

这能确保你的更改被自动同步，并保持 JSONL 数据库与 Git 之间的一致性。

智能体工作流（关键规则）

作为 AI 智能体，必须严格遵守以下规则才能正确与 bd 交互。

不要使用交互式编辑器

绝不要使用 bd edit。它会打开文本编辑器（vim/nano），你无法与之交互。始终使用带具体标志的 bd update。

始终同步

在会话结束时或完成一批更改后，始终运行：

bd sync

这会强制立即刷新 30 秒防抖缓冲区，提交更改、从远程拉取、导入更新并推送到远程。否则你的更改可能丢失或变得过时。

创建任务

使用标题和优先级（-p）创建新任务。

优先级 0：高优先级 1：中优先级 2：低

bd create "Refactor login component" -p 1

输出：Created task bd-a1b2

更新任务

使用标志更新特定字段。

更新描述

bd update bd-a1b2 --description "Refactoring the login component to use hooks."

更新标题

bd update bd-a1b2 --title "Refactor Login to Functional Component"

更新状态

bd update bd-a1b2 --status in_progress

更新设计说明

bd update bd-a1b2 --design "Using React.useState and React.useEffect"

更新验收标准

bd update bd-a1b2 --acceptance "1. User can login\n2. User can logout"

管理依赖

以层级方式组织工作。

为父任务添加子任务

bd dep add bd-child-id bd-parent-id

关闭任务

任务完成后关闭它。

bd close bd-a1b2 --reason "Completed"

列出任务

查看当前任务以了解你的状态。

bd ready # 显示可执行任务（未被阻塞、处于打开状态） bd show bd-a1b2 # 显示特定任务的详情

示例会话

1. 开始一个新功能

bd create "Implement Dark Mode" -p 0

> Created bd-d4rks

2. 拆解它

bd create "Add theme context" -p 1

> Created bd-ctx1

bd dep add bd-ctx1 bd-d4rks

bd create "Add toggle button" -p 1

> Created bd-t0g1

bd dep add bd-t0g1 bd-d4rks

3. 开始工作

bd update bd-ctx1 --status in_progress

...（进行编码工作）...

4. 标记为完成

bd close bd-ctx1 --reason "Implemented"

5. 同步你的工作