Beads 示例仓库实战指南：用 bd 为 AI Agent 构建自动化任务工作流

Beads 示例仓库实战指南用 bd 为 AI Agent 构建自动化任务工作流【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读本指南以 Beads 仓库 examples/README.md 为骨架系统讲解如何利用 bdBeads 命令行工具为 AI Agent 构建发现就绪任务 → 认领执行 → 发现新问题 → 建立依赖 → 完成任务的闭环工作流。文章覆盖 Agent 集成Python / Bash / MCP / 启动钩子、团队与多角色协作模式贡献者、团队、多阶段、多角色、受保护分支以及运维工具Dolt 自动同步、数据库压缩所有命令均给出可复制的完整示例并结合仓库源码如 internal/types/types.go、internal/config/config.go补充底层实现依据。读完你将掌握如何用bd ready/bd update --claim/bd dep add/bd close四类命令驱动 Agent 自主作业如何在多仓库、多成员、受保护分支环境下同步与协作以及如何用启动钩子与压缩脚本做日常维护。一、示例仓库整体地图examples/目录是 Beads 官方为AI Agent 集成与工作流提供的实战素材库按主题划分为三大类分类示例核心价值Agent 集成python-agent/、bash-agent/、startup-hooks/、claude-desktop-mcp/让 Agent 通过 bd 自主管理任务工作流模式contributor-workflow/、team-workflow/、multi-phase-development/、multiple-personas/、protected-branch/多仓库、多成员、多角色的协作组织方式工具与运维compaction/、formulas/、library-usage/、bd-example-extension-go/压缩、公式、Go 库调用等扩展能力注意原示例中的monitor-webui、git-hooks、branch-merge、markdown-to-jsonl等条目已被移除examples/README.md中以REMOVED注释标记hash 型 issue ID 已使冲突消解不再必要bd 的原生 jira/linear/gitlab 同步已取代旧转换器因此当前仓库中不存在这些目录请勿按旧文档路径查找。二、Agent 集成六步闭环工作流所有 Agent 示例共享同一条核心工作流examples/README.md 中的 Creating Your Own Agent 一节它也是全书反复出现的模式# 1. 查找就绪任务无阻塞依赖、按优先级排序 bd ready --json --limit 1 # 2. 认领任务将状态置为 in_progress bd update id --claim --json # 3. 执行任务真实 Agent 中调用 LLM / 执行代码 # 4. 工作中发现新问题 bd create Found bug --json # 5. 将发现链接回父任务 bd dep add new-id parent-id --type discovered-from # 6. 完成任务并继续下一轮 bd close id --reason Done --json所有命令均支持--json输出便于程序化解析——这是整个示例体系的技术基石。从源码看discovered-from是 bd 原生支持的六种依赖类型之一定义于 internal/types/types.go与blocks、parent-child、conditional-blocks、waits-for、related并列见 internal/types/types.go。它专门用于表达实现某任务时发现的新工作让 Agent 的探索过程可追溯。2.1 Python AgentBeadsAgent类逐行拆解examples/python-agent/agent.py 实现了一个约 150 行的完整 Agent核心是BeadsAgent类的六个方法与六步工作流一一对应run_bd(*args)将任意bd子命令追加--json参数执行并json.loads解析输出examples/python-agent/agent.pyfind_ready_work()调用bd ready --limit 1取优先级最高的就绪任务examples/python-agent/agent.pyclaim_task(issue_id)bd update id --status in_progress认领examples/python-agent/agent.py。注意示例脚本同时演示了--claim快捷标志bash 版使用两种写法等价create_issue(...)封装bd create支持-p优先级与-tissue 类型参数examples/python-agent/agent.pylink_discovery(...)bd dep add new-id parent-id --type discovered-fromexamples/python-agent/agent.pycomplete_task(...)bd close id --reason reasonexamples/python-agent/agent.py。run()主循环默认迭代 10 轮每轮执行run_once()发现任务 → 认领 → 模拟工作 → 完成。模拟逻辑中只要任务标题含 implement 或 add就自动创建Add tests for ...的补测试任务并链接回父任务examples/python-agent/agent.py直观演示了工作中发现新工作的自动闭环。运行方式chmod x agent.py ./agent.py # 默认最多 10 轮迭代前置条件Python 3.7、已安装 bdbd init初始化过数据库。2.2 Bash Agent零依赖的完整 Agent 循环examples/bash-agent/agent.sh 是纯 bash 实现依赖jq做 JSON 解析演示了完整生命周期并额外提供彩色终端输出log_info/log_success/log_warning/log_error见 examples/bash-agent/agent.sh环境变量BEADS_AGENT_NAME指定 Agent 身份启动自检未安装 bd、或不在 beads 初始化目录时给出明确指引examples/bash-agent/agent.sh工作中以 50% 概率模拟发现后续任务RANDOM % 2见 examples/bash-agent/agent.sh每轮显示bd stats统计。运行与自定义./agent.sh # 默认 10 轮 ./agent.sh 20 # 自定义轮数 ./agent.sh 1 # 只处理一个任务将发现概率从 50% 改为 30%if [[ $((RANDOM % 10)) -lt 3 ]]; then # 30% chance自定义就绪查询与创建参数# 按分配者过滤 bd ready --json --assignee bot --limit 1 # 按优先级过滤 bd ready --json --priority 1 --limit 1 # 创建带标签的任务 bd create New task -l automated,agent-discoveredbash 版 READMEexamples/bash-agent/README.md还给出了三类落地场景CI 中运行./agent.sh 5批量处理测试任务cron 每小时./agent.sh 3一次性处理./agent.sh 1。2.3 从模拟到真实 LLM Agent 的改造路径两个 README 都给出了同一套改造建议examples/python-agent/README.md用真实 LLM API 调用替换simulate_work()/do_work()解析 LLM 响应识别需要追踪的新 bug / 任务用 issue ID 跨会话维护上下文任务认领后 ID 不变Agent 重启可续作通过 JSONL 导出 / 导入在 Agent 会话间共享状态。2.4 会话启动钩子自动感知 bd 升级examples/startup-hooks/bd-version-check.sh 解决一个真实痛点bd 升级后 Agent 如何自动获知变化。脚本在会话开始时对比当前 bd 版本与.beads/metadata.json中记录的last_bd_version发现变化即输出bd info --whats-new并顺带用bd hooks list检测 git hooks 是否过期、自动执行bd hooks install更新。# 推荐source 方式脚本末尾的 return 0 兼容 source 场景 source examples/startup-hooks/bd-version-check.sh # 或直接执行 bash examples/startup-hooks/bd-version-check.sh集成到各 Agent 环境的方式examples/startup-hooks/README.mdClaude Code放入.claude/hooks/session-startGitHub Copilot / Cursor写入~/.bashrc或~/.zshrc并加目录判断if [ -d .beads ]; then source /path/to/beads/examples/startup-hooks/bd-version-check.sh fi脚本的健壮性设计值得借鉴不在 beads 项目、bd 未安装、bd 命令失败时均静默退出jq缺失仅告警不中断metadata.json缺失时自动创建初始内容{database: beads.db, jsonl_export: beads.jsonl}首次运行只记录版本不弹升级提示。版本写入采用 mktemp 临时文件 jq 原子替换避免损坏元数据examples/startup-hooks/bd-version-check.sh。典型输出形如 bd upgraded: 0.23.0 → 0.24.2 Whats New in bd (Current: v0.24.2) ... Git hooks outdated. Updating to match bd v0.24.2... ✓ Git hooks updated successfully2.5 MCP 服务器把 bd 能力接入 Claude Desktopexamples/claude-desktop-mcp/README.md 记录了两个重要事实一是 beads 的 MCP 服务器已正式实现生产级代码位于 integrations/beads-mcp/二是官方给出了明确的选择建议——在具备 shell 访问的环境Claude Code、Cursor、Windsurf优先用 CLI hooks 而非 MCP因为 CLI 方案仅消耗约 1-2k tokens而 MCP schema 需 10-50k tokens计算成本与延迟更高仅对 Claude Desktop 这类纯 MCP 环境才推荐 MCP。在 Claude Desktop 中接入# 推荐用 uv 安装 uv tool install beads-mcp # 或 pip pip install beads-mcp编辑~/Library/Application Support/Claude/claude_desktop_config.jsonmacOS{ mcpServers: { beads: { command: beads-mcp } } }文档同时保留了设计阶段的工具接口蓝图examples/claude-desktop-mcp/README.md映射关系如下MCP 工具底层 bd 命令核心参数beads_ready_workbd ready --jsonlimit、priority0-4、assigneebeads_create_issuebd create --jsontitle、description、priority、typebug/feature/task/epic/chorebeads_update_issuebd update --jsonid、statusopen/in_progress/blocked/closed、priority、assigneebeads_add_dependencybd dep addfrom、to、typeblocks/related/parent-child/discovered-from该表同时可作为 Agent 工具参数的速查手册。对于尚无 MCP 的环境文档还提供了直接在项目说明文件如 CLAUDE.md中声明 bd 命令集的替代方案让 Agent 通过 shell 直接使用 bd。三、工作流模式从单人 Agent 到团队协作3.1 贡献者工作流规划与代码提交彻底分离examples/contributor-workflow/README.md 解决 OSS 贡献者的经典痛点个人规划todo、设计笔记、实验性工作不应污染上游 PR。方案是bd init --contributor向导git clone https://github.com/YOUR_USERNAME/project.git cd project git remote add upstream https://github.com/ORIGINAL_OWNER/project.git # 分叉检测关键 bd init --contributor # 向导自动完成检测 fork → 创建规划仓库 ~/.beads-planning → 配置自动路由 → git 初始化规划仓库路由配置的默认值有源码依据routing.maintainer默认为.当前仓库、routing.contributor默认为~/.beads-planning而routing.mode默认空字符串表示关闭见 internal/config/config.go 及 internal/config/config_test.go 的测试断言。启用后bd create创建的任务会自动落入规划仓库# 自动路由到 ~/.beads-planning/.beads/而非当前仓库 bd create Fix authentication bug -p 1 # 跨仓库统一视图 bd list # 两个仓库的全部 issue bd list --source-repo . # 仅当前仓库 bd list --source-repo ~/.beads-planning # 仅规划仓库派生工作继承父任务来源--deps discovered-from:id创建的新 issue 自动归属父任务所在仓库代码提交则只走 fork规划永不进入 PR。文档还给出了完整的手动配置路径与旧版兼容键contributor.planning_repo/contributor.auto_route已弃用但可用以及三个常用覆盖手段--repo .强制写入当前仓库、routing.contributor更换规划仓库位置、routing.mode explicitrouting.default .关闭自动路由。3.2 团队工作流共享仓库 自动同步examples/team-workflow/README.md 面向共享仓库的多成员协作核心是bd init --team向导检测 git 配置 → 询问 main 是否受保护 → 配置同步分支 → 开启自动同步与团队模式。核心机制是Dolt 数据库的分布式同步issue 元数据存储在 Dolt 中由 Dolt 服务器自动提交。两种同步策略# 自动同步推荐开启后 Dolt 服务器自动 commit push bd config set dolt.auto-commit on bd dolt start # 手动同步完全掌控节奏 bd dolt push # 推送本地变更到远端 bd dolt pull # 拉取远端变更冲突处理借助 Dolt 原生的三方合并与 git 类似配合 hash 型 ID 从根本上减少冲突bd sql SELECT * FROM dolt_conflicts bd sql CALL dolt_conflicts_resolve(--ours) # 或 --theirs bd dolt push日常场景覆盖完整每日站会bd list --status in_progress/bd ready/bd list --status closed --limit 10、冲刺规划bd update id --assignee alice分配、bd dep add ... --type blocks排依赖、PR 集成bd close id --reason PR #123 merged。问题排查路径清晰bd doctor检查服务器、bd config get dolt.auto-commit验证配置、bd dolt stop bd dolt start重启、bd validate --checksconflicts校验。3.3 受保护分支工作流beads-metadata旁路同步examples/protected-branch/README.md 解决了main 受保护要求 PR却想把 issue 元数据纳入 git的矛盾把元数据提交到独立同步分支定期经 PR 合并回 main。# 一次性初始化指定同步分支 bd init --branch beads-metadata --quiet bd config get sync.branch # 输出: beads-metadata # Agent 正常创建/更新 issue无需感知分支 bd create Implement user authentication -t feature -p 1 # 启动 Dolt 服务器后自动提交到 beads-metadata bd config set dolt.auto-commit on bd dolt start # 或手动推送 bd dolt push目录结构的关键点.git/beads-worktrees/beads-metadata/是隐藏的轻量 worktreesparse checkout 仅含.beads/你的src/代码永远不会被 beads 提交波及磁盘开销仅数 MB。合并到 main 的两条路径# 路径一PR推荐 git push origin beads-metadata gh pr create --base main --head beads-metadata \ --title Update issue metadata \ --body Automated issue tracker updates from beads # 路径二有 push 权限时直接合并 git checkout main git merge beads-metadata --no-ff git push bd dolt pull # 将合并结果拉回本地数据库多克隆多 Agent场景下克隆 Abd createbd dolt pushgit push origin beads-metadata克隆 B 只需git fetch origin beads-metadatabd dolt pullbd list即可看到新 issue。文档还附带了 GitHub Actions 每日自动合并 workflow 的完整 YAMLcron 触发 → 检测.beads/是否有 diff → 有则gh pr create。3.4 多阶段开发epic 层级依赖驱动项目节奏examples/multi-phase-development/README.md 展示如何用epic 层级 issue blocks 依赖组织大型项目规划 → MVP → 迭代 → 打磨# 创建 epic子任务自动获得层级 IDbd-a1b2c3.1、bd-a1b2c3.2 ... bd create Build real-time collaboration system -t epic -p 1 # 阶段间用 blocks 依赖串行化 bd dep add bd-a1b2c3.2 bd-a1b2c3.1 --type blocks bd dep add bd-a1b2c3.3 bd-a1b2c3.2 --type blocks bd dep add bd-a1b2c3.4 bd-a1b2c3.3 --type blocks # 关闭上一阶段即自动解锁下一阶段 bd close bd-a1b2c3.1 --reason Research complete, chose Socket.IO CRDT bd ready # 现在只显示 Phase 2 及以后的任务阶段内的任务用--deps discovered-from:phase-id挂到对应阶段形成可追溯树bd dep tree bd-a1b2c3输出完整的层级视图含每个任务的 CLOSED / IN_PROGRESS / OPEN 状态与阻塞说明。文档还总结了五条最佳实践阶段要有明确退出标准、阶段内区分优先级P0 关键路径 vs P3 锦上添花、发现的工作一律链接父级、低优先级任务不要阻塞阶段推进可降级为 P4 放入 backlog、每周用bd stats/bd list --status blocked/bd ready复盘。并行工作流前后端无 blocks 依赖同时出现在bd ready与回滚预案--type related非阻塞关联也是文档中的可用模式。3.5 多角色工作流label 依赖表达职责边界examples/multiple-personas/README.md 用label角色/类型/状态/领域/质量/客户六维标签体系为 architect、implementer、reviewer、product owner 划分视图与交接# 架构师建 epic、打 architecture 标签、产出 ADR bd create Design new caching layer -t epic -p 1 bd label add bd-a1b2c3 architecture # 实现者按标签过滤就绪工作 bd ready | grep implementation bd list --label implementation --type bug --priority 0 # 审查者创建 review 任务并用 blocks 阻塞到问题修复 bd create Code review: Redis caching layer -p 1 bd label add bd-review1 review bd dep add bd-review1 bd-bug2 --type blocks # 产品负责人调整优先级、关联用户故事 bd update bd-impl2 --priority 0 bd create As a user, I want faster page loads -t feature -p 1 bd dep add bd-impl1 bd-story1 --type related推荐的标签组织示例examples/multiple-personas/README.md角色标签architecture, implementation, review, product类型标签bug, feature, task, chore, documentation状态标签critical, blocked, waiting-feedback, needs-design领域标签frontend, backend, infrastructure, database。多标签组合过滤如bd list --label backend --label implementation --status open可实现任意角色视图。交接模式的要点是关闭任务时写清原因Design complete, created bd-impl1...而非 done、实现与架构用related关联、升级处理时给 issue 加architecture/needs-design标签转交架构师。四、自动化运维数据库压缩脚本examples/compaction/README.md 提供三个数据库压缩脚本均需ANTHROPIC_API_KEY调用语义压缩脚本定位运行方式workflow.sh交互式每级压缩前提示确认export ANTHROPIC_API_KEYsk-ant-... ./workflow.shcron-compact.sh全自动适合 cron需BD_REPO_PATH、BD_LOG_FILE环境变量auto-compact.sh阈值触发的智能压缩./auto-compact.sh --threshold 50/--dry-run预览cron 安装示例cp cron-compact.sh /etc/cron.monthly/bd-compact chmod x /etc/cron.monthly/bd-compact # 或 crontab -e 添加: 0 2 1 * * /path/to/cron-compact.sh按规模选择的官方建议小型项目500 issue手动workflow.sh每年 1-2 次中型500-5000季度cron-compact.sh或在 CI 用auto-compact.sh大型5000月度cron-compact.sh高节奏团队组合使用。成本估算公式(issues_compacted / 1000) * $1.00可用bd admin compact --stats查看压缩统计。注意文档明确说明Tier 2 超压缩仍属规划中目前仅--tier 1可用写作时勿引用不存在的功能。五、与仓库源码的相互印证示例中的核心机制均有源码支撑可作为深入阅读入口依赖类型体系blocks、parent-child、conditional-blocks、waits-for、related、discovered-from六种类型定义于 internal/types/types.go示例中大量使用的discovered-from与blocks均在此列路由配置默认值routing.mode默认空关闭、routing.maintainer默认.、routing.contributor默认~/.beads-planning定义于 internal/config/config.go并有 internal/config/config_test.go 的回归测试锁定这些默认值Agent 模板仓库自带的 Agent 引导模板位于 internal/templates/agents/defaults/beads-section.md与示例中的bd ready/bd create/bd dep add用法同源MCP 生产实现integrations/beads-mcp/README.md 是 examples/claude-desktop-mcp/README.md 中设计蓝图落地的最终形态issue 生命周期与关闭理由bd close --reason、--claim、--assignee等参数在cmd/bd/下对应实现如 close.go、update.gobd ready的--limit截断提示可在 ready.go 找到。六、快速上手十分钟跑通第一个 Agent# 1. 安装 bd 并初始化数据库 bd init # 2. 创建两条初始任务供 Agent 消费 bd create Implement user authentication -t feature -p 1 bd create Add login page -t task -p 1 # 3. 运行 Python Agent最多 10 轮迭代 cd examples/python-agent ./agent.py # 4. 观察输出认领 → 模拟实现 → 发现测试缺口 → 链接 → 关闭 # 5. 用统计命令复盘 bd stats bd list --status closed七、示例选择速查你的场景首选示例核心命令给 Agent 一个简单的任务闭环python-agent/ 或 bash-agent/bd ready/bd update --claim/bd closeAgent 需要感知 bd 升级startup-hooks/bd --version/bd info --whats-new/bd hooks install仅 MCP 环境Claude Desktopclaude-desktop-mcp/配置mcpServers.beads贡献 OSS不想污染上游 PRcontributor-workflow/bd init --contributor/--source-repo团队共享仓库协作team-workflow/bd init --team/bd dolt push/pullmain 分支受保护protected-branch/bd init --branch beads-metadata大型项目分阶段推进multi-phase-development/epic --type blocks--deps discovered-from多角色分工与交接multiple-personas/bd label add/ 多标签过滤数据库体积控制compaction/./auto-compact.sh --dry-run【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考