beads-workflow

Beads 工作流

Beads 是一款面向 Agent 工作流设计的 AI 原生问题跟踪工具。问题存放在仓库中，通过 git 同步，无需 Web UI。

核心命令

命令	描述
bd create "Title" -t feature -p 2	创建问题（类型、优先级）
bd list --status open	列出未解决的问题
bd show <id>	查看问题详情
bd update <id> --status in_progress	更新状态或受派人
bd close <id> --reason "..."	关闭问题并说明原因
bd ready --sort hybrid	查找未受阻的问题
bd dep add <blocking> <blocked> --type blocks	添加依赖关系
bd dep tree <id>	查看依赖关系树
bd dep rm <blocking> <blocked>	移除依赖关系
bd sync	与 git 远程仓库同步
bd flush	强制写入 JSONL

工作流模式

开始会话

1. 检查可处理的工作：bd ready --sort hybrid
2. 认领问题：bd update <id> --status in_progress
3. 检查依赖关系：bd dep tree <id>
4. 开始实现

实现期间

1. 跟踪子任务：bd create "Sub-task" --parent <id>
2. 添加阻塞项：bd dep add <new-blocker> <id> --type blocks
3. 更新进度：bd comment <id> "Progress update"

完成工作

1. 确认完成：满足所有验收标准
2. 关闭问题：bd close <id> --reason "Implemented X, PR #123"
3. 同步：bd sync
4. 检查下一个问题：bd ready

多 Agent 协作

# See who's working on what
bd list --status in_progress --json | jq '.[] | {id, title, assignee}'

# Hand off work
bd update <id> --assignee other-agent
bd comment <id> "Handoff: context and next steps"

问题类型

类型	适用场景
feature	新功能
bug	修复缺陷
task	常规工作项
spike	研究/调查
chore	维护、清理

优先级

优先级	含义
0	紧急 — 暂停所有其他工作
1	高 — 接下来处理
2	中 — 正常流程
3	低 — 时间允许时处理
4	待办 — 以后考虑

状态流转

open -> in_progress -> done
         |-> blocked -> in_progress

最佳实践

1. 每个逻辑单元对应一个问题：不要合并无关工作
2. 标题清晰：应说明做什么，而不是怎么做
3. 使用依赖关系：让可处理的工作一目了然
4. 经常同步：让其他 Agent 随时了解情况
5. 及时关闭：不要让过时的 in_progress 问题一直挂着

与 Swarm 集成

1. 编辑前先认领：修改代码前更新状态
2. 记录阻塞项：为发现的阻塞项创建问题
3. 顺利交接：更新受派人并补充上下文
4. 结束前同步：使用 bd sync 共享状态

故障排除

# Check daemon health
bd daemons health

# View daemon logs
bd daemons logs

# Force reimport from JSONL
bd import --force

# Check for conflicts
bd sync --dry-run