核心用法
Beads 是一款面向 AI 编程 Agent 的 Git 原生问题追踪器，以 JSONL 格式在 .beads/ 目录中存储依赖感知的任务图，彻底取代传统的 Markdown 计划文档。
关键工作流：
1. 初始化：bd init --quiet 在仓库中静默设置
2. 获取任务：bd ready --json 输出可执行的未阻塞任务队列
3. 执行追踪：bd update <id> --status in_progress 认领任务，完成后 bd close
4. 强制同步：bd sync 在会话结束前刷新变更到 Git
Agent 专用特性：
- 强制
--json输出确保机器可读 - 禁用
bd edit（调用 $EDITOR），改用bd update程序化修改 - 支持多级 Epic ID（如
bd-a3f8.1.2） - 内置多 Agent 协调：
--assignee字段 +discovered-from依赖类型
依赖管理：blocks（默认）、related、parent、discovered-from 四种类型，支持 bd dep tree 可视化与循环检测。
显著优点
- Git 原生：任务状态即代码，天然版本控制、分支隔离、冲突解决
- Agent 优先设计：JSON 接口、非交互式初始化、程序化更新，无 GUI 依赖
- 依赖感知：自动计算就绪队列，避免人工筛选任务
- 多 Agent 安全：显式认领机制防止重复工作
- 轻量无服务端：纯本地运行，无需数据库部署
潜在缺点与局限
- 生态早期：brew/npm 双渠道分发，成熟度待验证
- 学习成本：CLI 命令丰富（20+ 子命令），需记忆专用语义
- Git 污染：
.beads/目录可能增大仓库体积，需定期admin compact - 无 Web UI：纯终端工具，人类协作体验弱于 GitHub Issues
- 锁定风险：专有 JSONL 格式，迁移工具未提及
适合人群
- AI 编程 Agent：Claude Code、Devin、Cline 等工具链集成
- 多 Agent 协作团队：需要防冲突任务分配的工程团队
- Git 原生工作流拥护者：厌恶 Jira/Linear 等外部 SaaS 的开发者
- 边缘/离线开发场景：无网络依赖的本地-first 需求
常规风险
- 数据丢失：
--stealth模式不提交 Git，本地故障可能丢失任务 - 并发冲突：多 Agent 同时
bd sync可能引发 Git 合并冲突 - ID 漂移：Epic 子任务 ID 自动生成，重命名 Epic 会破坏层级
- 过度工程：小型项目可能不需要完整的依赖图管理
- 钩子依赖：
bd hooks install修改 Git 配置，可能影响其他工作流