beads-task-tracker

Beads 任务跟踪器

概述

Beads 是一款专为 AI 编码 Agent 设计、采用 Git 版本控制且支持依赖关系的议题跟踪器。它通过提供持久、可查询的任务数据库，解决 Agent 在不同会话之间丢失上下文的“失忆问题”。Agent 可以利用该数据库了解当前情况、查找可开始的工作，并跟踪长期项目中的依赖关系。

在以下情况下使用 Beads：

• 处理包含多个相互关联任务的项目
• 任务需要跨越多个 Agent 会话（>10 分钟）
• 需要跟踪哪些工作受阻、哪些工作已就绪
• 在实施过程中发现需要记录的新工作
• 多个 Agent 或机器正在处理同一代码库
• 想避免“Markdown 计划泥潭”，即计划逐渐过时、变得杂乱无章

安装检查

使用 Beads 之前，请确认已安装 bd 命令：

bd version

如果尚未安装，请通过以下方式安装：

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

安装后设置 PATH：

安装后，如果在 PATH 中找不到 bd，请将 Go bin 目录添加到 shell 配置文件中：

对于 zsh（大多数 macOS 系统），添加到 ~/.zshrc：

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

对于 bash，添加到 ~/.bashrc 或 ~/.bash_profile：

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

然后重新加载 shell：

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

此外，在配置 PATH 之前，也可以使用完整路径 /Users/[username]/go/bin/bd。

工作流概述

1. 项目初始化

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

bd init

这会创建一个 .beads/ 目录，其中包含：

• issues.jsonl - Git 版本控制的事实来源
• *.db - 本地 SQLite 缓存（已加入 gitignore）

2. 创建工作项

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

基本创建：

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

议题类型：

• task - 标准工作项（默认）
• feature - 新功能
• bug - 待修复的缺陷
• epic - 大型工作项（多个任务的父项）
• chore - 维护工作

优先级（0-4）：

• 0 - 紧急／阻塞
• 1 - 高优先级
• 2 - 中优先级（默认）
• 3 - 低优先级
• 4 - 有则更好

从 Markdown 文件创建：

bd create -f plan.md --json

格式：## Issue Title 会创建新议题，可选的章节包括 ### Priority、### Type、### Description、### Dependencies

添加标签以便整理：

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

3. 管理依赖关系

关联相关工作，以确定顺序并跟踪阻塞项：

添加依赖：

# Format: bd dep add <dependent> <blocker>
bd dep add bd-5 bd-3  # bd-5 depends on bd-3 completing first

依赖类型：

• blocks（默认）- 硬性阻塞；阻塞项关闭前，依赖项无法开始
• parent-child - 层级关系（子项依赖于父项）

  bd dep add bd-task bd-epic --type parent-child
  

• discovered-from - 在处理另一议题期间发现的议题

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

• related - 弱关联；议题之间有关联，但不会造成阻塞

可视化依赖关系：

bd dep tree bd-42 --json

检测循环依赖：

bd dep cycles --json

循环依赖会影响就绪工作检测，必须予以解决。

4. 查找就绪工作

查询没有未关闭阻塞项的可执行工作：

# 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

查找近期／最新任务

重要： 开始会话时，务必先检查最新／编号最高的任务，因为这些任务通常代表最近的工作和当前优先事项。

按 ID 降序查看近期任务：

# List all open tasks, sorted by ID number (highest/newest first)
bd list --status open --json | jq -r '.[] | .id' | sort -t'-' -k3 -n -r | head -20

# Show full details of highest-numbered tasks
bd list --status open --json | jq 'sort_by(.id | sub(".*-"; "") | tonumber) | reverse | .[0:10]'

# Find tasks in a specific number range (e.g., 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}'

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

# 1. First, check what the highest task numbers are
HIGHEST=$(bd list --json | jq -r '.[].id' | grep -oE '[0-9]+$' | sort -n | tail -1)
echo "Highest task number: $HIGHEST"

# 2. View tasks in the recent range (e.g., last 30 tasks)
RANGE_START=$((HIGHEST - 30))
bd list --json | jq --arg start "$RANGE_START" '[.[] | select(.id | test(".*-([0-9]+)$") and (.id | match(".*-([0-9]+)$").captures[0].string | tonumber) >= ($start | tonumber))] | sort_by(.id | sub(".*-"; "") | tonumber) | reverse'

# 3. Find ready work among recent tasks
bd ready --json | jq -r '.[] | .id' | sort -t'-' -k3 -n -r | head -10

优先检查近期任务的原因：

• 最近的工作通常就是当前重点
• 近期任务往往包含最新的上下文
• 避免遗漏新创建的高优先级工作
• 帮助确定最近处理过哪些工作

会话开始时，务必：

1. 检查编号最高的任务，了解当前工作范围
2. 列出近期任务（编号最高的 20-30 个 ID），了解当前重点
3. 运行 bd ready --json 查找未受阻的工作，并优先考虑近期任务
4. 选择优先级最高的就绪议题（优先选择近期任务，优先级相同时）
5. 开始工作前，将状态更新为 in_progress

5. 工作与更新

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

开始工作：

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

有效状态：

• open - 尚未开始
• in_progress - 正在处理
• closed - 已完成

更新其他字段：

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

关闭已完成的工作：

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

6. 工作中发现新任务

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

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

# 2. Link back to parent work
bd dep add $NEW_ID bd-current --type discovered-from --json

# 3. Decide: handle now or defer?
# If blocking current work: switch to new issue
# If not blocking: continue current work, new issue will show in bd ready

7. 查询与检查

按筛选条件列出问题：

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

显示完整的问题详情：

bd show bd-42 --json

查看受阻问题：

bd blocked --json

项目统计信息：

bd stats --json

JSON 输出解析

以编程方式访问时，始终使用 --json 标志。使用 jq 解析：

# 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

# 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}'

最佳实践

应该：

• 在项目开始时初始化 Beads（bd init）
• 为发现的工作创建问题，而不是记非正式笔记
• 使用依赖关系来表示任务间的关联
• 在会话开始时查询 bd ready，了解当前情况
• 关闭问题时提供明确的原因
• 使用标签对工作分类（例如：backend、frontend、urgent）
• 将 .beads/issues.jsonl 提交到 Git（更改后会自动导出）

不应该：

• 创建循环依赖（使用 bd dep cycles 检查）
• 跳过状态更新（过时的状态会影响对可处理工作的判断）
• 忘记将发现的工作关联回父问题
• 在有 Beads 可用时使用 Markdown 文件跟踪任务
• 长期忽略受阻问题（重新评估依赖关系）

多会话工作流模式

会话 1 - 全新开始：

# 1. Check for ready work
bd ready --json

# 2. If no ready work, check what's blocked
bd blocked --json

# 3. Start working on highest-priority ready issue
bd update bd-5 --status in_progress --json

# 4. During work, discover new issue
bd create "Fix validation bug" -t bug -p 0 --json
bd dep add bd-new bd-5 --type discovered-from --json

# 5. Complete original work
bd close bd-5 --reason "Feature implemented" --json

会话 2 - Agent 恢复工作（不同会话，可能是不同日期）：

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

# 2. See discovered issue from previous session
# 3. Continue work seamlessly without context loss
bd update bd-new --status in_progress --json

快速参考

请参阅 references/quick-reference.md，查看全面的命令速查表。

有关工作流模式和高级用法，请参阅 references/workflow-patterns.md。

内置帮助

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

bd quickstart

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

与项目文档集成

将以下内容添加到 AGENTS.md 或 CLAUDE.md：

## Task Tracking with 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.

资源

此技能包含参考文档，可帮助有效使用 Beads：

references/

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