尧图网站建设 
为编码 Agent 而生Beads 仓库 AGENTS.md 任务追踪规范与 bd CLI 实战指南【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeadsbd是一个为编码 Agent 提供记忆升级的依赖感知型任务追踪系统其仓库根目录的 AGENTS.md 是整个项目 Agent 协作规范的入口它定义了编码代理在该仓库中如何用bd命令进行任务追踪、如何安全地处理 PR、如何在会话结束时安全降落并显式声明了与CLAUDE.md之间有意分歧divergence的检查机制。读完本文你将掌握 Beads 面向 AI Agent 的完整工作流——从bd ready领取就绪任务、原子化--claim、用discovered-from链接新发现的工作到 Dolt 同步与会话收尾的质量门禁并看到这些规范背后对应的 Go 源码实现。AGENTS.md 的定位兼容入口与有意分歧标记AGENTS.md全文只有 290 行却是整个仓库 Agent 协作体系的门面。它开宗明义本文件用于兼容那些会主动查找AGENTS.md的工具完整指令则在 AGENT_INSTRUCTIONS.md 中给出。这意味着仓库刻意维护了两份面向不同受众的 Agent 指令AGENTS.md是要点速查 强制规则AGENT_INSTRUCTIONS.md是开发、测试、发布全流程细节。文件第 3 行的注释标记是它最特殊的地方!-- bd-doctor-divergence: ok --该标记告诉bd doctor本文件与CLAUDE.md之间的内容差异面向不同受众、阅读顺序不同是有意为之的、预期的差异不应被当作告警上报。在 cmd/bd/doctor.go 中可以看到对应的Check 12aAGENTS.md / CLAUDE.md 用户编写内容分歧检查——doctor.CheckAgentDocDivergence会扫描两份文档并对比但不会让检查失败只是输出警告级别结果。这构成了一个自我验证的文档治理闭环规范文件本身也是bd doctor健康检查的监测对象。项目范围与存储边界两条不可逾越的架构红线新增功能面之前先读 PROJECT_CHARTERAGENTS.md的 Project Scope 小节规定在新增功能表面积feature surface area之前必须先阅读 engdocs/PROJECT_CHARTER.md。该章程划定了 Beads 的自我定位Beads 拥有问题追踪issue tracking原语不应编码编排层策略orchestration-layer policy、不应变成存储引擎、也不应随意扩张数据库 schema——当元数据metadata足以承载时就用元数据。Storage Boundary驱动接口是唯一的对话通道Storage Boundary 小节给出了 Beads 与底层存储之间的规范边界Beads 通过驱动接口Dolt 对应dolthub/driver与存储对话并明确禁止在 beads 侧添加flock文件锁类逻辑引擎内省engine introspection存储专用的重试或崩溃恢复逻辑泄漏驱动内部实现细节的公共 SDK 返回类型。如果边界过窄正确做法是加宽接口或把问题转交驱动侧解决而不是在 beads 里绕过它打补丁。该规则的一个活例是嵌入式模式的bd doctor支持每个子命令逐一启用、逐一人工评审GH#3794不得整体放开 cmd/bd/doctor.go 中的嵌入式模式门禁数据库层的检查与修复必须等驱动接口覆盖后才能取消服务端门控。这解释了为什么bd doctor的嵌入式模式支持是渐进式的——架构纪律直接体现在代码演进节奏上。PR 安全Agent 处理外部贡献者的前置检查对于任何要审阅triage、评审review、合并land、关闭close或维护 PR 的 AgentAGENTS.md强制要求先读 PR_MAINTAINER_GUIDELINES.md并执行维护者政策最大化社区吞吐——找到外部贡献者的有效价值、尽量本地吸收或改造、保留署名、把 request-changes 作为最后手段。在实现任何功能、打开 PR、或合并/关闭 PR 之前必须先跑只读的 PR 前置检查脚本scripts/pr-preflight.sh --search topic keywords --repo gastownhall/beads scripts/pr-preflight.sh pr-number --repo gastownhall/beads从 scripts/pr-preflight.sh 的实现看该脚本把贡献者保护政策转成了一份具体检查清单判断既有 PR 是否为外部/跨仓库贡献、检查 draft/review/mergeability/check 状态、探测基础分支的 CI 健康度红底基座会令失败是既有问题的推理不可靠可用PR_PREFLIGHT_BLOCK_RED_BASE1从告警升级为阻断、扫描危险 diff 信号.beads数据变更、改代码却缺测试、超大 diff最后给出贡献者保护的下一步与署名提醒。外部贡献者 PR 享有优先级尽可能检出对方分支、在其上修复/改编后再合并保留他们的测试与署名绝不静默关闭或取代其 PR。若重写不可避免必须在原 PR 上说明理由并致谢其设计/测试。配套的 AGENT_INSTRUCTIONS.md 还要求用gh pr list --repo gastownhall/beads --state open --search topic在动手前先检查是否已有同主题的开放 PR。任务追踪为什么这个仓库用 bd 而不是 Markdown TODOAGENTS.md明确宣告本项目使用 bdbeads承担所有问题追踪禁止使用 Markdown TODO 列表、任务清单或其他追踪方法。选择 bd 的理由有四条依赖感知追踪 issue 之间的阻塞blockers与关系Git 友好Dolt 驱动的版本控制原生同步Agent 优化JSON 输出、就绪工作检测ready work detection、discovered-from链接防止重复追踪体系避免双轨制造成的混乱。快速开始五条命令完成一个任务闭环# 1. 查看是否有就绪工作open 且无活跃阻塞 bd ready --json # 2. 创建新 issue类型 优先级 JSON 输出 bd create Issue title --descriptionDetailed context -t bug|feature|task -p 0-4 --json # 带依赖链接从 bd-123 中发现的新工作 bd create Issue title --descriptionWhat this issue is about -p 1 --deps discovered-from:bd-123 --json # 3. 认领并更新 bd update id --claim --json bd update bd-42 --priority 1 --json # 4. 完成工作 bd close bd-42 --reason Completed --json在 cmd/bd/create.go 中可以看到--deps的完整语法接受type:id或裸id形式——裸id、depends-on:id、blocked-by:id都表示本 issue 依赖 idblocks:id则反转方向id 依赖本 issue。例如blocked-by:bd-20,discovered-from:bd-15表示同时被 bd-20 阻塞、并从 bd-15 中发现。discovered-from依赖还会让新 issue 继承来源 issue 的source_repo见 cmd/bd/create.go。Issue 类型与优先级五种类型Issue Types类型含义bug出故障的事物feature新功能task工作项测试、文档、重构epic带子任务的大型特性chore维护依赖、工具链五档优先级Priorities值含义0关键安全、数据丢失、构建被破坏1高主要特性、重要 bug2中默认锦上添花3低打磨、优化4积压未来想法AI Agent 标准工作流检查就绪工作bd ready展示未被阻塞的 issue原子化认领任务bd update id --claim开展工作实现、测试、记录发现新工作创建链接 issuebd create Found bug --description... -p 1 --deps discovered-from:parent-id完成bd close id --reason Done。质量要求创建 issue 时使用--acceptance验收标准与--design设计说明字段用--validate检查描述完整性。生命周期与卫生命令bd defer id/bd supersede id延期 / 取代某个 issuebd stale/bd orphans/bd lint陈旧项、孤儿 issue、规范检查bd human id标记需要人类决策bd formula list/bd mol pour name结构化工作流配方与分子。铁律清单✅ 所有任务追踪都用 bd✅ 程序化使用一律带--json✅ 用discovered-from依赖链接新发现的工作✅ 问我该做什么之前先跑bd ready❌ 不要创建 Markdown TODO 列表❌ 不要使用外部 issue 追踪器❌ 不要重复建立追踪体系。源码纵深bd ready的就绪工作语义AGENTS.md把bd ready定位为 Agent 工作流的起点其底层实现在 cmd/bd/ready.go 中值得展开就绪的严格定义ready命令展示开放且无活跃阻塞的工作open, no active blockers显式排除in_progress、blocked、deferred和被钩子hooked的 issue。它调用GetReadyWorkAPI该 API 应用阻塞器感知语义blocker-aware semantics找出真正可认领的工作bd list --ready复用同一套语义。多模式入口见 cmd/bd/ready.go 的 RunE 分发逻辑bd ready --claim原子化认领符合过滤条件的第一个就绪 issue。从源码看认领走ReadyClaimer角色claimer.ClaimNext选择、compare-and-set、以及喂给--json的水合hydration在同一个事务内完成——这正是原子认领的实现保证cmd/bd/ready.gobd ready --explain依赖感知诊断解释每个 issue 为何就绪或被阻塞包括已解决的阻塞器Resolved blockers、解锁 N 个 issueUnblocks统计、以及依赖环检测cycles——其过滤条件把 limit 固定为无限避免解释被 100 行默认上限静默截断bd ready --mol name过滤到某个分子molecule内的就绪步骤并展示并行组parallel groups与可并行运行Can run with提示bd ready --gated找出某个门关闭后可恢复调度的分子。过滤能力cmd/bd/ready.go 注册的全部 flag--limit/-n默认workapi.DefaultReadyLimit0 表示不限、--priority/-p、--assignee/-a、--unassigned/-u、--sortpriority/hybrid/oldest、标签类--label/-lAND 语义、--label-anyOR 语义、--exclude-label、--label-patternglob、--label-regex、--type/-t含别名 mr→merge-request、feat→feature、mol→molecule、dec/adr→decision、--parent、--mol-typeswarm/patrol/work、--include-deferred、--include-ephemeralwisps、--exclude-type、元数据过滤--metadata-field keyvalue与--has-metadata-key、以及防御性行数上限--max-rows越界退出码 2默认关闭。目录感知标签作用域cmd/bd/ready_input.go当命令行没有显式标签时bd ready会把配置的目录标签directory.labelsGH#541作为LabelsAny应用到过滤器——同一个仓库不同子目录的 Agent 只会看到各自作用域内的就绪工作。实现上目录标签直接写到过滤器上保留原文不被规范化同时在readyRoleRequest里单独携带给认领/计数角色防止bd ready --claim在受限目录中从整个就绪队列认领这是ReadyClaimer契约明令禁止的见 issueops/readyclaimer.go。用法冲突校验--claim不能与--assignee、--gated、--mol、--explain、--brief、--offset组合--brief必须配合--json使用因为文本渲染不会打印它省略的字段cmd/bd/ready_input.go。这些校验由gatherReadyInput统一处理直连与代理服务器两条路径共享同一份定义。更新与完成bd update、bd close的 Agent 语义为什么禁用bd editAGENTS.md有一条醒目警告绝不要使用bd edit——它会打开交互式编辑器$EDITORAI Agent 无法使用。替代方案是bd update配合 flagsbd 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含特殊字符的描述走 stdin反引号、!、嵌套引号在 shell 里容易转义出错echo Description with backticks and quotes | bd create Title --description- echo Updated text | bd update id --description-配套的 AGENT_INSTRUCTIONS.md 还补充了bd show id --json | jq .[0] | {id,title,metadata,description,notes}的执行元数据读取习惯——execution_agent_type、execution_suggested_model、execution_reasoning_effort、execution_mode、execution_parallel_group这五个键是父 Agent 派生子代理前必须读取的权威执行提示因为已运行的子代理无法中途更换模型或推理强度。bd close的多 issue 与 last-touched 语义cmd/bd/close.go 展示了bd close别名done的 Agent 安全设计多 ID 关闭时--reason按位置映射第一个--reason作用于第一个 ID第二个作用于第二个 ID与 flag 在命令行中出现的位置无关last-touched 回退仅限交互会话不提供 ID 时默认回退到最近触碰的 issue最近一次 create/update/show/close。但该回退只在 stdin 是终端时生效在脚本与 Agent 会话中缺失 ID 直接报错——这样由空变量拼出来的命令不会静默关闭一个无关的 issue。可用BD_LAST_TOUCHED_FALLBACK1在任何环境启用、0彻底禁用。同步架构Dolt 本地库 refs/dolt/databd把 issue 历史存放在本地 Dolt 数据库中AGENTS.md用一句话概括了同步架构issues live in a local Dolt DB; sync usesrefs/dolt/dataon your git remote;.beads/issues.jsonlis a passive export.每次写入自动提交到 Dolt 历史一个写命令对应一个 Dolt commit远程同步用bd dolt push/bd dolt pull不要把.beads/issues.jsonl当作同步协议——它只是一个被动导出passive export真正同步靠的是 git remote 上refs/dolt/data这个独立于普通 Git refs 的引用。配套文档见 docs/reference/protected-branches.mdDolt 数据存放在refs/dolt/data下与标准 Git refs 隔离。由于使用哈希 ID合并冲突极少见即便出现Dolt 也用单元格级三方合并cell-level 3-way merge解决。会话收尾协议Landing the Plane 与 Agent Context ProfilesLanding the Plane强制收尾流程AGENTS.md规定结束工作会话或用户说 lets land the plane时必须完成全部步骤且git push成功之前工作不算完成为剩余工作建档创建需要跟进的 issue跑质量门禁若改了代码make ci-pr-lint零告警的格式化与 lint 包装见 engdocs/LINTING.mdmake test仅在确实需要 ICU 正则路径时加跑make test-icu-path质量门禁坏了就建 P0 issue更新 issue 状态关闭已完成项、更新进行中项推送远程强制git pull --rebase git push git status # 必须显示 up to date with origin清理git stash clear清除旧 stash、git remote prune origin清理已删除的远程分支验证所有变更均已提交且推送无未跟踪文件残留交接选一个跟进 issue给用户写出下一会话的提示词。关键规则工作未推送前不算完成绝不在推送前停下绝不说ready to push when you are——你必须自己推送推送失败就解决后重试。收尾时向用户总结本会话完成内容、建档的跟进 issue、质量门禁状态、推送确认、以及下一会话的建议提示词。Agent Context Profiles三级权限模型AGENTS.md将 Agent 分为三个语境画像托管 Beads 块是任务追踪指导无权覆盖仓库、用户或编排器的指令Conservative默认使用bd做任务追踪除非被明确要求不执行 git commit、git push 或 Dolt 远程同步交接时报告变更文件、验证结果与建议的后续命令Minimal工具指令文件只作为指向bd prime的指针沿用与 Conservative 相同的 git 保守策略Team-maintainer仅当仓库显式选择加入时Agent 才可以在会话收尾时关闭 beads、跑质量门禁、commit 与 push任何现行的 do not commit / do not push 指令仍然优先。Session Completion 的差异化执行会话收尾协议服从明确的用户、仓库与编排器指令。按活跃画像执行 git/同步步骤# Conservative/minimal/default报告状态和建议命令等待批准 git status # Team-maintainer opt-in除非现行指令禁止 git pull --rebase bd dolt push git push git status两条硬性规则显式用户或编排器指令优先于 Beads 块没有活跃画像或当前用户请求的明确授权不得 commit 或 push若必需的同步/推送被阻塞停下并报告确切命令与错误。非交互 Shell 规范防止 Agent 悬挂在确认提示上AGENTS.md明确要求文件操作始终使用非交互 flag因为cp、mv、rm可能被别名成带-i的交互模式导致 Agent 无限期悬挂等待 y/n# 强制覆盖不弹提示 cp -f source dest # 不要写: cp source dest mv -f source dest # 不要写: mv source dest rm -f file # 不要写: rm file # 递归操作 rm -rf directory # 不要写: rm -r directory cp -rf source dest # 不要写: cp -r source dest其他可能弹提示的命令也有对应规范scp/ssh加-o BatchModeyes失败而非提示、apt-get加-y、brew设HOMEBREW_NO_AUTO_UPDATE1环境变量。视觉设计规范小 Unicode 符号 语义色AGENTS.md对 CLI 输出视觉有硬性规范——绝不在 CLI 输出中使用 emoji 风格图标⚪理由是认知过载。必须使用带语义色的小型 Unicode 符号状态status 用符号○ ◐ ● ✓ ❄优先级priority 用带色标签不用状态字形P0–P4详细的符号映射与实现见 AGENT_INSTRUCTIONS.md 与 internal/ui/styles.go○ open - 可认领白/默认 ◐ in_progress - 进行中黄 ● blocked - 等待依赖红 ✓ closed - 已完成暗灰 ❄ deferred - 延期蓝/暗优先级配色P0红加粗、P1橙、P2琥珀、P3–P4默认文本issue 类型中bug红、epic紫。设计原则包括只用小符号、只给可操作项上色、已关闭项用暗灰淡化、树形层级用├──└──│连接符、以及不要显示needs:1当它只是父 epic 时这类降噪规则。代码实现时直接复用ui.StatusInProgressStyle、ui.PriorityP0Style、ui.TypeBugStyle等导出样式保证 list、graph、show、related 各命令间的图标一致。测试与开发规范要点测试命令与 PR 就绪门禁统一遵循 engdocs/TESTING.md绝不要污染生产数据库手工测试要在一次性工作目录中初始化——bd init --quiet --prefix test --skip-hooks --skip-agents配合mktemp -d且注意BEADS_DB单独并不能重定向bd init的工作区设置提交信息携带 issue IDgit commit -m Fix auth validation bug (bd-abc)这使bd doctor能检测孤儿 issue已提交但未关闭的工作Agent 准备的提交还要带Agent-Signature:trailer见 engdocs/AGENT_SIGNING.md构建必须走make install不要用go build -o bd ./cmd/bd、go install ./cmd/bd或裸go run因为它们会绕过规范构建路径、可能留下过期二进制且裸go run会漏掉必需的gms_pure_go构建标签——需要 go run 时用go run -tags gms_pure_go ./cmd/bd ...版本升级统一走脚本./scripts/bump-version.sh version --commit会原子性更新 CLI、插件、MCP server 与文档中的所有版本号。总结从规范文件到可执行的 Agent 记忆AGENTS.md不是一份普通的 README它是 Beads 项目Agent 优先工程理念的可执行体现bd-doctor-divergence标记让规范文档自身进入健康检查体系bd ready/bd update/bd close的命令设计原子认领、last-touched 防误伤、位置映射 reason处处为无头headlessAgent 的安全操作兜底Dolt 驱动的refs/dolt/data同步让任务历史具备 Git 级别的可审计性而 Conservative / Minimal / Team-maintainer 三级画像则把何时可以 commit/push的授权边界讲得一清二楚。对于任何想为编码 Agent 构建任务追踪系统的开发者这份文档连同 cmd/bd/ready.go、issueops/readyclaimer.go 等实现构成了一套从规范到源码的完整参考。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 为编码 Agent 而生：Beads 仓库 AGENTS.md 任务追踪规范与 bd CLI 实战指南
为编码 Agent 而生Beads 仓库 AGENTS.md 任务追踪规范与 bd CLI 实战指南【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeadsbd是一个为编码 Agent 提供记忆升级的依赖感知型任务追踪系统其仓库根目录的 AGENTS.md 是整个项目 Agent 协作规范的入口它定义了编码代理在该仓库中如何用bd命令进行任务追踪、如何安全地处理 PR、如何在会话结束时安全降落并显式声明了与CLAUDE.md之间有意分歧divergence的检查机制。读完本文你将掌握 Beads 面向 AI Agent 的完整工作流——从bd ready领取就绪任务、原子化--claim、用discovered-from链接新发现的工作到 Dolt 同步与会话收尾的质量门禁并看到这些规范背后对应的 Go 源码实现。AGENTS.md 的定位兼容入口与有意分歧标记AGENTS.md全文只有 290 行却是整个仓库 Agent 协作体系的门面。它开宗明义本文件用于兼容那些会主动查找AGENTS.md的工具完整指令则在 AGENT_INSTRUCTIONS.md 中给出。这意味着仓库刻意维护了两份面向不同受众的 Agent 指令AGENTS.md是要点速查 强制规则AGENT_INSTRUCTIONS.md是开发、测试、发布全流程细节。文件第 3 行的注释标记是它最特殊的地方!-- bd-doctor-divergence: ok --该标记告诉bd doctor本文件与CLAUDE.md之间的内容差异面向不同受众、阅读顺序不同是有意为之的、预期的差异不应被当作告警上报。在 cmd/bd/doctor.go 中可以看到对应的Check 12aAGENTS.md / CLAUDE.md 用户编写内容分歧检查——doctor.CheckAgentDocDivergence会扫描两份文档并对比但不会让检查失败只是输出警告级别结果。这构成了一个自我验证的文档治理闭环规范文件本身也是bd doctor健康检查的监测对象。项目范围与存储边界两条不可逾越的架构红线新增功能面之前先读 PROJECT_CHARTERAGENTS.md的 Project Scope 小节规定在新增功能表面积feature surface area之前必须先阅读 engdocs/PROJECT_CHARTER.md。该章程划定了 Beads 的自我定位Beads 拥有问题追踪issue tracking原语不应编码编排层策略orchestration-layer policy、不应变成存储引擎、也不应随意扩张数据库 schema——当元数据metadata足以承载时就用元数据。Storage Boundary驱动接口是唯一的对话通道Storage Boundary 小节给出了 Beads 与底层存储之间的规范边界Beads 通过驱动接口Dolt 对应dolthub/driver与存储对话并明确禁止在 beads 侧添加flock文件锁类逻辑引擎内省engine introspection存储专用的重试或崩溃恢复逻辑泄漏驱动内部实现细节的公共 SDK 返回类型。如果边界过窄正确做法是加宽接口或把问题转交驱动侧解决而不是在 beads 里绕过它打补丁。该规则的一个活例是嵌入式模式的bd doctor支持每个子命令逐一启用、逐一人工评审GH#3794不得整体放开 cmd/bd/doctor.go 中的嵌入式模式门禁数据库层的检查与修复必须等驱动接口覆盖后才能取消服务端门控。这解释了为什么bd doctor的嵌入式模式支持是渐进式的——架构纪律直接体现在代码演进节奏上。PR 安全Agent 处理外部贡献者的前置检查对于任何要审阅triage、评审review、合并land、关闭close或维护 PR 的 AgentAGENTS.md强制要求先读 PR_MAINTAINER_GUIDELINES.md并执行维护者政策最大化社区吞吐——找到外部贡献者的有效价值、尽量本地吸收或改造、保留署名、把 request-changes 作为最后手段。在实现任何功能、打开 PR、或合并/关闭 PR 之前必须先跑只读的 PR 前置检查脚本scripts/pr-preflight.sh --search topic keywords --repo gastownhall/beads scripts/pr-preflight.sh pr-number --repo gastownhall/beads从 scripts/pr-preflight.sh 的实现看该脚本把贡献者保护政策转成了一份具体检查清单判断既有 PR 是否为外部/跨仓库贡献、检查 draft/review/mergeability/check 状态、探测基础分支的 CI 健康度红底基座会令失败是既有问题的推理不可靠可用PR_PREFLIGHT_BLOCK_RED_BASE1从告警升级为阻断、扫描危险 diff 信号.beads数据变更、改代码却缺测试、超大 diff最后给出贡献者保护的下一步与署名提醒。外部贡献者 PR 享有优先级尽可能检出对方分支、在其上修复/改编后再合并保留他们的测试与署名绝不静默关闭或取代其 PR。若重写不可避免必须在原 PR 上说明理由并致谢其设计/测试。配套的 AGENT_INSTRUCTIONS.md 还要求用gh pr list --repo gastownhall/beads --state open --search topic在动手前先检查是否已有同主题的开放 PR。任务追踪为什么这个仓库用 bd 而不是 Markdown TODOAGENTS.md明确宣告本项目使用 bdbeads承担所有问题追踪禁止使用 Markdown TODO 列表、任务清单或其他追踪方法。选择 bd 的理由有四条依赖感知追踪 issue 之间的阻塞blockers与关系Git 友好Dolt 驱动的版本控制原生同步Agent 优化JSON 输出、就绪工作检测ready work detection、discovered-from链接防止重复追踪体系避免双轨制造成的混乱。快速开始五条命令完成一个任务闭环# 1. 查看是否有就绪工作open 且无活跃阻塞 bd ready --json # 2. 创建新 issue类型 优先级 JSON 输出 bd create Issue title --descriptionDetailed context -t bug|feature|task -p 0-4 --json # 带依赖链接从 bd-123 中发现的新工作 bd create Issue title --descriptionWhat this issue is about -p 1 --deps discovered-from:bd-123 --json # 3. 认领并更新 bd update id --claim --json bd update bd-42 --priority 1 --json # 4. 完成工作 bd close bd-42 --reason Completed --json在 cmd/bd/create.go 中可以看到--deps的完整语法接受type:id或裸id形式——裸id、depends-on:id、blocked-by:id都表示本 issue 依赖 idblocks:id则反转方向id 依赖本 issue。例如blocked-by:bd-20,discovered-from:bd-15表示同时被 bd-20 阻塞、并从 bd-15 中发现。discovered-from依赖还会让新 issue 继承来源 issue 的source_repo见 cmd/bd/create.go。Issue 类型与优先级五种类型Issue Types类型含义bug出故障的事物feature新功能task工作项测试、文档、重构epic带子任务的大型特性chore维护依赖、工具链五档优先级Priorities值含义0关键安全、数据丢失、构建被破坏1高主要特性、重要 bug2中默认锦上添花3低打磨、优化4积压未来想法AI Agent 标准工作流检查就绪工作bd ready展示未被阻塞的 issue原子化认领任务bd update id --claim开展工作实现、测试、记录发现新工作创建链接 issuebd create Found bug --description... -p 1 --deps discovered-from:parent-id完成bd close id --reason Done。质量要求创建 issue 时使用--acceptance验收标准与--design设计说明字段用--validate检查描述完整性。生命周期与卫生命令bd defer id/bd supersede id延期 / 取代某个 issuebd stale/bd orphans/bd lint陈旧项、孤儿 issue、规范检查bd human id标记需要人类决策bd formula list/bd mol pour name结构化工作流配方与分子。铁律清单✅ 所有任务追踪都用 bd✅ 程序化使用一律带--json✅ 用discovered-from依赖链接新发现的工作✅ 问我该做什么之前先跑bd ready❌ 不要创建 Markdown TODO 列表❌ 不要使用外部 issue 追踪器❌ 不要重复建立追踪体系。源码纵深bd ready的就绪工作语义AGENTS.md把bd ready定位为 Agent 工作流的起点其底层实现在 cmd/bd/ready.go 中值得展开就绪的严格定义ready命令展示开放且无活跃阻塞的工作open, no active blockers显式排除in_progress、blocked、deferred和被钩子hooked的 issue。它调用GetReadyWorkAPI该 API 应用阻塞器感知语义blocker-aware semantics找出真正可认领的工作bd list --ready复用同一套语义。多模式入口见 cmd/bd/ready.go 的 RunE 分发逻辑bd ready --claim原子化认领符合过滤条件的第一个就绪 issue。从源码看认领走ReadyClaimer角色claimer.ClaimNext选择、compare-and-set、以及喂给--json的水合hydration在同一个事务内完成——这正是原子认领的实现保证cmd/bd/ready.gobd ready --explain依赖感知诊断解释每个 issue 为何就绪或被阻塞包括已解决的阻塞器Resolved blockers、解锁 N 个 issueUnblocks统计、以及依赖环检测cycles——其过滤条件把 limit 固定为无限避免解释被 100 行默认上限静默截断bd ready --mol name过滤到某个分子molecule内的就绪步骤并展示并行组parallel groups与可并行运行Can run with提示bd ready --gated找出某个门关闭后可恢复调度的分子。过滤能力cmd/bd/ready.go 注册的全部 flag--limit/-n默认workapi.DefaultReadyLimit0 表示不限、--priority/-p、--assignee/-a、--unassigned/-u、--sortpriority/hybrid/oldest、标签类--label/-lAND 语义、--label-anyOR 语义、--exclude-label、--label-patternglob、--label-regex、--type/-t含别名 mr→merge-request、feat→feature、mol→molecule、dec/adr→decision、--parent、--mol-typeswarm/patrol/work、--include-deferred、--include-ephemeralwisps、--exclude-type、元数据过滤--metadata-field keyvalue与--has-metadata-key、以及防御性行数上限--max-rows越界退出码 2默认关闭。目录感知标签作用域cmd/bd/ready_input.go当命令行没有显式标签时bd ready会把配置的目录标签directory.labelsGH#541作为LabelsAny应用到过滤器——同一个仓库不同子目录的 Agent 只会看到各自作用域内的就绪工作。实现上目录标签直接写到过滤器上保留原文不被规范化同时在readyRoleRequest里单独携带给认领/计数角色防止bd ready --claim在受限目录中从整个就绪队列认领这是ReadyClaimer契约明令禁止的见 issueops/readyclaimer.go。用法冲突校验--claim不能与--assignee、--gated、--mol、--explain、--brief、--offset组合--brief必须配合--json使用因为文本渲染不会打印它省略的字段cmd/bd/ready_input.go。这些校验由gatherReadyInput统一处理直连与代理服务器两条路径共享同一份定义。更新与完成bd update、bd close的 Agent 语义为什么禁用bd editAGENTS.md有一条醒目警告绝不要使用bd edit——它会打开交互式编辑器$EDITORAI Agent 无法使用。替代方案是bd update配合 flagsbd 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含特殊字符的描述走 stdin反引号、!、嵌套引号在 shell 里容易转义出错echo Description with backticks and quotes | bd create Title --description- echo Updated text | bd update id --description-配套的 AGENT_INSTRUCTIONS.md 还补充了bd show id --json | jq .[0] | {id,title,metadata,description,notes}的执行元数据读取习惯——execution_agent_type、execution_suggested_model、execution_reasoning_effort、execution_mode、execution_parallel_group这五个键是父 Agent 派生子代理前必须读取的权威执行提示因为已运行的子代理无法中途更换模型或推理强度。bd close的多 issue 与 last-touched 语义cmd/bd/close.go 展示了bd close别名done的 Agent 安全设计多 ID 关闭时--reason按位置映射第一个--reason作用于第一个 ID第二个作用于第二个 ID与 flag 在命令行中出现的位置无关last-touched 回退仅限交互会话不提供 ID 时默认回退到最近触碰的 issue最近一次 create/update/show/close。但该回退只在 stdin 是终端时生效在脚本与 Agent 会话中缺失 ID 直接报错——这样由空变量拼出来的命令不会静默关闭一个无关的 issue。可用BD_LAST_TOUCHED_FALLBACK1在任何环境启用、0彻底禁用。同步架构Dolt 本地库 refs/dolt/databd把 issue 历史存放在本地 Dolt 数据库中AGENTS.md用一句话概括了同步架构issues live in a local Dolt DB; sync usesrefs/dolt/dataon your git remote;.beads/issues.jsonlis a passive export.每次写入自动提交到 Dolt 历史一个写命令对应一个 Dolt commit远程同步用bd dolt push/bd dolt pull不要把.beads/issues.jsonl当作同步协议——它只是一个被动导出passive export真正同步靠的是 git remote 上refs/dolt/data这个独立于普通 Git refs 的引用。配套文档见 docs/reference/protected-branches.mdDolt 数据存放在refs/dolt/data下与标准 Git refs 隔离。由于使用哈希 ID合并冲突极少见即便出现Dolt 也用单元格级三方合并cell-level 3-way merge解决。会话收尾协议Landing the Plane 与 Agent Context ProfilesLanding the Plane强制收尾流程AGENTS.md规定结束工作会话或用户说 lets land the plane时必须完成全部步骤且git push成功之前工作不算完成为剩余工作建档创建需要跟进的 issue跑质量门禁若改了代码make ci-pr-lint零告警的格式化与 lint 包装见 engdocs/LINTING.mdmake test仅在确实需要 ICU 正则路径时加跑make test-icu-path质量门禁坏了就建 P0 issue更新 issue 状态关闭已完成项、更新进行中项推送远程强制git pull --rebase git push git status # 必须显示 up to date with origin清理git stash clear清除旧 stash、git remote prune origin清理已删除的远程分支验证所有变更均已提交且推送无未跟踪文件残留交接选一个跟进 issue给用户写出下一会话的提示词。关键规则工作未推送前不算完成绝不在推送前停下绝不说ready to push when you are——你必须自己推送推送失败就解决后重试。收尾时向用户总结本会话完成内容、建档的跟进 issue、质量门禁状态、推送确认、以及下一会话的建议提示词。Agent Context Profiles三级权限模型AGENTS.md将 Agent 分为三个语境画像托管 Beads 块是任务追踪指导无权覆盖仓库、用户或编排器的指令Conservative默认使用bd做任务追踪除非被明确要求不执行 git commit、git push 或 Dolt 远程同步交接时报告变更文件、验证结果与建议的后续命令Minimal工具指令文件只作为指向bd prime的指针沿用与 Conservative 相同的 git 保守策略Team-maintainer仅当仓库显式选择加入时Agent 才可以在会话收尾时关闭 beads、跑质量门禁、commit 与 push任何现行的 do not commit / do not push 指令仍然优先。Session Completion 的差异化执行会话收尾协议服从明确的用户、仓库与编排器指令。按活跃画像执行 git/同步步骤# Conservative/minimal/default报告状态和建议命令等待批准 git status # Team-maintainer opt-in除非现行指令禁止 git pull --rebase bd dolt push git push git status两条硬性规则显式用户或编排器指令优先于 Beads 块没有活跃画像或当前用户请求的明确授权不得 commit 或 push若必需的同步/推送被阻塞停下并报告确切命令与错误。非交互 Shell 规范防止 Agent 悬挂在确认提示上AGENTS.md明确要求文件操作始终使用非交互 flag因为cp、mv、rm可能被别名成带-i的交互模式导致 Agent 无限期悬挂等待 y/n# 强制覆盖不弹提示 cp -f source dest # 不要写: cp source dest mv -f source dest # 不要写: mv source dest rm -f file # 不要写: rm file # 递归操作 rm -rf directory # 不要写: rm -r directory cp -rf source dest # 不要写: cp -r source dest其他可能弹提示的命令也有对应规范scp/ssh加-o BatchModeyes失败而非提示、apt-get加-y、brew设HOMEBREW_NO_AUTO_UPDATE1环境变量。视觉设计规范小 Unicode 符号 语义色AGENTS.md对 CLI 输出视觉有硬性规范——绝不在 CLI 输出中使用 emoji 风格图标⚪理由是认知过载。必须使用带语义色的小型 Unicode 符号状态status 用符号○ ◐ ● ✓ ❄优先级priority 用带色标签不用状态字形P0–P4详细的符号映射与实现见 AGENT_INSTRUCTIONS.md 与 internal/ui/styles.go○ open - 可认领白/默认 ◐ in_progress - 进行中黄 ● blocked - 等待依赖红 ✓ closed - 已完成暗灰 ❄ deferred - 延期蓝/暗优先级配色P0红加粗、P1橙、P2琥珀、P3–P4默认文本issue 类型中bug红、epic紫。设计原则包括只用小符号、只给可操作项上色、已关闭项用暗灰淡化、树形层级用├──└──│连接符、以及不要显示needs:1当它只是父 epic 时这类降噪规则。代码实现时直接复用ui.StatusInProgressStyle、ui.PriorityP0Style、ui.TypeBugStyle等导出样式保证 list、graph、show、related 各命令间的图标一致。测试与开发规范要点测试命令与 PR 就绪门禁统一遵循 engdocs/TESTING.md绝不要污染生产数据库手工测试要在一次性工作目录中初始化——bd init --quiet --prefix test --skip-hooks --skip-agents配合mktemp -d且注意BEADS_DB单独并不能重定向bd init的工作区设置提交信息携带 issue IDgit commit -m Fix auth validation bug (bd-abc)这使bd doctor能检测孤儿 issue已提交但未关闭的工作Agent 准备的提交还要带Agent-Signature:trailer见 engdocs/AGENT_SIGNING.md构建必须走make install不要用go build -o bd ./cmd/bd、go install ./cmd/bd或裸go run因为它们会绕过规范构建路径、可能留下过期二进制且裸go run会漏掉必需的gms_pure_go构建标签——需要 go run 时用go run -tags gms_pure_go ./cmd/bd ...版本升级统一走脚本./scripts/bump-version.sh version --commit会原子性更新 CLI、插件、MCP server 与文档中的所有版本号。总结从规范文件到可执行的 Agent 记忆AGENTS.md不是一份普通的 README它是 Beads 项目Agent 优先工程理念的可执行体现bd-doctor-divergence标记让规范文档自身进入健康检查体系bd ready/bd update/bd close的命令设计原子认领、last-touched 防误伤、位置映射 reason处处为无头headlessAgent 的安全操作兜底Dolt 驱动的refs/dolt/data同步让任务历史具备 Git 级别的可审计性而 Conservative / Minimal / Team-maintainer 三级画像则把何时可以 commit/push的授权边界讲得一清二楚。对于任何想为编码 Agent 构建任务追踪系统的开发者这份文档连同 cmd/bd/ready.go、issueops/readyclaimer.go 等实现构成了一套从规范到源码的完整参考。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考