Beads
Beads 是一个面向编码 Agent 的图状 issue tracker。它的命令行工具叫 bd，底层存储使用 Dolt 这个带版本控制能力的 SQL 数据库。
它最值得关注的点不是“又一个待办清单”，而是给 Agent 一个结构化任务图，让长任务、多分支、多 Agent 协作和上下文压缩都更容易处理。
它解决什么问题
Markdown 计划很好起步，但任务一长就容易失控：
- 依赖关系藏在自然语言里
- 多个 Agent 可能改同一份计划文件
- 已完成内容继续占上下文
- 恢复任务时要重读大量描述
- 分支、机器或 Agent 之间交接很脆弱
Beads 把任务状态变成数据库里的图。Agent 可以查询哪些任务已经 ready、声明自己要做哪一项、记录阻塞关系，并保留操作历史。
核心模型
Beads 把 issue 存成结构化记录，而不是纯文本笔记。
几个关键概念：
- Issue：任务、bug、epic、消息或其他工作项。
- 依赖关系：父子任务、阻塞、关联、重复和替代关系。
- Ready 队列：
bd ready 列出当前没有开放阻塞的任务。
- 声明任务：
bd update <id> --claim 让 Agent 原子化认领任务。
- 压缩：旧的已关闭任务可以被总结，减少上下文消耗。
- JSON 输出：命令设计上更方便 Agent 和脚本解析。
所以它更像 Agent 的外部记忆层，而不是只给人看的 issue 系统。
基本用法
先安装 CLI，再在项目里初始化：
brew install beads
cd your-project
bd init
echo "Use 'bd' for task tracking" >> AGENTS.md
| 命令 | 用途 |
|---|
bd ready | 列出没有阻塞的任务。 |
bd create "Title" -p 0 | 创建高优先级任务。 |
bd update <id> --claim | 原子化认领任务。 |
bd dep add <child> <parent> | 添加依赖或层级关系。 |
bd show <id> | 查看详情和操作历史。 |
存储模式
Beads 主要有两种存储模式：
- Embedded mode：
bd init 使用进程内 Dolt 数据库，是默认模式，适合多数个人或单写者工作流。
- Server mode：
bd init --server 连接外部 dolt sql-server，更适合多写者并发访问。
它还支持通过 BEADS_DIR 和 bd init --stealth 做 git-free usage，适合 CI、评测、monorepo、非 git 版本控制，或者不想污染共享仓库的个人任务跟踪。
什么时候用
这些场景可以考虑 Beads：
- 编码任务会跨很多轮或很多天
- 多个 Agent 或多个分支需要协作
- 任务依赖比普通 checklist 更重要
- 希望任务状态机器可读，而不是只写在自然语言计划里
- 想保留进度，但不想把全部历史塞进 prompt
如果只是一次性小改动，普通 Markdown 更简单。只要任务开始变成长周期 Agent 工作流，Beads 就能给 harness 一个更可靠的外部记忆面。
它在 Agent harness 里的位置
在 Agent harness 设计里，Beads 属于记忆与协调层：
- 把任务状态从模型上下文里外化出来
- 给 Agent 一个可查询的 ready 队列
- 通过生成 ID 和结构化存储减少冲突
- 让交接更容易，因为任务状态不再只藏在聊天历史里
它可以和 git worktree、browser harness、仓库里的 AGENTS.md 配合使用。背后的思路一样：把稳定状态从模型里拿出来，放进可检查的项目基础设施。
采用前要检查什么
- 决定
.beads/ 应该提交、忽略，还是用 stealth mode。
- 给 Agent 自动化时优先使用 JSON 输出。
- 多 Agent 场景里，先测试认领任务和依赖更新。
- 信任下载的二进制前，先确认校验和或签名策略。
- 任务标题和依赖关系保持简短，方便 Agent 快速扫描。
参考资料
Last modified on April 27, 2026
