Beadsbd使用指南面向 AI 编码代理的 Dolt 驱动依赖感知问题追踪器【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads命令行工具bd是一个构建在 Dolt版本控制的 SQL 数据库之上的问题追踪器专为 AI 监督的编码工作流而设计它用持久化、结构化的依赖图取代易腐烂的 Markdown 计划让编码代理在会话结束后依然保有记忆。读完本文你将掌握 Beads 的安装初始化、issue 创建与依赖建模、bd ready就绪工作流、--json机器可读接口以及基于 Dolt 的多机同步方案。为什么需要 Beads传统追踪器在 AI 工作流中的失效传统问题追踪器Jira、GitHub Issues并非为 AI 代理设计。编码代理的会话一结束上下文随之丢失Markdown 计划逐渐腐化、TODO 注释散落各处、崩溃的代理连同上下文一起消失。Beads 从零开始为以下场景构建AI 原生工作流基于哈希的 ID如bd-a1b2防止多个代理并发工作时产生 ID 冲突Dolt 后端存储issue 存储在版本控制的 SQL 数据库中通过 Dolt 原生复制实现协作依赖感知执行bd ready只展示未被阻塞的、可立即执行的工作Formula 系统声明式模板用于可重复的工作流多代理协调routing、gates、molecules 支撑复杂工作流。核心循环可以用一句话概括创建和关闭 bead 会重塑依赖图而决定下一步做什么的是这张图本身而不是人工调度者。bd create产生新的 bead 进入依赖图bd ready从中挑出可认领的工作代理通过bd update --claim原子认领完成后再以bd close关闭被释放的阻塞者重新进入 ready 队列。快速开始安装、初始化与第一条 issue安装# 通过 Homebrew 安装macOS/Linux brew install beads # 或使用官方安装脚本macOS/Linux/FreeBSD curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash其他安装方式还包括 npmnpm install -g beads/bd、go install以及从源码构建完整说明见 安装指南。Beads 是一个全局安装的 CLI 工具无需克隆本仓库到你的项目中。初始化项目# 进入你的项目目录 cd your-project bd init --quiet # 非交互模式适合 AI 代理bd init会创建.beads/目录与内嵌 Dolt 数据库、根据提示或标志确定你的角色maintainer 或 contributor、从 git 导入既有 issue如有并安装 git hooks可用--skip-hooks跳过。它默认还会创建或更新AGENTS.md让代理可以发现 beads 工作流。初始化向导会询问 Contributing to someone elses repo?回答 Y 走 contributor 向导fork 场景issue 存入独立规划仓库回答 N 则按 maintainer 处理issue 存入仓库内.beads/。该选择写入git config beads.role也可手动配置与查看git config beads.role contributor git config beads.role maintainer git config --get beads.role创建第一条 issuebd create Set up database -p 1 -t task bd readybd create是创建 issue 的入口-p指定优先级、-t指定类型详见 bd create 文档。核心概念beads、依赖、同步、公式与门控Beadsissues工作单元模型一个bead就是一个被追踪的工作单元哈希 IDbd-a1b2、标题、类型bug、task、feature、epic、chore等可用bd types查看、优先级0严重 →4积压以及从open→in_progress→closed流转的状态。Bead 与 issue 指同一事物——CLI 里叫 issue产品层面叫 bead。每个 issue 的字段可以通过bd show bd-42 --json查看典型结构如下{ id: bd-42, title: Implement authentication, description: Add JWT-based auth, type: feature, status: open, priority: 1, labels: [backend, security], created_at: 2024-01-15T10:30:00Z, updated_at: 2024-01-15T10:30:00Z }完整字段与类型、优先级定义见 Issues Dependencies。依赖决定什么工作可以开始依赖把 beads 连接成一张图。有两种边类型决定代理能做什么类型含义是否影响 ready 工作blocks硬性排序——阻塞者必须先关闭是parent-childepic/子任务结构间接——被阻塞的父级会阻塞其子级discovered-from来源追踪——在处理父任务时发现否related软关联否工作流步骤还引入两种额外的阻塞类型conditional-blocks、waits-for见 Molecules更丰富的知识图谱边relates-to、duplicates、supersedes、replies-to见 Graph Links。常用依赖命令bd dep add bd-2 bd-1 # bd-2 依赖 bd-1blocks 关系 bd dep tree bd-3 # 查看依赖树 bd dep relate bd-1 bd-2 # 软关联 bd blocked # 查看被阻塞的 issueReady 工作bd ready的计算Ready 工作是依赖图的可认领前沿没有未关闭阻塞者的 open beads同时排除 in_progress、blocked、deferred 以及被 gate 挂起的项。代理从不扫描整个追踪器而是直接询问前沿并原子认领bd ready --json # 可认领前沿机器可读 bd ready --claim --json # 原子认领第一个匹配项 bd ready --explain # 展示完整的图推理过程--explain会逐条列出每个 ready 项的理由、每个 blocked 项被谁阻塞以及 ready/blocked 汇总。从源码看这一能力由 issueops/reader.go 中的ReadyRequest与 issueops/readyclaimer.go 的ReadyClaimer接口共同支撑后者提供原子认领语义issueops/readycounter.go 中的ReadyCounter/ReadyCountResult则负责就绪计数统计issueops/reader_ready_scope.go 中还有对ready标志作用域的校验逻辑ValidateReadyFlagScope。同步Dolt 推送与拉取Beads 把所有数据存放在 Dolt 中。每次写入都会自动提交到 Dolt 历史同步是原生的 push/pull借道你现有的 git 远程存放于独立 ref 之下无需运行任何服务器Dolt DB (.beads/embeddeddolt/ 内嵌模式.beads/dolt/ 服务器模式已被 gitignore) ↕ dolt commit 本地 Dolt 历史 ↕ dolt push/pull 远程 Dolt 仓库跨机器共享同步命令bd dolt push bd dolt pull对于普通的 git 托管项目Dolt 远程可以直接复用源码所用的originURLissue 历史存放在refs/dolt/data与refs/heads/main等源码分支相互独立。bd init会自动检测git remote get-url origin并配置名为origin的 Dolt 远程新克隆的项目运行bd bootstrap即可克隆 Dolt 历史并自动接通远程。需要特别澄清.beads/issues.jsonl只是一个被动导出文件供查看器、数据交换、迁移与备份使用不是数据库、不是同步协议、也不是备份——不要用bd import .beads/issues.jsonl替代bd dolt pullJSONL 导入是仅 upsert 的无法推断被删除的记录。完整模型与反模式见 Sync Concepts。存储模式模式命令数据位置写入者内嵌默认bd init.beads/embeddeddolt/单写入者文件锁服务器bd init --server.beads/dolt/多并发写入者内嵌模式在进程内运行 Dolt适合绝大多数用户服务器模式连接外部dolt sql-server用于多写入者场景详见 Dolt 后端架构。Formula → Proto → Molecule 工作流管道可重复的多步工作发布检查清单、功能流水线、评审流程只需声明一次、按需实例化formula是源头定义步骤 DAG 的 TOML/JSON 文件见 Formulascook将其编译为proto带{{variables}}占位符的模板 epic带template标签可复用但还不是活的工作pour实例化出molecule真实的 beads其步骤和其他工作一样流经bd ready见 Moleculeswisp是同样的实例化但生命周期是临时的——下一次bd purge时消失见 Wispsgate让某个步骤挂起直到外部条件发生人工签核、定时器或 GitHub run/PR见 Gates。bd formula list # 列出搜索路径上可见的公式 bd cook release.formula.toml # 将公式编译为 proto bd mol pour release --var version1.2.0 # 实例化真实工作 bd ready --mol mol-id # 当前可以运行哪些步骤面向 AI 代理程序化访问接口Beads 为 AI 编码代理做了专门优化代理应该始终使用--json做程序化访问# 始终使用 --json 进行程序化访问 bd list --json bd show bd-42 --json # 在实现过程中追踪发现的工作 bd create Found bug in auth --descriptionDetails... \ --deps discovered-from:bd-100 --json # 会话结束时推送变更 bd dolt push代理工作流的基础命令还包括bd update id --claim原子认领同时设置 assignee 与 in_progress、bd remember insight持久化项目记忆之后由bd prime注入、bd prime打印代理工作流上下文与持久记忆。详细的代理接入指引见 Claude Code 集成。为什么代理永远不会撞 IDbd-a1b2这样的 ID 是内容派生的哈希基于标题、描述、创建者、创建时间及冲突随机数而不是序列号。两个代理或两个分支同时创建 beads 也不可能产出相同 ID合并时永远不会给工作重新编号发生碰撞时哈希长度自动扩展并随数据库规模自适应——原理与配置详见 Hash IDs 与 Adaptive ID Length。ID 前缀与长度可配置# 设置前缀默认 bd bd config set id.prefix myproject # 设置哈希长度默认 4 bd config set id.hash_length 6大型功能还可以使用层级 IDbd-a3f8Epic、bd-a3f8.1Task、bd-a3f8.1.1Sub-task子项自动编号最多支持 3 层嵌套便于在哈希命名空间内组织父子关系。完整工作流示例从初始化到团队同步创建依赖链# 创建三条 issue bd create Set up database -p 1 -t task bd create Create API -p 2 -t feature bd create Add authentication -p 2 -t feature # 建立依赖API 依赖数据库认证依赖 API bd dep add bd-2 bd-1 bd dep add bd-3 bd-2 # 查看就绪工作 bd ready此时只有bd-1是 ready 的因为bd-2与bd-3都被阻塞。注意bd ready与bd list --status open并不相同list展示所有 open issue不关心阻塞关系ready会计算依赖图只展示真正未被阻塞的工作。这正是 Beads 与传统扁平追踪器的本质差异——扁平追踪器里代理随机挑一个任务却立刻卡住而 Beads 保证代理每次都能选到正确的任务。推进队列并同步# 认领并完成第一个任务 bd update bd-1 --claim bd close bd-1 --reason Database setup complete # 现在 bd-2 变为 ready # 与团队同步复用 git origin bd dolt remote list bd dolt push bd dolt pull队友克隆仓库后运行bd bootstrap即可自动检测refs/dolt/data上的既有数据库、克隆它并接通origin供后续 push/pull。旧项目若在自动远程接线功能之前初始化可在一台权威机器上手动执行bd dolt remote add origin git-origin-url支持gitssh://、githttps://形式后bd dolt push其他人执行bd dolt pull或bd bootstrap跟上。维护迁移、压缩与清理升级 bd 后用bd migrate检查并迁移旧数据库文件数据库随关闭的 issue 累积而膨胀时用压缩与清理命令控制体积bd migrate --inspect --json # 检查迁移计划AI 代理用 bd admin compact --stats # 查看压缩统计 bd admin compact --analyze --json # 预览 30 天以上已关闭的压缩候选 bd admin cleanup --force # 立即删除已关闭 issue永久操作谨慎压缩是优雅的语义衰减原内容被丢弃但可通过bd restore id从压缩前快照恢复Dolt 历史兜底。下一步安装指南 —— 全平台安装方式与校验快速上手 —— 创建、认领、关闭你的第一批 beadsHow Beads Works —— 一页看完概念模型CLI Reference —— 全部可用命令Workflows —— formulas、molecules 与 gates 深入【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考