Beads 与 bd CLI 实战指南用仓库级任务系统为 Coding Agent 建立持久工作记忆【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读Beads 是当前仓库提供的一套面向 Coding Agent如 Claude Code、Gemini CLI、Codex的持久化项目任务系统它以本地 Dolt 数据库为存储底座用bd命令行作为最紧凑的操作接口为找活、认领、跟踪依赖与阻塞、跨会话交接提供唯一可信的事实来源。本文以仓库内置的 SKILL.md 技能说明为骨架逐条展开其核心 CLI 工作流、适用边界与使用纪律并结合 docs/cli-reference 中各命令的完整参数说明与源码实现帮你把本地临时计划和仓库级持久任务正确分层让 agent 在上下文压缩compaction、线程重置与多智能体交接后依然能无缝恢复项目上下文。Beads 的定位本地计划 vs 共享任务系统的分界线SKILL.md 开篇就给出一条关键原则本地计划、草稿文件与个人记忆有用但它们不是项目工作的持久事实来源。Beads 作为共享项目任务系统承担的是团队/多智能体可恢复的职责agent 本地规划工具只应该承担当前这一轮执行的检查清单。对应到仓库实现上这条分界有明确的存储支撑任务数据落盘在本地 Dolt 数据库中而非普通文本文件cmd/bd 下的init.go、bootstrap.go等负责仓库工作区的初始化与引导使每个使用 Beads 的仓库拥有独立且可持续演进的持久状态bd update --no-history/--history等标志见 update.md控制单条 issue 是否参与 Dolt 提交历史进一步强化持久、可审计的定位。理解这层定位后后续所有命令的使用动机就非常清晰凡是另一个 agent 或人应当能接着干的工作一律进 Beads仅限当前轮次的执行步骤才留在本地 scratch 计划里。第一步用 bd prime 注入工作流上下文在进入任何 Beads 仓库工作时SKILL.md 规定的第一步是运行bd prime如果该命令没有任何输出则用bd where检查仓库是否存在活跃的 Beads 工作区bd where这两个命令的行为可以从 prime.md 与 where.md 的完整文档中展开bd prime输出AI 优化的 markdown 格式的核心工作流上下文专为 Claude Code、Gemini CLI、Codex 的 SessionStart 钩子设计防止上下文压缩后 agent 忘记 bd 工作流。它会自动探测 MCP server 是否激活并切换输出形态——MCP 模式只输出约 50 token 的简要提醒CLI 模式则输出约 1~2k token 的完整命令参考。bd where显示当前激活的 beads 数据库位置含重定向信息。文档明确说明它在调试 redirect 场景、确认实际使用哪个 beads workspace 时非常有用并支持bd where --json以 JSON 形式输出。bd prime还支持若干影响输出内容的标志标志作用--export输出默认内容忽略本地PRIME.md覆盖--full强制完整 CLI 输出忽略 MCP 探测--hook-json用 SessionStart 钩子 JSON 信封包裹输出Claude Code / Gemini CLI / Codex--mcp强制 MCP 模式极简输出--memories-only仅输出持久记忆适用于紧凑的钩子上下文--stealth隐身模式不做 git 操作仅 flush工作流定制方面可在本地克隆或已解析的 workspace 中放置.beads/PRIME.md完全覆盖默认输出或用--export导出默认内容后自行改造。no-git-ops配置项bd config set no-git-ops true可让 prime 输出隐身模式即会话关闭协议中不包含 git 命令适合希望手动控制提交时机的场景。从源码角度看bd prime是 agent 生命周期钩子体系的核心。在 agent_hook.go 中runBdPrime通过exec.CommandContext以子进程方式重新调用bd prime [args...]注释明确解释这么做的原因以子进程方式而非进程内调用避免存储的重复初始化re-entrant store initialization且os.Args[0]固定为 bd 二进制自身、参数为固定的 prime 子命令不存在注入风险。关于钩子注入的事实说明SKILL.md 的规则部分提到If hooks are installed,bd primemay already be injected即如果安装了钩子bd prime可能已被自动注入。这与仓库中的两处实现相互印证hooks.md 说明bd hooks install可安装 git 钩子pre-commit、post-merge、pre-push、post-checkout、prepare-commit-msg支持--beads安装到.beads/hooks/Dolt 后端推荐、--shared安装到可提交共享的.beads-hooks/等选项且使用 section markers 与既有钩子共存、升级不破坏用户内容cmd/bd 下的codex_hook.go、cursor_hook.go、agent_hook.go等实现了面向不同 agent 的 SessionStart 生命周期钩子prime-runner与一次性刷新标记机制在各 agent 间共用。因此当上下文缺失时手动运行bd prime是一个安全且推荐的动作agent 无需担心重复注入的副作用因为 prime 只是输出上下文文本。核心 CLI 工作流五步闭环SKILL.md 给出了一套从找活到收尾的五步闭环下面结合各命令的完整参数文档逐条展开并补充可编程解析所需的细节。1. 找活bd ready / bd listbd ready bd list --statusopen bd list --statusin_progressbd ready展示可认领的活即没有活跃阻塞active blockers的 open issue。根据 ready.md它底层调用 GetReadyWork API采用阻塞感知blocker-aware语义自动排除 in_progress、blocked、deferred 和 hooked 的 issuebd list --ready使用同一套语义。常用标志包括--claim原子认领匹配过滤条件的第一个 ready issue配合--json使用效果最佳适合 agent 执行 molecule 时自动推进下一步--explain展示为什么这些 issue ready/blocked的依赖感知推理--gated查找 gate 关闭后待恢复调度的 molecule--mol/--mol-type按 molecule 或 molecule 类型swarm / patrol / work过滤-a/--assignee、-u/--unassigned、-p/--priority、-t/--type、-l/--label、--label-any、--exclude-label、--include-deferred、--include-ephemeral等过滤组合-s/--sort排序策略priority 默认 / hybrid / oldest-n/--limit默认 100--plain普通编号列表与--pretty带状态/优先级符号的树形默认开启。bd list通用列表命令。状态过滤使用存储状态 open / in_progress / blocked / deferred / closed且文档特别提醒多状态过滤务必用逗号分隔形式--status open,in_progress因为重复传-s/--status会静默覆盖前值。其他实用点默认只展示非 closed 的 issue--all显式包含 closed树形层级默认开启--tree--flat关闭--long输出每条 issue 的多行详情过滤维度丰富时间--created-after/before、--due-before/after、--updated-*、--closed-*、文本--title-contains、--desc-contains、--notes-contains、标签--label-patternglob、--label-regex正则、元数据--metadata-field keyvalue、优先级区间--priority-min/max、特殊集合--overdue、--deferred、--pinned、--no-parent-w/--watch可监听变化自动刷新隐含--pretty。2. 编辑前检视bd showbd show idshow.md 说明bd show别名view可一次传多个 ID也支持--idid...处理形如gt--xyz这种容易被当成 flag 的 ID。常用标志--long展示全部字段扩展元数据、agent 身份、gate 字段等--current展示当前活跃 issuein_progress、hooked 或最近触碰过的--as-of查看某个 commit hash 或分支时刻的 issue 状态需 Dolt--children、--refs、--include-dependents、--include-comments围绕关系与全文后两者仅--json有效且注释提醒对评论/依赖多的 issue 可能较慢--local-time用本地时区替代 UTC 展示时间戳。3. 原子认领bd update --claimbd update id --claimupdate.md 对该标志的定义非常精确Atomically claim the issue (sets assignee to you, status to in_progress; idempotent if already claimed by you)——即原子地把 assignee 设为你、状态置为 in_progress且若已由你认领则幂等不报错。这正是多 agent 并发场景下避免两个人同时开干的关键机制。值得补充的是bd update的其他高频字段-p/--priority0-4 或 P0-P40 最高、-d/--description、--title、-t/--type、-a/--assignee、-e/--estimate分钟、--due支持6h、1d、2w、tomorrow、next monday、2025-01-15等格式、--add-label/--remove-label/--set-labels、--metadata与--set-metadata keyvalue、--external-ref如gh-9、jira-ABC、Linear URL、--parent改父级、--defer推迟到某日后才出现在bd ready中。若不传 ID则更新最近触碰的 issue最近一次 create / update / show / close 操作的对象。4. 派生后续任务bd create实现过程中发现新工作时SKILL.md 给出的标准动作是创建持久化的后续任务bd create Short title --descriptionWhy this exists and what needs to be done --typetask --priority2create.md 别名new除标题位置参数与上述字段外还支持--deps声明依赖格式type:id或id如discovered-from:bd-20,blocks:bd-15——这正是发现型后续任务建立依赖关系的标准写法--parent作为某个 issue 的子级层级化拆分--acceptance验收标准、--design/--design-file设计说明、--spec-id关联规范文档、--skills所需技能--ephemeral创建短生命周期的临时 issue受 TTL 压缩管理--wisp-type进一步指定 wisp 类型--file从 markdown 文件批量创建--graph从 JSON 计划文件创建带依赖关系的 issue 图--dry-run预演不落地--silent仅输出 issue ID适合脚本化--stdin/--body-file -从标准输入读取描述--validate校验描述是否包含该 issue 类型要求的章节。5. 收尾bd closebd close id --reasonCompletedclose.md 别名done不传 ID 时同样关闭最近触碰的 issue。多 ID 关闭时多个--reason与 ID 按位置一一对应与 flag 出现顺序无关。进一步的能力--claim-next关闭后自动认领下一个最高优先级可用的 issue——适合流水线式执行--suggest-next关闭后展示新解除阻塞的 issue--continue自动推进到 molecule 的下一步--no-auto则只展示下一步但不认领-f/--force强制关闭 pinned issue 或未满足的 gate--reason-file从文件读取关闭原因-表示 stdin。SKILL.md 的纪律性要求在这里同样适用不要自动关闭或变更任务除非工作确实完成见下文规则。什么内容该放进 BeadsSKILL.md 给出了一个清晰的放/不放清单值得原样继承放进来共享项目任务shared project tasks阻塞与依赖blockers and dependencies发现型后续任务discovered follow-up work必须在线程重置、上下文压缩或交接后依然存活的工作另一个 person 或 agent 应当能接着恢复的状态不放进来agent 本地规划工具只用于当前这一轮执行的检查清单不得当作共享项目状态。这条边界与仓库的 issue 类型体系、阻塞语义bd blocked、bd ready的 blocker-aware 语义、依赖机制--deps、--waits-for以及面向多 agent 的 moleculeswarm / patrol / work一脉相承——凡是需要跨会话、跨执行者存续的状态Beads 都提供了对应的持久化表达。使用规则与纪律RulesSKILL.md 末尾的五条规则是整个技能文档的行为契约逐条展开如下不要用 markdown TODO 文件作为事实来源Beads 可用时杜绝把 TODO 文件当作持久真相——因为普通文本文件既不阻塞感知、也无法原子认领、更不能在 Dolt 历史中审计。仓库中.beads/PRIME.md属于 prime 输出覆盖定制文件与此类 TODO 文件性质完全不同。不要用bd edit交互式编辑器它打开交互式编辑器不适合脚本化与自动化场景一律使用bd update的非交互 flag如--title、--description、--status、--claim等见 update.md。程序化解析优先--jsonbd输出默认是面向人眼的树形/表格文本解析时应使用--jsonbd ready --claim --json、bd where --json等均为文档直接给出的用法避免脆弱的文本正则。钩子注入时仍可手动补跑 prime如钩子已安装bd prime可能已被 SessionStart 自动注入但上下文缺失时手动运行是安全动作前文已结合 agent_hook.go 的runBdPrime子进程实现说明其幂等无害性。不要提前关闭或变更任务只有工作真正完成才 close / mutate——这与原子认领--claim幂等和关闭语义close 会触发--suggest-next/--claim-next等连锁行为相配合确保任务状态机不被误操作污染。从技能文档到仓库资源进一步阅读SKILL.md 本质上是给 agent 的一份行为技能卡完整能力清单远超该文档本身。继续深入可按以下路径命令全量参考docs/cli-reference/ 收录了prime、where、ready、list、show、update、create、close、hooks等 90 命令的完整参数说明均由bd help --doc cmd自动生成源码实现cmd/bd/ 是 CLI 入口main.goagent_hook.go/codex_hook.go/cursor_hook.go展示 agent 生命周期钩子如何复用runBdPrime的子进程模式ready.go、create.go、close.go对应本工作流各命令领域逻辑issueops/ 提供 claimer、readyclaimer、blockedstate、cycledetector、batchcreator 等与认领/阻塞/批处理直接相关的角色实现Agent 集成模板仓库的 agent 模板internal/templates/agents/defaults/agents.md.tmpl在项目初始化时写入Runbd primefor full workflow context的指引与本文第一步互相印证。总结Beads 的价值不在于多一条 CLI而在于它为 Coding Agent 提供了一个阻塞感知、原子认领、持久可审计的共享任务层。掌握本文的闭环——bd prime注入上下文 →bd ready/bd list找活 →bd show检视 →bd update --claim原子认领 →bd create沉淀派生任务 →bd close收尾——并恪守本地计划只管本轮、持久状态进 Beads的分界就能让 agent 在上下文压缩、线程重置与多智能体交接后依然拥有一致的项目工作记忆。所有命令细节均可在 docs/cli-reference 中查到与当前仓库版本完全一致的参数说明。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考