企业官网建设流程全解析

为编码 Agent 而生：Beads 仓库 AGENTS.md 任务追踪规范与 bd CLI 实战指南

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

Beads（bd）是一个"为编码 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 12a：AGENTS.md / CLAUDE.md 用户编写内容分歧"检查——doctor.CheckAgentDocDivergence会扫描两份文档并对比，但不会让检查失败，只是输出警告级别结果。这构成了一个自我验证的文档治理闭环：规范文件本身也是bd doctor健康检查的监测对象。

项目范围与存储边界：两条不可逾越的架构红线

新增功能面之前：先读 PROJECT_CHARTER

AGENTS.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 的 Agent，AGENTS.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_BASE=1从告警升级为阻断）、扫描危险 diff 信号（.beads数据变更、改代码却缺测试、超大 diff），最后给出贡献者保护的下一步与署名提醒。

外部贡献者 PR 享有优先级：尽可能检出对方分支、在其上修复/改编后再合并，保留他们的测试与署名，绝不静默关闭或取代其 PR。若重写不可避免，必须在原 PR 上说明理由并致谢其设计/测试。配套的 AGENT_INSTRUCTIONS.md 还要求用gh pr list --repo gastownhall/beads --state open --search "<topic>"在动手前先检查是否已有同主题的开放 PR。

任务追踪：为什么这个仓库用 bd 而不是 Markdown TODO

AGENTS.md明确宣告：本项目使用 bd（beads）承担所有问题追踪，禁止使用 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" --description="Detailed context" -t bug|feature|task -p 0-4 --json # 带依赖：链接"从 bd-123 中发现"的新工作 bd create "Issue title" --description="What 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 依赖 id"；blocks: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）：

五档优先级（Priorities）：

AI Agent 标准工作流

1. 检查就绪工作：bd ready展示未被阻塞的 issue；
2. 原子化认领任务：bd update <id> --claim；
3. 开展工作：实现、测试、记录；
4. 发现新工作？创建链接 issue：bd create "Found bug" --description="..." -p 1 --deps discovered-from:<parent-id>；
5. 完成：bd close <id> --reason "Done"。

质量要求：创建 issue 时使用--acceptance（验收标准）与--design（设计说明）字段；用--validate检查描述完整性。

生命周期与卫生命令

• bd defer <id>/bd supersede <id>：延期 / 取代某个 issue；
• bd 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.go）；
• bd ready --explain：依赖感知诊断，解释每个 issue 为何就绪或被阻塞，包括"已解决的阻塞器"（Resolved blockers）、"解锁 N 个 issue"（Unblocks）统计、以及依赖环检测（cycles）——其过滤条件把 limit 固定为无限，避免解释被 100 行默认上限静默截断；
• bd ready --mol <name>：过滤到某个分子（molecule）内的就绪步骤，并展示并行组（parallel groups）与"可并行运行"（Can run with）提示；
• bd ready --gated：找出"某个门关闭后可恢复调度"的分子。

过滤能力（cmd/bd/ready.go 注册的全部 flag）：--limit/-n（默认workapi.DefaultReadyLimit，0 表示不限）、--priority/-p、--assignee/-a、--unassigned/-u、--sort（priority/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-type（swarm/patrol/work）、--include-deferred、--include-ephemeral（wisps）、--exclude-type、元数据过滤（--metadata-field key=value与--has-metadata-key）、以及防御性行数上限--max-rows（越界退出码 2，默认关闭）。

目录感知标签作用域（cmd/bd/ready_input.go）：当命令行没有显式标签时，bd ready会把配置的目录标签（directory.labels，GH#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 edit

AGENTS.md有一条醒目警告：绝不要使用bd edit——它会打开交互式编辑器（$EDITOR），AI Agent 无法使用。替代方案是bd update配合 flags：

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"

含特殊字符的描述走 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_FALLBACK=1在任何环境启用、=0彻底禁用。

同步架构：Dolt 本地库 + refs/dolt/data

bd把 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.md（Dolt 数据存放在refs/dolt/data下，与标准 Git refs 隔离）。由于使用哈希 ID，合并冲突极少见；即便出现，Dolt 也用单元格级三方合并（cell-level 3-way merge）解决。

会话收尾协议：Landing the Plane 与 Agent Context Profiles

Landing the Plane（强制收尾流程）

AGENTS.md规定，结束工作会话（或用户说 "let's land the plane"）时，必须完成全部步骤，且git push成功之前工作不算完成：

1. 为剩余工作建档：创建需要跟进的 issue；
2. 跑质量门禁（若改了代码）：
   • make ci-pr-lint（零告警的格式化与 lint 包装，见 engdocs/LINTING.md）；
   • make test（仅在确实需要 ICU 正则路径时加跑make test-icu-path）；
   • 质量门禁坏了就建 P0 issue；
3. 更新 issue 状态：关闭已完成项、更新进行中项；
4. 推送远程（强制）：

   git pull --rebase git push git status # 必须显示 "up to date with origin"

5. 清理：git stash clear（清除旧 stash）、git remote prune origin（清理已删除的远程分支）；
6. 验证：所有变更均已提交且推送，无未跟踪文件残留；
7. 交接：选一个跟进 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 BatchMode=yes（失败而非提示）、apt-get加-y、brew设HOMEBREW_NO_AUTO_UPDATE=1环境变量。

视觉设计规范：小 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 ID：git 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）处处为无头（headless）Agent 的安全操作兜底；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