Beads 教程：给 Coding Agent 一张任务记忆图，别再靠 Markdown TODO 硬撑

Beads 的定位很清楚：给 Coding Agent 用的 distributed graph issue tracker，底层用 Dolt，提供结构化、可合并、可查询的任务记忆。说白了，它想替代那种越来越乱的 Markdown TODO、聊天记录计划和临时任务清单。长任务里，Agent 最容易忘的不是代码，而是“现在到底该做哪一步、哪些任务被谁接了、哪个 bug 依赖哪个改动”。

这类工具很值得看，因为 Agent 开发已经不只是一次对话。真正的长链路任务需要持久状态：任务图、依赖、claim、ready 队列、关闭记录、旧任务压缩。Beads 把这些东西做成 CLI，Agent 可以通过 JSON 输出和命令直接读写，不用在人类写的 Markdown 里猜。

官方推荐把 beads CLI 当作系统工具安装，不要把仓库 clone 到你的项目里。

# 安装 beads CLI
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# 进入你的项目
cd your-project
bd init

# 告诉 Agent 使用 bd 做任务跟踪
echo "Use 'bd' for task tracking" >> AGENTS.md

macOS / Linux 用户也可以用包管理器或 npm：

brew install beads
npm install -g @beads/bd

初始化后，项目里会有 Beads 的数据目录。你可以把它理解成一个专门给 Agent 和团队协作使用的任务数据库。

TODO.md 适合一个人写几条待办，不适合多个 Agent、多分支、多依赖的开发。比如任务 A 要等数据库迁移，任务 B 要等 A 的接口，任务 C 可以并行做。Markdown 可以写，但 Agent 很难可靠地判断哪个 ready、哪个被占用、哪个已经在别的分支处理。

Beads 的核心价值是把任务变成图。任务之间有依赖，任务有状态，Agent 可以 claim，完成后 close，旧任务还可以 compaction，减少上下文占用。这比“请继续看上面的计划”靠谱得多。

# 创建任务
bd create "Fix auth bug" -p 1 -t bug

# 查看可执行任务，适合 Agent 选择下一步
bd ready --json

# 认领任务，避免多个 Agent 撞车
bd update bd-a1b2 --claim

# 给 Agent 提供当前任务上下文
bd prime

# 完成任务
bd close bd-a1b2 "Fixed"

真正落地时，`bd ready --json` 很关键。Agent 不应该凭感觉挑任务，而应该读取 ready 队列：依赖已满足、没人处理、优先级合适，才开始动手。

在 `AGENTS.md` 里不要只写“Use bd”。要把行为写清楚。

任务管理使用 Beads：
1. 开始前运行 bd ready --json，选择一个 ready 任务。
2. 修改代码前 claim 任务，避免并行冲突。
3. 如果发现新问题，用 bd create 记录，不要塞进聊天。
4. 任务完成后 bd close，并写清楚验证方式。
5. 没有 ready 任务时，不要自行发明大任务，先向人确认。

这段规则能明显降低多 Agent 乱跑。尤其是“发现新问题要建任务”这一条，把临时发现从聊天里捞出来，变成可追踪资产。

Beads 底层用 Dolt，提供类似版本控制的数据能力。多 Agent 场景下，任务数据库也会出现并发修改：一个 Agent 新建任务，另一个 Agent 关闭任务，第三个 Agent 在分支上认领任务。普通 JSON/Markdown 很容易冲突；结构化数据库更适合合并。

这不是花活。只要你让两个 Agent 同时干活，就会遇到“谁改了任务状态”的问题。代码有 Git，任务状态也应该有能合并的机制。

长期项目里，关闭任务会越来越多。它们有历史价值，但不应该每次都塞给 Agent。Beads 提到 semantic memory decay / compaction，思路是把旧任务压缩成摘要，保留关键结论，释放上下文窗口。这个方向很对：Agent 需要长期记忆，但不是全量记忆。

实际使用时可以设规则：最近一周任务保留详细记录；已关闭超过一个月的任务只保留摘要、关联 PR、关键决策；涉及安全/架构的任务单独保留。

太细：每个函数改动都建任务，Agent 一天都在切任务。太粗：“重构整个后端”，Agent 根本不知道从哪开始。好的任务应该能在一次会话或一个小 PR 内完成，并有明确验收标准。

另一个坑是只让 Agent 写 Beads，人类不看。任务系统要成为团队共同事实源，不然 Agent 写得再好也只是另一个黑盒日志。

Beads 的价值，是把 Agent 的“记性”从聊天窗口里挪出来，放进可查询、可合并、可同步的任务图。长项目要跑得稳，这一步迟早要补。