阿超 > beads

beads

2026-01-13

ai

一年之计在于春，一日之计在于晨。——萧绎

Beads：给你的 AI Coding Agent 装上一块“长期记忆”

如果你的日常开发已经离不开 Claude Code、Cursor、Windsurf 或自建 Agent，很快会遇到一个共同问题：任务一多、上下文一长、分支一复杂，Agent 的“短时记忆”撑不住了，计划和依赖也散落在文档或对话里，难以复用与审计。
steveyegge/beads 给出的答案很直接：把任务、依赖、状态、审计轨迹都放进你的仓库，用 Git 管理，用结构化数据表达，用命令行驱动，让 Agent 能够稳定地跑长周期任务，还能和人类协作。

项目的自我定义非常克制：分布式、Git 驱动、面向 AI Agent 的图式 Issue 追踪器。它不是另一个“网页工单系统”，而是一套贴着代码活的工作记忆。

一句话核心

  • 描述来自仓库：Distributed, git-backed graph issue tracker for AI agents
  • 定位来自 README：为编码代理提供持久、结构化记忆，用依赖图替代散乱的 Markdown 计划，支撑长期任务

为什么是 Git 里的“图”

  • Git 即数据库：Issue 存在 .beads/ 下，以 JSONL 存储，随分支与合并自然演进
  • 面向 Agent 设计：所有命令支持 JSON 输出，具备依赖跟踪与自动就绪检测
  • 零冲突 ID：采用哈希型短 ID 格式 bd-a1b2，多人多分支下避免合并冲突
  • 隐形基础设施：本地 SQLite 作为高速缓存，常驻守护进程自动同步
  • 记忆压缩：对已关闭的老任务做“语义概括”，节省上下文窗口

这些不是“花式功能”，而是将“计划即数据、数据即版本”的思想落地。AI Agent 最擅长读写结构化数据与命令行接口，Beads 把这条路打通了。

快速开始

官方最快方式：

1
2
3
4
5
6
7
8
# 安装（macOS / Linux / FreeBSD）
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# 在你的仓库初始化一次
bd init

# 提醒你的 Agent：用 bd 管任务
echo "Use 'bd' for task tracking" >> AGENTS.md

也可以用你习惯的包管理器：

1
2
3
4
5
6
7
8
# npm
npm install -g @beads/bd

# Homebrew
brew install steveyegge/beads/bd

# Go
go install github.com/steveyegge/beads/cmd/bd@latest

系统支持 Linux、FreeBSD、macOS、Windows。

基础命令：让任务“结构化”

来自 README 与 .beads 说明文档的必备命令：

1
2
3
4
5
6
7
8
9
10
11
# 查看“就绪任务”（没有阻塞）
bd ready

# 创建一个最高优先级任务
bd create "修复登录重试的指数退避" -p 0

# 建立依赖关系：child 依赖 parent
bd dep add <child> <parent>

# 查看任务详情与审计轨迹
bd show <id>

你也可以把它当作一个“纯命令行的轻量工单系统”来用：

1
2
3
4
5
6
7
8
9
# 常规清单
bd list

# 把任务状态切到进行中、已完成
bd update <id> --status in_progress
bd update <id> --status done

# 同步到远端
bd sync

层级管理也很自然，ID 支持分层：

1
2
3
bd-a3f8          史诗级 Epic
bd-a3f8.1        其下任务
bd-a3f8.1.1      子任务

如果你只想自己在本地用，而不希望 .beads 内容进主仓库：

1
bd init --stealth

让 Agent 真正“会工作”的最小闭环

Beads 的命令天然适合被 Agent 调用，所有命令都能输出 JSON，便于解析与自动化。一个最小闭环：

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 找“就绪”工作
bd ready --json --limit 1

# 2. 领取任务
bd update <id> --status in_progress --json

# 3. 期间如果发现新问题，创建并挂上关系
bd create "新发现：认证中间件时间漂移" --json
bd dep add <new-id> <parent-id> --type discovered-from

# 4. 完成任务并关闭
bd close <id> --reason "Done" --json

在仓库的 examples 目录里还有一个 Bash Agent 示例，演示了“自动发现就绪任务、随机生成跟进 Issue、建立依赖并完工”的循环，你可以直接跑起来体验节奏。

直接以库方式使用：Go 代码示例

如果不想通过进程拉起 CLI，Beads 也提供 Go 库接口。来自 examples/library-usage 的示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
package main

import (
    "context"
    "log"

    "github.com/steveyegge/beads"
)

func main() {
    ctx := context.Background()

    // 查找并打开数据库
    dbPath := beads.FindDatabasePath()
    store, err := beads.NewSQLiteStorage(dbPath)
    if err != nil {
        log.Fatal(err)
    }
    defer store.Close()

    // 获取就绪工作
    ready, err := store.GetReadyWork(ctx, beads.WorkFilter{
        Status: beads.StatusOpen,
        Limit: 10,
    })
    if err != nil {
        log.Fatal(err)
    }

    // 在此处理 ready 中的任务
    _ = ready
}

当你在构建自己的 IDE 扩展、集成面板或 Agent 编排器时，库模式会更高效，也有完整的事务与错误处理能力。

与 Claude Desktop 的 MCP 集成

在无 Shell 的环境下，官方提供了 MCP 服务器 beads-mcp，从 PyPI 安装即可：

1
2
3
4
5
# 使用 uv
uv tool install beads-mcp

# 使用 pip
pip install beads-mcp

Claude Desktop 的最简配置：

1
2
3
4
5
6
7
{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp"
    }
  }
}

文档对比指出：如果环境能用 Shell，推荐 CLI + 钩子方案，Token 成本与延迟都会更低；若必须 MCP，beads-mcp 是官方路径。多仓多项目场景下，它会自动路由到各项目本地守护进程，实现数据库隔离。

团队与生态

官方维护了一个社区工具清单：终端界面、Web UI、编辑器扩展、原生应用等都在路上，详见仓库的 docs/COMMUNITY_TOOLS.md。
Windows 用户还可通过 winget 分发，相关清单在 winget/ 目录。
Release 流程标准化，脚本化维护位于 scripts/ 目录，便于持续交付。

典型落地场景

  • 多代理联合工作：把规划拆成可执行的依赖图，Agent 只需“看 JSON、跑命令、回写结构化结果”
  • 长期任务记忆：旧的已关闭任务自动做语义压缩，不挤占上下文窗口
  • 分支与协作：Issue 跟着 Git 演进，合并时不怕冲突，审计轨迹可回放
  • 开源协作：contributors 可以在自己的 Fork 或计划仓里先做规划，然后合并进主线

许可与技术栈

  • 语言：Go
  • 许可：MIT License

结语

Beads 不是把“工单系统”搬到网页，而是把“工作记忆”搬进你的仓库。
当任务与依赖成为 Git 里的结构化数据，Agent 的执行就不再是一次性的“对话魔法”，而变成可追溯、可复用、可合并、可协作的工程资产。
如果你已经在用 AI Coding Agent，建议在你的主力项目里跑一遍 bd init，把零散的计划和上下文收拢进 .beads/。当第一条跨分支的依赖链条顺利合并，你会感受到那种“工程节奏终于稳住了”的安心。

更多信息与示例，请直接查看项目仓库与 examples 目录：
steveyegge/beads