bd - 珠子

由 Dolt 提供支持的、面向 AI 代理的分布式图式问题跟踪器。

支持平台： macOS、Linux、Windows、FreeBSD

文档： https://gastownhall.github.io/beads/

Beads 为编码代理提供了一种持久化的结构化记忆。它用依赖感知的图结构取代了杂乱的 Markdown 计划，使代理能够在不丢失上下文的情况下处理长期任务。

⚡ 快速入门

# 安装 beads CLI（系统全局安装——不要将此仓库克隆到你的项目中）
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# 在你的项目中初始化
cd your-project
bd init

# 告诉你的代理
echo "Use 'bd' for task tracking" >> AGENTS.md

注意： Beads 是一个只需安装一次即可在任何地方使用的命令行工具。你不需要将这个仓库克隆到你的项目中。

🛠 功能特性

• 基于 Dolt 的支持： 可版本控制的 SQL 数据库，具备单元级合并、原生分支功能，并可通过 Dolt 远程仓库实现内置同步。
• 针对代理优化： JSON 输出、依赖关系跟踪以及自动检测就绪任务。
• 零冲突： 基于哈希的 ID（bd-a1b2）可防止多代理或多分支工作流中的合并冲突。
• 压缩机制： 语义上的“记忆衰退”会总结旧的已关闭任务，以节省上下文窗口。
• 消息传递： 支持带线程的消息类型（--thread），具有短暂的生命周期和邮件委派功能。
• 图链接： relates_to、duplicates、supersedes 和 replies_to，适用于知识图谱。

📖 核心命令

命令	功能
bd ready	列出没有未完成阻塞项的任务。
bd create "Title" -p 0	创建一个 P0 级别任务。
bd update <id> --claim	原子性地认领一个任务（设置经办人并标记为进行中）。
bd dep add <child> <parent>	链接任务（阻止、相关、父子关系）。
bd show <id>	查看任务详情及审计轨迹。

🔗 层次结构与工作流

Beads 支持用于史诗级任务的层次化 ID：

• bd-a3f8（史诗级任务）
• bd-a3f8.1（任务）
• bd-a3f8.1.1（子任务）

隐身模式： 运行 bd init --stealth 可以在本地使用 Beads，而无需将文件提交到主仓库。非常适合在共享项目中个人使用。请参阅下方的 无 Git 使用方式。

贡献者与维护者： 在参与开源项目时：

• 贡献者（分叉的仓库）：运行 bd init --contributor 将规划问题路由到一个独立的仓库（例如 ~/.beads-planning）。这样可以将实验性工作排除在 PR 之外。
• 维护者（拥有写入权限）：Beads 会通过 SSH URL 或带有凭据的 HTTPS 自动检测维护者角色。只有在使用 GitHub HTTPS 而没有凭据但拥有写入权限的情况下，才需要运行 git config beads.role maintainer。

📦 安装方法

brew install beads           # macOS / Linux（推荐）
npm install -g @beads/bd     # Node.js 用户

其他方法： 快速安装脚本（所有平台） | go install（推荐） | 从源码编译（仅限贡献者） | Windows | Arch AUR

要求： macOS、Linux、Windows 或 FreeBSD。完整的安装指南请参阅 docs/INSTALLING.md。

安全与验证

在信任任何下载的二进制文件之前，请根据发行版中的 checksums.txt 文件验证其校验和。

安装脚本会在安装前验证发行版的校验和。对于手动安装，请在首次运行前自行完成此验证。

在 macOS 上，scripts/install.sh 默认会保留下载的签名。本地临时重新签名需要显式启用 BEADS_INSTALL_RESIGN_MACOS=1。

有关 Windows AV 误报的指导以及验证流程，请参阅 docs/ANTIVIRUS.md。

💾 存储模式

Beads 使用 Dolt 作为其数据库。有两种可用模式：

嵌入式模式（默认）

bd init

Dolt 在进程中运行——无需外部服务器。数据存储在 .beads/embeddeddolt/ 目录下。仅支持单写操作（强制文件锁定）。这是大多数用户的推荐模式。

服务器模式

bd init --server

连接到外部的 dolt sql-server。数据存储在 .beads/dolt/ 目录下。支持多个并发写入者。可以通过标志或环境变量配置连接：

标志	环境变量	默认值
--server-host	BEADS_DOLT_SERVER_HOST	127.0.0.1
--server-port	BEADS_DOLT_SERVER_PORT	3307
--server-user	BEADS_DOLT_SERVER_USER	root
	BEADS_DOLT_PASSWORD	（无）

备份与迁移

使用 bd backup 备份数据库并在不同模式之间迁移：

# 设置备份目标并推送
bd backup init /path/to/backup
bd backup sync

# 恢复到新项目中（任意模式）
bd init           # 或 bd init --server
bd backup restore --force /path/to/backup

完整的迁移说明请参阅 docs/DOLT.md。

🌐 社区工具

请参阅 docs/COMMUNITY_TOOLS.md，了解社区构建的 UI、扩展和集成的精选列表——包括终端界面、Web UI、编辑器扩展和原生应用。

🚀 无 Git 使用方式

Beads 不需要 Git 即可工作。Dolt 数据库是存储后端——Git 集成（钩子、仓库发现、身份识别）是可选的。

# 在没有 Git 的情况下初始化
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# 所有核心命令都不需要调用 Git
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"

BEADS_DIR 告诉 bd 将 .beads/ 数据库目录放置在哪里，从而绕过 Git 仓库的自动发现。--stealth 会在配置中设置 no-git-ops: true，禁用所有 Git 钩子的安装和 Git 操作。

这在以下场景中非常有用：

• 非 Git VCS（Sapling、Jujutsu、Piper）——无需 .git/ 目录
• 单体仓库——将 BEADS_DIR 指向特定的子目录
• CI/CD——隔离的任务跟踪，不会对整个仓库产生副作用
• 评估/测试——临时数据库位于 /tmp

若需在无 Git 的情况下以守护进程模式运行，可使用 bd daemon start --local（参见 PR #433）。

📝 文档

• 文档网站（版本化）| 安装 | 代理工作流 | Copilot 集成 | 文章 | 同步分支模式 | 故障排除 | 常见问题解答
• 

Beads (bd) 快速上手指南

Beads 是一个专为 AI 编程代理设计的分布式图结构任务追踪工具。它基于 Dolt（支持版本控制的 SQL 数据库），用依赖感知的图谱取代了杂乱的 Markdown 计划，帮助代理在处理长周期任务时保持上下文不丢失。

环境准备

• 操作系统：macOS, Linux, Windows, FreeBSD
• 前置依赖：
  • 无需手动安装 Dolt，Beads 会自动处理嵌入式数据库或连接外部服务。
  • 若使用 Git 集成模式，需确保系统已安装 git。
  • 若使用无 Git 模式（Stealth Mode），则完全不需要 Git 环境。

安装步骤

推荐以下两种安装方式（任选其一）：

方式一：使用官方安装脚本（推荐，适用于所有平台）

此方法会全局安装 CLI 工具，无需将仓库克隆到你的项目中。

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

方式二：使用包管理器

macOS / Linux (Homebrew):

brew install beads

Node.js 用户:

npm install -g @beads/bd

安全提示：手动下载二进制文件时，请务必对照发布页的 checksums.txt 验证校验和。官方安装脚本已内置验证逻辑。

基本使用

1. 初始化项目

进入你的代码项目目录并初始化 Beads。这会在项目中创建 .beads/ 目录用于存储数据。

cd your-project
bd init

提示：如果你想在共享项目中个人私有使用（不提交文件到主仓库），可使用隐身模式： bd init --stealth

2. 配置 AI 代理

在你的项目说明文件（如 AGENTS.md 或 System Prompt）中加入以下指令，让 AI 知道如何使用 Beads：

Use 'bd' for task tracking

3. 核心工作流示例

以下是日常开发中最常用的命令序列：

创建高优先级任务：

bd create "修复登录认证 Bug" -p 0

查看当前可执行任务（无阻塞依赖的任务）：

bd ready

认领任务（原子操作，设置负责人和状态为进行中）：

bd update <task-id> --claim
# 例如：bd update bd-a1b2 --claim

建立任务依赖关系（子任务依赖于父任务）：

bd dep add <child-id> <parent-id>

查看任务详情及审计记录：

bd show <task-id>

关闭任务：

bd close <task-id> "已完成修复"

4. 无 Git 环境使用（可选）

如果你在不使用 Git 的版本控制系统（如 Sapling, Jujutsu）或纯测试环境中工作：

export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# 之后所有命令均可正常运行，不会调用任何 git 操作
bd create "测试任务" -p 1
bd ready --json