让 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 Agent（Claude 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）、--sort（priority/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直接显示当前活跃 issue（in-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 使用 Dolt（Git 风格版本化数据库）作为存储层，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-P4，0 最高）；-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 Plane：Agent 会话收尾强制流程
文档把会话收尾比作"降落飞机"，并声明在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），仅供参考
