Back to Details

beads

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
This skill teaches effective use of beads (
bd
), a distributed git-backed issue tracker designed for AI agents. Use beads to track tasks, manage dependencies, and coordinate work across sessions.
本技能将教授如何高效使用beads（
bd
）——一款基于Git的分布式问题跟踪器，专为AI Agent设计。通过beads可跟踪任务、管理依赖关系，并跨会话协调工作。

Getting Started

快速开始

First, check if beads is available and initialized:
bash
undefined
首先，检查beads是否已安装并初始化：
bash
undefined

Check if bd is installed

检查bd是否已安装

bd version
bd version

Check if current project has beads initialized

检查当前项目是否已初始化beads

bd status

**If `bd` is not installed**, ask the user which installation method they prefer:
- **npm:** `npm install -g @beads/bd`
- **Homebrew:** `brew install beads` (macOS)
- **Go:** `go install github.com/steveyegge/beads/cmd/bd@latest`

Do not install without user confirmation, as these are global system packages.

**If not initialized in the project**, run:
```bash
bd init
For personal use on shared projects (won't commit to repo):
bash
bd init --stealth
For contributors on forked repos (routes to separate planning repo):
bash
bd init --contributor
bd status

**若未安装`bd`**，询问用户偏好的安装方式：
- **npm：** `npm install -g @beads/bd`
- **Homebrew：** `brew install beads`（适用于macOS）
- **Go：** `go install github.com/steveyegge/beads/cmd/bd@latest`

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

**若项目未初始化**，运行：
```bash
bd init
适用于共享项目的个人使用（不会提交到仓库）：
bash
bd init --stealth
适用于复刻仓库的贡献者（路由至独立的规划仓库）：
bash
bd init --contributor

Essential Commands

核心命令

CommandPurpose
bd ready
List tasks with no open blockers (what to work on next)
bd create "Title" -p 1
Create a task (priority 0-3, lower = higher priority)
bd show <id>
View task details and dependencies
bd list
List all open issues
bd close <id>
Mark task as complete
bd update <id> --status in_progress
Update task status
bd dep add <child> <parent>
Create dependency (child blocked by parent)
bd sync
Force immediate sync to git
Always use 
--json
flag for machine-readable output when parsing results.
命令用途
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
参数，以获取机器可读的输出格式。

Task Hierarchy

任务层级

Beads supports hierarchical IDs for organizing work:
  • bd-a3f8
    — Epic (large feature)
  • bd-a3f8.1
    — Task under epic
  • bd-a3f8.1.1
    — Sub-task
Create hierarchical tasks:
bash
bd create "Epic: User Authentication" -t epic -p 1
bd create "Implement login flow" -p 1 --parent bd-a3f8
Beads支持通过层级ID组织工作：
  • bd-a3f8
    — 史诗任务（大型功能）
  • bd-a3f8.1
    — 史诗任务下的子任务
  • bd-a3f8.1.1
    — 二级子任务
创建层级任务：
bash
bd create "Epic: User Authentication" -t epic -p 1
bd create "Implement login flow" -p 1 --parent bd-a3f8

Session Workflow

会话工作流

Starting a Session

开启会话

bash
undefined
bash
undefined

See what's ready to work on

查看可立即开展的工作

bd ready --json
bd ready --json

Pick a task and mark it in progress

选择任务并标记为进行中

bd update <id> --status in_progress
bd update <id> --status in_progress

View full details

查看完整详情

bd show <id> --json
undefined
bd show <id> --json
undefined

During Work

工作过程中

bash
undefined
bash
undefined

Create new tasks as you discover them

发现新任务时创建新条目

bd create "Fix edge case in validation" -p 2
bd create "Fix edge case in validation" -p 2

Add dependencies

添加依赖关系

bd dep add <new-task> <blocking-task>
bd dep add <new-task> <blocking-task>

Update task with notes

为任务添加备注

bd update <id> --notes "Found issue with timezone handling"
undefined
bd update <id> --notes "Found issue with timezone handling"
undefined

Ending a Session ("Land the Plane")

结束会话（"收尾工作"）

When finishing work, complete ALL these steps:
bash
undefined
完成工作时，需执行以下所有步骤：
bash
undefined

1. File issues for remaining work

1. 为剩余工作创建任务

bd create "TODO: Add integration tests" -p 2
bd create "TODO: Add integration tests" -p 2

2. Close completed tasks

2. 关闭已完成的任务

bd close <id> --reason "Completed"
bd close <id> --reason "Completed"

3. Sync and push (MANDATORY)

3. 同步并推送（必须执行）

git pull --rebase bd sync git push
git pull --rebase bd sync git push

4. Verify push succeeded

4. 验证推送是否成功

git status # Must show "up to date with origin"
git status # 必须显示"up to date with origin"

5. Identify next task for follow-up

5. 确定后续任务

bd ready --json

**CRITICAL**: Always push before ending a session. Unpushed work causes coordination problems in multi-agent workflows.
bd ready --json

**重要提示**：结束会话前务必推送代码。未推送的工作会在多Agent工作流中引发协作问题。

Important Rules

重要规则

DO use 
bd update
with flags

请使用带参数的
bd update
命令

bash
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
bash
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

DO NOT use 
bd edit

请勿使用
bd edit
命令

The 
edit
command opens an interactive editor (
$EDITOR
) which AI agents cannot use. Always use 
bd update
with flags instead.
edit
命令会打开交互式编辑器（
$EDITOR
），AI Agent无法使用该功能。请始终使用带参数的
bd update
命令替代。

DO sync before ending sessions

结束会话前请执行同步

bash
bd sync  # Forces immediate export, commit, and push
Without 
bd sync
, changes sit in a 30-second debounce window and may not be committed.
bash
bd sync  # 强制立即导出、提交并推送
若未执行
bd sync
，更改会处于30秒的防抖窗口中，可能不会被提交。

DO include issue IDs in commit messages

请在提交信息中包含任务ID

bash
git commit -m "Fix auth validation bug (bd-abc)"
This enables 
bd doctor
to detect orphaned issues.
bash
git commit -m "Fix auth validation bug (bd-abc)"
这能让
bd doctor
检测到孤立任务。

Dependency Types

依赖类型

bash
undefined
bash
undefined

Hard blocker - child cannot start until parent is done

强阻塞 - 子任务需等待父任务完成后方可启动

bd dep add <child> <parent> --type blocks
bd dep add <child> <parent> --type blocks

Soft link - related but not blocking

弱关联 - 相关但不阻塞

bd dep add <issue1> <issue2> --type related
bd dep add <issue1> <issue2> --type related

Parent-child - hierarchical relationship

父子关系 - 层级关联

bd dep add <child> <parent> --type parent-child
undefined
bd dep add <child> <parent> --type parent-child
undefined

Handling Merge Conflicts

处理合并冲突

If conflicts occur in 
.beads/issues.jsonl
:
bash
undefined
若
.beads/issues.jsonl
文件出现冲突：
bash
undefined

Accept remote version

接受远程版本

git checkout --theirs .beads/issues.jsonl
git checkout --theirs .beads/issues.jsonl

Re-import to database

重新导入至数据库

bd import -i .beads/issues.jsonl
bd import -i .beads/issues.jsonl

Continue with your work

继续工作

undefined
undefined

Git Hooks (Recommended)

Git钩子（推荐）

Install hooks for automatic sync:
bash
bd hooks install
This prevents stale JSONL problems by auto-syncing on commit, merge, push, and checkout.
安装钩子以实现自动同步：
bash
bd hooks install
该钩子会在提交、合并、推送与切换分支时自动同步，避免JSONL文件过期问题。

MCP Server Alternative

MCP服务器替代方案

For tighter integration, beads also offers an MCP server (
beads-mcp
) that provides tools directly to your agent. Install via:
bash
pip install beads-mcp
The CLI (
bd
) and MCP server work with the same underlying database.
如需更紧密的集成，beads还提供MCP服务器（
beads-mcp
），可直接为Agent提供工具。安装方式：
bash
pip install beads-mcp
CLI工具（
bd
）与MCP服务器共用底层数据库。

Quick Reference

速查指南

bash
undefined
bash
undefined

What should I work on?

我该做什么工作？

bd ready
bd ready

Create a task

创建任务

bd create "Fix bug in login" -p 1
bd create "Fix bug in login" -p 1

Start working

开始工作

bd update bd-xyz --status in_progress
bd update bd-xyz --status in_progress

Done working

完成工作

bd close bd-xyz --reason "Completed" bd sync git push
undefined
bd close bd-xyz --reason "Completed" bd sync git push
undefined