br

br — Beads Rust 问题跟踪器（官方技能）

非侵入式： br 绝不会运行 git 命令。同步和提交由你负责。

Agent 的关键规则

规则	原因
二进制文件是 br	绝不要使用 bd（那是旧版 Go 版本）
始终使用 --json	便于解析的结构化输出；使用 --format toon 可减少令牌用量
绝不要直接运行 bv	会在交互式 TUI 模式下阻塞会话
同步需要显式执行	br sync --flush-only 只会将数据库导出为 JSONL
Git 由你负责	br 只会操作 .beads/——你必须执行 git add .beads/ && git commit
不允许存在循环依赖	br dep cycles 必须返回空结果
运行时解析执行者	使用 ACTOR="${BR_ACTOR:-assistant}" 并传入 --actor "$ACTOR"

快速工作流

ACTOR="${BR_ACTOR:-assistant}"

# 1. Find work
br ready --json

# 2. Claim it
br update --actor "$ACTOR" <id> --status in_progress

# 3. Do work...

# 4. Complete
br close --actor "$ACTOR" <id> --reason "Implemented X"

# 5. Sync to git (EXPLICIT!)
br sync --flush-only
git add .beads/ && git commit -m "feat: X (<id>)"

必备命令

问题生命周期

ACTOR="${BR_ACTOR:-assistant}"

br init                                              # Initialize .beads/ workspace
br create --actor "$ACTOR" "Title" -p 1 -t task      # Create issue (priority 0-4)
br q --actor "$ACTOR" "Quick note"                   # Quick capture (ID only output)
br show <id> --json                                  # Show issue details
br update --actor "$ACTOR" <id> --status in_progress # Update status
br update --actor "$ACTOR" <id> --priority 0         # Change priority
br close --actor "$ACTOR" <id> --reason "Done"       # Close with reason
br close --actor "$ACTOR" <id1> <id2> --reason "..."  # Close multiple at once
br reopen --actor "$ACTOR" <id>                      # Reopen closed issue

创建选项

br create --actor "$ACTOR" "Title" \
  --priority 1 \             # 0-4 scale (0=critical, 4=backlog)
  --type task \              # task, bug, feature, epic, question, docs
  --assignee "user@..." \    # Optional assignee
  --labels backend,auth \    # Comma-separated labels
  --description "..."        # Detailed description

更新选项

br update --actor "$ACTOR" <id> \
  --title "New title" \
  --priority 0 \
  --status in_progress \     # open, in_progress, closed
  --assignee "new@..." \
  --add-label reliability \
  --parent <parent-id> \
  --claim                    # Shorthand for claim-and-start

批量更新（批量分类）：

br update --actor "$ACTOR" <id1> <id2> <id3> --priority 2 --add-label triage-reviewed --json

查询（Agent 始终使用 --json）

br ready --json                      # Actionable work (no blockers)
br list --json                       # All issues
br list --status open --sort priority --json  # Filter and sort
br list --priority 0-1 --json        # Filter by priority range
br list --assignee alice --json      # Filter by assignee
br blocked --json                    # Show blocked issues
br search "keyword" --json           # Full-text search
br show <id> --json                  # Issue details with dependencies
br stale --days 30 --json            # Stale issues
br count --by status --json          # Count with grouping

依赖项

br dep add <child> <parent>          # child depends on parent
br dep add <id> <depends-on> --type blocks  # Explicit block type
br dep remove <child> <parent>       # Remove dependency
br dep list <id> --json              # List dependencies for issue
br dep tree <id> --json              # Show dependency tree
br dep cycles --json                 # Find circular deps (MUST be empty!)

关键： br dep cycles 必须返回空结果。循环依赖会破坏依赖关系图，并导致 br ready 不可靠。

标签

br label add <id> backend auth       # Add multiple labels
br label remove <id> urgent          # Remove label
br label list <id>                   # List issue's labels
br label list-all                    # All labels in project

评论

ACTOR="${BR_ACTOR:-assistant}"
br comments add --actor "$ACTOR" <id> --message "Triage note" --json
br comments list <id> --json

同步（显式执行——绝不自动）

br sync --flush-only                 # Export DB to JSONL (before git commit)
br sync --import-only                # Import JSONL to DB (after git pull)
br sync --status                     # Check sync status

更改后的工作流：

br sync --flush-only
git add .beads/ && git commit -m "Update issues"

拉取后的工作流：

git pull
br sync --import-only

系统与诊断

br doctor                            # Full diagnostics
br stats --json                      # Project statistics
br config list                       # Show all configuration
br config get id.prefix              # Get specific value
br config set defaults.priority=1    # Set value
br where                             # Show workspace location
br version                           # Show version
br upgrade                           # Self-update (if enabled)
br lint --json                       # Lint issues for problems

优先级范围

优先级	含义	使用数字，而非文字
0	紧急	需要立即处理
1	高	重要，应尽快处理
2	中（默认）	普通优先级
3	低	有时间时处理
4	待办	未来考虑

问题类型

task、bug、feature、epic、question、docs

输出格式

标志	用途
--json	Agent 的默认选项——完整结构化数据
--format toon	面向上下文窗口敏感型 Agent 的令牌优化替代格式
（无标志）	带颜色的人类可读终端输出

bv 集成

关键： 绝不要直接运行 bv——它会启动交互式 TUI 并阻塞。

# Always use --robot-* flags:
bv --robot-next                      # Single top pick + claim command
bv --robot-triage                    # Full triage with recommendations
bv --robot-plan                      # Parallel execution tracks
bv --robot-insights | jq '.Cycles'   # Check graph health (must be empty)
bv --robot-priority                  # Priority misalignment detection
bv --robot-alerts                    # Stale issues, blocking cascades

Agent Mail 协调

多 Agent 协调时，将 bead ID 用作 thread_id：

概念	值
Mail thread_id	bd-###（问题 ID）
Mail 主题	[bd-###] ...
文件预留 reason	bd-###
提交消息	包含 bd-### 以便追溯

# 1. Reserve files for bead
file_reservation_paths(..., reason="bd-123")

# 2. Announce work in thread
send_message(..., thread_id="bd-123", subject="[bd-123] Starting...")

# 3. Do work...

# 4. Close bead and release
br close bd-123 --reason "Completed"
release_file_reservations(...)

会话结束流程

结束任何工作会话前：

git pull --rebase
br sync --flush-only
git add .beads/ && git commit -m "Update issues"
git push
git status  # MUST show "up to date with origin"

标准 Agent 工作流（完整）

ACTOR="${BR_ACTOR:-assistant}"

# 1. Verify workspace
br where
br ready --json
br blocked --json
br list --status open --sort priority --json

# 2. Pick highest-priority ready work
br show <id> --json

# 3. Claim it
br update --actor "$ACTOR" <id> --status in_progress --claim

# 4. Do work...

# 5. Close with evidence
br close --actor "$ACTOR" <id> --reason "Implemented X in commit abc123"

# 6. Check queue impact
br ready --json
br blocked --json

# 7. Sync to git
br sync --flush-only
git add .beads/ && git commit -m "feat: X (<id>)"
git push

分类决策矩阵

将每个问题准确归为以下一个类别：

分类	操作
implemented	附上证据（提交/PR/文件/行为）后关闭
out-of-scope	说明明确的范围边界原因后关闭
needs-clarification	评论中列出具体的未解问题
actionable	保持打开，并修正状态/优先级/标签/依赖项

大规模分类时，每更新几项就创建检查点：

br ready --json
br blocked --json

反模式

• 运行 br sync 时未使用 --flush-only 或 --import-only
• 忘记在 git 提交前同步
• 创建循环依赖
• 直接运行 bv（会阻塞会话）
• 假设会自动提交（br 绝不会自动提交）
• 捏造关闭问题的证据——不确定时应发表评论
• 分类时修改无关问题
• 添加推测性依赖项

存储布局

.beads/
  beads.db        # SQLite database (primary storage)
  beads.db-shm    # SQLite shared memory (WAL mode)
  beads.db-wal    # SQLite write-ahead log
  issues.jsonl    # JSONL export (for git)
  config.yaml     # Project configuration
  metadata.json   # Workspace metadata

故障排除

br doctor                    # Full diagnostics
br dep cycles                # Must be empty
br config list               # Check settings
which br                     # Verify br is installed

“Database locked”：使用 pgrep -f "br " 检查是否有其他 br 进程。

工作树错误（'main' is already checked out）：

git branch beads-sync main
br config set sync.branch beads-sync

详细调试：

br -v list                   # Verbose
br -vv list                  # Debug
RUST_LOG=debug br list       # Detailed trace logs

References

Topic	File
Command cookbook	references/COMMANDS.md
Configuration details	references/CONFIG.md
Troubleshooting guide	references/TROUBLESHOOTING.md
Multi-agent integration	references/INTEGRATION.md