Beads：给 AI 编程 Agent 装上「项目经理大脑」的开源工具，底层原理与完整操作指南

本文由 莫潇羽@源码七号站（www.fuyuan7.com）原创撰写，转载请注明出处。

快速摘要

核心结论：Beads 是一个专门为 AI 编程助手设计的分布式图状任务追踪系统，底层以版本控制数据库 Dolt 作为存储引擎，通过依赖感知的图结构管理任务，解决多 Agent 协作时上下文丢失、任务冲突、状态不持久等根本性问题。它不依赖 Jira 这样的重量级平台，也不像 Markdown 那样结构松散，而是让每一个 AI Agent 都拥有持久化、可追溯、可合并的「项目记忆」。

关键信息速览：

• 项目地址：https://github.com/gastownhall/beads，目前已获得超过 22.4K Star，近期登上 GitHub Trending 榜单
• 核心技术：基于 Dolt（Git 风格的版本控制 SQL 数据库）作为存储后端
• 命令行工具：bd（Beads CLI），一次安装、全局使用
• 适用场景：Claude Code、Codex 等 AI 编程助手处理长期复杂项目、多 Agent 并行协作
• 安装方式：支持 Homebrew、NPM、curl 脚本、Go 源码编译等多种方式

往下看有更详细的原理拆解和命令操作手册。本文包含完整的底层原理分析（Dolt Prolly Tree、三路合并机制）、从零开始的安装配置步骤、全量命令参考手册，以及适合真实项目的多 Agent 协作实战场景示例，内容较长，建议收藏后按需查阅。

一、AI 编程 Agent 的任务管理困境

在正式介绍这个工具之前，有必要先说清楚它的适用边界：Beads 是一个开发者工具，它的目标用户是那些正在用 AI 编程助手处理真实工程项目的开发者，不是面向普通用户的消费级产品。如果你每天只是用 AI 写写短代码片段、回答几个技术问题，Beads 对你来说可能过于重量级；但如果你正在尝试把一整个功能模块、甚至一个完整项目的开发过程交给 AI 来自主推进，那么接下来的内容会对你很有参考价值。

在 AI 编程助手刚出现的早期，一个 Agent 接到一个任务、写几十行代码、返回结果，这套流程简单直接，几乎不需要额外的任务管理机制。但随着 Claude Code、OpenAI Codex、Cursor 这类工具越来越成熟，工程师开始把整个项目交给 AI 来推进，甚至同时启动多个 Agent 分别处理不同模块，情况就彻底变了。

上下文窗口的天花板问题。哪怕是目前最强的大模型，上下文窗口再大也是有限的。当一个项目的任务列表、代码历史、讨论记录塞进同一个对话时，Agent 在处理后续任务时会悄悄"遗忘"早期的关键决策。你让它"接着上次的进度实现支付模块"，它可能完全不记得上次已经约定了用哪套 API 风格，于是重新来了一套，和前面的代码风格完全不一致。更糟糕的情况是，之前已经标记为"不做"的方案，它在新的对话里可能又重新开始实现，造成大量重复劳动。

多 Agent 并发写入的冲突问题。当你同时让 Agent A 负责前端、Agent B 负责后端 API、Agent C 负责数据库设计时，它们各自维护一份自己的"任务理解"，没有任何共享的状态中心，任务 ID 会重复、依赖关系会断掉，更严重的是它们可能在同一个时间点都去做同一件事，或者都在等对方做完之后才能继续——但谁也不知道对方做完了没有。这种"互相等待又互相不知情"的死锁状态，是多 Agent 协作中最令人抓狂的场景之一。

现有工具的两难困境。面对这些问题，工程师通常有两条路可走，但两条路都不好走。

其一，用 Jira 这类企业级项目管理工具。Jira 的功能固然强大，但它是为人类团队设计的，有复杂的权限体系、工作流配置和 UI 交互。让 AI Agent 直接操作 Jira API 不仅集成成本高，而且 AI 调用 REST API 的出错率让人头疼，返回的 JSON 层级之深往往让 Agent 在解析上就耗尽了大量 Token。

其二，用 Markdown 文件记录任务。这是最常见的临时解法——在项目根目录放一个 TODO.md，让 AI 来更新它。但 Markdown 是纯文本，它没有事务保证，两个 Agent 同时写同一行会导致内容损坏；它没有依赖图，AI 无法自动判断哪个任务现在是可以执行的；它没有历史版本，一旦 AI 把某个已完成的任务标记删掉，这条记录就永远消失了。

还有一个容易被忽视的问题是任务发现的碎片化。AI Agent 在执行任务的过程中，往往会发现一些新问题、新需求——比如在实现登录功能时发现了一个隐藏的权限漏洞，或者在写测试时发现原有接口文档有遗漏。这些"途中发现的工作"如果没有一个系统性的地方记录下来，要么被 Agent 在当前会话里附带处理掉（但没有记录），要么就被遗忘了，等到下次开新会话时谁也不知道这件事曾经被发现过。

这些问题加在一起，构成了一个相当棘手的工程困境：AI Agent 越强大、越自主，任务管理和上下文同步的问题就越突出。你不可能一直坐在电脑前盯着 AI 工作，但如果你不盯着，就很可能回来发现它做了一堆重复的事、跳过了关键的前置步骤、或者完全搞不清楚现在项目进展到哪里了。

正是在这样的背景下，Beads 出现了。它从设计之初就把 AI Agent 作为唯一的使用者，不是把人类的项目管理工具"适配"给 AI，而是专门为 AI 的使用模式重新设计了一套任务管理范式。

二、Beads 是什么：定位与核心概念

Beads 的全称是"分布式图状任务追踪器"（Distributed Graph Issue Tracker），由 gastownhall 团队开发，是其更大愿景项目 Gas Town 的底层记忆系统。Gas Town 被设计为 AI 编程协作领域的基础设施平台，而 Beads 是这个平台中负责"记住所有任务"的那个大脑。

从使用者角度来说，Beads 提供了一个名为 bd 的命令行工具。你在项目目录里跑一句 bd init，它就在当前项目下创建一个 .beads/ 目录，这里面存放着这个项目所有任务的结构化数据。之后，不管是你手动创建任务，还是让 AI Agent 自主创建和认领任务，所有操作都通过 bd 这个工具来完成。

"Bead"这个词本身是"珠子"的意思——每一个任务就像一颗珠子，珠子和珠子之间通过"线"（依赖关系）串联在一起，形成一条有序的项目进展链条。这个比喻很形象：你不是在管理一张平铺的清单，而是在维护一串结构清晰、前后有序的任务链。

值得一提的是，Beads 是更大愿景项目 Gas Town 的底层基石。Gas Town 的目标是构建一个完整的多 Agent 协作平台，类似于容器编排领域的 Kubernetes——负责调度、路由、监控多个 AI Agent 的协同工作。在这个体系里，Beads 扮演的角色是"记忆层"：它不关心 Agent 怎么执行任务，只负责记住所有任务的状态、依赖关系和历史变更，为上层的调度系统提供持久化的基础数据。这也是为什么 Beads 的设计非常克制——它只做任务管理这一件事，但把这件事做到了专业级别。

Beads 解决的核心问题可以归纳为三点：

首先是持久化记忆。AI Agent 重启、对话结束、甚至机器重启，任务状态都不会丢失，因为它们存储在本地的版本控制数据库里，不依赖任何对话上下文。

其次是依赖感知。任务不是孤立的列表项，而是一张有向图。Beads 会自动追踪哪些任务依赖哪些任务，bd ready 命令能立刻告诉 AI 哪些任务现在是可以执行的（即没有未完成的前置依赖），不需要 AI 自己去梳理优先级。

第三是多 Agent 无冲突协作。借助底层 Dolt 数据库的单元格级合并能力，多个 Agent 可以在各自的数据库分支上独立工作，最后像合并代码一样合并任务数据，理论上将冲突降到最低。

三、核心底层原理：Dolt 数据库深度解析

要真正理解 Beads 为什么能做到这些，必须先搞明白它的底层存储引擎——Dolt。

3.1 Dolt 是什么

Dolt 是由 DoltHub 公司开发的一款开源数据库，其官方自我介绍非常简洁："Git 和 MySQL 生了一个孩子。" 它完全兼容 MySQL 的 SQL 查询语法，可以像使用普通关系型数据库一样对它执行 SELECT、INSERT、UPDATE、DELETE 等操作；同时，它还支持 Git 风格的版本控制操作，包括 commit（提交）、branch（分支）、merge（合并）、push（推送）、pull（拉取）、diff（查看差异）等。

换句话说，在 Dolt 里，版本不是文件的版本，而是数据库表格行级别的版本。你可以回滚到三天前某个特定 commit 时数据库的状态，也可以创建一个新分支来做试验性的数据修改，最后再合并回主分支。

对于习惯使用 Git 的开发者来说，Dolt 的操作几乎是零学习成本的：

# Git 的操作           →   Dolt 的等价操作
git add .             →   dolt add .
git commit -m "msg"   →   dolt commit -m "msg"
git log               →   dolt log
git diff              →   dolt diff
git branch feat       →   dolt branch feat
git checkout feat     →   dolt checkout feat
git merge feat        →   dolt merge feat
git push              →   dolt push
git clone <url>       →   dolt clone <url>

唯一的区别是：Git 版本化的是文件，Dolt 版本化的是数据库表的行。这个类比一旦理解，Dolt 的整套操作体系就豁然开朗了。

Dolt 还提供了一个 DoltHub 平台（类似于 GitHub），用于托管和分享公开的 Dolt 数据库。但对于 Beads 的使用场景来说，你并不需要 DoltHub——Beads 直接复用你已有的 GitHub 或 GitLab 仓库来存储任务数据，不需要额外注册任何第三方服务。

3.2 Dolt 的底层数据结构：Prolly Tree

Dolt 能实现行级版本控制，背后依赖的是一种名为 Prolly Tree（概率树）的数据结构。这是 Dolt 团队在 Noms 项目的基础上发展出来的独特技术，是传统 B-Tree 的一个变种。

普通数据库使用 B-Tree 存储数据，B-Tree 的内部结构依赖于数据的插入顺序，这意味着同样的数据集如果插入顺序不同，生成的 B-Tree 结构也会不同，因此无法对两棵 B-Tree 进行有意义的内容差异比较（diff）。

而 Prolly Tree 的关键特性是历史独立性：无论数据以何种顺序插入，只要最终的数据集相同，生成的 Prolly Tree 结构就相同。这个特性使得 diff 操作变得高效——比较两个版本的差异，只需要比较各自的 Prolly Tree 根节点的内容哈希，不一致的节点才需要继续深入比较，从而把时间复杂度从 O(n) 降低到接近 O(k)（k 为实际变更的行数）。

在 Dolt 的具体实现中，每一张表都有两棵 Prolly Tree：一棵存储表的数据（以主键为索引键），另一棵存储表的 Schema（字段定义）。这两棵树的根节点哈希组合在一起，形成该表在某个时刻的唯一内容地址。当你对数据库执行 dolt commit 时，Dolt 会把所有表的内容地址汇总起来形成一个提交节点，写入提交图（commit graph）。这个提交图的结构和 Git 的提交图完全一致，每个节点指向父节点，形成可以无限追溯的历史链条。

正是这套底层的 Prolly Tree 结构，让 Dolt 能够做到单元格级别的三路合并（3-way merge）。当两个分支分别修改了同一行记录的不同字段时，Dolt 可以识别出这是两个不冲突的修改并自动合并；只有当同一个字段被两个分支以不同方式修改时，才会触发真正的合并冲突。这一点对于 Beads 的多 Agent 并发写入场景非常关键——Agent A 修改了某个任务的"认领者"字段，Agent B 修改了同一任务的"优先级"字段，这两个操作完全不冲突，Dolt 会自动合并。

3.3 Dolt 的两种运行模式

在 Beads 中，Dolt 以两种模式运行，理解这两种模式的区别对于正确配置多 Agent 环境非常重要：

嵌入式模式（Embedded Mode，默认）。这是大多数用户的推荐选择。Dolt 以进程内嵌方式运行，不需要启动独立的数据库服务器进程。任务数据存放在 .beads/embeddeddolt/ 目录下。这种模式使用文件锁（flock）来保证单写入者，防止并发写入导致数据损坏。对于单台机器上的单个 Agent 场景，这种模式足够高效稳定。

服务器模式（Server Mode）。当你需要在同一台机器上让多个 Agent 并发写入同一个项目的任务数据库时，需要切换到服务器模式。此时 Beads 会连接到一个独立运行的 dolt sql-server 进程，数据存放在 .beads/dolt/ 目录下。服务器模式天然支持多并发写入，Dolt 的 MVCC（多版本并发控制）机制负责保证事务一致性。

服务器模式还支持 Unix Domain Socket 连接方式，通过 --server-socket 参数指定 socket 文件路径，从而避免多个项目的服务器进程之间发生端口冲突，在 Claude Code 这类沙箱化的运行环境中尤其实用。

3.4 版本控制与同步机制

Beads 写入任务数据时，每一次写操作（bd create、bd update、bd close 等）都会自动生成一个 Dolt commit，这意味着任务变更历史是完整且可追溯的，就像代码的 git log 一样。

跨机器同步方面，Beads 复用了你已有的 Git 远程仓库。Dolt 将任务数据存储在 refs/dolt/data 这个引用下，与普通的 Git 代码引用（refs/heads/main 等）互不干扰，因此可以指向同一个 GitHub/GitLab 远程仓库地址，不需要额外的存储服务：

# 添加远程同步目标（复用 Git 仓库）
bd dolt remote add origin git+ssh://git@github.com/org/repo.git

# 推送任务数据到远程
bd dolt push

# 从远程拉取最新任务数据
bd dolt pull

对于已有 Beads 数据的仓库，新成员克隆后需要手动引导初始化，因为标准 git clone 不会自动拉取 refs/dolt/data 引用下的数据：

git clone <repo_url>
cd <repo>
bd bootstrap   # 自动检测并初始化 Dolt 数据库
bd list        # 验证任务数据已拉取

四、系统架构与工作原理

4.1 整体架构层次

从整体来看，Beads 的架构可以分为三个层次：

命令行接口层：用户（或 AI Agent）通过 bd 这个 CLI 工具与系统交互。bd 是一个用 Go 语言编写的二进制可执行文件，所有命令都支持 --json 参数输出机器友好的 JSON 格式，这让 AI Agent 可以方便地解析结果。bd 的设计原则是"最小认知负担"——官方在贡献指南里明确要求：每增加一个新命令或选项，都要充分论证是否有必要，因为命令越复杂，Agent 出错的概率就越高。

业务逻辑层：包含任务（Issue）的 CRUD 管理、依赖图（Dependency Graph）的维护、就绪任务检测（Ready Detection）、上下文压缩（Compaction）等核心功能。这一层负责把用户的高级意图（"给任务 A 添加依赖 B"）翻译成底层的 SQL 操作，同时维护数据的业务逻辑约束（比如不允许创建循环依赖）。

存储层：底层是 Dolt 数据库，任务数据以关系表的形式存储，版本控制、分支、合并由 Dolt 负责处理。存储层对业务逻辑层提供了两个关键保证：一是每次写操作都自动生成 Dolt commit，保证历史可追溯；二是并发写入时的事务隔离，保证数据一致性。

用户 / AI Agent
      │
      ▼
  bd CLI 命令
      │
      ▼
   业务逻辑层
 ┌──────────────┐
 │ 任务管理     │
 │ 依赖图计算   │
 │ 就绪检测     │
 │ 上下文压缩   │
 └──────────────┘
      │
      ▼
   Dolt 数据库
 ┌──────────────┐
 │ SQL 查询     │
 │ 版本控制     │
 │ 分支/合并    │
 │ 远程同步     │
 └──────────────┘
      │
      ▼
  .beads/ 目录
  (本地存储)

这个三层架构的好处是层次清晰，每一层都可以独立演进。比如，Beads 从 v0.50 开始把存储层从 SQLite 换成了 Dolt，业务逻辑层和 CLI 层基本不需要修改；如果未来社区想要提供 Web 界面，只需要在 CLI 层之上另建一个 HTTP API 层，不需要碰底层逻辑。

4.2 任务数据模型

每一个 Beads 任务（Issue）包含以下核心字段：

任务 ID     - 唯一哈希 ID，格式如 bd-a1b2c（5位字母数字组合）
标题        - 任务的简要描述
描述        - 可选的详细说明
优先级      - P0（紧急）/ P1（高）/ P2（中）/ P3（低）
类型标签    - bug / feature / task / chore 等
状态        - open / in-progress / closed
认领者      - 当前负责该任务的 Agent 或用户身份
依赖列表    - 该任务依赖的其他任务 ID 列表
链接关系    - relates_to / duplicates / supersedes / replies_to
历史记录    - 所有状态变更的完整审计日志（由 Dolt 自动维护）

任务 ID 采用哈希生成而非顺序自增，这是一个有意的设计决策。顺序自增 ID 在分布式写入时会产生竞争和冲突（两个 Agent 同时创建任务，都自称 ID=42），而哈希 ID 在数学上保证了全局唯一性，不需要任何中央协调机制。

优先级的设计借鉴了工程团队的惯例：P0 对应线上紧急故障级别，需要立刻处理；P1 是本迭代内必须完成的高优任务；P2 是常规功能开发；P3 是可以延后的低优先级事项。在 bd ready --json 的输出中，任务按优先级从高到低排列，AI Agent 拿到列表后默认应该优先处理排在最前面的任务。

任务类型（type）字段用于分类和过滤，常用的几个内置类型包括：bug（缺陷修复）、feature（新功能）、task（工程任务，如重构、配置、CI 等）、chore（日常杂务，如依赖更新、文档维护）。类型字段是自由文本，你也可以定义自己的类型标签来满足特定项目的分类需求。

审计日志是 Dolt 底层版本控制的自然产物——每次对任务的修改（状态变更、认领者变更、优先级调整等）都会自动生成一个 Dolt commit，这个 commit 里记录了变更时间、变更内容和执行者身份。通过 bd show <id> 查看任务详情时，这条完整的变更历史链一目了然，对于复杂项目的问题排查和决策追溯非常有价值。

4.3 依赖图的工作原理

Beads 的任务依赖关系在数据库层面以一张独立的关系表存储，记录每对「任务A 依赖 任务B」的关系。当你查询 bd ready 时，系统会对整个依赖图执行拓扑排序，找出所有入度为零（即没有未完成前置任务）的节点，这些节点就是当前可以开始执行的任务。

这个机制的价值在于，当一个 Agent 完成了某个任务并执行 bd close 时，系统自动重新计算依赖图，那些原本被这个任务阻塞的下游任务就会自动进入"就绪"状态，下一个执行 bd ready 的 Agent 就能立刻发现并认领它们。

4.4 任务认领的原子性保证

多 Agent 场景中，"两个 Agent 同时抢同一个任务"是个经典的竞争条件问题。Beads 通过 bd update <id> --claim 命令解决了这个问题。

--claim 操作在 Dolt 的事务层面是原子的：它会在单个数据库事务中同时完成「设置认领者 = 当前 Agent 身份」和「将任务状态从 open 切换为 in-progress」两个操作。即便两个 Agent 同时发起 claim，数据库的 MVCC 机制保证只有一个能成功，另一个会收到失败响应，然后重新查询 bd ready 去找下一个可用任务。

4.5 项目隔离机制

Beads 采用目录感知的项目隔离机制，工作方式类似于 Git：当你在某个目录下执行 bd 命令时，它会从当前目录向上层目录逐级查找 .beads/ 目录，找到的第一个就是当前项目的数据库。

这意味着你可以在同一台机器上为多个项目独立使用 Beads，各个项目的任务数据库互相隔离：

# 项目 A 的 Agent
cd ~/work/webapp && bd ready --json
# 使用 ~/work/webapp/.beads/ 数据库

# 项目 B 的 Agent
cd ~/work/api && bd ready --json
# 使用 ~/work/api/.beads/ 数据库

# 两者完全隔离，没有冲突

五、五大核心机制深度剖析

5.1 JSON 原生输出：AI 可直接解析

这是 Beads 最"接地气"的设计之一。每一个 bd 命令都内置了 --json 参数，输出规范的 JSON 格式数据。对于 AI Agent 来说，这意味着它不需要用字符串解析去猜测任务状态，直接拿到结构化数据就能进行下一步判断：

# 查询所有就绪任务，返回 JSON
bd ready --json

# 示例输出
{
  "issues": [
    {
      "id": "bd-a1b2c",
      "title": "实现用户登录功能",
      "priority": 0,
      "type": "feature",
      "status": "open",
      "dependencies": []
    },
    {
      "id": "bd-d3e4f",
      "title": "修复数据库连接超时",
      "priority": 1,
      "type": "bug",
      "status": "open",
      "dependencies": []
    }
  ]
}

AI Agent 只需把这个 JSON 交给自己的推理模块，立刻就能决定先做哪个任务，不需要解析任何自然语言描述。

5.2 记忆衰减（Compaction）：节省上下文窗口

Beads 有一个专门针对 AI 上下文窗口限制设计的功能——记忆衰减，也叫上下文压缩（Compaction）。

随着项目推进，会积累大量已关闭的历史任务。这些任务的详细记录对当前工作已经没有多少参考价值，但如果每次 AI 启动新会话时都把所有历史任务的完整数据塞进上下文，会白白浪费大量 Token，甚至可能让 AI 在历史任务的信息中迷失，搞不清楚哪些是正在进行的工作。

为了理解这个问题的严重性，可以做一个简单估算：假设一个项目累计创建了 200 个任务，每个任务平均有 150 字的标题+描述，加上状态、依赖关系等结构化字段，每个任务消耗约 300 个 Token，200 个任务就是 6 万个 Token。而目前主流大模型的上下文窗口一般在 10 万到 20 万 Token 之间，单是历史任务就能占据 30%~60% 的窗口空间，严重压缩了模型用于理解代码、分析问题的空间。

bd prime 命令（在文档中也被称为 Compaction）的工作原理是：扫描所有已关闭的历史任务，生成一份语义摘要，将大量细节压缩成几段关键结论，同时保留原始数据用于需要时的查询。AI Agent 在会话开始时调用 bd prime，拿到的是高度浓缩的项目历史摘要，而不是几百条任务的完整列表。

bd prime 的输出通常包括以下内容：

• 当前开放任务的总览（按优先级分组统计）
• 当前进行中任务的状态快照
• 最近已完成阶段的关键决策和结论（以摘要形式）
• 需要特别关注的阻塞项或风险任务

对于需要完整历史记录的场景（比如排查某个决策的来龙去脉），bd show <task_id> 仍然可以查看任意任务的完整审计日志，历史数据始终保存在 Dolt 数据库中，随时可以按需展开。

官方文档建议在 AGENTS.md 文件中加入以下指令，让 Agent 在每次会话开始时自动执行上下文恢复：

# AGENTS.md 中添加：
# At the start of every session, run:
# bd prime

5.3 图状链接：任务之间的语义关系网

任务不只是列表里的一行，它们之间有丰富的语义关联。Beads 支持以下四种图状链接类型：

relates_to（相关）：两个任务在业务上有关联，但没有严格的执行顺序依赖。比如"前端登录页面"和"后端认证 API"是相关任务，但可以并行开发。

duplicates（重复）：某个新任务和已有任务描述了同样的工作。AI Agent 在创建任务前，可以先检查是否已有重复任务存在，避免重复劳动。

supersedes（替代）：某个任务被一个更新的决策替代了。原来的任务不需要执行，但需要保留记录以便追溯为什么放弃了原来的方案。

replies_to（回复）：某个任务是对另一个任务的讨论或追踪。类似于 GitHub Issues 里的评论线程，但以独立任务的形式存在。

这些链接关系让 AI Agent 在理解任务背景时，不再只是看到孤立的一条描述，而是能看到整张知识图谱——这个任务是为了替代哪个旧方案，它和哪些模块的开发有关联，是否有人已经提过类似的需求。

用命令来创建这些链接：

# 标记任务 b 和任务 a 相关
bd link bd-b5c6d relates_to bd-a1b2c

# 标记任务 d 是任务 c 的重复
bd link bd-d7e8f duplicates bd-c3d4e

# 标记任务 f 替代了任务 e
bd link bd-f9g0h supersedes bd-c3d4e

5.4 Git 钩子自动集成：提交时自动关联任务

Beads 提供了可选的 Git 钩子集成，安装后每次 git commit 时，它会自动检测提交信息中是否包含任务 ID（格式如 bd-a1b2c），并将这次提交与对应任务关联起来。

# 安装 Git 钩子
bd hooks install

# 之后 git commit 时带上任务 ID
git commit -m "Fix auth validation bug (bd-a1b2c)"

关联记录存储在 Dolt 数据库中，后续可以通过 bd show bd-a1b2c 查看某个任务对应的所有代码提交历史，实现代码变更和任务进度的完整追踪。

bd doctor 命令可以检查项目健康状态，其中有一项专门检查"孤立任务"（orphaned issues）——即代码已经提交了但任务没有关闭的情况，帮助团队及时发现漏标状态的任务。

5.5 Formula（公式）系统：可复用的工作流模板

Beads 还有一个进阶功能叫做 Formula（公式）系统，这是为需要重复执行标准化流程的场景设计的。

公式用 TOML 格式定义一个工作流模板，包含多个步骤（wisps）。每次需要执行这个流程时，通过实例化公式来生成一组相互关联的任务，避免每次都手动重新创建同样的任务结构。

比如，你可以定义一个"标准功能开发流程"公式，包含"需求评审 → 接口设计 → 编码实现 → 单元测试 → 集成测试 → 文档更新"这几个步骤，每次开发新功能时，一条命令就能生成这六个有依赖关系的任务。一个简化的公式文件示例如下：

# formulas/feature-dev.toml
[formula]
name = "feature-dev"
description = "标准功能开发流程"

[[steps]]
title = "需求评审"
type = "task"
priority = 1

[[steps]]
title = "接口设计"
type = "task"
priority = 1
depends_on = ["需求评审"]

[[steps]]
title = "编码实现"
type = "feature"
priority = 1
depends_on = ["接口设计"]

[[steps]]
title = "单元测试"
type = "task"
priority = 2
depends_on = ["编码实现"]

[[steps]]
title = "文档更新"
type = "chore"
priority = 3
depends_on = ["编码实现"]

公式分为两种实例化方式：

根节点 Wisps（轻量级）：步骤在运行时动态生成，不预先创建所有子任务，适合流程步骤较多但每步相对独立的场景。

Poured Wisps（检查点恢复）：所有步骤提前以独立子任务的形式物化，每个子任务都有自己的状态，支持从任意检查点恢复，适合长时间运行、可能中途中断的任务流程。这种模式对于那些可能跨越数天、需要多次 Agent 会话才能完成的大型工程任务特别有价值，因为即便中途遭遇 Agent 宕机或会话中断，下次重新启动时只需要 bd prime 获取当前检查点，从断点继续即可。

六、完整安装与配置指南

6.1 安装 Beads CLI

Beads 的 CLI 工具 bd 需要全局安装一次，安装完成后可以在任意项目中使用，注意不要把 Beads 的代码仓库克隆进你的项目目录，它是一个独立的工具，不是项目依赖。

方式一：Homebrew（macOS/Linux，推荐）

brew install beads

Homebrew 是最稳定的安装方式，自动处理依赖和更新。

方式二：curl 快速安装脚本（macOS/Linux/FreeBSD）

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

这是最快的安装方式，适合在 CI 环境或服务器上快速部署。

方式三：NPM（需要 Node.js 环境）

npm install -g @beads/bd

适合前端开发者已有 Node.js 环境的场景。

方式四：Go 源码编译（适合需要最新开发版本）

go install github.com/gastownhall/beads/cmd/bd@latest

需要本地已安装 Go 工具链，编译的二进制会放在 $GOPATH/bin 目录下，确保该目录在系统 PATH 中。

安装完成后验证：

bd --version
# 输出类似：bd version 0.x.x

6.2 在项目中初始化 Beads

进入你的项目根目录，执行初始化命令：

cd your-project
bd init

bd init 会完成以下操作：

• 在当前目录创建 .beads/ 子目录
• 初始化 Dolt 数据库（默认为嵌入式模式）
• 检测当前目录是否为 Git 仓库，如果是则提示是否安装 Git 钩子
• 生成 .beads/config.yaml 配置文件

初始化完成后，.beads/ 目录结构大致如下：

.beads/
├── config.yaml          # Beads 配置文件
├── embeddeddolt/        # 嵌入式 Dolt 数据库文件（默认模式）
│   ├── beads_<项目名>/  # 实际数据库目录
│   └── ...
└── metadata.json        # 记录当前使用的存储模式（embedded/server）

这个 .beads/ 目录本身建议提交到 Git 仓库（不要加入 .gitignore），这样团队成员克隆仓库后，通过 bd bootstrap 就能同步到已有的任务数据。但注意 Dolt 的历史数据存储在 refs/dolt/data 引用下，普通 git clone 不会自动拉取，需要额外执行 bd dolt pull 或 bd bootstrap。

如果不想要任何交互提示，使用安静模式：

bd init --quiet

如果项目不在 Git 仓库中，或者你希望完全绕开 Git 操作，使用隐身模式：

export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

--stealth 标志会禁用所有 Git 钩子安装和 Git 操作，适合在非 Git 项目或特殊环境中使用。这种模式下，bd 所有核心命令仍然完全可用，只是不会有任何 Git 相关的副作用。

6.3 配置自定义前缀

默认情况下，任务 ID 以 bd- 为前缀（如 bd-a1b2c）。如果你在同一台机器上管理多个项目，建议给每个项目设置不同前缀以便区分：

# 项目 webapp 使用 web- 前缀
cd ~/work/webapp && bd init --prefix web

# 项目 api 使用 api- 前缀
cd ~/work/api && bd init --prefix api

6.4 告诉 AI Agent 使用 Beads

这一步非常重要。大多数 AI 编程助手（Claude Code、Codex、Cursor 等）支持在项目目录下放置 AGENTS.md 或 CLAUDE.md 文件来提供行为指引。把以下内容加入你的指引文件：

echo "Use 'bd' for task tracking" >> AGENTS.md

更完整的 AGENTS.md 内容建议如下：

## 任务管理规范

使用 `bd`（Beads）进行任务追踪，不要用 Markdown 文件管理任务。

每次会话开始时执行：
- `bd prime` 获取项目上下文摘要
- `bd ready --json` 查看当前可执行任务

认领任务时执行：
- `bd update <id> --claim` 原子认领（避免与其他 Agent 竞争）

完成任务时执行：
- `bd close <id> "完成原因"` 关闭任务

发现新工作时执行：
- `bd create "任务描述" -p <优先级>` 创建新任务

6.5 配置跨机器同步

如果需要在多台机器之间同步任务数据，或者和团队成员共享任务状态，需要配置 Dolt 远程仓库：

# 方式一：通过 SSH 使用现有 GitHub 仓库（推荐，更安全）
bd dolt remote add origin git+ssh://git@github.com/yourname/your-repo.git

# 方式二：通过 HTTPS
bd dolt remote add origin https://github.com/yourname/your-repo.git

之后就可以像操作 Git 一样推送和拉取任务数据：

bd dolt push    # 推送任务数据到远程
bd dolt pull    # 从远程拉取最新任务数据

七、核心命令完整操作手册

7.1 任务创建

bd create 是最常用的命令，用于创建新任务：

# 基础语法
bd create "任务标题" [选项]

# 常用选项：
# -p <0-3>     优先级（0=紧急，1=高，2=中，3=低）
# -t <类型>    任务类型（bug/feature/task/chore）
# --description="详细描述"  添加详细描述
# --json       返回 JSON 格式结果

# 创建 P0 紧急任务
bd create "修复线上支付接口崩溃" -p 0 -t bug

# 创建带详细描述的功能任务
bd create "实现用户头像上传" -p 2 -t feature \
  --description="支持 JPG/PNG 格式，最大 5MB，需要压缩处理"

# 创建任务并以 JSON 格式返回（AI Agent 使用）
bd create "添加单元测试" -p 2 -t task --json

7.2 查看任务列表

# 列出所有任务
bd list

# 只列出开放任务
bd list --status open

# 只列出进行中的任务
bd list --status in-progress

# 按优先级过滤
bd list -p 0     # 只显示 P0 任务
bd list -p 1     # 只显示 P1 任务

# 按类型过滤
bd list -t bug   # 只显示 bug 类型

# JSON 格式输出（AI Agent 使用）
bd list --json

# 查看就绪任务（没有未完成前置依赖的任务）
bd ready
bd ready --json  # JSON