beads

Beads - AI Agent 的持久任务记忆

基于图的议题跟踪器，可在对话压缩后继续使用。为具有复杂依赖关系的多会话工作提供持久记忆。

bd 与 TodoWrite

判断标准：“两周后我还需要这些上下文吗？”需要 = bd，不需要 = TodoWrite。

bd（持久）	TodoWrite（临时）
多会话、依赖关系、可在压缩后继续使用	单会话线性任务
基于 Dolt 的团队同步	限于对话范围

详细对比请参阅 BOUNDARIES.md。

前置条件

bd --version  # Requires v0.60.0+

• bd CLI 已安装并位于 PATH 中
• Git 仓库（可选——使用 BEADS_DIR + --stealth 即可不依赖 git 运行）
• 初始化：运行一次 bd init（由人类执行，而非 Agent）

CLI 参考

运行 bd prime 获取针对 AI 优化的工作流上下文（由钩子自动加载）。 运行 bd <command> --help 查看特定命令的用法。

必备命令：bd ready、bd create、bd show、bd update、bd close、bd dolt push

会话协议

1. bd ready — 查找未被阻塞的工作
2. bd show <id> — 获取完整上下文
3. bd update <id> --claim — 原子地认领并开始工作
4. 工作过程中添加备注（这对在压缩后继续工作至关重要）
5. bd close <id> --reason "..." — 完成任务
6. bd dolt push — 推送到 Dolt 远程端（如已配置）

输出

在任何命令后添加 --json 可获取结构化输出。使用 bd show <id> --long 获取扩展元数据。状态图标：○ 开放 ◐ 进行中 ● 已阻塞 ✓ 已关闭 ❄ 已延期。

错误处理

错误	修复方法
database not found	在项目根目录运行 bd init <prefix>
not in a git repository	先运行 git init
disk I/O error (522)	将 .beads/ 移出云同步文件系统
状态更新滞后	使用服务端模式：bd dolt start

完整详情请参阅 TROUBLESHOOTING.md。

示例

跟踪一项跨多个会话的功能：

bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json                    # Shows unblocked work
bd update <id> --claim --json      # Claim and start
bd close <id> --reason "Implemented with refresh tokens" --json

压缩后恢复工作： bd list --status in_progress --json，然后运行 bd show <id> --long

在任务进行中发现工作项： bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json

高级功能

功能	CLI	资源
Molecules（模板）	bd mol --help	MOLECULES.md
Chemistry（pour/wisp）	bd pour、bd wisp	CHEMISTRY_PATTERNS.md
Agent beads	bd agent --help	AGENTS.md
异步门控	bd gate --help	ASYNC_GATES.md
Worktrees	bd worktree --help	WORKTREES.md

资源

类别	文件
入门	BOUNDARIES.md、CLI_REFERENCE.md（实时参考指针）、WORKFLOWS.md
核心概念	DEPENDENCIES.md、ISSUE_CREATION.md、PATTERNS.md
韧性	RESUMABILITY.md、TROUBLESHOOTING.md
高级	MOLECULES.md、CHEMISTRY_PATTERNS.md、AGENTS.md、ASYNC_GATES.md、WORKTREES.md
参考	STATIC_DATA.md、INTEGRATION_PATTERNS.md

验证

如果 bd --version 报告的版本高于 0.60.0，此技能可能已过时。运行 bd prime 获取最新 CLI 指南——它会随每次 bd 发布自动更新，是权威信息源（ADR-0001）。