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

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

核心命令

Command	Purpose
`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

Pick a task and mark it 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

Add dependencies

添加依赖关系

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

2. Close completed tasks

2. 关闭已完成的任务

bd close <id> --reason "Completed"

3. Sync and push (MANDATORY)

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

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

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

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

Re-import to database

重新导入至数据库

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

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

undefined

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

undefined

beads

Original

Translation

Getting Started

快速开始

Check if bd is installed

检查bd是否已安装

Check if current project has beads initialized

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

Essential Commands

核心命令

Task Hierarchy

任务层级

Session Workflow

会话工作流

Starting a Session

开启会话

See what's ready to work on

查看可立即开展的工作

Pick a task and mark it in progress

选择任务并标记为进行中

View full details

查看完整详情

During Work

工作过程中

Create new tasks as you discover them

发现新任务时创建新条目

Add dependencies

添加依赖关系

Update task with notes

为任务添加备注

Ending a Session ("Land the Plane")

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

1. File issues for remaining work

1. 为剩余工作创建任务

2. Close completed tasks

2. 关闭已完成的任务

3. Sync and push (MANDATORY)

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

4. Verify push succeeded

4. 验证推送是否成功

5. Identify next task for follow-up

5. 确定后续任务

Important Rules

重要规则

DO use bd update with flags

请使用带参数的bd update命令

DO NOT use bd edit

请勿使用bd edit命令

DO sync before ending sessions

结束会话前请执行同步

DO include issue IDs in commit messages

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

Dependency Types

依赖类型

Hard blocker - child cannot start until parent is done

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

Soft link - related but not blocking

弱关联 - 相关但不阻塞

Parent-child - hierarchical relationship

父子关系 - 层级关联

Handling Merge Conflicts

处理合并冲突

Accept remote version

接受远程版本

Re-import to database

重新导入至数据库

Continue with your work

继续工作

Git Hooks (Recommended)

Git钩子（推荐）

MCP Server Alternative

MCP服务器替代方案

Quick Reference

速查指南

What should I work on?

我该做什么工作？

Create a task

创建任务

Start working

DO use
`bd update`
with flags

请使用带参数的
`bd update`
命令

DO NOT use
`bd edit`

请勿使用
`bd edit`
命令