beads

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beads (bd) Usage Rules

Beads (bd) 使用规则

First-Time Setup

首次设置

If
bd
command is not found, tell the user:

Run:
curl -fsSL https://raw.githubusercontent.com/schlenks/superpowers-bd/main/scripts/setup-beads-local.sh | bash
This installs beads, initializes stealth mode, and adds git worktree support. For team use (shared
.beads/
), use
bd init
without
--stealth
.

如果未找到
bd
命令，请告知用户：

运行：
curl -fsSL https://raw.githubusercontent.com/schlenks/superpowers-bd/main/scripts/setup-beads-local.sh | bash
此命令会安装beads、初始化隐身模式并添加git worktree支持。如果是团队使用（共享
.beads/
目录），请使用不带
--stealth
参数的
bd init
命令。

TL;DR

快速上手

bash

bd ready                    # What can I work on?
bd update <id> --claim      # I'm starting this
bd close <id>               # I'm done with this
bd sync                     # Save my changes

Critical rules:

Never use semicolons in
```
--acceptance
```
(triggers permission prompts)
Never use
```
bd edit
```
(opens interactive editor)
Always run
```
bd sync
```
before ending a session

bash

bd ready                    # 我可以处理哪些工作？
bd update <id> --claim      # 我开始处理这个任务了
bd close <id>               # 我完成这个任务了
bd sync                     # 保存我的更改

关键规则：

切勿在
```
--acceptance
```
中使用分号（会触发权限提示）
切勿使用
```
bd edit
```
（会打开交互式编辑器）
结束会话前务必运行
```
bd sync
```

Permission Avoidance (Critical)

权限规避（至关重要）

Never use semicolons in
```
--acceptance
```
:
```
;
```
pattern triggers prompts. Use commas or
```
$'...\n...'
```
Use
```
--body-file
```
for multi-line content: newlines break pattern matching. Write to temp file first
Never delete temp files with
```
rm
```
: triggers permission prompts. Leave for human cleanup

切勿在
```
--acceptance
```
中使用分号：
```
;
```
会触发提示。请使用逗号或
```
$'...\n...'
```
多行内容请使用
```
--body-file
```
：换行符会破坏模式匹配。请先写入临时文件
切勿使用
```
rm
```
删除临时文件：会触发权限提示。留给人工清理

Issue Operations

问题操作

Create epic:

bd create --silent --type epic "Title" --body-file temp/desc.md -p 1

Create child task:

bd create --silent --parent <epic-id> "Title" --body-file temp/desc.md -p 2

Add dependencies:
```
--deps "id1,id2"
```
(comma-separated, no spaces)
View issue:
```
bd show <id>
```
Update issue:
```
bd update <id> --status=in_progress
```
Claim issue:
```
bd update <id> --claim
```
(sets assignee + in_progress atomically)
Close issue:
```
bd close <id>
```
Close multiple:
```
bd close <id1> <id2> <id3>
```
Close with reason:
```
bd close <id> --reason "explanation"
```
Add comment:
```
bd comments add <id> "comment text"
```
Add comment from file:
```
bd comments add <id> -f temp/comment.md
```

创建Epic：

bd create --silent --type epic "标题" --body-file temp/desc.md -p 1

创建子任务：

bd create --silent --parent <epic-id> "标题" --body-file temp/desc.md -p 2

添加依赖：
```
--deps "id1,id2"
```
（逗号分隔，无空格）
查看问题：
```
bd show <id>
```
更新问题：
```
bd update <id> --status=in_progress
```
认领问题：
```
bd update <id> --claim
```
（自动设置经办人并标记为进行中）
关闭问题：
```
bd close <id>
```
批量关闭：
```
bd close <id1> <id2> <id3>
```
带原因关闭：
```
bd close <id> --reason "说明"
```
添加评论：
```
bd comments add <id> "评论内容"
```
从文件添加评论：
```
bd comments add <id> -f temp/comment.md
```

Query Commands

查询命令

Ready work (no blockers):
```
bd ready
```
Blocked work:
```
bd blocked
```
Search issues:
```
bd search --query "text" --status open
```

List with filters:

bd list --status open --type task --priority-max 2

View dependency graph:
```
bd graph <id>
```
Check stale issues:
```
bd stale --days 14
```
Lint issues:
```
bd lint --status open
```

可处理的工作（无阻塞）：
```
bd ready
```
被阻塞的工作：
```
bd blocked
```

搜索问题：

bd search --query "文本" --status open

带筛选的列表：

bd list --status open --type task --priority-max 2

查看依赖图：
```
bd graph <id>
```
检查停滞问题：
```
bd stale --days 14
```
检查问题规范：
```
bd lint --status open
```

Maintenance Commands

维护命令

Health check:
```
bd doctor
```
Auto-fix issues:
```
bd doctor --fix
```
Cleanup old issues:
```
bd cleanup
```
Prime AI context:
```
bd prime
```
Database info:
```
bd info
```

健康检查：
```
bd doctor
```
自动修复问题：
```
bd doctor --fix
```
清理旧问题：
```
bd cleanup
```
初始化AI上下文：
```
bd prime
```
数据库信息：
```
bd info
```

Key Flags

关键标记

```
--silent
```
: output only ID (for scripting)
```
--json
```
: output in JSON format
```
--quiet
```
: suppress non-essential output
```
--type
```
: bug, feature, task, epic, chore, merge-request, molecule, gate
```
--parent <id>
```
: create as child of epic
```
-d "text"
```
: single-line description (prefer
```
--body-file
```
for multi-line)
```
--body-file <path>
```
: read description from file
```
-p N
```
: priority 0-4 (0=critical, 4=backlog)
```
--deps "id1,id2"
```
: dependencies (blocked by these)
```
--acceptance "..."
```
: acceptance criteria (no semicolons!)
```
--external-ref "ref"
```
: external link (e.g., "sc-1234")
```
-l "label1,label2"
```
: labels (comma-separated)

```
--silent
```
：仅输出ID（用于脚本）
```
--json
```
：以JSON格式输出
```
--quiet
```
：抑制非必要输出
```
--type
```
：bug、feature、task、epic、chore、merge-request、molecule、gate
```
--parent <id>
```
：创建为Epic的子任务
```
-d "文本"
```
：单行描述（多行内容优先使用
```
--body-file
```
）
```
--body-file <路径>
```
：从文件读取描述
```
-p N
```
：优先级0-4（0=严重，4=待办）
```
--deps "id1,id2"
```
：依赖项（被这些问题阻塞）
```
--acceptance "..."
```
：验收标准（切勿使用分号！）
```
--external-ref "ref"
```
：外部链接（例如："sc-1234"）
```
-l "label1,label2"
```
：标签（逗号分隔）

Session End Protocol

会话结束流程

bash

bd create "Remaining work" -d "..." -p 2   # 1. File remaining work
bd close <completed-ids>                    # 2. Close completed (unblocks dependents)
bd sync                                     # 3. Force sync (bypasses 30s debounce)
git status                                  # 4. Check what changed
git add <files>                             # 5. Stage code changes
git commit -m "..."                         # 6. Commit changes

bash

bd create "剩余工作" -d "..." -p 2   # 1. 记录剩余工作
bd close <已完成任务ID>                    # 2. 关闭已完成任务（解除依赖阻塞）
bd sync                                     # 3. 强制同步（绕过30秒防抖）
git status                                  # 4. 检查更改内容
git add <文件>                             # 5. 暂存代码更改
git commit -m "..."                         # 6. 提交更改

Integration with Skills

与技能集成

```
superpowers-bd:plan2beads
```
: convert markdown plan to epic with child tasks

superpowers-bd:writing-plans

: create plans with

Depends on:

and

Files:

sections

```
superpowers-bd:subagent-driven-development
```
: parallel execution with dependency awareness

```
superpowers-bd:plan2beads
```
：将Markdown计划转换为带子任务的Epic

superpowers-bd:writing-plans

：创建包含

Depends on:

和

Files:

章节的计划

superpowers-bd:subagent-driven-development

：支持依赖感知的并行执行

Reference Files

参考文件

```
references/acceptance-and-multiline.md
```
: writing acceptance criteria or multi-line descriptions
```
references/bd-edit-and-sandbox.md
```
: encountering bd edit usage or sandbox errors
```
references/dependency-management.md
```
: creating dependencies, fixing deadlocks, verifying dep structure
```
references/workflow-patterns.md
```
: running autonomous work loops, checking status values
```
references/session-end-details.md
```
: why bd sync matters or ephemeral branch handling
```
references/sync-workflow.md
```
: using sync subcommands, daily maintenance schedule
```
references/troubleshooting.md
```
: database sync issues, worktree limitations, merge conflicts
```
references/parallel-execution-safety.md
```
: dispatching parallel subagents, epic scoping, priority values, ID format

```
references/acceptance-and-multiline.md
```
：编写验收标准或多行描述
```
references/bd-edit-and-sandbox.md
```
：遇到bd edit使用问题或沙箱错误
```
references/dependency-management.md
```
：创建依赖、修复死锁、验证依赖结构
```
references/workflow-patterns.md
```
：运行自主工作循环、检查状态值
```
references/session-end-details.md
```
：bd sync的重要性或临时分支处理
```
references/sync-workflow.md
```
：使用同步子命令、日常维护计划
```
references/troubleshooting.md
```
：数据库同步问题、worktree限制、合并冲突
```
references/parallel-execution-safety.md
```
：调度并行子代理、Epic范围界定、优先级值、ID格式