Beads - AI 代理的持久任務記憶
基於圖表的問題追蹤器，能跨越對話壓縮。為具有複雜依賴關係的多階段工作提供持久記憶。
概述
bd (beads) 用一個儲存在 git 中的、能感知依賴關係的圖表來取代 Markdown 任務列表。與 TodoWrite（會話範圍）不同，bd 能在壓縮後持久存在，並追蹤複雜的依賴關係。
主要區別：
- bd：多階段工作、依賴關係、跨壓縮存活、基於 git
- TodoWrite：單會話任務、線性執行、對話範圍
核心能力：
- 📊 依賴圖表：追蹤什麼阻塞了什麼（阻塞、父子、發現於、相關）
- 💾 壓縮存活：當對話歷史被壓縮時，任務依然存在
- 🐙 Git 整合：問題版本化在
.beads/issues.jsonl中，透過bd sync同步 - 🔍 智慧發現：自動尋找可處理的工作（
bd ready）和受阻的工作（bd blocked） - 📝 審計軌跡：狀態變更、備註和決策的完整歷史
- 🏷️ 豐富的元數據：優先級 (P0-P4)、類型 (bug/feature/task/epic)、標籤、負責人
何時使用 bd 與 TodoWrite：
- ❓ 「我兩週後還需要這個上下文嗎？」→ 是 = bd
- ❓ 「對話歷史可能會被壓縮嗎？」→ 是 = bd
- ❓ 「這個有阻塞項/依賴關係嗎？」→ 是 = bd
- ❓ 「這個工作是模糊/探索性的嗎？」→ 是 = bd
- ❓ 「這個會在本次會話中完成嗎？」→ 是 = TodoWrite
- ❓ 「這只是一個給我自己看的任務列表嗎？」→ 是 = TodoWrite
決策規則：如果沒有 bd，兩週後恢復工作會很困難，那就使用 bd。
先決條件
必要：
- bd CLI：0.34.0 或更高版本，已安裝且在 PATH 中
- Git 倉庫：當前目錄必須是 git 倉庫
- 初始化：必須執行過一次
bd init（由人類執行，非代理）
驗證安裝：
bd --version # 應該返回 0.34.0 或更高
首次設定（人類執行一次）：
cd /path/to/your/repo
bd init # 建立 .beads/ 目錄與資料庫
可選：
- 用於替代資料庫位置的 BEADS_DIR 環境變數
- 用於背景同步的守護行程：
bd daemon --start
使用說明
會話開始協議
每個會話，從這裡開始：
步驟 1：檢查可處理的工作
bd ready
顯示沒有任何未解決阻塞項的任務，按優先級排序 (P0 → P4)。
這會顯示：
- 任務 ID（例如
myproject-abc） - 標題
- 優先級
- 問題類型 (bug, feature, task, epic)
輸出範例：
claude-code-plugins-abc [P1] [task] open
Implement user authentication
claude-code-plugins-xyz [P0] [epic] in_progress
Refactor database layer
步驟 2：挑選最高優先級任務
選擇已準備就緒且優先級最高 (P0 > P1 > P2 > P3 > P4) 的任務。
步驟 3：取得完整上下文
bd show <task-id>
顯示：
- 完整的任務描述
- 依賴圖表（什麼阻塞此任務，此任務阻塞什麼）
- 審計軌跡（所有狀態變更、備註）
- 元數據（建立時間、更新時間、負責人、標籤）
步驟 4：開始工作
bd update <task-id> --status in_progress
將任務標記為正在積極處理中。
步驟 5：工作時添加備註
bd update <task-id> --notes "已完成：X。進行中：Y。被 Z 阻塞"
對壓縮存活至關重要：撰寫備註時，要像是向一個完全沒有對話上下文的未來代理解釋一樣。
備註格式（最佳實踐）：
已完成：具體交付物（例如「已實作 JWT refresh 端點 + 速率限制」）
進行中：當前狀態 + 下一步立即要做的
阻塞項：阻礙進度的原因
關鍵決策：重要的上下文或使用者指導
任務建立工作流程
何時建立任務
在下列情況下建立 bd 任務：
- 使用者提到要跨會話追蹤工作
- 使用者說「我們應該修復/建立/加入 X」
- 工作有依賴關係或阻塞項
- 探索/研究性質的工作，邊界模糊
基本任務建立
bd create "任務標題" -p 1 --type task
引數：
- 標題：簡短描述（必要）
- 優先級：0-4，0=關鍵，1=高，2=中，3=低，4=待辦事項（預設：2）
- 類型：bug, feature, task, epic, chore（預設：task）
範例：
bd create "修復驗證錯誤" -p 0 --type bug
建立時附加描述
bd create "實作 OAuth" -p 1 --description "為 Google、GitHub、Microsoft 加入 OAuth2 支援。使用 passport.js 函式庫。"
史詩與子任務
# 建立父級史詩
bd create "史詩：OAuth 實作" -p 0 --type epic
# 回傳：myproject-abc
# 建立子任務
bd create "研究 OAuth 提供者" -p 1 --parent myproject-abc
bd create "實作驗證端點" -p 1 --parent myproject-abc
bd create "加入前端登入 UI" -p 2 --parent myproject-abc
更新與進度工作流程
變更狀態
bd update <task-id> --status <新狀態>
狀態值：
open- 尚未開始in_progress- 正在積極處理blocked- 卡住，等待某件事closed- 已完成
範例：
bd update myproject-abc --status blocked
加入進度備註
bd update <task-id> --notes "在此輸入進度更新"
附加到現有的備註欄位（不會取代）。
變更優先級
bd update <task-id> -p 0 # 提升為關鍵
加入標籤
bd label add <task-id> backend
bd label add <task-id> security
標籤提供了超越狀態/類型的分類方式。
依賴關係管理
加入依賴關係
bd dep add <子任務-id> <父任務-id>
含義：<父任務-id> 阻塞 <子任務-id>（父任務必須先完成）。
依賴類型：
- blocks：父任務必須關閉，子任務才能準備就緒
- parent-child：父子層級關係（史詩和子任務）
- discovered-from：任務 A 導致發現任務 B
- related：任務相關但不阻塞
範例：
# 部署被測試通過阻塞
bd dep add deploy-task test-task # test-task 阻塞 deploy-task
檢視依賴關係
bd dep list <task-id>
顯示：
- 此任務阻塞什麼（依賴它的任務）
- 什麼阻塞此任務（阻塞它的任務）
防止循環依賴
bd 會自動防止循環依賴。如果您嘗試建立循環，命令會失敗。
完成工作流程
關閉任務
bd close <task-id> --reason "完成摘要"
最佳實踐：始終包含一個描述完成內容的原因。
範例：
bd close myproject-abc --reason "已完成：已實作 OAuth 端點，支援 Google、GitHub 提供者。測試通過。"
檢查新解除阻塞的工作
關閉任務後，執行：
bd ready
關閉一個任務可能會解除依賴該任務的其他任務的阻塞，使其變得可用。
子任務完成時關閉史詩
bd epic close-eligible
自動關閉所有子任務都已完成的史詩。
Git 同步工作流程
一鍵同步
bd sync
執行：
- 將資料庫匯出到
.beads/issues.jsonl - 提交變更到 git
- 從遠端拉取（必要時合併）
- 將更新的 JSONL 匯入回資料庫
- 將本地提交推送到遠端
使用時機：會話結束時、交接給同事前、重大進展後。
僅匯出
bd export -o backup.jsonl
建立 JSONL 備份，不執行 git 操作。
僅匯入
bd import -i backup.jsonl
從 JSONL 檔案匯入資料庫。
背景守護行程
bd daemon --start # 背景自動同步
bd daemon --status # 檢查守護行程健康狀態
bd daemon --stop # 停止自動同步
守護行程監控資料庫變更並自動匯出到 JSONL。
尋找與搜尋命令
尋找可處理的工作
bd ready
顯示沒有任何未解決阻塞項的任務。
列出所有任務
bd list --status open # 僅開放的任務
bd list --priority 0 # 僅 P0（關鍵）
bd list --type bug # 僅錯誤
bd list --label backend # 僅標記為「backend」
bd list --assignee alice # 僅指派給 alice
顯示任務詳細資訊
bd show <task-id>
完整詳細資訊：描述、依賴關係、審計軌跡、元數據。
按文字搜尋
bd search "authentication" # 搜尋標題和描述
bd search login --status open # 結合篩選條件
尋找受阻的工作
bd blocked
顯示所有因有未解決阻塞項而無法工作的任務。
專案統計
bd stats
顯示：
- 按狀態分類的總問題數 (open, in_progress, blocked, closed)
- 按優先級 (P0-P4)
- 按類型 (bug, feature, task, epic, chore)
- 完成率
完整命令參考
| 命令 | 使用時機 | 範例 |
|---|---|---|
| 尋找命令 | ||
bd ready | 尋找未阻塞的任務 | 使用者問「我該做什麼？」 |
bd list | 檢視所有任務（可篩選） | 「顯示所有開放的錯誤」 |
bd show <id> | 取得任務詳細資訊 | 「顯示任務 bd-42」 |
bd search <查詢> | 跨任務文字搜尋 | 「尋找關於 auth 的任務」 |
bd blocked | 尋找卡住的工作 | 「什麼在阻塞我們？」 |
bd stats | 專案指標 | 「有多少任務是開放的？」 |
| 建立命令 | ||
bd create | 追蹤新工作 | 「為這個錯誤建立一個任務」 |
bd template create | 使用問題模板 | 「從錯誤模板建立任務」 |
bd init | 初始化 beads | 「在此倉庫設定 beads」（僅人類） |
| 更新命令 | ||
bd update <id> | 變更狀態/優先級/備註 | 「標記為進行中」 |
bd dep add | 連結依賴關係 | 「這個阻塞那個」 |
bd label add | 用標籤標記 | 「將此標記為 backend」 |
bd comments add | 加入評論 | 「為任務加入評論」 |
bd reopen <id> | 重新開放已關閉的任務 | 「重新開放 bd-42，發現回歸」 |
bd rename-prefix | 重新命名問題前綴 | 「將前綴從 bd- 改為 proj-」 |
bd epic status | 檢查史詩進度 | 「顯示史詩完成百分比」 |
| 完成命令 | ||
bd close <id> | 將任務標記為完成 | 「關閉此任務，已完成」 |
bd epic close-eligible | 自動關閉完成的史詩 | 「關閉所有子任務都已完成的史詩」 |
| 同步命令 | ||
bd sync | Git 同步（一鍵） | 「將任務同步到 git」 |
bd export | 匯出到 JSONL | 「備份所有任務」 |
bd import | 從 JSONL 匯入 | 「從備份還原」 |
bd daemon | 背景同步管理器 | 「啟動自動同步守護行程」 |
| 清理命令 | ||
bd delete <id> | 刪除問題 | 「刪除測試任務」（需要 --force） |
bd compact | 歸檔舊的已關閉任務 | 「壓縮資料庫」 |
| 報告命令 | ||
bd stats | 專案指標 | 「顯示專案健康狀態」 |
bd audit record | 記錄互動 | 「記錄此 LLM 呼叫」 |
bd workflow | 顯示工作流程指南 | 「我該如何使用 beads？」 |
| 進階命令 | ||
bd prime | 刷新 AI 上下文 | 「載入 bd 工作流程規則」 |
bd quickstart | 互動式教學 | 「教我 beads 基礎」 |
bd daemons | 多倉庫守護行程管理 | 「管理所有 beads 守護行程」 |
bd version | 版本檢查 | 「檢查 bd 版本」 |
bd restore <id> | 還原已壓縮的問題 | 「從 git 取得完整歷史」 |
輸出
此技能產生：
任務 ID：格式 <前綴>-<雜湊>（例如 claude-code-plugins-abc, myproject-xyz）
狀態摘要：
5 開放, 2 進行中, 1 受阻, 47 已關閉
依賴圖表（視覺化樹狀結構）：
myproject-abc: 部署到正式環境 [P0] [blocked]
被以下項目阻塞:
↳ myproject-def: 執行整合測試 [P1] [in_progress]
↳ myproject-ghi: 修復失敗的測試 [P1] [open]
審計軌跡（完整歷史）：
2025-12-22 10:00 - 由 alice 建立 (P2, task)
2025-12-22 10:15 - 優先級變更: P2 → P0
2025-12-22 10:30 - 狀態變更: open → in_progress
2025-12-22 11:00 - 備註已加入: "已實作 JWT auth..."
2025-12-22 14:00 - 狀態變更: in_progress → blocked
2025-12-22 14:01 - 備註已加入: "被阻塞：API 端點回傳 503"
錯誤處理
常見失敗
1. bd: command not found
原因：bd CLI 未安裝或不在 PATH 中 解決方案：從 https://github.com/steveyegge/beads 安裝
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# 或透過 npm
npm install -g @beads/bd
# 或透過 Homebrew
brew install steveyegge/beads/bd
2. No .beads database found
原因：此倉庫中未初始化 beads
解決方案：執行 bd init（人類執行一次，非代理）
bd init # 建立 .beads/ 目錄
3. Task not found: <id>
原因：無效的任務 ID 或任務不存在
解決方案：使用 bd list 檢視所有任務並驗證 ID 格式
bd list # 檢視所有任務
bd search <部分標題> # 按標題尋找任務
4. Circular dependency detected
原因：嘗試建立循環依賴（A 阻塞 B，B 阻塞 A） 解決方案：bd 會自動防止循環依賴。重新安排依賴圖結構。
bd dep list <id> # 檢視當前依賴關係
5. Git merge conflicts in .beads/issues.jsonl
原因：多位使用者修改了同一個問題 解決方案：bd sync 會自動處理 JSONL 衝突。如果需要手動介入：
# 檢視衝突
git status
# bd 提供衝突解決工具
bd sync --merge # 嘗試自動解決
6. Database is locked
原因：守護行程或其他程序持有獨佔鎖 解決方案：重新啟動守護行程或等待鎖釋放
bd daemon --stop
bd daemon --start
7. 同步失敗
原因：網路問題、認證失敗或 git 配置 解決方案：檢查 git 遠端存取和憑證
git fetch # 測試連線
git status # 驗證倉庫狀態
範例
...