AI 写代码写到一半就＂失忆＂?这个开源工具给它装上了永不丢失的项目经理大脑

Beads：给 AI 编程助手装上「项目经理大脑」的开源分布式任务追踪器

快速摘要

核心结论：Beads 是一个专为 AI 编程助手（如 Claude Code、Codex）设计的开源任务追踪系统，底层由版本控制 SQL 数据库 Dolt 驱动，能让多个 AI Agent 协同处理复杂项目时不丢失上下文、不产生任务冲突。 它的 GitHub 地址为 https://github.com/gastownhall/beads，官方文档见 https://gastownhall.github.io/beads/，目前 Star 数已超过 22,000。

关键信息速览：

它解决了什么问题？ 多 Agent 并行工作时，任务上下文频繁丢失、优先级混乱、合并冲突频发。

底层技术是什么？ Dolt —— 一个支持 Git 式分支与合并的版本控制 SQL 数据库，实现单元格级智能合并。

怎么上手？ 一行命令安装，bd init 初始化，告诉 AI 助手使用 bd 即可。

适合谁用？ 重度使用 Claude Code、Cursor、Codex 等 AI 编程工具的开发者，以及探索多 Agent 工作流的技术人员。

👇 往下看有架构原理的完整拆解、操作步骤和社区生态介绍。

一、AI 编程助手「失忆」问题有多严重

在正式介绍 Beads 之前，我们先聊清楚它究竟在解决什么痛点，这对理解它的设计选择非常重要。

现在大家用 Claude Code、Codex 等 AI 编程助手处理项目的方式，往往是这样的：在对话里描述一个任务，AI 执行一部分，然后你关掉终端或者上下文窗口满了，下次重新打开，AI 对之前做了什么一无所知。于是你要重新解释背景，重新描述进度，重新确认优先级……这个过程耗费的精力，有时候比任务本身还多。

当项目规模更大、涉及多个 AI Agent 并行工作时，问题会指数级放大。假设你让 Agent A 负责前端功能开发，Agent B 负责 API 接口实现，Agent C 负责数据库迁移，三者都在同一个代码仓库里工作。谁先执行？任务之间有依赖关系吗？某个 Agent 修改了共享的任务状态，另一个 Agent 知道吗？如果两个 Agent 同时更新同一条任务记录，数据会不会损坏？

以前大家的应对方式，要么是用 Jira 这类重量级项目管理工具——但 Jira 的 API 对 AI 来说太复杂，集成成本极高；要么是维护一个 TODO.md 文件——但 Markdown 文件没有依赖关系图，没有版本控制，多个 Agent 同时写的时候极容易出现内容冲突甚至数据损坏。

Beads 就是在这个夹缝中诞生的。

二、Beads 是什么，它从哪里来

Beads 的完整定义是：一个为 AI 编程助手打造的分布式图状任务追踪器（Distributed Graph Issue Tracker for AI Agents），由 gastownhall 团队开发，命令行工具名为 bd。

它并不是在现有项目管理工具上做二次封装，而是从零开始、完全围绕 AI Agent 的使用习惯重新设计的。所有命令都原生支持 –json 输出，AI 解析起来几乎没有额外负担；任务 ID 采用哈希生成的短码（如 bd-a1b2c），避免多 Agent 并行工作时的 ID 命名冲突；bd ready 命令可以一键返回当前所有「没有阻塞依赖」的可执行任务列表，AI 不需要自己去梳理优先级逻辑。

从更宏观的视角看，Beads 是一个叫做 Gas Town 的大型开源项目的底层基石。Gas Town 的目标是成为 AI Coding 领域的多 Agent 工作空间管理器，而 Beads 承担的角色是整个系统的「记忆层」——它负责持久化任务状态，确保每一个 Agent、每一次会话、每一次重启之后，项目的全貌都不会消失。

三、底层原理：Dolt 是什么，为什么选它

理解 Beads 的关键，在于理解它所依赖的底层数据库：Dolt。

大多数任务管理工具选择 SQLite 或 MySQL 作为存储后端，原因很简单——这两者成熟稳定，生态完善。但 Beads 选择了一条不同的路：使用 Dolt，一个被称为「Git for Data」的版本控制 SQL 数据库。

Dolt 的核心理念可以用一句话概括：它是 MySQL 和 Git 的结合体。你可以用标准的 SQL 语句查询和写入数据，同时可以像操作 Git 仓库一样对数据库进行 branch（分支）、commit（提交）、merge（合并）、push（推送）、pull（拉取）等操作。

在技术实现上，Dolt 使用了一种叫做 Prolly Tree（Probabilistic B-tree）的新型数据结构来存储表数据。这种结构的特点是：每个版本的表都拥有一个不可变的内容寻址哈希，使得两个不同版本之间的差异可以被高效计算，从而支持真正意义上的「单元格级合并」——也就是说，当两个 Agent 分别修改了同一条任务记录的不同字段时，Dolt 可以像 Git 合并代码一样智能地将两个修改合并，而不是简单地以最后写入的版本覆盖。

下面这张图展示了 Beads 的数据同步流程：

本地 .beads/ 目录（Dolt 数据库）
        ↕ 每次写操作自动 Dolt commit
本地 Dolt 提交历史（类似 Git log）
        ↕ bd dolt push / bd dolt pull
远端 Dolt 仓库（DoltHub 或自建 remote）
        ↕ 多机器、多 Agent 共享

Dolt 提供两种运行模式，Beads 都支持：

嵌入式模式（Embedded Mode）：Dolt 作为进程内库运行，无需外部服务器，数据存储在 .beads/embeddeddolt/ 目录下，通过文件锁保证单写安全。这是大多数个人开发者的首选，零配置即用。
服务器模式（Server Mode）：连接到外部运行的 dolt sql-server，数据存储在 .beads/dolt/ 目录下，支持多进程并发写入。适合团队协作场景或需要多个 Agent 同时修改任务状态的复杂工作流。

对于想在 Claude Code 这类沙箱环境中使用的开发者，Beads 还支持通过 Unix 域套接字连接 Dolt 服务端，避免端口冲突，也更容易在网络受限的环境中工作。

四、核心架构：依赖感知的图状数据结构

Beads 与普通任务管理工具最根本的区别，在于它对任务关系的建模方式。

普通的待办清单（包括大多数 Markdown TODO 文件）把任务组织成一个线性列表，最多加上优先级标签。Beads 不同，它把任务组织成一张有向无环图（DAG，Directed Acyclic Graph），任务与任务之间可以存在多种类型的关系：

• blocks：「A blocks B」意味着 B 依赖 A，A 没完成，B 就不能开始执行
• relates_to：两个任务在语义上相关，但没有硬依赖
• duplicates：标识重复任务，系统会在合并时自动处理依赖引用的重写
• supersedes：新任务替代旧任务
• discovered-from：当 AI 在执行任务过程中发现了新的子任务，可以用这个关系类型记录「发现来源」，保留任务的追溯链路

这种图状结构带来了一个关键能力：bd ready 命令。它会遍历整张任务图，找出所有「没有未完成前置依赖」的任务，即时返回可执行列表。对于 AI Agent 来说，这意味着它不需要自己去读取全部任务信息、理解依赖关系、判断哪些可以并行——Beads 已经帮它做完了。

# 查看当前所有可执行任务（无阻塞依赖）
bd ready
# 以 JSON 格式输出，供 AI 程序化读取
bd ready --json
# 包含延迟任务
bd ready --include-deferred --json

每个任务节点在 Beads 中包含以下核心字段：

字段	说明
id	哈希生成的唯一短码，如 bd-a1b2c
title	任务标题
description	详细描述
status	状态：open / in_progress / closed
priority	优先级 0（最高）到 4（最低）
type	类型：bug / feature / task 等
assignee	认领该任务的 Agent 标识
due	截止时间
defer	延迟时间（在此时间前从 bd ready 列表中隐藏）

五、记忆压缩机制：解决上下文窗口瓶颈

AI 模型的上下文窗口虽然在持续扩大，但对于一个跨越数周、涉及几百条任务记录的长期项目来说，把所有历史信息都塞进上下文仍然是一种浪费。Beads 为此设计了记忆压缩（Compaction）机制。

压缩的逻辑是：对已经关闭（closed）超过一定时间的旧任务，自动生成语义摘要并替代原始的详细记录。完整的历史数据仍然保存在 Dolt 的提交历史中，随时可以通过版本回溯查看，但日常使用中 AI 看到的是压缩后的精简版本，大幅减少了 Token 消耗。

# 预览哪些任务会被压缩（不执行）
bd admin compact --dry-run --all
# 压缩 90 天前已关闭的任务
bd admin compact --days 90
# 执行 Dolt 垃圾回收，清理无效数据
cd .beads/dolt && dolt gc

这个设计思路其实与大脑的工作记忆机制有些相似：近期发生的事情记得清晰，久远的历史只保留关键摘要，按需才去翻档案。

六、从零开始上手 Beads

安装

Beads 支持多平台（macOS、Linux、Windows、FreeBSD），提供多种安装方式：

# macOS 推荐：Homebrew
brew install beads
# 通用快速安装脚本（macOS/Linux/FreeBSD）
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
# NPM
npm install -g @beads/bd
# Go 直接安装（需要本地 Go 环境）
go install github.com/gastownhall/beads/cmd/bd@latest

安装完成后，可以运行 bd –version 验证是否成功。

初始化项目

进入你的项目目录，执行：

cd your-project
bd init

这会在项目根目录下创建一个 .beads/ 目录，其中包含 Dolt 数据库文件。如果你的项目使用 Git，建议把 .beads/ 加入 .gitignore，因为任务数据的同步走 Dolt 自己的通道，而非 Git。

接着，告诉你的 AI 助手使用 Beads 来管理任务：

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

AGENTS.md 是 Claude Code 等工具会读取的配置文件，这一行指令会让 AI 知道它需要通过 bd 命令来查询和更新任务，而不是自己维护 Markdown 列表。

创建与管理任务

# 创建一个 P0 紧急任务
bd create "实现用户认证模块" -p 0-t feature
# 创建一个 P1 的 Bug 任务，带详细描述
bd create "修复数据库连接池泄漏" -p 1-t bug -d "在高并发场景下连接未被正确释放"
# 创建一个延迟任务（明天才在 ready 列表中显示）
bd create "编写 API 文档" --defer=tomorrow
# 查看所有可执行任务
bd ready
# 认领任务（原子操作：同时设置 assignee 和 status=in_progress）
bd update bd-a1b2c --claim
# 或者手动指定认领者
bd update bd-a1b2c --claim --assignee agent-frontend
# 添加任务依赖关系（a1b2c 依赖 d3e4f 先完成）
bd dep add bd-a1b2c bd-d3e4f
# 查看任务详情（包含完整审计历史）
bd show bd-a1b2c
# 关闭任务
bd close bd-a1b2c "功能已实现并通过测试"

值得一提的是 –claim 标志：它是一个原子操作，会同时把任务的 assignee 设为当前 Agent 标识，并将状态改为 in_progress。在多 Agent 并发场景下，这个原子性非常重要——可以避免两个 Agent 同时认领同一任务。

任务状态的完整生命周期

一个典型的任务生命周期如下：

[创建] open
    ↓ bd update --claim
[执行中] in_progress
    ↓ bd close
[完成] closed
    ↓ bd admin compact（若干天后）
[摘要归档]

如果任务执行过程中发现了新的子任务，AI 可以用 discovered-from 依赖类型记录：

# 在执行 bd-a1b2c 过程中发现了 bd-x9y8z 这个新问题
bd dep add bd-x9y8z bd-a1b2c --type discovered-from

七、多 Agent 协作：零冲突的实现原理

这是 Beads 最核心的技术价值所在，也是它与普通任务管理工具本质不同的地方。

在多 Agent 协作场景中，Beads 的工作方式是：每个 Agent 在自己的工作范围内独立修改任务状态，每次写操作（bd create、bd update、bd close 等）都会自动提交一个 Dolt commit，形成本地的提交历史。当 Agent 完成一段工作后，通过 bd dolt push 把本地的 Dolt 历史推送到远端共享仓库；其他 Agent 通过 bd dolt pull 拉取最新状态，Dolt 的单元格级合并算法负责解决潜在的写入冲突。

整个流程与 Git 的分支协作模型高度一致，开发者无需额外学习新的协作范式。

# Agent 完成工作后推送
bd dolt push
# 其他 Agent 同步最新状态
bd dolt pull
# 查看同步状态
bd ready  # 自动使用最新数据

对于更复杂的场景，可以使用 Dolt 的原生分支功能：让每个 Agent 在独立分支上工作，通过 PR 方式合并，完全模拟代码协作的流程，把任务管理和代码管理统一在同一套工作流里。

哈希 ID 的设计也值得单独提一下。传统工具的任务 ID 通常是自增整数（Task-1、Task-2……），在多写入方场景下极易产生冲突。Beads 使用基于内容哈希的短码（如 bd-a1b2c），每个任务的 ID 在全局范围内唯一，无论哪个 Agent 在哪台机器上创建，都不会产生 ID 碰撞。

八、与 Claude Code 的深度集成

Beads 为 Claude Code 提供了一套完整的插件方案，安装后可以在 Claude Code 内直接使用斜杠命令操作任务，无需切换终端。

# 在 Claude Code 中安装插件
/plugin marketplace add gastownhall/beads
/plugin install beads

安装后，Claude Code 会通过 MCP（Model Context Protocol）服务器与 Beads 通信，可用的斜杠命令包括：

/beads:init          — 在当前项目中初始化 Beads
/beads:create        — 创建新任务
/beads:ready         — 查看可执行任务列表
/beads:show          — 查看任务详情
/beads:update        — 更新任务状态
/beads:close         — 关闭任务
/beads:stats         — 查看项目整体进度统计
/beads:workflow      — 显示 AI 监督工作流指南

此外，插件还提供了一个 @task-agent 自治模式：Agent 会自动循环执行「找到可执行任务 → 认领 → 执行 → 发现子任务 → 关闭 → 继续下一个」的完整工作流，无需人工干预每个步骤。

在使用 Claude Code 的过程中，有一个细节值得注意：默认情况下，每次 Beads MCP 服务器执行命令，Claude Code 都会弹出确认提示。这是安全机制，但在高频操作时会打断工作流。可以在项目的 Claude 配置中设置信任该工具，以减少不必要的确认步骤。

九、社区生态：围绕 Beads 涌现的工具矩阵

Beads 的开源社区活跃程度出乎意料，围绕它已经涌现出一批实用工具：

beads-sdk：由社区开发者 @HerbCaudill 维护的 TypeScriptSDK，零运行时依赖，提供高层次的 BeadsClient，封装了任务的增删改查、依赖管理、标签、评论、Epic 等功能。通过 pnpmadd @herbcaudill/beads-sdk 安装。
Foolery：本地 WebUI，提供可视化的任务编排界面，支持依赖感知的「波次规划」（WavePlanning）、内置终端实时监控 Agent 状态、已完成任务的验证队列，以及键盘优先的导航方式。
Thread：只读的取证与分析层，读取本地 Dolt 历史，生成包含「忠实度评分」「返工成本指标」「会话合规评分」的 HTML 报告，帮助团队复盘 Agent 的工作质量。
ListaBeads：功能完整的 VSCode 扩展，提供可过滤的树形视图、任务详情面板、带指标的仪表盘、依赖图谱可视化、CodeLens 引用高亮，以及与 AzureDevOps、GitHubIssues、Jira、Linear、GitLab 的多平台同步。
beads-orchestration：专为 ClaudeCode 设计的多 Agent 编排技能包，Orchestrator 会自动调查任务、分配给技术专项 Agent，支持通过钩子强制执行工作流规范。
MardiGras / beads-ui / perles：多款终端 UI 和本地 Web 界面，满足不同偏好的可视化需求。

这些工具的存在说明 Beads 并不只是一个 CLI 工具，而是一个逐渐成形的 AI Agent 任务管理生态系统的核心。

十、备份、迁移与无 Git 模式

备份与迁移

Beads 提供了内置的备份命令，方便在不同机器或项目之间迁移任务数据：

# 设置备份目标目录
bd backup init /path/to/backup
# 执行备份同步
bd backup sync
# 在新项目中恢复数据
bd init
bd backup restore --force /path/to/backup

无 Git 模式

Beads 不强制依赖 Git。对于没有 Git 仓库的项目，可以通过环境变量和启动参数绕过 Git 相关操作：

# 指定数据库目录，不走 Git repo 发现逻辑
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth
# 之后所有核心命令正常工作
bd create"修复认证 Bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd close bd-a1b2 "已修复"

–stealth 标志会在配置中设置 no-git-ops: true，禁用所有 Git 钩子安装和 Git 相关操作，让 Beads 以纯 Dolt 模式运行。

数据库直接查询

对于想要深度集成的开发者，Beads 支持直接执行 SQL 查询：

# 用标准 SQL 查询任务数据
bd query"SELECT id, title, status, priority FROM issues WHERE status = 'open' ORDER BY priority"

这使得构建自定义报表、数据分析脚本或第三方集成变得非常灵活。

十一、一点个人体会

在黑龙江节点云计算科技公司备考人工智能训练师的那段时间，我接触到了大量关于 AI 工作流设计、人机协同效率的理论知识，也亲眼看到了很多团队在引入 AI 编程工具之后，任务管理这块反而成了新的瓶颈——不是因为 AI 能力不够，而是因为整个协作流程缺乏一个结构化的记忆载体。AI 做得越多，「接力棒」交接的摩擦就越大。Beads 让我觉得这个问题终于有了一个工程上认真对待的解法，而不是靠堆 Prompt 打补丁。

对于普通开发者来说，Beads 的上手门槛并不高，只要你熟悉基本的命令行操作，按照文档一步步来，一个下午就能把它融入现有的工作流。对于深度使用 Claude Code 的用户，Beads 的插件集成让整个多 Agent 项目的管理体验有了质的改变：你可以放心地把一个复杂项目拆成几十个任务，交给 AI 去认领和执行，而不用担心它在某次会话结束后就把之前的进度全忘了。

十二、局限性与注意事项

任何工具都有它的适用边界，Beads 也不例外。

在 Dolt 后端迁移（从早期的 SQLite 迁移到 Dolt）的过程中，有用户反映迁移体验不够顺畅，甚至有 AI 助手在尝试配置过程中建议放弃使用 Beads 转而使用 GitHub Issues。不过目前最新版本的 Beads 已经稳定在 Dolt 后端，不再依赖 SQLite，新用户从头开始不会遇到这个历史包袱问题。

另外，每个项目的 .beads/ 数据库是相互隔离的，任务 ID 无法跨项目引用。如果你需要同时追踪多个子项目的任务并建立跨项目依赖，解决方案是在父目录层级初始化一个统一的 Beads 数据库，让所有子项目共享这个数据库。

使用嵌入式 Dolt 模式（默认模式）时，同一时刻只支持单一写入者（通过文件锁强制），不适合真正的多进程并发写场景。如需多进程同时写入，需要切换到服务器模式并手动运行 dolt sql-server。

十三、总结

Beads 在 AI Agent 工具链这个快速演进的领域里，找到了一个非常精准的切入点：不是替代 AI，而是给 AI 提供一个不会丢失的结构化记忆。它选择 Dolt 作为底层，把数据库的版本控制能力和 Git 的分布式协作模式结合在一起，构建出一套让多 Agent 能够真正高效协同的任务管理基础设施。

如果你只是偶尔让 AI 帮忙写个脚本、改个函数，Beads 对你来说可能过于复杂。但如果你开始用 AI 处理真正多步骤、跨会话、需要多个 Agent 分工配合的复杂工程项目，Beads 值得认真了解和尝试。

项目地址：https://github.com/gastownhall/beads
官方文档：https://gastownhall.github.io/beads/
Dolt 数据库：https://github.com/dolthub/dolt