Back to Details

beads

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Beads - Persistent Task Memory for AI Agents

Beads - AI Agent的持久化任务记忆

Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
基于图结构的问题跟踪工具，可在对话压缩后保留数据。为存在复杂依赖关系的多会话工作提供持久化记忆。

bd vs TodoWrite

bd 与 TodoWrite对比

Decision test: "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.
bd (persistent)TodoWrite (ephemeral)
Multi-session, dependencies, compaction survivalSingle-session linear tasks
Dolt-backed team syncConversation-scoped
See BOUNDARIES.md for detailed comparison.
决策测试：“我两周后还需要这个上下文吗？” 是 = 使用bd，否 = 使用TodoWrite。
bd（持久化）TodoWrite（临时）
多会话、支持依赖、可在压缩后保留数据单会话线性任务
基于Dolt的团队同步会话范围内有效
详细对比请查看 BOUNDARIES.md。

Prerequisites

前置条件

bash
bd --version  # Requires v0.60.0+
  • bd CLI installed and in PATH
  • Git repository (optional — use 
    BEADS_DIR
    + 
    --stealth
    for git-free operation)
  • Initialization: 
    bd init
    run once (humans do this, not agents)
bash
bd --version  # 需要 v0.60.0+
  • 已安装 bd CLI 并添加至PATH
  • Git仓库（可选 — 使用 
    BEADS_DIR
    + 
    --stealth
    参数可在无Git环境下操作）
  • 初始化：需手动执行一次 
    bd init
    （由人类操作，而非Agent）

CLI Reference

CLI参考

Run 
bd prime
 for AI-optimized workflow context (auto-loaded by hooks). Run 
bd <command> --help
 for specific command usage.
Essential commands: 
bd ready
, 
bd create
, 
bd show
, 
bd update
, 
bd close
, 
bd dolt push
执行 
bd prime
获取AI优化的工作流上下文（由钩子自动加载）。 执行 
bd <command> --help
获取特定命令的使用说明。
核心命令：
bd ready
, 
bd create
, 
bd show
, 
bd update
, 
bd close
, 
bd dolt push

Session Protocol

会话流程

  1. bd ready
    — Find unblocked work
  2. bd show <id>
    — Get full context
  3. bd update <id> --claim
    — Claim and start work atomically
  4. Add notes as you work (critical for compaction survival)
  5. bd close <id> --reason "..."
    — Complete task
  6. bd dolt push
    — Push to Dolt remote (if configured)
  1. bd ready
    — 查找未被阻塞的工作
  2. bd show <id>
    — 获取完整上下文
  3. bd update <id> --claim
    — 原子化操作：认领并开始工作
  4. 工作过程中添加备注（这对在压缩后保留数据至关重要）
  5. bd close <id> --reason "..."
    — 完成任务
  6. bd dolt push
    — 推送至Dolt远程仓库（若已配置）

Output

输出

Append 
--json
to any command for structured output. Use 
bd show <id> --long
for extended metadata. Status icons: 
○
open 
◐
in_progress 
●
blocked 
✓
closed 
❄
deferred.
在任意命令后添加 
--json
参数可获取结构化输出。使用 
bd show <id> --long
获取扩展元数据。状态图标：
○
未开始 
◐
进行中 
●
已阻塞 
✓
已完成 
❄
已延期。

Error Handling

错误处理

ErrorFix
database not found
bd init <prefix>
in project root
not in a git repository
git init
first
disk I/O error (522)
Move 
.beads/
off cloud-synced filesystem
Status updates lagUse server mode: 
bd dolt start
See TROUBLESHOOTING.md for full details.
错误信息修复方法
database not found
在项目根目录执行 
bd init <prefix>
not in a git repository
先执行 
git init
disk I/O error (522)
将 
.beads/
目录移至非云同步文件系统
状态更新延迟使用服务器模式：
bd dolt start
详细内容请查看 TROUBLESHOOTING.md。

Examples

示例

Track a multi-session feature:
bash
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
Recover after compaction: 
bd list --status in_progress --json
then 
bd show <id> --long
Discover work mid-task: 
bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json
跟踪跨会话的功能开发：
bash
bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json                    # 显示未被阻塞的工作
bd update <id> --claim --json      # 认领并开始工作
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

Advanced Features

高级功能

FeatureCLIResource
Molecules (templates)
bd mol --help
MOLECULES.md
Chemistry (pour/wisp)
bd pour
, 
bd wisp
CHEMISTRY_PATTERNS.md
Agent beads
bd agent --help
AGENTS.md
Async gates
bd gate --help
ASYNC_GATES.md
Worktrees
bd worktree --help
WORKTREES.md
功能CLI命令参考文档
Molecules（模板）
bd mol --help
MOLECULES.md
Chemistry（pour/wisp）
bd pour
, 
bd wisp
CHEMISTRY_PATTERNS.md
Agent beads
bd agent --help
AGENTS.md
Async gates
bd gate --help
ASYNC_GATES.md
Worktrees
bd worktree --help
WORKTREES.md

Resources

参考资源

CategoryFiles
Getting StartedBOUNDARIES.md, CLI_REFERENCE.md (live reference pointers), WORKFLOWS.md
Core ConceptsDEPENDENCIES.md, ISSUE_CREATION.md, PATTERNS.md
ResilienceRESUMABILITY.md, TROUBLESHOOTING.md
AdvancedMOLECULES.md, CHEMISTRY_PATTERNS.md, AGENTS.md, ASYNC_GATES.md, WORKTREES.md
ReferenceSTATIC_DATA.md, INTEGRATION_PATTERNS.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

Validation

版本验证

If 
bd --version
reports newer than 
0.60.0
, this skill may be stale. Run 
bd prime
for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth (ADR-0001).
若 
bd --version
显示版本高于 
0.60.0
，则此技能文档可能已过期。执行 
bd prime
获取当前CLI指南 — 它会随每个bd版本自动更新，是权威的信息来源（ADR-0001）。