核心定位
Beads 是专为 AI 代理设计的分布式 Git 支持型任务追踪系统，用依赖感知图替代传统 Markdown 计划，将任务数据以 JSONL 形式存储于 .beads/ 目录。
核心用法
初始化与基础操作
bd init --quiet：非交互式初始化，自动安装 Git hooksbd ready --json：获取就绪任务队列（核心工作入口）bd create "标题" -p 1 --json：创建任务，支持 epic/subtask 层级（如bd-a3f8→bd-a3f8.1）bd update <id> --status in_progress --assignee agent-1：认领并更新状态bd close <id> --reason "Done"：关闭任务bd sync：会话结束前强制同步到 Git
依赖管理
bd dep add child parent建立阻塞关系bd dep tree可视化依赖树bd dep cycles检测循环依赖- 支持
blocks/related/parent/discovered-from四种关系类型
多代理协作
- 通过
--assignee分配任务 bd ready --assignee agent-1查询特定代理的待办- 支持
--deps discovered-from追溯任务发现来源
显著优点
1. 机器优先设计：所有命令支持 --json 输出，无 GUI 依赖，完美适配 LLM 解析
2. Git 原生集成：任务数据版本化，天然支持分支、合并、回滚与团队协作
3. 依赖驱动工作流：自动计算就绪任务，避免代理执行阻塞操作
4. 层级化 ID 系统：Epic-Subtask 三级结构（如 bd-a3f8.1.2），便于大规模项目分解
5. 多安装渠道：Homebrew 与 npm 双渠道分发，降低部署门槛
潜在缺点与局限性
1. 生态早期阶段：作为新兴工具，社区规模、IDE 插件、第三方集成有限
2. 学习曲线：依赖图模型对传统待办清单用户有认知成本
3. Git 仓库污染：.beads/ 目录可能增大仓库体积，需定期 bd admin compact
4. 无云端托管：纯 Git 方案缺乏 SaaS 仪表盘，非技术成员参与门槛较高
5. 编辑限制：bd edit 命令依赖 $EDITOR，代理无法使用，需通过 bd update 逐项修改
适合人群
- AI 代理开发者：需要结构化任务队列与机器可读接口
- 技术驱动型团队：熟悉 Git 工作流，追求数据主权与离线优先
- 复杂项目管理者：任务间存在强依赖关系，需要拓扑排序执行
- 多代理协作场景：需明确任务归属与交接状态追踪
常规风险
- 数据一致性：代理异常终止可能导致本地变更未
bd sync，造成任务状态丢失 - Git 冲突：多代理同时修改
.beads/可能引发合并冲突，需依赖自动同步机制 - ID 硬编码风险：脚本或提示词中硬编码
bd-a1b2格式 ID，若重新初始化会失效 - 权限管理：无内置权限层，依赖 Git 托管平台的访问控制，敏感任务需额外保护