gastownhall/beads

# bd - Beads **面向 AI 代理的分布式图谱化问题跟踪器，由 [Dolt](https://github.com/dolthub/dolt) 驱动。** **平台：** macOS, Linux, Windows, FreeBSD [](LICENSE) [](https://goreportcard.com/report/github.com/steveyegge/beads) [](https://github.com/steveyegge/beads/releases) [](https://www.npmjs.com/package/@beads/bd) [](https://pypi.org/project/beads-mcp/) **文档：** https://gastownhall.github.io/beads/ Beads 为编程代理提供持久且结构化的记忆。它用支持依赖关系的图谱替代了混乱的 markdown 计划，使代理能够处理长周期任务而不丢失上下文。 ## ⚡ 快速开始 ``` # 安装 beads CLI (系统全局 - 不要将此 repo 克隆到你的项目中) curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash # 在你的项目中初始化 cd your-project bd init # 告诉你的 agent echo "Use 'bd' for task tracking" >> AGENTS.md ``` **注意：** Beads 是一个一次安装即可随处使用的 CLI 工具。你不需要将此仓库克隆到你的项目中。 ## 🛠 功能特性 * **[Dolt](https://github.com/dolthub/dolt) 驱动：** 具有版本控制功能的 SQL 数据库，支持单元格级别合并、原生分支，并通过 Dolt 远程仓库进行内置同步。 * **为代理优化：** JSON 输出、依赖追踪以及自动就绪任务检测。 * **零冲突：** 基于哈希的 ID（`bd-a1b2`）防止多代理/多分支工作流中的合并冲突。 * **数据压缩：** 语义化的“记忆衰退”会总结旧的已关闭任务，以节省上下文窗口。 * **消息传递：** 具有线程化（`--thread`）、短暂生命周期和邮件委托功能的消息类型 issue。 * **图谱链接：** 用于知识图谱的 `relates_to`、`duplicates`、`supersedes` 和 `replies_to` 关系。 ## 📖 常用命令 | 命令 | 操作 | | --- | --- | | `bd ready` | 列出没有未完成阻塞的任务。 | | `bd create "Title" -p 0` | 创建一个 P0 任务。 | | `bd update --claim` | 原子化认领任务（设置指派人 + 进行中状态）。 | | `bd dep add ` | 关联任务（阻塞、相关、父子）。 | | `bd show ` | 查看任务详情和审计记录。 | ## 🔗 层次结构与工作流 Beads 支持史诗（Epic）的层级 ID： * `bd-a3f8`（史诗） * `bd-a3f8.1`（任务） * `bd-a3f8.1.1`（子任务） **隐身模式：** 运行 `bd init --stealth` 可以在本地使用 Beads，而不会将文件提交到主仓库。非常适合在共享项目中的个人使用。请参阅下面的[无 Git 用法](#-git-free-usage)。 **贡献者 vs 维护者：** 在参与开源项目时： * **贡献者**（复刻的仓库）：运行 `bd init --contributor` 将规划问题路由到单独的仓库（例如，`~/.beads-planning`）。使实验性工作远离 PR。 * **维护者**（写权限）：Beads 通过 SSH URL 或带有凭据的 HTTPS 自动检测维护者角色。只有在你拥有写权限但使用没有凭据的 GitHub HTTPS 时，才需要 `git config beads.role maintainer`。 ## 📦 安装 ``` brew install beads # macOS / Linux (recommended) npm install -g @beads/bd # Node.js users ``` **其他方式：** [安装脚本](docs/INSTALLING.md#quick-install-script-all-platforms) | [go install](docs/INSTALLING.md#quick-install-recommended) | [从源码构建](docs/INSTALLING.md#build-dependencies-contributors-only) | [Windows](docs/INSTALLING.md#windows-11) | [Arch AUR](docs/INSTALLING.md#linux) **系统要求：** macOS, Linux, Windows 或 FreeBSD。有关完整的安装指南，请参阅 [docs/INSTALLING.md](docs/INSTALLING.md)。 ### 安全与验证 在信任任何下载的二进制文件之前，请针对发布版 `checksums.txt` 验证其校验和。 安装脚本在安装前会验证发布版校验和。对于手动安装，请在首次运行前自行进行此验证。 在 macOS 上，`scripts/install.sh` 默认保留下载的签名。本地的临时重新签名需要通过 `BEADS_INSTALL_RESIGN_MACOS=1` 显式选择启用。 有关 Windows 杀毒软件误报指南和验证工作流，请参阅 [docs/ANTIVIRUS.md](docs/ANTIVIRUS.md)。 ## 💾 存储模式 Beads 使用 [Dolt](https://github.com/dolthub/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-socket` | `BEADS_DOLT_SERVER_SOCKET` | (无；使用 TCP) | | `--server-user` | `BEADS_DOLT_SERVER_USER` | `root` | | | `BEADS_DOLT_PASSWORD` | (无) | **Unix 域套接字：** 使用 `--server-socket` 通过 Unix socket 连接 而不是 TCP。这避免了并发项目之间的端口冲突，并 在沙盒环境（例如 Claude Code）中很有用，因为在这些环境中，文件级 访问控制比网络白名单更简单。Dolt 服务器必须 使用 `dolt sql-server --socket ` 启动。Socket 模式不支持 自动启动。 ### 备份与迁移 使用 `bd backup` 备份数据库并在模式间进行迁移： ``` # 设置备份目标并推送 bd backup init /path/to/backup bd backup sync # 恢复到新项目中 (任何模式) bd init # or bd init --server bd backup restore --force /path/to/backup ``` 有关完整的迁移说明，请参阅 [docs/DOLT.md](docs/DOLT.md#migrating-between-backends)。 ## 🌐 社区工具 有关社区构建的 UI、扩展和集成的精选列表，请参阅 [docs/COMMUNITY_TOOLS.md](docs/COMMUNITY_TOOLS.md) —— 包括终端界面、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](https://github.com/steveyegge/beads/pull/433))。 ## 📝 文档 * [文档网站](https://gastownhall.github.io/beads/)（带版本控制） | [安装](docs/INSTALLING.md) | [代理工作流](AGENT_INSTRUCTIONS.md) | [Copilot 设置](docs/COPILOT_INTEGRATION.md) | [文章](ARTICLES.md) | [同步分支模式](docs/PROTECTED_BRANCHES.md) | [故障排除](docs/TROUBLESHOOTING.md) | [常见问题](docs/FAQ.md) * [](https://deepwiki.com/gastownhall/beads)

标签：AI代理, Dolt, EVTX分析, GNU通用公共许可证, Go语言, Markdown替代, MCP, Node.js, Python, SOC Prime, SQL数据库, 上下文窗口优化, 上下文管理, 人工智能, 任务跟踪器, 依赖追踪, 分布式图, 多代理系统, 多平台, 多线程, 安全可观测性, 开发工具, 无后门, 日志审计, 暗色界面, 正则匹配, 消息传递, 版本控制, 用户模式Hook绕过, 程序破解, 编码助手, 自动化编程, 记忆增强, 语义压缩, 零冲突