beads-task-tracker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beads Task Tracker

Beads 任务跟踪工具

Overview

概述

Beads is a git-versioned, dependency-aware issue tracker designed specifically for AI coding agents. It solves the "amnesia problem" where agents lose context between sessions by providing a persistent, queryable task database that agents can use to orient themselves, find ready work, and track dependencies across long-horizon projects.

Use Beads when:

Working on projects with multiple interconnected tasks
Tasks span multiple agent sessions (>10 minutes)
Need to track what work is blocked vs. ready
Discovering new work during implementation that should be captured
Multiple agents or machines are working on the same codebase
Want to avoid the "markdown plan swamp" where plans become stale and disorganized

Beads是一款专为AI编码Agent设计的、基于Git版本控制的依赖感知型问题跟踪工具。它解决了Agent在不同会话间丢失上下文的“失忆问题”，通过提供一个持久化、可查询的任务数据库，帮助Agent定位自身工作方向、找到可执行任务，并在长期项目中跟踪任务依赖关系。

以下场景适合使用Beads：

处理包含多个相互关联任务的项目
任务跨多个Agent会话（超过10分钟）
需要跟踪哪些工作处于阻塞状态、哪些可以立即开始
在实施过程中发现需要记录的新工作
多个Agent或机器在同一代码库上工作
希望避免“Markdown计划泥潭”——即计划变得过时且混乱的情况

Installation Check

安装检查

Before using Beads, verify the

bd

command is installed:

bash

bd version

If not installed, install via:

bash

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

Post-installation PATH setup:

After installation, if

bd

is not found in your PATH, add the Go bin directory to your shell profile:

For zsh (most macOS systems), add to

~/.zshrc

bash

export PATH="$PATH:$HOME/go/bin"

For bash, add to

~/.bashrc

~/.bash_profile

bash

export PATH="$PATH:$HOME/go/bin"

Then reload your shell:

bash

source ~/.zshrc  # or source ~/.bashrc

Alternatively, you can use the full path

/Users/[username]/go/bin/bd

until PATH is configured.

使用Beads之前，请验证

bd

命令是否已安装：

bash

bd version

如果未安装，可通过以下命令安装：

bash

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

安装后PATH配置：

安装完成后，如果在PATH中找不到

bd

，请将Go的bin目录添加到你的shell配置文件中：

对于zsh（大多数macOS系统），添加到

~/.zshrc

：

bash

export PATH="$PATH:$HOME/go/bin"

对于bash，添加到

~/.bashrc

或

~/.bash_profile

：

bash

export PATH="$PATH:$HOME/go/bin"

然后重新加载shell：

bash

source ~/.zshrc  # 或 source ~/.bashrc

或者，在PATH配置完成前，你可以使用完整路径

/Users/[username]/go/bin/bd

来执行命令。

Workflow Overview

工作流概述

1. Project Initialization

1. 项目初始化

Initialize Beads in a project directory (only needed once per project):

bash

bd init

This creates a

.beads/

directory with:

```
issues.jsonl
```
- Git-versioned source of truth
```
*.db
```
- Local SQLite cache (gitignored)

在项目目录中初始化Beads（每个项目只需执行一次）：

bash

bd init

此命令会创建一个

.beads/

目录，包含：

```
issues.jsonl
```
- 基于Git版本控制的事实数据源
```
*.db
```
- 本地SQLite缓存（已被Git忽略）

2. Creating Work

2. 创建任务

Create issues when starting new work or discovering tasks during implementation:

Basic creation:

bash

bd create "Task title" -d "Description" -p 1 -t task --json

Issue types:

```
task
```
- Standard work item (default)
```
feature
```
- New functionality
```
bug
```
- Defect to fix
```
epic
```
- Large body of work (parent to multiple tasks)
```
chore
```
- Maintenance work

Priority levels (0-4):

```
0
```
- Critical/blocking
```
1
```
- High priority
```
2
```
- Medium priority (default)
```
3
```
- Low priority
```
4
```
- Nice to have

Creating from markdown file:

bash

bd create -f plan.md --json

Format:

## Issue Title

creates new issue, with optional sections

### Priority

### Type

### Description

### Dependencies

Add labels for organization:

bash

bd create "Add auth" -l "backend,security,p1" --json

在开始新工作或实施过程中发现任务时，创建问题：

基础创建方式：

bash

bd create "任务标题" -d "描述内容" -p 1 -t task --json

问题类型：

```
task
```
- 标准工作项（默认类型）
```
feature
```
- 新功能
```
bug
```
- 需要修复的缺陷
```
epic
```
- 大型工作模块（可包含多个子任务）
```
chore
```
- 维护性工作

优先级等级（0-4）：

```
0
```
- 关键/阻塞级
```
1
```
- 高优先级
```
2
```
- 中优先级（默认）
```
3
```
- 低优先级
```
4
```
- 可选优化

从Markdown文件创建：

bash

bd create -f plan.md --json

格式说明：

## 问题标题

会创建新问题，可附带可选章节

### Priority

、

### Type

、

### Description

、

### Dependencies

添加标签用于分类：

bash

bd create "添加认证功能" -l "backend,security,p1" --json

3. Managing Dependencies

3. 管理依赖关系

Link related work to establish ordering and track blockers:

Add dependency:

bash

undefined

关联相关工作以建立任务顺序并跟踪阻塞项：

添加依赖：

bash

undefined

Format: bd dep add <dependent> <blocker>

格式：bd dep add <依赖项> <阻塞项>

bd dep add bd-5 bd-3 # bd-5 depends on bd-3 completing first


**Dependency types:**

- `blocks` (default) - Hard blocker; dependent cannot start until blocker closes
- `parent-child` - Hierarchical relationship (child depends on parent)
  ```bash
  bd dep add bd-task bd-epic --type parent-child

discovered-from

- Issue found during work on another issue

bash

bd dep add bd-new bd-current --type discovered-from

```
related
```
- Soft connection; issues are related but not blocking

Visualize dependencies:

bash

bd dep tree bd-42 --json

Detect cycles:

bash

bd dep cycles --json

Cycles break ready work detection and must be resolved.

bd dep add bd-5 bd-3 # bd-5 需在 bd-3 完成后才能开始


**依赖类型：**

- `blocks`（默认）- 硬阻塞；依赖项必须等待阻塞项完成才能开始
- `parent-child` - 层级关系（子任务依赖父任务）
  ```bash
  bd dep add bd-task bd-epic --type parent-child

discovered-from

- 在处理其他问题时发现的新问题

bash

bd dep add bd-new bd-current --type discovered-from

```
related
```
- 软关联；问题相关但无阻塞关系

可视化依赖关系：

bash

bd dep tree bd-42 --json

检测循环依赖：

bash

bd dep cycles --json

循环依赖会破坏可执行任务的检测，必须解决。

4. Finding Ready Work

4. 查找可执行任务

Query for actionable work with no open blockers:

bash

undefined

查询无未解决阻塞的可执行工作：

bash

undefined

All ready work

所有可执行任务

bd ready --json

Filter by priority

按优先级过滤

bd ready --priority 1 --json

Filter by labels

按标签过滤

bd ready --label backend --json

Limit results

限制结果数量

bd ready --limit 5 --json

undefined

bd ready --limit 5 --json

undefined

Finding Recent/Latest Tasks

查找最近/最新任务

IMPORTANT: When starting a session, always check for the latest/highest-numbered tasks first, as these typically represent the most recent work and current priorities.

View recent tasks sorted by ID (descending):

bash

undefined

重要提示： 开始会话时，务必先查看编号最高的最新任务，因为它们通常代表最近的工作和当前优先级。

按ID降序查看最近任务：

bash

undefined

List all open tasks, sorted by ID number (highest/newest first)

列出所有未完成任务，按ID编号降序排列（最新的在前）

bd list --status open --json | jq -r '.[] | .id' | sort -t'-' -k3 -n -r | head -20

Show full details of highest-numbered tasks

显示编号最高的任务的完整详情

Find tasks in a specific number range (e.g., 120-150)

查找特定编号范围的任务（例如120-150）

bd list --json | jq '[.[] | select(.id | test("Twilio-Aldea-1[2-5][0-9]"))] | sort_by(.id | sub(".*-"; "") | tonumber) | reverse | .[] | {id, title, status, priority}'


**Example workflow at session start:**

```bash

bd list --json | jq '[.[] | select(.id | test("Twilio-Aldea-1[2-5][0-9]"))] | sort_by(.id | sub(".*-"; "") | tonumber) | reverse | .[] | {id, title, status, priority}'


**会话开始时的示例工作流：**

```bash

1. First, check what the highest task numbers are

1. 首先，查看当前最高任务编号

HIGHEST=$(bd list --json | jq -r '.[].id' | grep -oE '[0-9]+$' | sort -n | tail -1) echo "Highest task number: $HIGHEST"

HIGHEST=$(bd list --json | jq -r '.[].id' | grep -oE '[0-9]+$' | sort -n | tail -1) echo "最高任务编号: $HIGHEST"

2. View tasks in the recent range (e.g., last 30 tasks)

2. 查看最近范围内的任务（例如最近30个任务）

3. Find ready work among recent tasks

3. 在最近任务中查找可执行工作

bd ready --json | jq -r '.[] | .id' | sort -t'-' -k3 -n -r | head -10


**Why check recent tasks first:**

- Most recent work is usually the current focus
- Recent tasks often have the freshest context
- Prevents overlooking newly-created high-priority work
- Helps identify what was worked on most recently

**At session start, always:**

1. Check the highest task numbers to understand the current work range
2. List recent tasks (highest 20-30 IDs) to see current focus areas
3. Run `bd ready --json` to find unblocked work, prioritizing recent tasks
4. Choose highest-priority ready issue (preferring recent tasks when priorities are equal)
5. Update status to `in_progress` before starting work

bd ready --json | jq -r '.[] | .id' | sort -t'-' -k3 -n -r | head -10


**为什么要先查看最近任务：**

- 最近的工作通常是当前的焦点
- 最近的任务通常包含最新的上下文信息
- 避免忽略新创建的高优先级工作
- 帮助了解最近正在处理的内容

**会话开始时，请务必：**

1. 查看最高任务编号以了解当前工作范围
2. 列出最近任务（编号最高的20-30个）以查看当前重点领域
3. 运行`bd ready --json`查找未阻塞任务，优先考虑最近的任务
4. 选择优先级最高的可执行问题（优先级相同时优先选择最近任务）
5. 开始工作前将状态更新为`in_progress`

5. Working and Updating

5. 工作与任务更新

Update issue status as work progresses:

Start work:

bash

bd update bd-42 --status in_progress --json

Valid statuses:

```
open
```
- Not started
```
in_progress
```
- Currently being worked on
```
closed
```
- Completed

Update other fields:

bash

bd update bd-42 --priority 0 --json
bd update bd-42 --assignee alice --json

Close completed work:

bash

bd close bd-42 --reason "Implementation complete, tests passing" --json

随着工作推进，更新问题状态：

开始工作：

bash

bd update bd-42 --status in_progress --json

有效状态：

```
open
```
- 未开始
```
in_progress
```
- 正在处理中
```
closed
```
- 已完成

更新其他字段：

bash

bd update bd-42 --priority 0 --json
bd update bd-42 --assignee alice --json

关闭已完成的工作：

bash

bd close bd-42 --reason "实现完成，测试通过" --json

6. Discovery During Work

6. 工作中发现新任务

When discovering new work during implementation:

bash

undefined

在实施过程中发现新工作时：

bash

undefined

1. Create the discovered issue

1. 创建新发现的问题

NEW_ID=$(bd create "Fix discovered bug in auth" -t bug -p 1 --json | jq -r '.id')

NEW_ID=$(bd create "修复认证模块中发现的bug" -t bug -p 1 --json | jq -r '.id')

2. Link back to parent work

2. 将其与父任务关联

bd dep add $NEW_ID bd-current --type discovered-from --json

3. Decide: handle now or defer?

3. 决定：立即处理还是延后？

If blocking current work: switch to new issue

如果当前工作被阻塞：切换到新任务

If not blocking: continue current work, new issue will show in bd ready

如果未被阻塞：继续当前工作，新任务会在bd ready中显示

undefined

undefined

7. Querying and Inspection

7. 查询与检查

List issues with filters:

bash

bd list --status open --json
bd list --priority 1 --json
bd list --label backend,urgent --json  # AND: must have ALL
bd list --label-any frontend,backend --json  # OR: at least one

Show full issue details:

bash

bd show bd-42 --json

View blocked issues:

bash

bd blocked --json

Project statistics:

bash

bd stats --json

带过滤条件的问题列表：

bash

bd list --status open --json
bd list --priority 1 --json
bd list --label backend,urgent --json  # 逻辑与：必须包含所有标签
bd list --label-any frontend,backend --json  # 逻辑或：至少包含一个标签

查看问题完整详情：

bash

bd show bd-42 --json

查看被阻塞的问题：

bash

bd blocked --json

项目统计信息：

bash

bd stats --json

JSON Output Parsing

JSON输出解析

Always use

--json

flag for programmatic access. Parse with

jq

bash

undefined

对于程序化访问，请始终使用

--json

标志。可使用

jq

进行解析：

bash

undefined

Get first ready issue

获取第一个可执行任务

ISSUE=$(bd ready --json | jq -r '.[0]') ISSUE_ID=$(echo "$ISSUE" | jq -r '.id') ISSUE_TITLE=$(echo "$ISSUE" | jq -r '.title')

Check if any ready work exists

检查是否存在可执行任务

READY_COUNT=$(bd ready --json | jq 'length') if [ "$READY_COUNT" -eq 0 ]; then echo "No ready work. Check blocked issues:" bd blocked --json fi

READY_COUNT=$(bd ready --json | jq 'length') if [ "$READY_COUNT" -eq 0 ]; then echo "无可用可执行任务。查看被阻塞的问题：" bd blocked --json fi

Get highest task number and list recent tasks

获取最高任务编号并列出最近任务

HIGHEST=$(bd list --json | jq -r 'max_by(.id | sub(".-"; "") | tonumber) | .id | sub(".-"; "")') echo "Highest task: #$HIGHEST" bd list --json | jq --arg num "$HIGHEST" '[.[] | select((.id | sub(".-"; "") | tonumber) >= (($num | tonumber) - 20))] | sort_by(.id | sub(".-"; "") | tonumber) | reverse | .[] | {id, title, status, priority}'

undefined

HIGHEST=$(bd list --json | jq -r 'max_by(.id | sub(".-"; "") | tonumber) | .id | sub(".-"; "")') echo "最高任务编号: #$HIGHEST" bd list --json | jq --arg num "$HIGHEST" '[.[] | select((.id | sub(".-"; "") | tonumber) >= (($num | tonumber) - 20))] | sort_by(.id | sub(".-"; "") | tonumber) | reverse | .[] | {id, title, status, priority}'

undefined

Best Practices

最佳实践

DO:

Initialize Beads at project start (
```
bd init
```
)
Create issues for discovered work instead of informal notes
Use dependencies to model task relationships
Query
```
bd ready
```
at session start to orient yourself
Close issues with descriptive reasons
Use labels to categorize work (e.g.,
```
backend
```
,
```
frontend
```
,
```
urgent
```
)
Commit
```
.beads/issues.jsonl
```
to git (auto-exported after changes)

DON'T:

Create circular dependencies (use
```
bd dep cycles
```
to detect)
Skip updating status (stale statuses confuse ready work detection)
Forget to link discovered work back to parent issues
Use markdown files for task tracking when Beads is available
Ignore blocked issues indefinitely (reassess dependencies)

建议：

在项目开始时初始化Beads（
```
bd init
```
）
为发现的新工作创建问题，而非使用非正式笔记
使用依赖关系来建模任务间的关联
会话开始时查询
```
bd ready
```
以明确工作方向
关闭问题时添加描述性的原因
使用标签对工作进行分类（例如
```
backend
```
、
```
frontend
```
、
```
urgent
```
）
将
```
.beads/issues.jsonl
```
提交到Git（更改后会自动导出）

不建议：

创建循环依赖（使用
```
bd dep cycles
```
检测）
跳过状态更新（过期状态会干扰可执行任务的检测）
忘记将发现的新工作与父任务关联
在Beads可用时仍使用Markdown文件进行任务跟踪
无限期忽略被阻塞的问题（重新评估依赖关系）

Multi-Session Workflow Pattern

多会话工作流模式

Session 1 - Starting fresh:

bash

undefined

会话1 - 首次启动：

bash

undefined

1. Check for ready work

1. 查看可执行任务

bd ready --json

2. If no ready work, check what's blocked

2. 如果无可用可执行任务，查看被阻塞的任务

bd blocked --json

3. Start working on highest-priority ready issue

3. 开始处理优先级最高的可执行任务

bd update bd-5 --status in_progress --json

4. During work, discover new issue

4. 工作中发现新问题

bd create "Fix validation bug" -t bug -p 0 --json bd dep add bd-new bd-5 --type discovered-from --json

bd create "修复验证模块bug" -t bug -p 0 --json bd dep add bd-new bd-5 --type discovered-from --json

5. Complete original work

5. 完成原任务

bd close bd-5 --reason "Feature implemented" --json


**Session 2 - Agent resumes (different session, possibly different day):**
```bash

bd close bd-5 --reason "功能实现完成" --json


**会话2 - Agent恢复工作（不同会话，可能间隔数天）：**
```bash

1. Check ready work (newly created bd-new is now ready)

1. 查看可执行任务（新创建的bd-new现在已可用）

bd ready --json

2. See discovered issue from previous session

2. 看到上一会话中发现的问题

3. Continue work seamlessly without context loss

3. 无缝继续工作，无上下文丢失

bd update bd-new --status in_progress --json

undefined

bd update bd-new --status in_progress --json

undefined

Quick Reference

快速参考

See

references/quick-reference.md

for a comprehensive command cheat sheet.

For workflow patterns and advanced usage, see

references/workflow-patterns.md

完整的命令速查表请查看

references/quick-reference.md

。

关于工作流模式和高级用法，请查看

references/workflow-patterns.md

。

Built-in Help

内置帮助

Beads includes an interactive quickstart guide:

bash

bd quickstart

Run this to see comprehensive examples and workflows.

Beads包含交互式快速入门指南：

bash

bd quickstart

运行此命令可查看全面的示例和工作流。

Integration with Project Documentation

与项目文档集成

Add to

AGENTS.md

CLAUDE.md

markdown

undefined

将以下内容添加到

AGENTS.md

或

CLAUDE.md

：

markdown

undefined

Task Tracking with Beads

使用Beads进行任务跟踪

We track implementation work using Beads (

bd

), a dependency-aware issue tracker. Use

bd ready --json

to see unblocked work,

bd create

to add tasks, and

bd update <id> --status in_progress

to claim work. Run

bd quickstart

for full documentation.

undefined

我们使用Beads（

bd

）这款依赖感知型问题跟踪工具来管理实施工作。使用

bd ready --json

查看未阻塞任务，使用

bd create

添加任务，使用

bd update <id> --status in_progress

认领工作。运行

bd quickstart

获取完整文档。

undefined

Resources

资源

This skill includes reference documentation to support effective Beads usage:

此技能包含参考文档以支持高效使用Beads：

references/

```
quick-reference.md
```
- Command cheat sheet organized by category
```
workflow-patterns.md
```
- Common patterns and best practices for agent workflows

```
quick-reference.md
```
- 按类别组织的命令速查表
```
workflow-patterns.md
```
- Agent工作流的常见模式和最佳实践