问题：Agent 做长任务就像金鱼
你让 Claude Code 做一个重构任务——把一个单体应用拆成微服务。Agent 开始干活，写了一堆代码，改了 20 个文件。然后你发现它改错了方向，说「回退一下，换个方案」。
它一脸茫然：「什么方案？我之前做了什么？」
这就是 Coding Agent 的核心痛点：没有持久化的结构化记忆。
当前的解决方案要么是：
- Markdown 计划文件（如 planning-with-files）—— 能用，但本质是纯文本，没有依赖关系、没有状态机、没有冲突解决
- Agent 自己的上下文窗口—— 一清空就全忘了
- 人工记笔记—— 那要 Agent 干嘛？
Beads 是什么
Beads（CLI 命令：bd）是一个分布式图结构 Issue 追踪器，底层用 Dolt（一个版本控制的 SQL 数据库）做存储。
一句话：它把 Git 的版本控制能力搬到了任务管理上，但数据结构是图，不是文件树。
每个任务（bead）是一个节点，节点之间有依赖关系（blocks、relates_to、duplicates、supersedes）。Agent 可以用 bd ready 查看「哪些任务没有被阻塞」，用 bd claim 原子性地认领任务，用 bd close 关闭任务。
它解决了什么问题
| 场景 | Markdown 计划文件 | Beads |
|---|---|---|
| 任务依赖 | 手动写「先做 A 再做 B」 | 图结构依赖，bd ready 自动过滤 |
| 多 Agent 协作 | 文件冲突，互相覆盖 | 哈希 ID + Dolt 合并，零冲突 |
| 长任务记忆 | 上下文满了就丢 | Dolt 持久化 + 语义压缩 |
| 跨会话连续性 | 重新读文件，可能过时 | bd prime 注入最新状态 |
| 任务审计 | 无 | Dolt commit 历史，完整审计链 |
| 多分支并行 | 每人一份计划，合并靠人 | Dolt cell-level merge，自动合并 |
核心架构：为什么是 Dolt + 图
Beads 的设计哲学很明确：Agent 的任务管理应该像 Git 管理代码一样——有版本、有分支、有合并、有冲突解决。
Dolt 是一个 MySQL 兼容的版本控制数据库。这意味着：
- 版本控制：每次
bd create、bd update都是一个 Dolt commit，可以 diff、blame、rollback - 分支合并：两个 Agent 在不同分支上修改同一个任务的不同字段，Dolt 能自动 cell-level merge
- 分布式同步：用
bd dolt push/pull像 Git 一样同步任务数据 - SQL 查询：底层是 SQL，复杂查询不用写一堆 grep
图结构体现在任务之间的关系：
bd dep add bd-a1b2 bd-c3d4 --type blocks # c3d4 阻塞 a1b2
bd dep add bd-a1b2 bd-e5f6 --type relates # 相关
bd dep add bd-a1b2 bd-g7h8 --type parent # 父子关系Agent 执行 bd ready 时，Beads 会遍历依赖图，只返回没有未完成 blocker 的任务。这比 Markdown 里手写的「- [ ] 任务 A（依赖任务 B）」靠谱多了。
上手体验
# 安装
brew install beads # macOS / Linux
npm install -g @beads/bd # Node.js 用户
# 在项目中初始化
cd your-project
bd init
# 让 Agent 自动发现 Beads
bd setup claude # Claude Code
bd setup codex # Codex CLI
bd setup cursor # Cursor初始化后，bd init 会在项目根目录创建 AGENTS.md，告诉 Agent：「这个项目用 Beads 管理任务，用这些命令操作。」Agent 读到这个文件后，就会自动用 bd 命令而不是 Markdown TODO 来管理任务。
关键命令速查
# 创建任务
bd create "重构用户认证模块" -p 0 # P0 优先级
bd create "添加单元测试" -p 1
# 建立依赖
bd dep add bd-b2c3 bd-a1b2 --type blocks # 测试阻塞重构
# Agent 工作流
bd ready --json # 可以做的任务
bd update bd-a1b2 --claim # 认领任务
bd update bd-a1b2 --status in_progress # 开始干活
bd close bd-a1b2 "已完成重构" # 关闭
# 持久化记忆
bd remember "JWT 密钥存在 env 里，不要硬编码"
bd prime # 注入上下文给 Agent踩坑与注意事项
- 嵌入模式是单写者：默认的 embedded Dolt 用文件锁，同一时间只有一个 Agent 能写。多 Agent 并行需要用 server 模式
- Git 集成有开销：每次
bd操作都会触发 Dolt commit，如果项目 Git remote 配了自动 push，频繁操作会有延迟 - Stealth 模式很重要：在共享项目里用
bd init --stealth，不要把.beads/目录提交到别人的仓库 - 升级要小心：Beads 的 schema 可能随版本升级变化，升级前先
bd export --all备份 - Compaction 是杀手特性：
bd remember存的记忆会通过语义压缩自动「衰减」旧内容，避免上下文窗口爆掉
跟现有方案对比
| 方案 | 持久化 | 依赖图 | 多 Agent | 版本控制 | 学习成本 |
|---|---|---|---|---|---|
| Markdown TODO | ✅ 文件 | ❌ | ❌ 冲突 | ❌ | 零 |
| planning-with-files | ✅ 文件 | ❌ | ⚠️ 手动 | ❌ | 低 |
| Linear / Jira | ✅ 云 | ✅ | ✅ | ❌ | 中 |
| Beads | ✅ Dolt | ✅ 图 | ✅ 零冲突 | ✅ Dolt | 低 |
Beads 的独特之处在于：它是唯一一个同时具备「图结构依赖 + 版本控制 + Agent 原生集成」的任务管理工具。Linear/Jira 功能更强但不是给 Agent 用的；Markdown 方案更轻但没有结构化能力。
什么时候该用 Beads
- 你的 Agent 经常做超过 30 分钟的长任务
- 你在用多个 Agent 并行改同一个项目
- 你需要跨会话的任务连续性（今天做到一半，明天继续）
- 你需要审计 Agent 做了什么、为什么这么做
如果你只是让 Agent 改个 bug、写个函数，Beads 是过度设计。但如果你在用 Agent 做真正的工程任务——重构、迁移、多模块改造——Beads 是目前最靠谱的选择。
项目信息
- GitHub：gastownhall/beads
- Star：25,170 ⭐
- 语言：Go
- License：MIT
- 文档：gastownhall.github.io/beads