Beads - AI Agent 的持久任务记忆
基于图的问题跟踪器，在对话压缩后仍有数据留存。为跨多个会话、具有复杂依赖关系的工作提供持久记忆。
概述
bd (beads) 用存储在 Git 中的依赖关系感知图取代了 Markdown 任务列表。与 TodoWrite（会话范围）不同，bd 会在压缩后仍然存在并跟踪复杂依赖关系。
关键区别:
- bd: 多会话工作、存在依赖关系、在压缩后幸存、基于 Git
- TodoWrite: 单会话任务、线性执行、仅限于会话
核心能力:
- 📊 依赖图: 跟踪什么阻塞什么 (blocks, parent-child, discovered-from, related)
- 💾 压缩生存: 当对话历史被压缩时任务仍然存在
- 🐙 Git 集成: 问题版本化在
.beads/issues.jsonl中，通过bd sync同步 - 🔍 智能发现: 自动查找可开始的工作 (
bd ready)，被阻塞的工作 (bd blocked) - 📝 审计追踪: 状态更改、备注和决策的完整历史
- 🏷️ 丰富的元数据: 优先级 (P0-P4)、类型 (bug/feature/task/epic)、标签、负责人
何时使用 bd 与 TodoWrite:
- ❓ “两周后我还需要这个上下文吗？” → 是 = bd
- ❓ “对话历史会被压缩吗？” → 是 = bd
- ❓ “它有阻塞项/依赖关系吗？” → 是 = bd
- ❓ “这是模糊/探索性工作吗？” → 是 = bd
- ❓ “这个会话内能完成吗？” → 是 = TodoWrite
- ❓ “这只是我当前的一个任务列表吗？” → 是 = TodoWrite
决策规则: 如果两周后恢复工作没有 Beads 会很困难，请使用 bd。
前提条件
必需的:
- bd CLI: 0.34.0 或更高版本，已安装并在 PATH 中
- Git 仓库: 当前目录必须是 Git 仓库
- 初始化: 必须运行一次
bd init（由人类执行，而非 Agent）
验证安装:
bd --version # 应返回 0.34.0 或更高版本
首次设置（人类运行一次）:
cd /path/to/your/repo
bd init # 创建 .beads/ 目录并初始化数据库
可选的:
- BEADS_DIR 环境变量用于指定备用数据库位置
- 守护进程用于后台同步:
bd daemon --start
说明
会话开始协议
每一个会话，从这里开始:
步骤 1: 检查可开始的工作
bd ready
显示没有未关闭阻塞项的任务，按优先级排序 (P0 → P4)。
显示内容:
- 任务 ID (例如
myproject-abc) - 标题
- 优先级
- 问题类型 (bug, feature, task, epic)
示例输出:
claude-code-plugins-abc [P1] [task] open
Implement user authentication
claude-code-plugins-xyz [P0] [epic] in_progress
Refactor database layer
步骤 2: 选择最高优先级的任务
选择准备就绪的任务中优先级最高 (P0 > P1 > P2 > P3 > P4) 的任务。
步骤 3: 获取完整上下文
bd show <task-id>
显示:
- 完整的任务描述
- 依赖图 (什么阻塞此任务，此任务阻塞什么)
- 审计追踪 (所有状态更改、备注)
- 元数据 (创建时间、更新时间、负责人、标签)
步骤 4: 开始工作
bd update <task-id> --status in_progress
标记任务正在积极处理中。
步骤 5: 工作时添加备注
bd update <task-id> --notes "已完成: X。进行中: Y。被阻塞: Z"
对于压缩生存至关重要: 写备注时要像向一个没有对话上下文的未来 Agent 解释一样。
备注格式（最佳实践）:
已完成: 具体的交付物（例如“实现了 JWT 刷新端点 + 速率限制”）
进行中: 当前状态 + 立即执行的下一步
阻塞项: 阻止进展的事项
关键决策: 重要的上下文或用户指导
任务创建工作流
何时创建任务
在以下情况下创建 bd 任务:
- 用户提及跨会话跟踪工作
- 用户说“我们应该修复/构建/添加 X”
- 工作有依赖项或阻塞项
- 探索/研究边界模糊的工作
基本任务创建
bd create "任务标题" -p 1 --type task
参数:
- 标题: 简要描述 (必需的)
- 优先级: 0-4，0=关键，1=高，2=中，3=低，4=积压 (默认: 2)
- 类型: bug, feature, task, epic, chore (默认: task)
示例:
bd create "修复认证错误" -p 0 --type bug
创建附带描述
bd create "实现 OAuth" -p 1 --description "为 Google、GitHub、Microsoft 添加 OAuth2 支持。使用 passport.js 库。"
史诗及其子任务
# 创建父级史诗
bd create "Epic: OAuth 实现" -p 0 --type epic
# 返回: myproject-abc
# 创建子任务
bd create "研究 OAuth 提供商" -p 1 --parent myproject-abc
bd create "实现认证端点" -p 1 --parent myproject-abc
bd create "添加前端登录 UI" -p 2 --parent myproject-abc
更新和进度工作流
更改状态
bd update <task-id> --status <新状态>
状态值:
open- 未开始in_progress- 正在积极处理blocked- 卡住，等待某些事项closed- 已完成
示例:
bd update myproject-abc --status blocked
添加进度备注
bd update <task-id> --notes "此处的进度更新"
追加到现有备注字段（不会替换）。
更改优先级
bd update <task-id> -p 0 # 提升为关键
添加标签
bd label add <task-id> backend
bd label add <task-id> security
标签提供了超越状态/类型的跨领域分类。
依赖管理
添加依赖关系
bd dep add <子任务> <父任务>
含义: <父任务> 阻塞 <子任务>（父任务必须先完成）。
依赖类型:
- blocks: 父任务必须关闭，子任务才能变为可开始状态
- parent-child: 层级关系 (epics 和 subtasks)
- discovered-from: 任务 A 导致发现任务 B
- related: 任务相关但不阻塞
示例:
# 部署被测试通过阻塞
deploy-task test-task # 测试任务阻塞部署任务
查看依赖关系
bd dep list <task-id>
显示:
- 此任务阻塞了什么 (依赖方)
- 什么阻塞了此任务 (阻塞项)
循环依赖预防
bd 自动防止循环依赖。如果尝试创建循环，命令将失败。
完成工作流
关闭任务
bd close <task-id> --reason "完成摘要"
最佳实践: 始终包含描述已完成工作的原因。
示例:
bd close myproject-abc --reason "已完成: 实现了 OAuth 端点，包含 Google、GitHub 提供商。测试通过。"
检查新解除阻塞的工作
关闭任务后，运行:
bd ready
关闭任务可能会解除对依赖任务的阻塞，使其变为可开始状态。
子任务完成后关闭史诗
bd epic close-eligible
自动关闭所有子任务都已关闭的史诗。
Git 同步工作流
一体化同步
bd sync
执行:
- 将数据库导出到
.beads/issues.jsonl - 提交更改到 Git
- 从远程拉取（如果需要则合并）
- 将更新后的 JSONL 导回数据库
- 将本地提交推送到远程
何时使用: 会话结束时、移交给队友前、取得重大进展后。
仅导出
bd export -o backup.jsonl
创建 JSONL 备份，无需 Git 操作。
仅导入
bd import -i backup.jsonl
将 JSONL 文件导入到数据库。
后台守护进程
bd daemon --start # 在后台自动同步
bd daemon --status # 检查守护进程健康状态
bd daemon --stop # 停止自动同步
守护进程监视数据库更改并自动导出到 JSONL。
查找和搜索命令
查找可开始的工作
bd ready
显示没有未关闭阻塞项的任务。
列出所有任务
bd list --status open # 仅开放任务
bd list --priority 0 # 仅 P0（关键）
bd list --type bug # 仅错误
bd list --label backend # 仅标记为“backend”
bd list --assignee alice # 仅分配给 alice
显示任务详情
bd show <task-id>
完整详情: 描述、依赖关系、审计追踪、元数据。
按文本搜索
bd search "authentication" # 搜索标题和描述
bd search login --status open # 结合过滤器
查找被阻塞的工作
bd blocked
显示所有有待处理阻塞项而无法进行的工作。
项目统计
bd stats
显示:
- 按状态分类的问题总数 (open, in_progress, blocked, closed)
- 按优先级分类的问题 (P0-P4)
- 按类型分类的问题 (bug, feature, task, epic, chore)
- 完成率
完整命令参考
| 命令 | 何时使用 | 示例 |
|---|---|---|
| 查找命令 | ||
bd ready | 查找未阻塞的任务 | 用户询问“我应该做什么？” |
bd list | 查看所有任务（带过滤器） | “显示所有开放的错误” |
bd show <id> | 获取任务详情 | “显示任务 bd-42” |
bd search <查询> | 跨任务文本搜索 | “查找关于 auth 的任务” |
bd blocked | 查找卡住的工作 | “什么阻塞了我们？” |
bd stats | 项目指标 | “有多少任务开放？” |
| 创建命令 | ||
bd create | 跟踪新工作 | “为这个错误创建一个任务” |
bd template create | 使用问题模板 | “从错误模板创建任务” |
bd init | 初始化 beads | “在此仓库中设置 beads”（仅限人类） |
| 更新命令 | ||
bd update <id> | 更改状态/优先级/备注 | “标记为进行中” |
bd dep add | 链接依赖关系 | “此任务阻塞那个任务” |
bd label add | 添加标签 | “将其标记为 backend” |
bd comments add | 添加评论 | “向任务添加评论” |
bd reopen <id> | 重新打开已关闭的任务 | “重新打开 bd-42，发现回归问题” |
bd rename-prefix | 重命名问题前缀 | “将前缀从 bd- 更改为 proj-” |
bd epic status | 检查史诗进度 | “显示史诗完成百分比” |
| 完成命令 | ||
bd close <id> | 标记任务为完成 | “关闭此任务，已完成” |
bd epic close-eligible | 自动关闭完成的史诗 | “关闭所有子任务完成的史诗” |
| 同步命令 | ||
bd sync | Git 同步（一体化） | “将任务同步到 Git” |
bd export | 导出到 JSONL | “备份所有任务” |
bd import | 从 JSONL 导入 | “从备份恢复” |
bd daemon | 后台同步管理器 | “启动自动同步守护进程” |
| 清理命令 | ||
bd delete <id> | 删除问题 | “删除测试任务”（需要 --force） |
bd compact | 存档旧的已关闭任务 | “压缩数据库” |
| 报告命令 | ||
bd stats | 项目指标 | “显示项目健康状况” |
bd audit record | 记录交互 | “记录此 LLM 调用” |
bd workflow | 显示工作流指南 | “如何使用 beads？” |
| 高级命令 | ||
bd prime | 刷新 AI 上下文 | “加载 bd 工作流规则” |
bd quickstart | 交互式教程 | “教我 beads 基础知识” |
bd daemons | 多仓库守护进程管理 | “管理所有 beads 守护进程” |
bd version | 版本检查 | “检查 bd 版本” |
bd restore <id> | 恢复已压缩的问题 | “从 Git 获取完整历史” |
输出
此技能会产生:
任务 ID: 格式 <前缀>-<哈希> (例如 claude-code-plugins-abc, myproject-xyz)
状态摘要:
5 open, 2 in_progress, 1 blocked, 47 closed
依赖图 (可视化树):
myproject-abc: Deploy to production [P0] [blocked]
Blocked by:
↳ myproject-def: Run integration tests [P1] [in_progress]
↳ myproject-ghi: Fix failing tests [P1] [open]
审计追踪 (完整历史):
2025-12-22 10:00 - Created by alice (P2, task)
2025-12-22 10:15 - Priority changed: P2 → P0
2025-12-22 10:30 - Status changed: open → in_progress
2025-12-22 11:00 - Notes added: "Implemented JWT auth..."
2025-12-22 14:00 - Status changed: in_progress → blocked
2025-12-22 14:01 - Notes added: "Blocked: API endpoint returns 503"
错误处理
常见失败
1. bd: command not found
原因: bd CLI 未安装或不在 PATH 中 解决方案: 从 https://github.com/steveyegge/beads 安装
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# 或通过 npm
npm install -g @beads/bd
# 或通过 Homebrew
brew install steveyegge/beads/bd
2. No .beads database found
原因: 此仓库中未初始化 beads
解决方案: 运行 bd init（人类运行一次，Agent 不要运行）
bd init # 创建 .beads/ 目录
3. Task not found: <id>
原因: 无效的任务 ID 或任务不存在
解决方案: 使用 bd list 查看所有任务并验证 ID 格式
bd list # 查看所有任务
bd search <部分标题> # 通过标题查找任务
4. Circular dependency detected
原因: 尝试创建循环依赖（A 阻塞 B，B 阻塞 A） 解决方案: bd 会自动防止循环依赖。重新组织依赖图。
bd dep list <id> # 查看当前依赖关系
5. Git 在 .beads/issues.jsonl 中发生合并冲突
原因: 多个用户修改了同一个问题 解决方案: bd sync 会自动处理 JSONL 冲突。如果需要手动干预:
# 查看冲突
git status
# bd 提供冲突解决工具
bd sync --merge # 尝试自动解决
6. Database is locked
原因: 守护进程或其他进程持有排他锁 解决方案: 重启守护进程或等待锁释放
bd daemon --stop
bd daemon --start
7. 同步失败
原因: 网络问题、认证失败或 Git 配置问题 解决方案: 检查 Git 远程访问和凭据
git fetch # 测试连接
git status # 验证仓库状态
示例
...
[为翻译截断]