Appearance
Beads：让 AI 编码助手拥有持久记忆。Dolt 驱动的分布式图结构 Issue 追踪器，让 AI 在长周期任务中保持连贯记忆。
痛点：AI 助手的"失忆症"
当 AI 助手处理需要数小时甚至数天才能完成的长周期任务时，上下文窗口的限制导致它无法记住：
| 痛点 | 说明 |
|---|---|
| 任务优先级 | 无法记住任务的优先级和依赖关系 |
| 完成进度 | 哪些工作已经完成 |
| 阻塞关系 | 哪些任务在等待其他任务 |
| 问题解决 | 遇到过的具体问题和解决方案 |
传统解决方案：让 AI 维护一份 Markdown 计划文件
传统方案的问题：
- 无法追踪状态变化
- 无法处理跨分支的并发任务
- 无法优雅地处理合并冲突
Beads 的出现，就是为了彻底解决这个问题。
核心特性：Dolt 驱动的图结构记忆
Beads 的底层存储使用 Dolt——一个版本控制的 SQL 数据库。
三大核心能力
| 能力 | 说明 |
|---|---|
| 完整版本历史 | 每一次任务变更都被记录，可以随时回溯 |
| 分支与合并 | 支持多分支工作流，cell 级合并不会产生冲突 |
| SQL 查询能力 | 可以用 SQL 语句查询任务关系和状态 |
AI 优化的设计
| 优化 | 说明 |
|---|---|
| JSON 输出 | 便于 AI 解析和处理 |
| 依赖追踪 | 自动追踪任务间的阻塞关系 |
| 自动就绪检测 | bd ready 命令自动列出所有没有阻塞的任务 |
| 哈希 ID | bd-a1b2 这样的短 ID 避免多 Agent 环境下的合并冲突 |
核心命令速查
| 命令 | 功能 |
|---|---|
bd create <title> | 创建新任务 |
bd list | 列出所有任务 |
bd ready | 列出就绪任务（无阻塞） |
bd status <id> | 查看任务状态 |
bd complete <id> | 标记任务完成 |
bd log | 查看任务历史 |
创建任务
bash
# 创建简单任务
bd create "实现用户认证模块"
# 创建带描述的任务
bd create "实现用户认证模块" --desc "包含登录、注册、登出功能"
# 创建带依赖的任务
bd create "实现前端页面" --dep bd-a1b2查看任务
bash
# 列出所有任务
bd list
# 列出就绪任务（无阻塞）
bd ready
# 查看特定任务
bd status bd-a1b2完成任务
bash
# 标记完成
bd complete bd-a1b2
# 添加备注
bd complete bd-a1b2 --note "已完成登录和注册功能"Beads vs 传统方案
| 维度 | Beads | Markdown 计划文件 |
|---|---|---|
| 状态追踪 | ✅ 自动 | ❌ 手动 |
| 依赖关系 | ✅ 自动追踪 | ❌ 手动维护 |
| 并发任务 | ✅ 支持多分支 | ❌ 不支持 |
| 合并冲突 | ✅ cell 级合并 | ❌ 容易冲突 |
| 版本历史 | ✅ 完整历史 | ❌ 无 |
| AI 友好 | ✅ JSON 输出 | ⚠️ 需要解析 |
| SQL 查询 | ✅ 支持 | ❌ 不支持 |
安装方法
macOS
bash
brew install beads-clinpm
bash
npm install -g beads-cliDocker（本地 Dolt）
bash
docker pull dolthub/dolt-sql
docker run -d -p 3306:3306 dolthub/dolt-sql初始化
bash
# 初始化 Beads 仓库
bd init
# 配置 Dolt 数据库
bd config set db-url localhost:3306适用场景
| 场景 | 推荐原因 |
|---|---|
| 长周期任务 | 需要数小时/数天完成的任务 |
| 多 Agent 协作 | 多个 AI 同时工作 |
| 复杂依赖 | 任务间有复杂的依赖关系 |
| 需要回溯 | 任务变更需要历史记录 |
不适用场景
| 场景 | 原因 |
|---|---|
| 简单任务 | 单轮就能完成的任务 |
| 单 Agent 短期 | 不需要持久记忆的场景 |
存储模式对比
Beads 支持多种存储模式：
| 模式 | 说明 | 适用场景 |
|---|---|---|
| 本地 Dolt | 本地 Dolt 数据库 | 个人使用 |
| 远程 Dolt | 远程 Dolt 服务器 | 团队协作 |
| GitHub Dolt | GitHub 托管的 Dolt | 开源项目 |
| DoltHub | DoltHub 云服务 | 需要托管 |
配置远程存储
bash
# 配置远程 Dolt
bd config set db-url your-dolt-server:3306
bd config set db-name my-project-beads
# 配置 GitHub Dolt
bd config set db-url https://github.com/yourname/dolt-repo与 AI 助手的集成
Claude Code 集成
bash
# 在 Claude Code 中使用
/claude "用 Beads 创建任务追踪"
Claude: 使用 bd create 创建任务Codex 集成
bash
# 在 Codex 中使用
/codex "用 Beads 管理这个重构任务"
Codex: 使用 bd create 创建任务自动任务追踪
bash
# 开启自动追踪
bd config set auto-track true
# 开启后，AI 的每次操作都会被记录语义压缩：上下文优化
问题
长周期任务会产生大量中间记录，消耗上下文窗口。
解决方案
Beads 提供语义压缩功能：
| 压缩类型 | 说明 |
|---|---|
| 历史摘要 | 将多个操作压缩为一个语义单元 |
| 状态快照 | 只保留关键状态点 |
| 依赖简化 | 简化已完成的依赖链 |
使用方法
bash
# 压缩历史
bd compress --since 2024-01-01
# 快照当前状态
bd snapshot "里程碑1完成"多 Agent 支持
问题
多个 AI Agent 同时工作时，会产生冲突。
Beads 的解决方案
| 机制 | 说明 |
|---|---|
| 短哈希 ID | bd-a1b2 避免长 ID 冲突 |
| Cell 级合并 | 最小合并单元，减少冲突 |
| 分支隔离 | 每个 Agent 可以在独立分支工作 |
| 冲突检测 | 自动检测并提示冲突 |
多 Agent 工作流
bash
# Agent 1 创建分支
bd branch create agent-1
bd checkout agent-1
bd create "Agent 1 的任务"
# Agent 2 创建分支
bd branch create agent-2
bd checkout agent-2
bd create "Agent 2 的任务"
# 合并
bd merge agent-1
bd merge agent-2一句话总结
Beads = AI 编码助手的持久记忆系统。
核心价值：
- Dolt 驱动的图结构任务追踪
- 完整版本历史 + 分支合并
- 依赖自动追踪 + 就绪检测
- 多 Agent 并发支持
适用场景：长周期任务、多 Agent 协作、复杂依赖关系、需要回溯的项目。
