Beads (bd) – 为 AI 代理打造的分布式议题追踪器

它是什么 – 一个命令行工具，为 AI 编码代理提供结构化、版本控制的“记忆”来追踪工作。它将任务（称为 beads）存储在 Dolt SQL 数据库中，该数据库的行为类似具有分支、合并与远程同步的 Git 风格数据存储。

为何对代理很重要 – 代理不再将 TODO 散落在 markdown 中，而是可以查询依赖图、以原子方式认领工作，并通过 bd remember 取回持久事实。JSON 输出与基于哈希的 ID 是为程序化消费而设计，让多个代理能协作而不产生合并冲突。

核心概念

概念	说明
Bead	存储在 Dolt DB 中的任务/议题。ID 看起来像 `bd‑a1b2`（epic）或 `bd‑a1b2.1`（子任务）。
依赖图	任务可以链接（`relates‑to`、`duplicates`、`supersedes`、`replies‑to`）。`bd dep add <child> <parent>` 创建阻塞/父项关系，使 `bd ready` 命令仅列出没有未解决阻塞的工作。
Dolt 后端	Dolt 提供具有单元格层级合并、原生分支与远程 push/pull 的 SQL 数据库。Beads 可以内嵌运行 Dolt（默认），或连接至外部 Dolt SQL 服务器以支持并发写入者。
代理优化工作流程	命令会输出 JSON，支持 `--claim`（原子认领 + 进行中旗标），并提供 `bd prime` 命令，将项目的“记忆”（事实、未完成任务）注入代理的提示中。
压缩 / 记忆衰减	已关闭的任务会自动摘要，使数据库保持精简并维持在 LLM 上下文窗口内。

典型工作流程（CLI 命令）

# One‑time install (system‑wide)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialise a project (creates .beads/ and AGENTS.md)
cd my‑project && bd init

# Add a high‑priority task
bd create "Implement search endpoint" -p 0

# Declare that it blocks another task
bd dep add bd‑a1b2.1 bd‑a1b2   # child blocks parent

# Agent asks for work it can start now
bd ready --json   # only tasks with no open blockers

# Agent claims a task atomically
bd update bd‑a1b2.1 --claim

# While working, store a reusable insight
bd remember "ElasticSearch pagination uses `search_after`" 

# When finished, close the task (releases blockers)
bd close bd‑a1b2.1 "Implemented and tested"

bd prime 会打印当前上下文（未完成任务、已存储的见解），以便基于 LLM 的编码助手能将其前置于提示中。

集成点

集成	它增加了什么
Codex / Claude / Factory.ai (`bd setup <name>`)	安装语言模型特定的指令文件（`AGENTS.md`）与 IDE 钩子，让模型知道 Beads 命令。
VS Code / Cursor / Copilot	提供扩展，将 Beads 命令转为 UI 动作，并在生成前自动运行 `bd prime`。
HTTP 后端（实验性）	运行一个轻量客户端，对抗远程 `bd serve` 进程，适用于共享服务器或将 Beads 嵌入为库。
无 Git 模式 (`bd init --stealth`)	将所有内容存储在 `.beads/` 中而不触碰仓库，非常适合 CI、monorepos 或非 Git 版本控制系统。

它如何融入 AI 代理堆栈

提示准备 – bd prime（或生成的 AGENTS.md 片段）将就绪任务与已记忆事实的简明列表注入 LLM 提示中。
决策 – 代理解析 bd ready/bd show 的 JSON 输出以挑选任务。
执行 – 代理运行 bd update … --claim，进行代码变更，然后 bd close …。
协作 – 多个代理（或人类）可以同时认领任务；Dolt 基于哈希的 ID 保证无冲突合并。
持久性 – 所有任务历史、依赖关系与已存储的见解都保存在 Dolt DB 中，并可通过 bd dolt push/pull 跨机器同步。

开始使用

安装 – brew install beads、npm install -g @beads/bd，或使用提供的安装脚本。
文档 – https://beads.gascity.com/（安装、同步概念、HTTP 后端、疑难排解）。
社区 – UI 扩展、网页前端与相关项目列于 docs/community-tools.md。

TL;DR

Beads 是一个专门打造的议题追踪器，将项目的任务列表转变为机器可读、版本控制的图。通过与基于 LLM 的编码代理结合，您可以获得可靠、无冲突的协调以及能在多次运行与多个代理之间存续的持久“记忆”。

gastownhall/beads