让 AI Agent 安全使用 bd 发号施令Beads 项目 Agent 指令AGENTS.md全解析与实战【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读Beads 是一个面向编码 Agent 的记忆升级工具而cmd/bd/AGENTS.md是仓库专门写给 AI AgentClaude Code、Codex、Gemini CLI 等看的操作手册它规定了 Agent 用bd命令发现工作、认领任务、更新进度、收尾提交的完整闭环并明确划出禁止使用交互式命令的边界。本文以这份文档为骨架结合仓库源码与官方 CLI 参考逐条拆解每条命令的语义、原子性保证与正确用法让读者无论是人类还是 Agent都能安全、合规地驱动 Beads 的 issue 追踪工作流。一、这份文档在项目中的位置与作用cmd/bd/AGENTS.md位于 CLI 命令源码目录cmd/bd/之下是一份面向机器读者AI Agent的快速行为准则。它只有三个部分却覆盖了 Agent 使用 bd 的完整生命周期快速参考Quick Reference一段可直接照抄的命令速查表交互式命令警告Agent Warning明确禁止 Agent 使用会拉起$EDITOR的bd edit会话收尾Landing the Plane强制性的着陆流程以git push成功作为工作完成的唯一标志。与面向人类的教程不同这份文档的核心诉求是把不确定性降到最低Agent 必须通过非交互的参数化命令完成所有写操作并且绝不允许把工作留在本地。其理念可以从仓库中bd prime的设计得到印证——该命令专门为 Claude Code、Gemini CLI 和 Codex SessionStart 钩子设计防止 Agent 在上下文压缩后忘记 bd 工作流见 prime 命令参考。AGENTS.md正是同一理念的静态载体把最小必要规则固化进仓库让任何 Agent 一进仓库就能拿到正确用法。二、快速参考Agent 每日工作命令全解文档给出的速查表是 Agent 发现与推进工作的主干。以下逐一展开其真实语义均以官方命令参考为准bd ready # Find available work (open, no blockers) bd blocked # Show blocked issues and what blocks them bd list # List all issues (with blocker annotations) bd show id # View issue details bd update id --claim # Claim work (atomic compare-and-swap) bd close id # Complete work bd dolt push # Push to Dolt remote1.bd ready找到真正可以认领的工作按 ready 命令参考bd ready展示的是没有活跃 blocker 的开放 issue并且会排除in_progress、blocked、deferred、hooked四类状态。它的实现依赖GetReadyWorkAPI该 API 采用 blocker 感知语义只返回真正可认领的工作。该命令与bd list --ready使用相同的就绪语义二者结果一致支持--mol过滤到某个 molecule分子式工作流的步骤、--gated查找门gate关闭后可继续派发的 molecule支持--claim直接原子认领第一个匹配过滤器的工作如bd ready --claim --json适合执行 molecule 的 Agent 一步到位看下一步 认领下一步常用过滤参数-a/--assignee、-l/--label、-t/--type、-p/--priority、--parent、-n/--limit默认 100、--sortpriority/hybrid/oldest等。2.bd blocked查看被阻塞的工作及阻塞原因按 blocked 命令参考bd blocked展示所有处于阻塞状态的 issue并支持--parent过滤到某个 bead/epic 的后代。它是判断哪些事当前无法推进的最直接入口。3.bd list带 blocker 注解的全量列表按 list 命令参考bd list默认以树形层级展示 issue--flat可退回平面列表并带有状态/优先级符号--pretty。其过滤器极其丰富Agent 常用的有--status按状态过滤open, in_progress, blocked, deferred, closed多状态必须用逗号分隔形式重复-s会静默覆盖前值-t/--type按类型过滤bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy支持mr→merge-request、mol→molecule等别名--ready与bd ready同语义只显示无活跃 blocker 的 issue--sort可按priority, created, updated, closed, status, id, title, type, assignee排序--id支持一次性查看多个指定 ID如bd-1,bd-5,bd-10。4.bd show id查看 issue 详情按 show 命令参考bd show支持一次查看多个 ID别名view。关键参数--long展示全部扩展字段元数据、Agent 身份、gate 字段等、--refs反向查找引用该 issue 的其他 issue、--children只看子 issue、--current直接显示当前活跃 issuein-progress、hooked 或最近触达的、--include-comments/--include-dependents在 JSON 输出中流式包含完整评论/依赖项。5.bd update id --claim原子认领compare-and-swap认领是 Agent 并发协作的基石文档特意标注atomic compare-and-swap。这一点有源码背书在 issueops/claimer.go 中ClaimRequest被定义为一次原子 compare-and-set 认领Claimer是独立的守卫角色验证并提交完整请求作为一次原子操作。bd update --claim的语义为将 assignee 设为你、状态置为in_progress且若已由你认领则幂等见 update 命令参考 的--claim说明。这种设计确保了多个 Agent 同时抢同一工作时只有一个能成功避免重复认领。6.bd close id完成任务按 close 命令参考bd close别名done。若不传 ID则关闭最近触达的 issue。支持批量关闭多个--reason按位置与 ID 一一对应。Agent 场景常用参数-r/--reason必填关闭原因--claim-next关闭后自动认领下一个最高优先级可用工作适合流水线式 Agent--continue自动前进到 molecule 的下一步--suggest-next显示关闭后新解除阻塞的 issue。7.bd dolt push把本地数据库推送到远程Beads 使用 DoltGit 风格版本化数据库作为存储层bd dolt push将本地数据提交推送至远程是 Agent 协作时数据同步的关键一步也是下文着陆流程中git push之前/之后的数据层配套操作。依赖状态的权威来源文档特别强调判断工作是否被阻塞bd ready和bd blocked才是权威来源bd list会展示活跃的 blocker 注解但如果要精确判断阻塞状态必须用前两者。这一点与bd ready文档中该命令使用 blocker 感知语义找到真正可认领的工作ready 命令参考相呼应——bd list的注解只是展示bd ready/bd blocked才执行真正的状态计算。三、Agent 红线为什么绝对不能用bd edit文档用大写强调DO NOT usebd edit。原因在 edit 命令参考 中写得很清楚bd edit会使用你配置的$EDITOR编辑 issue 字段——它会在终端里拉起交互式编辑器AI Agent 无法也不应操作这样的交互界面命令会挂起或失败。正确做法是全部改用bd update的参数化旗标每个字段对应一个 flag来自 update 命令参考bd update id --description new description bd update id --title new title bd update id --design design notes bd update id --notes additional notes bd update id --acceptance acceptance criteria除文档列出的五个字段外bd update还提供大量 Agent 可用的结构化参数这里补充几个高频项-a/--assignee指派人员-s/--status设置新状态open、in_progress、blocked、closed等-p/--priority优先级0-4 或 P0-P40 最高-e/--estimate耗时估算分钟--add-label/--remove-label/--set-labels标签增删改--defer延后到期时间格式如6h、1d、2w、tomorrow、2025-01-15延后期间该 issue 不会出现在bd ready中--body-file/--stdin从文件或标准输入读取描述用-表示 stdin配合--allow-empty-description可处理空描述场景--metadata/--set-metadata/--unset-metadata读写自定义元数据适合跨 Agent 传递结构化信息--parent变更父 issue重新挂到另一个 epic 之下。这条红线的本质是保持 Agent 操作的全自动化所有写操作都必须是非交互、可重放、可审计的单一命令而bd update --claim的原子性见 issueops/claimer.go 与 issueops/issueops.go 中Claim 原子地将 issue 认领给 Actor先设置 Assignee 再置状态的说明正是这一要求的底层保障。四、Landing the PlaneAgent 会话收尾强制流程文档把会话收尾比作降落飞机并声明在git push成功之前工作都不算完成。整套强制工作流如下为剩余工作建档File issues任何需要跟进的事都必须先创建 issue避免上下文丢失运行质量门Run quality gates若改动过代码必须跑测试、linter、构建更新 issue 状态Update issue status关闭已完成的工作更新进行中的条目推送到远端PUSH TO REMOTE强制git pull --rebase git push git status # MUST show up to date with origin清理Clean up清空 stash、清理远端多余分支验证Verify所有改动都已提交且推送交接Hand off为下一个会话提供上下文。三条不可逾越的规则只有git push成功工作才算完成绝不允许在推送前停下——那会让工作滞留本地绝不允许说准备好了你随时可以推——必须由 Agent 自己推送若推送失败解决后重试直到成功。这套流程与bd prime的定位形成呼应prime 命令参考 提到它输出AI 优化的会话上下文并可通过no-git-ops配置切换隐身模式不输出 git 命令的会话收尾协议说明默认的收尾协议本身就包含上述 git 步骤——AGENTS.md把其中最关键的步骤显式固化成了强制 checklist。对 Agent 而言这套流程的价值在于可验证的完成定义git status必须显示 up to date with origin把完成从模糊感觉变成可执行检查防止工作滞留git pull --rebase保证基于最新远端状态合入git push保证成果同步避免本地改了一堆、远端一无所知的协作事故上下文连续性第 1、7 步把下一步该做什么和这个会话做了什么落成持久化记录issue 与交接说明正好发挥 Beads 作为编码 Agent 记忆升级的核心价值。五、从 AGENTS.md 到完整 Agent 工作流把文档的速查表、红线和着陆流程串联起来就得到了一个完整的 Agent 工作循环入场读取AGENTS.md本文件如需完整工作流上下文运行bd prime见 prime 命令参考它按 MCP/CLI 模式自适应输出 ~50 tokens 的精简提醒或 1-2k tokens 的完整命令参考专为 SessionStart 钩子设计找活bd ready发现可认领工作必要时用--type、--label、--priority过滤或--mol进入 molecule 步骤认领bd update id --claim原子抢占bd ready --claim可合并 2、3 两步干活bd show id查看详情代码改动期间用bd update id --notes/--design/--acceptance持续记录绝不触碰bd edit卡住遇到依赖未就绪时用bd blocked判断阻塞原因解除后用bd ready重新确认可推进性完成bd close id -r reason关闭可用--claim-next自动进入下一项着陆严格走Landing the Plane七步——补 issue、跑质量门、更新状态、git pull --rebase git push git status确认同步、清理、验证、交接。其中第 3 步的原子认领是整个并发安全模型的关键源码中ReadyClaimer被定义为一次就绪工作的原子获取即bd ready --claim操作见 issueops/readyclaimer.go多个 Agent 并行抢活时由数据库层保证只成功一个从而避免重复劳动。六、给 Agent 作者的落地建议基于这份文档与仓库实现若你正在为自己的仓库编写同类 Agent 指令以下几点值得借鉴用速查表 权威来源声明像文档那样先给 5-7 条最高频命令再明确指出哪个命令才是状态判断的权威来源bd ready/bd blocked避免 Agent 误用展示型命令做决策显式划出交互红线凡是会拉起$EDITOR、进入 pager、要求人工确认的命令一律列入黑名单并给出参数化替代方案把完成定义成可执行检查git push成功 git status显示 up to date这样的完成标准可以让 Agent 自检而不是嘴上说完成了流程编号化、规则加粗编号步骤和 CRITICAL RULES 的写法让 Agent 在上下文被压缩后仍能快速重建行为约束——这与bd prime防止 Agent 在上下文压缩后忘记工作流的设计目标完全一致。结语cmd/bd/AGENTS.md虽然只有数十行却浓缩了 Beads 团队对机器协作的完整设计以bd ready/bd blocked作为事实源、以bd update --claim的原子 compare-and-swap 保证并发安全、以bd edit禁令守住全自动化底线、以 Landing the Plane 七步流程确保每次会话都以远端同步收尾。对照 ready、blocked、list、update、close、prime 等官方命令参考以及 issueops/claimer.go、issueops/readyclaimer.go 的源码实现文档中的每一条规则都能找到落点。对任何打算让 AI Agent 长期、稳定、安全地参与 issue 追踪与代码交付的团队这份文件本身就是一份值得直接复用的范本。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 让 AI Agent 安全使用 bd 发号施令：Beads 项目 Agent 指令（AGENTS.md）全解析与实战
让 AI Agent 安全使用 bd 发号施令Beads 项目 Agent 指令AGENTS.md全解析与实战【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读Beads 是一个面向编码 Agent 的记忆升级工具而cmd/bd/AGENTS.md是仓库专门写给 AI AgentClaude Code、Codex、Gemini CLI 等看的操作手册它规定了 Agent 用bd命令发现工作、认领任务、更新进度、收尾提交的完整闭环并明确划出禁止使用交互式命令的边界。本文以这份文档为骨架结合仓库源码与官方 CLI 参考逐条拆解每条命令的语义、原子性保证与正确用法让读者无论是人类还是 Agent都能安全、合规地驱动 Beads 的 issue 追踪工作流。一、这份文档在项目中的位置与作用cmd/bd/AGENTS.md位于 CLI 命令源码目录cmd/bd/之下是一份面向机器读者AI Agent的快速行为准则。它只有三个部分却覆盖了 Agent 使用 bd 的完整生命周期快速参考Quick Reference一段可直接照抄的命令速查表交互式命令警告Agent Warning明确禁止 Agent 使用会拉起$EDITOR的bd edit会话收尾Landing the Plane强制性的着陆流程以git push成功作为工作完成的唯一标志。与面向人类的教程不同这份文档的核心诉求是把不确定性降到最低Agent 必须通过非交互的参数化命令完成所有写操作并且绝不允许把工作留在本地。其理念可以从仓库中bd prime的设计得到印证——该命令专门为 Claude Code、Gemini CLI 和 Codex SessionStart 钩子设计防止 Agent 在上下文压缩后忘记 bd 工作流见 prime 命令参考。AGENTS.md正是同一理念的静态载体把最小必要规则固化进仓库让任何 Agent 一进仓库就能拿到正确用法。二、快速参考Agent 每日工作命令全解文档给出的速查表是 Agent 发现与推进工作的主干。以下逐一展开其真实语义均以官方命令参考为准bd ready # Find available work (open, no blockers) bd blocked # Show blocked issues and what blocks them bd list # List all issues (with blocker annotations) bd show id # View issue details bd update id --claim # Claim work (atomic compare-and-swap) bd close id # Complete work bd dolt push # Push to Dolt remote1.bd ready找到真正可以认领的工作按 ready 命令参考bd ready展示的是没有活跃 blocker 的开放 issue并且会排除in_progress、blocked、deferred、hooked四类状态。它的实现依赖GetReadyWorkAPI该 API 采用 blocker 感知语义只返回真正可认领的工作。该命令与bd list --ready使用相同的就绪语义二者结果一致支持--mol过滤到某个 molecule分子式工作流的步骤、--gated查找门gate关闭后可继续派发的 molecule支持--claim直接原子认领第一个匹配过滤器的工作如bd ready --claim --json适合执行 molecule 的 Agent 一步到位看下一步 认领下一步常用过滤参数-a/--assignee、-l/--label、-t/--type、-p/--priority、--parent、-n/--limit默认 100、--sortpriority/hybrid/oldest等。2.bd blocked查看被阻塞的工作及阻塞原因按 blocked 命令参考bd blocked展示所有处于阻塞状态的 issue并支持--parent过滤到某个 bead/epic 的后代。它是判断哪些事当前无法推进的最直接入口。3.bd list带 blocker 注解的全量列表按 list 命令参考bd list默认以树形层级展示 issue--flat可退回平面列表并带有状态/优先级符号--pretty。其过滤器极其丰富Agent 常用的有--status按状态过滤open, in_progress, blocked, deferred, closed多状态必须用逗号分隔形式重复-s会静默覆盖前值-t/--type按类型过滤bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy支持mr→merge-request、mol→molecule等别名--ready与bd ready同语义只显示无活跃 blocker 的 issue--sort可按priority, created, updated, closed, status, id, title, type, assignee排序--id支持一次性查看多个指定 ID如bd-1,bd-5,bd-10。4.bd show id查看 issue 详情按 show 命令参考bd show支持一次查看多个 ID别名view。关键参数--long展示全部扩展字段元数据、Agent 身份、gate 字段等、--refs反向查找引用该 issue 的其他 issue、--children只看子 issue、--current直接显示当前活跃 issuein-progress、hooked 或最近触达的、--include-comments/--include-dependents在 JSON 输出中流式包含完整评论/依赖项。5.bd update id --claim原子认领compare-and-swap认领是 Agent 并发协作的基石文档特意标注atomic compare-and-swap。这一点有源码背书在 issueops/claimer.go 中ClaimRequest被定义为一次原子 compare-and-set 认领Claimer是独立的守卫角色验证并提交完整请求作为一次原子操作。bd update --claim的语义为将 assignee 设为你、状态置为in_progress且若已由你认领则幂等见 update 命令参考 的--claim说明。这种设计确保了多个 Agent 同时抢同一工作时只有一个能成功避免重复认领。6.bd close id完成任务按 close 命令参考bd close别名done。若不传 ID则关闭最近触达的 issue。支持批量关闭多个--reason按位置与 ID 一一对应。Agent 场景常用参数-r/--reason必填关闭原因--claim-next关闭后自动认领下一个最高优先级可用工作适合流水线式 Agent--continue自动前进到 molecule 的下一步--suggest-next显示关闭后新解除阻塞的 issue。7.bd dolt push把本地数据库推送到远程Beads 使用 DoltGit 风格版本化数据库作为存储层bd dolt push将本地数据提交推送至远程是 Agent 协作时数据同步的关键一步也是下文着陆流程中git push之前/之后的数据层配套操作。依赖状态的权威来源文档特别强调判断工作是否被阻塞bd ready和bd blocked才是权威来源bd list会展示活跃的 blocker 注解但如果要精确判断阻塞状态必须用前两者。这一点与bd ready文档中该命令使用 blocker 感知语义找到真正可认领的工作ready 命令参考相呼应——bd list的注解只是展示bd ready/bd blocked才执行真正的状态计算。三、Agent 红线为什么绝对不能用bd edit文档用大写强调DO NOT usebd edit。原因在 edit 命令参考 中写得很清楚bd edit会使用你配置的$EDITOR编辑 issue 字段——它会在终端里拉起交互式编辑器AI Agent 无法也不应操作这样的交互界面命令会挂起或失败。正确做法是全部改用bd update的参数化旗标每个字段对应一个 flag来自 update 命令参考bd update id --description new description bd update id --title new title bd update id --design design notes bd update id --notes additional notes bd update id --acceptance acceptance criteria除文档列出的五个字段外bd update还提供大量 Agent 可用的结构化参数这里补充几个高频项-a/--assignee指派人员-s/--status设置新状态open、in_progress、blocked、closed等-p/--priority优先级0-4 或 P0-P40 最高-e/--estimate耗时估算分钟--add-label/--remove-label/--set-labels标签增删改--defer延后到期时间格式如6h、1d、2w、tomorrow、2025-01-15延后期间该 issue 不会出现在bd ready中--body-file/--stdin从文件或标准输入读取描述用-表示 stdin配合--allow-empty-description可处理空描述场景--metadata/--set-metadata/--unset-metadata读写自定义元数据适合跨 Agent 传递结构化信息--parent变更父 issue重新挂到另一个 epic 之下。这条红线的本质是保持 Agent 操作的全自动化所有写操作都必须是非交互、可重放、可审计的单一命令而bd update --claim的原子性见 issueops/claimer.go 与 issueops/issueops.go 中Claim 原子地将 issue 认领给 Actor先设置 Assignee 再置状态的说明正是这一要求的底层保障。四、Landing the PlaneAgent 会话收尾强制流程文档把会话收尾比作降落飞机并声明在git push成功之前工作都不算完成。整套强制工作流如下为剩余工作建档File issues任何需要跟进的事都必须先创建 issue避免上下文丢失运行质量门Run quality gates若改动过代码必须跑测试、linter、构建更新 issue 状态Update issue status关闭已完成的工作更新进行中的条目推送到远端PUSH TO REMOTE强制git pull --rebase git push git status # MUST show up to date with origin清理Clean up清空 stash、清理远端多余分支验证Verify所有改动都已提交且推送交接Hand off为下一个会话提供上下文。三条不可逾越的规则只有git push成功工作才算完成绝不允许在推送前停下——那会让工作滞留本地绝不允许说准备好了你随时可以推——必须由 Agent 自己推送若推送失败解决后重试直到成功。这套流程与bd prime的定位形成呼应prime 命令参考 提到它输出AI 优化的会话上下文并可通过no-git-ops配置切换隐身模式不输出 git 命令的会话收尾协议说明默认的收尾协议本身就包含上述 git 步骤——AGENTS.md把其中最关键的步骤显式固化成了强制 checklist。对 Agent 而言这套流程的价值在于可验证的完成定义git status必须显示 up to date with origin把完成从模糊感觉变成可执行检查防止工作滞留git pull --rebase保证基于最新远端状态合入git push保证成果同步避免本地改了一堆、远端一无所知的协作事故上下文连续性第 1、7 步把下一步该做什么和这个会话做了什么落成持久化记录issue 与交接说明正好发挥 Beads 作为编码 Agent 记忆升级的核心价值。五、从 AGENTS.md 到完整 Agent 工作流把文档的速查表、红线和着陆流程串联起来就得到了一个完整的 Agent 工作循环入场读取AGENTS.md本文件如需完整工作流上下文运行bd prime见 prime 命令参考它按 MCP/CLI 模式自适应输出 ~50 tokens 的精简提醒或 1-2k tokens 的完整命令参考专为 SessionStart 钩子设计找活bd ready发现可认领工作必要时用--type、--label、--priority过滤或--mol进入 molecule 步骤认领bd update id --claim原子抢占bd ready --claim可合并 2、3 两步干活bd show id查看详情代码改动期间用bd update id --notes/--design/--acceptance持续记录绝不触碰bd edit卡住遇到依赖未就绪时用bd blocked判断阻塞原因解除后用bd ready重新确认可推进性完成bd close id -r reason关闭可用--claim-next自动进入下一项着陆严格走Landing the Plane七步——补 issue、跑质量门、更新状态、git pull --rebase git push git status确认同步、清理、验证、交接。其中第 3 步的原子认领是整个并发安全模型的关键源码中ReadyClaimer被定义为一次就绪工作的原子获取即bd ready --claim操作见 issueops/readyclaimer.go多个 Agent 并行抢活时由数据库层保证只成功一个从而避免重复劳动。六、给 Agent 作者的落地建议基于这份文档与仓库实现若你正在为自己的仓库编写同类 Agent 指令以下几点值得借鉴用速查表 权威来源声明像文档那样先给 5-7 条最高频命令再明确指出哪个命令才是状态判断的权威来源bd ready/bd blocked避免 Agent 误用展示型命令做决策显式划出交互红线凡是会拉起$EDITOR、进入 pager、要求人工确认的命令一律列入黑名单并给出参数化替代方案把完成定义成可执行检查git push成功 git status显示 up to date这样的完成标准可以让 Agent 自检而不是嘴上说完成了流程编号化、规则加粗编号步骤和 CRITICAL RULES 的写法让 Agent 在上下文被压缩后仍能快速重建行为约束——这与bd prime防止 Agent 在上下文压缩后忘记工作流的设计目标完全一致。结语cmd/bd/AGENTS.md虽然只有数十行却浓缩了 Beads 团队对机器协作的完整设计以bd ready/bd blocked作为事实源、以bd update --claim的原子 compare-and-swap 保证并发安全、以bd edit禁令守住全自动化底线、以 Landing the Plane 七步流程确保每次会话都以远端同步收尾。对照 ready、blocked、list、update、close、prime 等官方命令参考以及 issueops/claimer.go、issueops/readyclaimer.go 的源码实现文档中的每一条规则都能找到落点。对任何打算让 AI Agent 长期、稳定、安全地参与 issue 追踪与代码交付的团队这份文件本身就是一份值得直接复用的范本。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考