名称： beads
描述： 面向 AI 代理的 Git 后端问题追踪器。适用于管理任务、依赖关系或多步骤工作。触发场景包括：任务追踪、问题管理、依赖图、就绪工作队列或提及 "beads" / "bd" CLI。
元数据：
openclaw:
emoji: 📿
requires:
bins: [bd]
install:
- id: brew
kind: brew
formula: beads
bins: [bd]
label: 安装 beads (brew)
- id: npm
kind: npm
package: "@beads/bd"
bins: [bd]
label: 安装 beads (npm)

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 <id> --status in_progress — 认领任务
3. 执行工作
4. bd close <id> --reason "完成" — 完成任务
5. bd sync — 在会话结束前强制同步

代理关键规则

• 始终使用 --json 以获取机器可读的输出。
• 切勿使用 bd edit — 会打开 $EDITOR，代理无法使用。
• 使用 bd update 替代：bd update <id> --title "新标题" --description "新描述"
• 在会话结束时运行 bd sync，将所有更改刷新到 Git。

命令

初始化

bd init --quiet              # 非交互模式，自动安装钩子
bd init --prefix myproj      # 自定义 ID 前缀
bd init --stealth            # 仅本地，不提交 .beads/ 目录
bd init --contributor        # 分叉工作流（独立的规划仓库）

创建问题

bd create "标题" -p 1 --json                    # 优先级 1 (0=紧急, 3=低)
bd create "标题" -t epic -p 0 --json            # 创建史诗
bd create "子任务" -p 1 --json                  # 在史诗下创建：bd-a3f8.1, .2, .3
bd create "发现的问题" --deps discovered-from:bd-a1b2 --json

问题类型：task, bug, feature, epic
优先级：0 (P0/紧急) 到 3 (P3/低)

查询问题

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                    # 统计信息

更新问题

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

关闭问题

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

依赖关系

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 钩子

守护进程会自动同步，并带有 30 秒的去抖动。使用 bd sync 可强制立即同步。

维护

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

分层 ID（史诗）

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

最多支持 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            # 显示待交接的下一项工作