Appearance
从Claude Code到Cursor再到Copilot，所有主流AI编程平台都有自己的待办系统。但这些内置任务列表往往是瞬态的——只存在于当前会话中，一旦上下文窗口填满或会话结束就消失了。这正是Beads诞生的原因。
AI代理任务管理的困境
许多开发者转而使用Markdown文件创建自己的任务管理系统。Cursor编辑器甚至把这种能力直接做进了编辑器，用交互式Markdown格式让你能看到每个任务的执行状态。
但这个方法也有局限：
- 绑定在特定编辑器上
- 需要遵循严格的格式规范
- 依然解决不了跨团队成员共享状态的问题
- 无法跨会话持久化上下文
Beads是什么
**Beads（命令：bd）**是一个面向AI代理的分布式图式问题跟踪器，底层基于Dolt——一个支持单元格级别合并的版本控制SQL数据库。
本质上，Beads是为编程代理打造的持久化结构化记忆。
- 用Go编写的CLI工具，只需安装一次即可在所有项目中使用
- 支持Homebrew、npm、直接安装脚本或Go install等方式
- 覆盖macOS、Linux、Windows和FreeBSD
关键洞察： Beads不把任务放在会话内存或Markdown文件里，而是将它们存储在一个版本控制的Dolt数据库中，放在项目的.beads/目录下。由于这个数据库会被提交到代码仓库，任务就变成了可共享、可审计、跨会话持久化的资产。
架构
Beads采用Go语言构建，架构清晰模块化：
- CLI层基于Cobra框架
- 核心逻辑分为types（数据类型）、storage（Dolt存储层）、schema（数据库迁移）、compact（记忆压缩）等内部包
- 存储层支持两种模式：嵌入模式和服务器模式
- 提供MCP服务器、Claude Code集成和Junie集成等扩展
存储：基于Dolt
Beads使用Dolt作为数据库后端——可以理解为"数据库界的Git"。每次写入都会产生一个Dolt提交，提供完整的审计历史。
两种部署模式：
| 模式 | 说明 | 适用场景 |
|---|---|---|
| 嵌入模式（默认） | Dolt在bd二进制进程内运行，无需外部服务器 | 个人开发者 |
| 服务器模式 | 连接外部dolt sql-server，支持多并发写入 | 多代理编排场景 |
核心数据模型与任务生命周期
数据库schema通过32个SQL迁移文件构建了Issues、Dependencies、Labels、Comments、Events、Wisps等表结构。
问题遵循清晰的状态流转：
Open → In Progress → Blocked / Deferred → Closed每次状态转换都会在审计日志中创建事件记录。
Issue结构体包含：
- 标题、描述、优先级、状态、类型、责任人、时间戳
- 支持基于时间的调度（DueAt、DeferUntil）
- 外部引用、自定义元数据和压缩追踪
6大核心功能
1. 依赖感知的任务图
Beads支持五种依赖关系类型：
- Blocks：阻塞
- Related：关联
- Parent-Child：父子层级
- Discovered From：衍生工作
- Conditional Blocks：条件阻塞
bd ready只列出没有未解决阻塞项的问题。当你关闭一个阻塞问题，依赖它的任务会自动变得可用。
2. 层级化问题ID
Beads支持树状ID结构用于史诗级任务：
bd-a3f8 （史诗）
├── bd-a3f8.1 （任务）
│ └── bd-a3f8.1.1（子任务）
└── bd-a3f8.2 （任务）3. 压缩（记忆衰减）
随着任务不断累积，把所有任务都保持在上下文中变得代价高昂。Beads实现了语义化的"记忆衰减"——旧已关闭的任务会被自动总结，节省上下文窗口空间。
4. 消息系统与图链接
Beads内置了用于代理间通信的消息问题类型，支持线程化对话和邮件委托。同时支持relates_to、duplicates、supersedes和replies_to等丰富的关系类型，使问题成为一张互联工作网络中的节点。
5. 零冲突ID与JSONL导出
基于哈希的ID（bd-a1b2）防止了多代理和多分支工作流中的合并冲突。同时Beads自动将任务导出到JSONL文件并提交到仓库，实现任务与代码一起进行版本控制。
6. Sentry集成
最强大的工作流演示了一条生产调试流水线：
- Sentry MCP查找过去14天的所有错误
- Sentry Seer AI分析根因
- Beads自动创建附带完整上下文的任务
- AI代理逐一修复
结果：结构化的、上下文丰富的bug修复流程，不会用无关信息填满代理的工作上下文。
从安装到日常使用
安装与初始化
bash
brew install beads # macOS/Linux（推荐）
npm install -g @beads/bd # npm
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash在项目目录中运行bd init，这会创建.beads/目录，设置Dolt数据库，配置项目前缀，并安装git hooks。然后运行bd onboard自动检测并配置所有已安装的AI代理。
日常工作流
bash
bd ready # 我现在可以做什么？
bd create "修复头部布局" -p 1 -t bug # 创建新任务
bd update bd-a1b2 --claim # 认领并开始工作
bd close bd-a1b2 --reason "已修复" # 完成
bd dep tree bd-a1b2 # 查看依赖树
bd list # 查看所有问题终端UI
Beads的终端UI（bv）提供看板视图、详细问题面板、依赖关系图分析和实时更新。虽然也有Web UI（npx beads-ui），但终端UI因其轻量和直观而特别受欢迎。
Git集成与团队协作
由于Beads把任务存储在项目仓库中的Dolt数据库里，团队协作变得无缝：
- 提交钩子在git操作时自动同步数据库
- Dolt分支独立于git分支，允许跨功能分支管理任务状态
- 隐身模式（
--stealth）让你在本地使用Beads但不提交到主仓库 - 贡献者模式则为开源项目将规划问题路由到独立仓库
Beads vs 其他方案
| 方案 | 局限性 |
|---|---|
| 会话内置待办列表 | 瞬态，无法共享，上下文溢出后丢失 |
| Markdown文件 | 无结构，无依赖追踪，AI容易偏离 |
| Cursor的Markdown规范 | 绑定单一编辑器，严格规范 |
| GitHub Issues | 外部工具，AI无感知，需要上下文切换 |
| Beads | ✅ 版本控制，依赖感知，AI原生，可共享 |
Beads从头开始就是为AI编程工作流设计的。 它原生支持JSON输出，理解依赖关系，处理上下文压缩。而且由于它是个只需安装一次的CLI工具，它可以与任何编辑器或代理配合使用。
结语
Beads解决了AI辅助开发中的一个根本问题：如何在会话、代理和团队成员之间维护持久化、结构化的任务状态。
通过用版本控制的、依赖感知的图数据库取代瞬态会话内存和临时Markdown文件，它为AI代理提供了处理长周期任务所需的结构化记忆。
