Beads 全平台安装指南bd CLI、Claude Code 插件与 MCP 服务器的完整安装与配置【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads命令行为bd是一个为编码 Agent 提供「记忆升级」的轻量级问题追踪系统。本篇技术指南以仓库中的 docs/getting-started/installation.md 为主体系统讲解其组件构成、macOS / Linux / Windows / FreeBSD 各平台的安装方式Homebrew、npm、go install、安装脚本、IDE 与编码 Agent 的集成配置以及安装后的验证、升级与卸载流程。读完本文你将能够在任意目标平台上正确选型并安装bd并为 Claude Code、Cursor、GitHub Copilot 等工具完成开箱即用的集成。组件概览bd CLI、Claude Code 插件与 MCP 服务器Beads 由多个组件组成理解它们的定位是正确安装的第一步。组件是什么何时需要bd CLI核心命令行工具始终需要——这是一切的基础Claude Code 插件Slash 命令 增强的 UX可选——需要/beads:ready、/beads:create等命令时MCP 服务器beads-mcpModel Context Protocol 接口仅用于纯 MCP 环境Claude Desktop、Amp 等无 Shell 环境三者的关系bd CLI 是核心应首先通过 Homebrew、npm 或脚本安装插件为 Claude Code 增加 Slash 命令但依赖CLI 已安装MCP 服务器是 CLI 在无 Shell 访问环境中的替代方案。重要概念Beads 是系统级安装的而不是克隆进你的项目。项目中的.beads/目录只存放问题数据库issue database不含任何可执行文件。典型环境安装组合环境需要安装的内容Claude Code、Cursor、Windsurfbd CLI 可选的 Claude Code 插件GitHub CopilotVS Codebd CLI MCP 服务器Claude Desktop无 Shell仅 MCP 服务器终端 / 脚本仅 bd CLICI/CD 流水线仅 bd CLI三者互斥吗不。CLI 插件 MCP 可以同时安装互不冲突但绝大多数用户只需要 CLI 一个组件。快速安装推荐方式HomebrewmacOS / Linuxbrew install beadsHomebrew core 中的beadsformula 是官方支持的 Homebrew 包。如果你之前通过旧的 tap formula 以bd名义安装过请参考 docs/getting-started/upgrading.md#homebrew 中的迁移说明切换到 core formula。为什么选择 Homebrew一条命令完成安装通过brew upgrade自动更新无需安装 Go 工具链自动处理 PATH 配置。Mise-en-placemacOS / Linux / Windows可以通过 mise 从最新 GitHub Release 安装 beadsmise install github:gastownhall/beads mise use -g github:gastownhall/beads-g标志将 beads 全局启用如需为特定项目启用不同版本省略该标志即可。为什么选择 Mise与 Homebrew 一样简单mise up更新、无需 Go、自动处理 PATH支持所有平台始终获取最新 Release可以为特定项目选择不同的 Release 版本。需要注意的是Mise 的 Go 后端与go install存在同样的限制默认应优先使用其 Release 后端。快速安装脚本macOS / Linux / FreeBSDcurl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash安装脚本位于仓库根目录 scripts/install.sh安装时会自动检测平台macOS / Linux / FreeBSDamd64 / arm64 / arm对照 Release 的checksums.txt校验下载的归档文件若本机有 Go回退到受支持的go install模式必要时回退到从源码构建如有需要指导你完成 PATH 配置。从源码看脚本的安装优先级是「Release 预编译归档 → go install → 从源码构建」三级回退scripts/install.sh 中的main()函数先尝试install_from_release失败后若检测到 Go 1.24 则尝试install_with_go最后才build_from_source。校验环节由verify_release_checksum完成——它会在 Release 元数据缺少checksums.txt时直接拒绝安装未经验证的二进制refusing to install unverified binary并从sha256sum/shasum/openssl中自动选择可用的 SHA-256 工具。macOS 签名说明在 macOS 上脚本默认保留下载二进制的 Release 签名Gatekeeper 行为。只有当你明确需要本地临时重签名时才需要显式开启BEADS_INSTALL_RESIGN_MACOS1 curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash安装方式对比方式最适合更新方式前置条件备注HomebrewmacOS/Linux 用户brew upgrade beadsHomebrew推荐。自动处理一切Mise所有平台mise upmise安装最新 GitHub ReleasenpmJS/Node.js 项目npm update -g beads/bdNode.js如果你身处 npm 生态则很方便bunJS/Bun.js 项目bun install -g --trust beads/bdBun.js如果你身处 bun 生态则很方便安装脚本快速安装、CI/CD重新执行脚本curl、bash适合自动化与一行式安装go installnocgoGo 开发者最简安装重新执行命令Go 1.24仅服务器模式无内嵌 Doltgo installcgo想要内嵌模式的 Go 开发者重新执行命令Go 1.24、C 编译器完整的内嵌 Dolt 支持源码构建仅贡献者git pull go buildGo、git完全可控可修改代码AURArchArch Linux 用户yay -Syuyay/paru社区维护TL;DR有 Homebrew 就用 Homebrew身处 Node.js 环境就用 npm一次性安装或 CI 场景用安装脚本。go install 与构建依赖如果你没有特别需求优先使用 Homebrew、npm 或安装脚本而不是go install。go install有两种受支持的构建模式对应不同能力仅服务器模式nocgo最简单CGO_ENABLED0 go install github.com/steveyegge/beads/cmd/bdlatest任何装有 Go 工具链的机器都能构建无需 C 编译器。产出的是仅服务器模式的二进制——必须运行外部dolt sql-server并使用bd init --server初始化。服务器模式的具体搭建参见 docs/architecture/dolt.md。内嵌能力cgoCGO_ENABLED1 GOFLAGS-tagsgms_pure_go go install github.com/steveyegge/beads/cmd/bdlatest需要 C 编译器Unix 下为 gcc/clangWindows 下为 MinGW。产出的是带默认内嵌 Dolt 后端的二进制——bd init开箱即用。关于 ICU两种模式都不需要ICU 头文件。内嵌能力的命令使用gms_pure_go标签让 go-mysql-server 使用 Go 标准库的regexp而非 ICU 正则。这一点在 engdocs/ICU-POLICY.md 中有完整说明仓库的 Makefile 也通过BUILD_TAGS : gms_pure_go全程携带该标签并在doctor-build目标中给出了诊断裸执行CGO_ENABLED1 go build ./cmd/bd不带-tagsgms_pure_go会因为 go-icu-regex 找不到unicode/uregex.h而链接失败。关于模块路径go install请使用github.com/steveyegge/beads路径。尽管仓库现已迁移到gastownhall/beads已发布的 Go 模块仍声明github.com/steveyegge/beads以保证兼容——这一点在 go.mod 第 1 行module github.com/steveyegge/beads与安装脚本 scripts/install.sh 的注释中均有印证。如果没有特殊偏好brew install beads或安装脚本即可得到开箱即用的内嵌能力构建。构建依赖仅贡献者需要注意这些依赖仅在从源码构建时需要。通过 Homebrew、npm 或安装脚本安装的用户可以完全跳过本节。从源码构建需要一个 C 编译器用于 CGO / 内嵌 Dolt。ICU不是必需的——所有构建都使用gms_pure_go标签选择 Go 标准库regexp而非 ICU 正则详见 engdocs/ICU-POLICY.md。macOSHomebrewbrew install zstdLinuxDebian/Ubuntusudo apt-get install -y libzstd-devLinuxFedora/RHELsudo dnf install -y libzstd-devel仅维护者需要如果确实需要运行 scripts/test-icu-path.sh该脚本演练遗留的 ICU 代码路径才需要安装 ICU 头文件macOS 用brew install icu4cLinux 用sudo apt-get install -y libicu-dev。正常开发不需要。平台特定安装macOS通过 Homebrew推荐brew install beads通过 go install仅服务器模式CGO_ENABLED0 go install github.com/steveyegge/beads/cmd/bdlatest通过 go install内嵌能力需要 Xcode CLI 工具CGO_ENABLED1 GOFLAGS-tagsgms_pure_go go install github.com/steveyegge/beads/cmd/bdlatest从源码构建git clone https://github.com/gastownhall/beads cd beads make build sudo mv bd /usr/local/bin/Linux通过 HomebrewLinux 同样适用brew install beadsArch LinuxAUR# 从 AUR 安装 yay -S beads-git # 或 paru -S beads-gitAUR 包由社区维护。通过 go install仅服务器模式CGO_ENABLED0 go install github.com/steveyegge/beads/cmd/bdlatest通过 go install内嵌能力需要 gccCGO_ENABLED1 GOFLAGS-tagsgms_pure_go go install github.com/steveyegge/beads/cmd/bdlatestFreeBSD通过快速安装脚本curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash通过 go install仅服务器模式CGO_ENABLED0 go install github.com/steveyegge/beads/cmd/bdlatestWindows 11Beads 提供原生 Windows 支持——无需 MSYS 或 MinGW即可完成基础安装。前置条件Go 1.24 已安装将%USERPROFILE%\go\bin加入PATHGit for Windows。通过 PowerShell 脚本安装irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex该脚本位于仓库根目录 install.ps1会优先安装预构建的 Windows Release若存在并对照 Release 的checksums.txt校验下载的 ZIP 校验和。从脚本源码看install.ps1 中的Get-ExpectedReleaseChecksum校验环节在 Release 缺少checksums.txt时会直接拒绝安装refusing unverified install并通过Get-FileHash -Algorithm SHA256与期望值比对不一致则中止。Go 仅在go install或源码构建时才需要。通过 go install仅服务器模式$env:CGO_ENABLED0; go install github.com/steveyegge/beads/cmd/bdlatest这会产出仅服务器模式的二进制无 C 编译器要求——这是在 Windows 上获得可用bd的最快路径。通过 go install内嵌能力需要 Windows CGO 工具链$env:CGO_ENABLED1; $env:GOFLAGS-tagsgms_pure_go; go install github.com/steveyegge/beads/cmd/bdlatest需要在 PATH 上提供 GCC 兼容的 Windows CGO 编译器例如 MinGW-w64/MSYS2 的gcc或 MSYS2 LLVM 中面向windows-gnu的clangclang64/clangarm64。ICU不是必需的——gms_pure_go会选择 Go 标准库regexp。Visual Studio 的cl.exe单独是不够的因为 Go 传递的是 GCC 风格的 CGO 标志请使用 MinGW/MSYS2 工具链或设置CC或在源码构建时设置WINDOWS_CGO_BINS。Makefile 的build目标同样印证了这一约束Windows 构建会依次探测CC、gcc、clang及WINDOWS_CGO_BINS列表中各工具链的 gcc/clang找不到则报错退出。从源码构建git clone https://github.com/gastownhall/beads cd beads make build Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\Windows 注意事项Dolt 服务器监听 loopback TCP 端点需要允许bd.exe的 loopback 流量通过主机防火墙通过 npm 安装时bd是一个bd.cmdshim——Node 的execFile/spawn需要shell: true才能运行它详见 docs/reference/troubleshooting.md#platform-specific-issues。另外仓库根目录的 install.ps1 还支持两个环境变量BEADS_INSTALL_SKIP_GOINSTALL1跳过 go install 步骤BEADS_INSTALL_SOURCEpath|url覆盖源码来源本地目录或 git 仓库地址。IDE 与编辑器集成CLI Hooks推荐方案这是 Claude Code、Cursor、Windsurf 及其他有 Shell 访问能力编辑器的最佳实践# 1. 安装 bd CLI见上文快速安装 brew install beads # 2. 在项目中初始化 cd your-project bd init --quiet # 3. 设置编辑器集成任选其一 bd setup claude # Claude Code - 安装 SessionStart hooks bd setup copilot # GitHub Copilot CLI - 创建 .copilot-plugin/plugin.json .github/copilot-instructions.md bd setup cursor # Cursor IDE - 创建 .cursor/rules/beads.mdc bd setup aider # Aider - 创建 .aider.conf.yml bd setup codex # Codex CLI - 安装 Beads skill、AGENTS.md 指引与原生 hooks bd setup factory # Factory.ai Droid - 创建/更新 AGENTS.md bd setup mux # Mux - 创建/更新 AGENTS.md工作原理bd init默认会创建或更新AGENTS.md并安装项目的 Claude/Codex 集成除非使用--skip-agents或--stealth编辑器 hooks/rules 会在会话启动时自动注入bd primeCodex 0.129.0 使用原生/hooksSessionStart 注入bd primecompact hooks 将上下文标记为过期压缩后的下一次提示会刷新一次 Beads 上下文bd prime提供约 1-2k token 的工作流上下文你直接使用bdCLI 命令Git hooks由bd init安装负责刷新导出与遗留回退bd dolt push/pull负责数据库同步bd onboard为不支持的 Agent 或自定义指令文件打印一段小型手动配置片段。为什么推荐这种方式上下文高效——约 1-2k token对比 MCP 工具 schema 的 10-50k token更低延迟——直接调用 CLI无 MCP 协议开销通用——适用于任何有 Shell 访问能力的编辑器。验证安装每个 recipe 都支持检查标志例如bd setup claude --check或bd setup copilot --check。关于bd setup的 recipe 架构、--check/--remove/--global等标志以及full/minimal模板配置文件的详细说明参见 docs/getting-started/ide-setup.md。Claude Code 插件可选需要 Slash 命令增强 UX 时# 在 Claude Code 中 /plugin marketplace add gastownhall/beads /plugin install beads # 重启 Claude Code插件提供Slash 命令/beads:ready、/beads:create、/beads:show、/beads:update、/beads:close等用于自主执行的任务 Agent。完整插件文档参见 docs/integrations/claude-code-plugin.md。GitHub CopilotVS Code 中的 GitHub Copilot安装 MCP 服务器uv tool install beads-mcp并在项目中创建.vscode/mcp.json——或将其加入 VS Code 用户级 MCP 配置以对全部项目生效。完整设置指南含各平台用户级配置路径参见 docs/integrations/github-copilot.md。GitHub Copilot CLI 终端集成bd setup copilot # 安装项目 Copilot 插件 仓库指令 bd setup copilot --check # 验证项目集成文件是否存在该配置当前仅限项目级。它写入.copilot-plugin/plugin.json和.github/copilot-instructions.md目前 Copilot 没有单独的--global或--project模式也不会管理~/.copilot/...路径。完整指南参见 docs/integrations/copilot-cli.md。MCP 服务器替代方案仅在 CLI 不可用时Claude Desktop、无 Shell 的 Sourcegraph Amp使用 MCP# 使用 uv推荐 uv tool install beads-mcp # 或使用 pip pip install beads-mcpbeads-mcp的 Python 包源码位于仓库 integrations/beads-mcp 目录。Claude Desktop 配置macOS在~/Library/Application Support/Claude/claude_desktop_config.json中添加{ mcpServers: { beads: { command: beads-mcp } } }Sourcegraph Amp 配置及 MCP 服务器的详细文档参见 docs/integrations/mcp-server.md。验证安装安装完成后验证bd是否工作bd version bd help故障排查更多排查内容参见 docs/reference/troubleshooting.md。bd: command not found说明bd不在 PATH 中# 检查是否已安装 go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd # 将 Go bin 加入 PATH添加到 ~/.bashrc 或 ~/.zshrc export PATH$PATH:$(go env GOPATH)/bin # 或使用推荐的安装器重新安装 curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash安装脚本自身也内置了 PATH 防护若安装目录不在 PATH 中会打印提示$install_dir is not in your PATH并检测 PATH 上是否存在多个bd可执行文件warn_if_multiple_bd以避免旧版本遮蔽新版本——详见 scripts/install.sh 中的warn_if_multiple_bd实现。zsh: killed bd或 macOS 上崩溃这通常由 CGO/SQLite 兼容性问题引起# 安装内嵌能力构建 CGO_ENABLED1 GOFLAGS-tagsgms_pure_go go install github.com/steveyegge/beads/cmd/bdlatest如果通过 Homebrew 安装通常无需如此——formula 已启用 CGO。若 Homebrew 版本仍然崩溃请提交 issue。MCP 服务器启动失败独立 beads-mcpClaude Code 插件本身并不捆绑 MCP 服务器。如果你配置了独立的beads-mcp服务器见 docs/integrations/mcp-server.md但它立即失败很可能是uv未安装或不在 PATH 中。症状插件 Slash 命令正常但 MCP 工具不可用错误日志显示command not found: uv服务器启动时静默失败。解决方案# 安装 uv curl -LsSf https://astral.sh/uv/install.sh | sh # 重启 Shell 或更新 PATH source ~/.local/bin/env # 验证 uv 可用 which uv # 重启 Claude Code替代安装方法参见 docs/integrations/claude-code-plugin.md。更新 bd升级检查清单用当前bd先同步远程后端数据库再安装新二进制bd dolt pushbd dolt pull迁移前备份bd export --all -o .beads/backup/pre-migrate-$(date %Y%m%d).jsonl按下表对应你安装方式的命令升级。升级后bd info --whats-newbd hooks installbd version如果跨过远程后端数据库的 schema 迁移只有指定迁移者执行bd migratebd dolt push其他克隆应安装新二进制后运行bd bootstrap而不是独立迁移。完整流程参见 docs/getting-started/upgrading.md。快速安装脚本macOS / Linux / FreeBSDcurl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bashPowerShell 安装器Windowsirm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iexHomebrewbrew upgrade beadsnpmnpm update -g beads/bdnpm 包定义位于仓库 npm-package/package.json包名为beads/bd通过postinstall脚本在安装时拉取对应平台的原生二进制。bunbun install -g --trust beads/bdgo install使用你最初安装时的对应模式# 仅服务器模式 CGO_ENABLED0 go install github.com/steveyegge/beads/cmd/bdlatest # 内嵌能力 CGO_ENABLED1 GOFLAGS-tagsgms_pure_go go install github.com/steveyegge/beads/cmd/bdlatest从源码cd beads git pull make build sudo mv bd /usr/local/bin/预发布版本如 release candidate只作为 GitHub prerelease 发布不会推送到稳定的 Homebrew/npm/PyPI 渠道因此brew upgrade等不会升级到它们——需要显式获取预发布构建。升级后的步骤hooks、迁移参见 docs/getting-started/upgrading.md。卸载完整地从仓库移除 Beads 的步骤参见 docs/recovery/uninstalling.md。下一步安装完成后初始化项目cd your-project bd init学习基础用法参见 docs/getting-started/quickstart.md配置你的 Agent参见 docs/getting-started/ide-setup.md或运行bd setup --list浏览示例仓库 examples 目录提供了 bash-agent、python-agent、formulas、多阶段开发、团队工作流等丰富用例关于 Dolt 后端的两种运行模式内嵌模式 vs 服务器模式及其迁移、备份、远程同步的完整说明可进一步阅读 docs/architecture/dolt.md。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考