Beads

在构建复杂的 AI 代理（Agent）应用时，我们常面临一个棘手问题：如何管理长期任务的上下文？

传统的 Markdown 计划文件往往变得杂乱无章，代理容易在多轮对话中迷失方向，忘记之前的依赖关系或任务状态。Beads (bd) 是一个专为 AI 代理设计的分布式图谱问题追踪器，底层由 Dolt（版本控制的 SQL 数据库）提供支持。

Beads 用具有依赖感知的知识图谱取代了混乱的文本计划，赋予代理持久化、结构化的记忆能力，使其能够处理跨越数天甚至数周的复杂任务，而不会丢失关键上下文。

为什么选择 Beads？

🧠 结构化记忆，而非混乱文本

• 图谱链接：通过知识图谱的关系链接，明确任务间的阻塞、相关和父子关系。
• 依赖感知：代理能自动识别哪些任务已就绪（bd ready），哪些仍在等待前置条件。
• JSON 原生输出：专为 LLM 设计，提供机器可读的结构化数据，减少解析错误。

🔄 基于 Dolt 的版本控制

• 单元格级合并：利用 Dolt 的强大能力，支持细粒度的数据合并，避免传统数据库的覆盖冲突。
• 原生分支与同步：支持任务规划的分支开发，通过 Dolt 远程仓库轻松同步状态。
• 零冲突 ID：基于哈希的任务 ID 确保在多代理、多分支工作流中永远不会发生 ID 冲突。

📉 智能上下文压缩

• 记忆衰减：自动总结旧的、已关闭的任务，释放宝贵的上下文窗口，让代理专注于当前活跃任务。

📨 内置消息传递

• 线程与委派：支持类似邮件的消息问题类型，允许代理之间进行线程化沟通和任务委派。

快速开始：30 秒接入你的 Agent

Beads 是一个全局 CLI 工具，无需克隆到每个项目中。

1. 安装

# macOS / Linux (推荐)
brew install beads

# 或者使用安装脚本
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

2. 初始化

在你的项目目录中运行：

cd your-project
bd init

3. 告诉你的代理

在项目的 AGENTS.md 或系统提示中添加：

Use 'bd' for task tracking. 
- Check `bd ready` for available tasks.
- Use `bd create` to add new tasks.
- Use `bd update <id> --claim` to start working.

核心工作流：像 Git 一样管理任务

Beads 的命令设计直观且强大，完美契合 Agent 的操作逻辑。

层次化 ID 系统

Beads 支持史诗（Epic）-> 任务（Task）-> 子任务（Subtask）的层级结构：

• bd-a3f8：史诗
• bd-a3f8.1：任务
• bd-a3f8.1.1：子任务

这种结构帮助代理更好地分解复杂目标。

高级配置：适应各种开发场景

🕵️ 隐身模式（Stealth Mode）

如果你不想将 Beads 数据库提交到主 Git 仓库（例如个人实验或敏感规划）：

bd init --stealth

这会在本地存储数据，忽略 Git 操作。

👥 贡献者与维护者模式

• 贡献者：在 Fork 的仓库中运行 bd init --contributor，将规划数据路由到独立目录（如 ~/.beads-planning），避免污染 Pull Request。
• 维护者：Beads 自动检测 SSH/HTTPS 权限，支持直接推送到主仓库。

💾 存储模式：嵌入式 vs 服务器

1. 嵌入式模式（默认，推荐单人/单代理）

Dolt 在进程内运行，无需外部服务器。

bd init

• 数据位置：.beads/embeddeddolt/
• 特点：单写入者，文件锁定，简单易用。

2. 服务器模式（推荐团队协作/多代理并发）

连接到外部 dolt sql-server，支持多并发写入。

bd init --server

• 配置连接：

  bd init --server --server-host 127.0.0.1 --server-port 3307
  

• Unix 域套接字：使用 --server-socket 避免端口冲突，适合沙箱环境。

🚫 无 Git 环境支持

Beads 不强制依赖 Git。你可以将其用于非 Git 版本控制系统（如 Sapling, Jujutsu）或 CI/CD 隔离环境。

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

# 所有核心功能照常使用
bd create "Fix auth bug" -p 1
bd ready --json

备份与迁移

使用 bd backup 轻松管理数据：

# 初始化备份
bd backup init /path/to/backup

# 同步数据
bd backup sync

# 恢复数据
bd backup restore --force /path/to/backup