📌 项目地址：gastownhall/beads | ⭐ 24,194 颗星 | 🔧 Go | 📜 MIT
markdown托管任务列表的三个致命缺陷
我见过几个团队让AI代理协作改同一个项目。每人一份TODO.md，几小时内就出乱子。
格式不统一。 代理A写“- [x] 登录完成”，代理B改成“- [ ] 登录模块还需测试”。AI需要猜这两条是否同一个任务。多数模型猜不准。
并发覆盖。 两个代理同时编辑TODO.md，后写的覆盖前者。跨分支时更糟：A在feature分支加任务，B在main分支改同一文件，合并必须手动处理。
依赖靠文本解析。 “- [ ] 任务B（依赖任务A）”这种写法，AI要在整个文档里搜“任务A”，找到后还要自己判断状态。解析经常出错，尤其是长文档。
这三个问题在单代理、短期项目中勉强能忍。多代理并行、长周期开发、跨会话维护时，每个问题都会重复出现。Beads就是冲着这些痛点来的——直接换存储层。
Beads的解法：用Dolt数据库代替Markdown
Beads的核心是Dolt，一个给SQL数据库加了Git式分支、合并、同步的数据库。每条任务是一条SQL记录，有哈希ID、状态（open/closed/in-progress等）、属性、依赖关系。代理直接查数据库，不需要解析文本。
同类工具中我看到过用JSON文件或自定义格式的，但最后都避免不了冲突。Beads选择了Dolt自有道理——它提供行级合并和内置网络同步，直接把版本控制做到数据库层面。
举个例子：代理想知道“哪些任务可以开始”。在Markdown系统里，代理要读全文、找出所有open任务、检查每个任务的依赖是否完成——步骤多、易出错。Beads里跑bd ready，输出的是所有前置任务已关闭的任务。结果是确定的，不依赖上下文长度。
三个核心设计
去中心化ID。 两个代理在不同分支上添加任务。ID是哈希值（比如bd-a1b2），不会冲突。合并时Dolt做SQL级别的行合并，不需要人手工修冲突。
显式状态和关系。 任务状态是数据库字段，不是人类写的文字。依赖关系通过relates_to、duplicates、supersedes、replies_to这类链接记录。调用bd close，任务就标记为closed，其他代理可以可靠地依赖这个状态。
持久记忆，禁止MEMORY.md。 bd remember "某个技术选择的原因"写入一条记录，代理随时可查。禁止代理自己创建MEMORY.md文件，避免多代理写同一个文件出冲突。
工作流：从安装到日常操作
安装用一行命令，不需要克隆仓库：
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash进你的项目目录初始化：
cd your-project
bd initbd init 会创建或更新 AGENTS.md 文件，默认加入beads工作流指引，也安装Claude/Codex集成（除非你传 --skip-agents 或 --stealth）。代理通过这个文件发现beads工作流。
日常用这几个命令：
bd prime：打印当前工作流指引，代理启动后先跑一次。bd ready：列出可执行的任务（所有依赖已关闭）。bd show <id>：查看任务详情。bd update <id> --claim：认领任务。bd close <id>：关闭任务。bd remember "xxx"：写入一条项目记忆。
Agent集成：不只是命令行
bd setup --list 查看支持的集成列表，包括 codex、claude、factory、mux、cursor 等。例如 bd setup codex 安装skill、AGENTS.md指引和hooks。bd setup factory 给Factory.ai Droid创建或更新AGENTS.md。bd setup claude 安装hooks/settings。
如果你的代理不在支持列表里，有两个办法：
- 跑
bd onboard，把打印的片段粘贴到代理指令文件。 - 手动在AGENTS.md里加这一段：
This project uses bd (beads) for issue tracking.
- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show `, `bd update --claim`, and `bd close `.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.两个值得展开的设计
compaction（记忆衰减）。 Beads会压缩已关闭的任务为一个短摘要。不是删除，是语义总结。项目运行几周后，旧任务可能攒了几十条。全部留在上下文中消耗token，还会分散注意力。压缩后保留结论，丢弃过程细节。这个设计解决的是长周期项目的token预算问题。
我试想一下实际场景：一个项目跑了两个月，关闭了150个任务。每条任务原始内容大约200 token，总token超过3万。压缩后每条只需要20 token，节省九成。对Claude这类按上下文长度收费的模型，省得很实在。
消息型issue。 支持messaging类型的任务，带 --thread 参数做回复链。代理之间可以发消息，甚至配置邮件转发。跟普通任务追踪分开生命周期。这意味着Beads不只是待办清单，也是代理之间的通信通道。比如代理A发现了一个阻塞问题，可以发一条消息给代理B，代理B回复后继续追踪。
24194个star说明了什么
Beads拿到这么多star，不太可能是“这个方案很酷”。更合理的解释是，不少团队在实际项目里碰到了同样类型的冲突问题，需要现成方案。
学习门槛存在。需要理解Dolt的基本操作（分支、合并、同步），命令有近十个，初次上手大概要一小时。另外，显式声明依赖要求工作流本身有清晰步骤。快速原型、单代理、短期项目，Markdown列表更轻量。
据我观察，Beads对这样三类项目最有用：
- 多个AI代理并行处理同一个项目
- 项目周期超过两周，需要跨会话维护上下文
- 频繁发生Markdown冲突，被手动修复搞烦了
其他情况，Markdown列表仍然是更简单的方案。无需安装依赖，无需学新命令，修改成本接近零。
但你若真遇到多代理协作的冲突问题，花一小时学Beads，省下来的时间远不止一小时。