Beads

面向 AI 代理的分布式、基于 Git 的图式问题追踪器。用存储在 .beads/ 目录下的 JSONL 格式依赖感知任务图，替代传统的 Markdown 计划。

快速上手

# 初始化（非交互式，适用于代理）
bd init --quiet

# 查看就绪任务
bd ready --json

# 创建任务
bd create "完成任务 X" -p 1 --json

# 查看任务详情
bd show bd-a1b2 --json

核心工作流

1. bd ready --json — 查找未被阻塞的任务（即就绪工作）
2. bd update --status in_progress — 领取任务
3. 执行任务
4. bd close --reason "Done" — 完成任务
5. bd sync — 会话结束前强制同步至 Git

对 AI 代理至关重要的规则

• 始终使用 --json 参数以获取机器可读输出
• 切勿使用 bd edit — 该命令会调用 $EDITOR，AI 代理无法使用
• 请改用 bd update：例如 bd update --title "新标题" --description "新描述"
• 在会话结束时运行 bd sync，将所有变更刷新至 Git

命令列表

初始化

bd init --quiet              # 非交互式初始化，自动安装 Git 钩子
bd init --prefix myproj      # 自定义 ID 前缀
bd init --stealth            # 仅本地使用，不提交 .beads/ 目录
bd init --contributor        # Fork 工作流（规划与执行分离为独立仓库）

创建问题（Issue）

bd create "标题" -p 1 --json                    # 优先级为 1（0=关键，3=低）
bd create "标题" -t epic -p 0 --json            # 创建史诗任务（epic）
bd create "子任务" -p 1 --json                  # 归属于 epic：bd-a3f8.1、.2、.3
bd create "发现的问题" --deps discovered-from:bd-a1b2 --json

类型支持：task、bug、feature、epic
优先级范围：0（P0 / 关键）至 3（P3 / 低）

查询问题（Issue）

bd ready --json                    # 未被阻塞的任务（即工作队列）
bd ready --priority 0 --json       # 仅 P0 级别任务
bd ready --assignee agent-1 --json # 指派给特定代理的任务

bd list --json                     # 所有问题
bd list --status open --json       # 开放状态的问题
bd list --priority 1 --json        # P1 级别问题

bd show bd-a1b2 --json             # 问题详情 + 审计日志
bd blocked --json                  # 等待依赖项的问题
bd stats --json                    # 统计信息

更新问题（Issue）

bd update bd-a1b2 --status in_progress --json
bd update bd-a1b2 --title "新标题" --json
bd update bd-a1b2 --description "详细说明" --json
bd update bd-a1b2 --priority 0 --json
bd update bd-a1b2 --assignee agent-1 --json
bd update bd-a1b2 --design "设计说明" --json
bd update bd-a1b2 --notes "补充备注" --json

状态值：open、in_progress、blocked、closed

关闭问题（Issue）

bd close bd-a1b2 --reason "已完成" --json
bd close bd-a1b2 bd-b2c3 --reason "批量关闭" --json

依赖关系（Dependencies）

bd dep add bd-child bd-parent      # 子任务被父任务阻塞
bd dep add bd-a1b2 bd-b2c3 --type related    # 添加关联链接
bd dep add bd-a1b2 bd-epic --type parent     # 设置父子关系

bd dep tree bd-a1b2                # 可视化依赖树
bd dep remove bd-child bd-parent   # 移除依赖关系
bd dep cycles                      # 检测循环依赖

依赖类型：blocks（默认）、related、parent、discovered-from

Git 同步

bd sync                    # 导出 → 提交 → 拉取 → 导入 → 推送
bd hooks install           # 安装 Git 钩子以实现自动同步

后台守护进程（daemon）采用 30 秒防抖策略自动同步。如需立即同步，请手动执行 bd sync。

维护命令

bd admin compact --dry-run --json   # 预览压缩效果
bd admin compact --days 90          # 压缩已关闭超过 90 天的问题
bd doctor                           # 检查数据库健康状况

分层 ID（史诗任务 Epic）

bd create "项目 Alpha" -t epic -p 1 --json   # 返回：bd-a3f8
bd create "阶段 1" -p 1 --json                 # 返回：bd-a3f8.1
bd create "调研" -p 1 --json                # 返回：bd-a3f8.2
bd create "评审" -p 1 --json                  # 返回：bd-a3f8.3

最多支持三级嵌套：bd-a3f8 → bd-a3f8.1 → bd-a3f8.1.1

多代理协同

# 代理领取任务
bd update bd-a1b2 --status in_progress --assignee agent-1 --json

# 查询指派给本代理的任务
bd ready --assignee agent-1 --json

# 跟踪新发现的任务
bd create "发现的问题" --deps discovered-from:bd-a1b2 --json

提交约定（可选）

对于由 Git 追踪的项目，建议在提交信息中包含问题 ID，以增强可追溯性：

git commit -m "完成调研阶段 (bd-a1b2)"

会话结束检查清单

在结束会话前，请执行以下操作：

bd sync                    # 刷新所有变更
bd ready --json            # 显示交接给下一环节的后续工作