beads

这项技能将教你如何有效使用 beads（bd），这是一款专为 AI Agent 设计、由 git 提供支持的分布式问题跟踪器。使用 beads 跟踪任务、管理依赖关系，并跨会话协调工作。

入门

首先，检查 beads 是否可用且已初始化：

# Check if bd is installed
bd version

# Check if current project has beads initialized
bd status

如果未安装 bd，请询问用户倾向于哪种安装方式：

• npm： npm install -g @beads/bd
• Homebrew： brew install beads（macOS）
• Go： go install github.com/steveyegge/beads/cmd/bd@latest

未经用户确认请勿安装，因为这些是全局系统软件包。

如果项目尚未初始化，请运行：

bd init

在共享项目中个人使用（不会提交到仓库）：

bd init --stealth

适用于分叉仓库的贡献者（将任务路由到单独的规划仓库）：

bd init --contributor

基本命令

命令	用途
bd ready	列出没有未解决阻塞项的任务（接下来要处理的任务）
bd create "Title" -p 1	创建任务（优先级为 0-3，数字越小，优先级越高）
bd show <id>	查看任务详情和依赖关系
bd list	列出所有未解决的问题
bd close <id>	将任务标记为已完成
bd update <id> --status in_progress	更新任务状态
bd dep add <child> <parent>	创建依赖关系（子项受父项阻塞）
bd sync	立即强制同步到 git

解析结果时，始终使用 --json 标志以获取机器可读的输出。

任务层级

Beads 支持分层 ID，用于整理工作：

• bd-a3f8 — Epic（大型功能）
• bd-a3f8.1 — Epic 下的任务
• bd-a3f8.1.1 — 子任务

创建分层任务：

bd create "Epic: User Authentication" -t epic -p 1
bd create "Implement login flow" -p 1 --parent bd-a3f8

会话工作流

开始会话

# See what's ready to work on
bd ready --json

# Pick a task and mark it in progress
bd update <id> --status in_progress

# View full details
bd show <id> --json

工作期间

# Create new tasks as you discover them
bd create "Fix edge case in validation" -p 2

# Add dependencies
bd dep add <new-task> <blocking-task>

# Update task with notes
bd update <id> --notes "Found issue with timezone handling"

结束会话（“平稳着陆”）

完成工作时，请完成以下所有步骤：

# 1. File issues for remaining work
bd create "TODO: Add integration tests" -p 2

# 2. Close completed tasks
bd close <id> --reason "Completed"

# 3. Sync and push (MANDATORY)
git pull --rebase
bd sync
git push

# 4. Verify push succeeded
git status  # Must show "up to date with origin"

# 5. Identify next task for follow-up
bd ready --json

重要： 结束会话前务必推送。未推送的工作会给多 Agent 工作流带来协调问题。

重要规则

应使用带标志的 bd update

bd update <id> --description "new description"
bd update <id> --title "new title"  
bd update <id> --design "design notes"
bd update <id> --notes "additional notes"
bd update <id> --acceptance "acceptance criteria"
bd update <id> --status in_progress

不要使用 bd edit

edit 命令会打开交互式编辑器（$EDITOR），AI Agent 无法使用。请始终改用带标志的 bd update。

结束会话前应同步

bd sync  # Forces immediate export, commit, and push

如果不运行 bd sync，更改会在 30 秒的防抖窗口中等待，可能无法提交。

提交消息中应包含问题 ID

git commit -m "Fix auth validation bug (bd-abc)"

这样 bd doctor 才能检测出孤立的问题。

依赖类型

# Hard blocker - child cannot start until parent is done
bd dep add <child> <parent> --type blocks

# Soft link - related but not blocking  
bd dep add <issue1> <issue2> --type related

# Parent-child - hierarchical relationship
bd dep add <child> <parent> --type parent-child

处理合并冲突

如果 .beads/issues.jsonl 中出现冲突：

# Accept remote version
git checkout --theirs .beads/issues.jsonl

# Re-import to database
bd import -i .beads/issues.jsonl

# Continue with your work

Git 钩子（推荐）

安装钩子以自动同步：

bd hooks install

这会在提交、合并、推送和检出时自动同步，从而避免 JSONL 内容过时的问题。

MCP 服务替代方案

如需更紧密的集成，beads 还提供 MCP 服务（beads-mcp），可直接向你的 Agent 提供工具。通过以下方式安装：

pip install beads-mcp

CLI（bd）和 MCP 服务使用同一个底层数据库。

快速参考

# What should I work on?
bd ready

# Create a task
bd create "Fix bug in login" -p 1

# Start working
bd update bd-xyz --status in_progress

# Done working
bd close bd-xyz --reason "Completed"
bd sync
git push