beads

Beads (bd)

面向 AI 编码 Agent 的分布式、由 Dolt 提供支持（类似 Git）的图谱问题跟踪器。通过依赖感知型任务跟踪实现持久记忆。

快速开始

安装：brew install beads，或使用 GitHub repo 中的安装脚本／二进制文件。

# Initialize in repo (humans run once)
bd init

# Tell your agent
echo "Use 'bd' for task tracking" >> AGENTS.md

适用场景

• AI Agent 需要跨会话持久保存任务记忆
• 跟踪任务间的依赖关系（blocks:、depends_on:）
• 多 Agent／多分支工作流（基于哈希的 ID 可避免冲突）
• 通过 molecules／gates 实现增量交付
• 与 GitLab、Linear、Jira、GitHub 同步问题

常用命令

命令	操作
bd ready	列出没有未解决阻塞项的任务
bd ready --explain	说明任务为何已就绪或尚未就绪
bd ready --gated	列出在 gate 检查点等待的任务
bd ready --exclude-type=X	排除指定的问题类型
bd create "Title" -p 0	创建 P0 任务
bd show <id>	查看任务详情和审计记录
bd update <id> --status=X	更新状态（open/in_progress/done）
bd close <id>	关闭任务
bd close <id> --claim-next	关闭当前任务并领取下一个
bd dep add <child> <parent>	关联任务（阻塞、相关、父级）
bd list	列出问题（默认：50 个，不包括已关闭的问题）
bd list --format json	JSON 输出（--json 的别名）
bd show --current	显示当前活跃问题（无需 ID）
bd update <id> --claim	原子式领取问题以开展工作
bd heartbeat <id>	延长领取的租约（v1.3.0）
bd reclaim --older-than=10m	将已过期的租约恢复为就绪状态（v1.3.0）
bd unclaim <id>	归还领取的任务（v1.3.0）
bd update <id> --if-status=S	CAS 更新：仅在状态匹配时应用
bd note <id> "text"	追加备注（简写）
bd import -i <file>	增量导入 JSONL
bd sync	拉取、解决冲突、重新计算并推送
bd events	读取持久化事件日志（v1.3.0）
bd serve	提供 HTTP API 服务（v1.3.0）
bd dolt pull	拉取最新数据库更改（高级）
bd dolt push	推送数据库更改（高级）
bd bootstrap	修复／引导工作区身份信息
bd context	显示当前工作区／任务上下文
bd kv set <key> <value>	存储键值对
bd kv get <key>	获取已存储的值
bd dolt show	显示 Dolt 连接／远程设置
bd config set-many	一次应用多项配置更改
bd ado sync	与 Azure DevOps 工作项同步
bd ado status	检查 Azure DevOps 同步状态
bd ado projects	列出 Azure DevOps 项目
bd gitlab sync	与 GitLab 同步
bd github sync	与 GitHub Issues 同步
bd remember	写入持久的 Agent 记忆
bd recall	读取持久的 Agent 记忆
bd purge	删除已关闭的临时 beads（wisps）

基于哈希的 ID

问题使用 bd-a1b2 这类基于哈希的 ID，以避免合并冲突：

bd create "Fix login bug" -p 1
# Created: bd-x7k3

bd show bd-x7k3

层级 ID

bd-a3f8      (Epic)
bd-a3f8.1    (Task)
bd-a3f8.1.1  (Sub-task)

使用 bd children <id> 查看层级结构。

参考资料

文件	用途
workflow.md	日常操作、状态流转、同步
authoring.md	编写质量问题、EARS 模式
molecules.md	分子、门控、公式、化合物
sync.md	Dolt 同步、升级和集成

关键概念

将 Dolt 用作数据库

Beads 将问题存储在 Dolt 数据库中。团队同步通过 Dolt 风格的 pull/push 完成，而不是将 JSONL 文件提交到仓库历史记录中。

依赖关系图

bd dep add bd-child bd-parent --blocks   # child blocks parent
bd dep add bd-a bd-b --related           # related items
bd ready                                 # only shows unblocked work

分子（进阶）

分子将相关问题组合在一起，并通过门控实现增量交付：

bd mol create "Feature X" --steps=3      # Create 3-step molecule
bd mol progress bd-xyz                   # Check progress
bd mol burn bd-xyz                       # Complete molecule

隐身模式

在本地使用 Beads，而不提交到仓库：

bd init --stealth

贡献者与维护者

# Contributor (forked repos) — separate planning repo
bd init --contributor

# Maintainer auto-detected via SSH/HTTPS credentials

配置

配置存储在 .beads/config.yaml 中：

具体架构会随版本演进。建议使用 CLI 辅助工具检查并验证当前设置：

• 使用 bd dolt show 查看当前 Dolt 连接和远程设置
• 使用 bd dolt test 验证连接
• 使用 bd doctor / bd doctor --deep 进行健康检查

存储后端（Dolt）

Beads 使用 Dolt 作为其主要后端。根据设置，Dolt 可以以以下方式运行：

• 嵌入式（单写入者，无守护进程）
• 服务器模式（多写入者）

使用 bd doctor（以及适用时的 bd doctor --server）验证环境。对于旧版存储，请使用 bd migrate 工作流。

Agent 集成

告知 Agent 使用 Beads

添加到 AGENTS.md：

## Task Tracking

Use `bd` for task tracking. Run `bd ready` to find work.

面向 Agent 优化的输出

BD_AGENT_MODE=1 bd list --json  # Ultra-compact JSON output
bd list --json                   # Standard JSON output

MCP 插件

Beads 包含 Claude Code MCP 插件，可直接集成。

版本亮点（1.2.2）

• 修复版本：v1.2.0/v1.2.1 发布时未经发布测试；v1.2.2 以更高版本号重新发布经过测试的 1.1 系列，因此所有安装渠道都会切换到经过测试的代码。仅适用于 1.2.x 的功能（工作租约、事件日志、同步联邦、HTTP API 服务、来源事件）不包含在此版本中——这些功能将在经过测试的未来版本中回归。
• 如果你运行过 v1.2.1 并遇到 schema version mismatch: database is at v65, binary knows up to v53：请将架构游标回退到 v53（参见 docs/RECOVERY-1.2.1.md），或使用临时方案 BD_IGNORE_SCHEMA_SKEW=1——参见 references/sync.md。请先将每台机器/克隆都升级到 v1.2.2，再进行恢复，否则遗留的 1.2.1 二进制文件会在不提示的情况下重新迁移数据库。

版本亮点（1.1.0）

• 更安全的迁移：增加架构变更检测，避免数据库迁移静默应用，并在所有层强制执行只读限制。
• 同步修复：修复此前存在问题的拉取合并；压缩现在会先归档，再丢弃信息。
• 新增命令/标志：新增 bd metrics（带有征求同意的提示）和幂等的 --init-if-missing 初始化。

版本亮点（1.0.3–1.0.4）

• 工作流/配置易用性：bd -C 会在运行前更改工作目录；bd close 新增 --reason-file；设置/引导流程改进了远程/服务器配置处理。
• Linear 同步：OAuth 客户端凭据、幂等标记、陈旧数据提示、按工作区设置同步锁、更丰富的类型映射，以及批量创建/更新，让大型同步循环更安全、更快速。
• 安全/导出默认设置：Beads 现在拒绝将密钥写入 Git 跟踪的配置；默认情况下，导出会排除记忆和临时 wisps，除非你选择将它们重新纳入。
• 依赖项/数据路径：JSONL 批量添加依赖项，以及多项钩子/引导/初始化修复，减少了自动化和共享服务器环境中的阻碍。

发行亮点（1.0.0–1.0.2）

• 分发：预编译二进制文件现已支持 Linux、macOS（Intel/Apple Silicon）、Windows（AMD64/ARM64）、Android/Termux 和 FreeBSD。
• 自动化：bd init --non-interactive / --role 和 bd bootstrap --non-interactive 改进了 CI/云端 Agent 的设置。
• 工作流：bd ready --explain、bd config set-many、批量依赖列表和逗号分隔的状态筛选器提升了 Agent 使用体验。
• 编写/建模：spike、story 和 milestone 现已成为一等议题类型；自定义状态/类型已移至规范化表。
• 集成/同步：GitLab 同步改进了去重和 epic→milestone 映射，ADO 同步支持更多筛选条件，嵌入式/共享服务恢复也更加安全。

发行亮点（0.62.0–0.63.3）

• Azure DevOps 集成：用于工作项跟踪的 bd ado CLI 命令（sync、status、projects）。
• 嵌入式 Dolt 支持：无需运行中的 Dolt 服务即可执行 dep、duplicate、epic、graph、supersede、swarm 操作。
• 自定义状态类别：配置 active/wip/done/frozen 状态分组。
• bd note 命令：向议题追加备注的简写命令。
• --exclude-type 标志：在 bd ready 和 bd list 中按议题类型筛选。
• --format json 别名：可替代 --json 标志，保持一致性。
• 审计日志：记录关闭原因；状态变更会记录到 interactions.jsonl。
• 导出/导入中的记忆：往返操作会包含 Agent 记忆。
• Init 默认值：AGENTS.md 默认采用 minimal 配置；新增 --agents-profile 标志。
• 质量/生命周期命令：已在 prime、template 和 doctor 中提供。
• 关闭时验证：--validate 会检查 --acceptance 字段；提供 validation.on-close 配置。

发行亮点（0.61.0）

• bd close --claim-next 缩短了 Agent 常见的关闭并领取下一项任务的流程。
• bd create 新增 --skills、--context 和 --no-history，用于创建更丰富的任务，并可选择不记录 Dolt 历史。
• bd import 新增增量 JSONL 导入，支持可移植性和恢复工作流。
• bd init / bd bootstrap 可根据仓库的 git origin 自动检测 Beads 数据库。
• Dolt/服务模式同步改进了凭据传递、运行时端口报告和运行状况检查。
• 配置和备份处理更加安全，包括正确合并项目与用户配置，以及支持 BD_BACKUP_ENABLED=false。

关键命令

# What to work on
bd ready                    # Unblocked tasks
bd ready --pretty           # Formatted output

# Create with dependencies
bd create "Task B" --blocks bd-a1b2
bd create "Task C" --context "Need schema review" --skills "python,sql"

# Doctor (fix issues)
bd doctor                   # Check health
bd doctor --fix             # Auto-fix problems

bd sync                     # Sync DB state
bd import -i backup.jsonl   # Incremental JSONL import

bd dolt pull                # Pull latest changes (advanced)
bd dolt push                # Push to remote (advanced)

反模式

❌ 错误	✅ 正确
priority: high	-p 1（P0-P4 数字值）
手动编辑 JSON	使用 bd 命令
忽略 bd ready	始终先检查阻塞项
跳过 bd sync	工作前后都进行同步
创建时不声明依赖	提前声明 --blocks

链接

• 发行版本
• 文档
• 社区工具