Issue Tracking【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsUse thebdcommand for all issue tracking instead of markdown TODOs:Create issues:bd create Task description -p 1 --jsonFind work:bd ready --jsonStart work:bd update id --claim --jsonView details:bd show id --jsonUse--jsonflags for programmatic parsing.### Agent 推荐工作流You are working on a project that uses bd (beads) for issue tracking.At the start of each session:Runbd ready --jsonto see available workChoose an issue to work onStart work:bd update id --claimWhile working:Create new issues for any bugs you discoverLink related issues withbd dep addAdd comments withbd comments add id comment textWhen done:Close the issue:bd close id --reason Description of what was doneRunbd dolt pushto push issue changes## 工作原理从 npm 安装到原生二进制调用 整个机制的核心是三步流水线全部有源码可查 1. **SessionStart Hook 自动触发**会话开始即运行 .claude/hooks/session-start.sh。 2. **postinstall 下载原生二进制**npm install -g beads/bd 会触发 [npm-package/scripts/postinstall.js](https://link.gitcode.com/i/93cb15319365c5e12b2ac4dae08631da)。该脚本的完整逻辑包括 - **平台/架构映射**把 Node.js 的 os.platform() / os.arch() 映射为发布命名——darwin、linux、android、win32发布名称为 windows且二进制名为 bd.exex64 映射为 amd64arm64 保持不变不支持的平台直接抛错。 - **下载 URL 构造**按 beads_版本_平台_架构.tar.gzWindows 为 .zip格式拼接 GitHub Release 下载地址。 - **下载与解压**处理 301/302 重定向与 HTTP 错误类 Unix 平台用 tar -xzf 解压并 chmod 0o755 赋予执行权限Windows 用 PowerShell Expand-Archive 解压并针对 NTFS 文件锁问题实现了 waitForFileAccess 轮询与指数退避重试extractZip 最多 5 次重试。 - **二进制自检**解压后立即执行 binary version 验证可用性。 - **CI 环境跳过**设置了 CI 环境变量时跳过二进制下载见 postinstall.js 末尾的 if (!process.env.CI) 判断。 3. **CLI 包装器调用原生二进制**bd 命令实际指向 [npm-package/bin/bd.js](https://link.gitcode.com/i/48ae4922981ee915241011872d94ed60)——一个极简的 Node.js 包装器根据平台选择 bd 或 bd.exe用 spawn 以 stdio: inherit 透传所有命令行参数与当前环境变量并把子进程的退出码/信号原样映射回调用方。 最后bd init 负责创建项目的 .beads 目录并导入 git 中的既有 issue。 ## 会话间数据延续JSONL 导出/导入 Claude Code for Web 的沙箱不持久化安装但项目的 git 仓库是持久化的。集成测试 [npm-package/test/integration.test.js](https://link.gitcode.com/i/a3185ffd3dc0238afe01abc6b7685282) 中的 Claude Code for Web Simulation 用例完整演示了数据如何在会话间延续 - 会话 1bd init → bd create → bd export -o .beads/issues.jsonl 导出为 JSONL - 模拟新会话只保留 git 提交的 JSONL、丢弃被 gitignore 的本地数据库删除 .beads 下除 issues.jsonl 外的所有条目 - 会话 2bd init --quiet --from-jsonl 从 JSONL 重新导入bd list --json 能查到会话 1 创建的 issue随后 bd create 产生的新 issue 也能再次 bd export 写入 JSONL 这意味着在每个会话结束时执行 bd export或依赖自动导出策略并把 .beads/issues.jsonl 提交进 git即可实现跨会话的记忆延续。 ## 性能预期 - **首次安装**约 5–10 秒每个会话只需一次 - **二进制下载**约 3–5 秒darwin-arm64 二进制约 17MB - **后续命令执行**原生速度100ms ## 排障手册 ### bd: command not found SessionStart 钩子未运行或安装失败手动执行一次 bash npm install -g beads/bdnpm postinstall 因 DNS 或 403 失败部分 Claude Code for Web 环境有网络限制阻止 postinstall 脚本下载二进制报错形如Error installing bd: getaddrinfo EAI_AGAIN github.com或curl: (22) The requested URL returned error: 403解决使用受支持的 go install 回退模式Web 环境通常装有 Go可用内嵌支持的go install回退# Install via Go without ICU CGO_ENABLED1 GOFLAGS-tagsgms_pure_go go install github.com/steveyegge/beads/cmd/bdlatest # Add to PATH (required each session) export PATH$PATH:$HOME/go/bin # Verify installation bd version这里用到的gms_pure_go构建标签与仓库构建约定一致仓库的 AGENT_INSTRUCTIONS.md 明确要求使用gms_pure_go构建标签如make install、./bd、go run -tags gms_pure_go ./cmd/bd该标签会去掉 ICU 链接使二进制更适合无 CGO 依赖的纯 Go 运行环境。带 go install 回退的 SessionStart Hook#!/bin/bash # .claude/hooks/session-start.sh echo Setting up bd (beads issue tracker)... # Try npm first, fall back to a supported Go install if ! command -v bd /dev/null; then if npm install -g beads/bd --quiet 2/dev/null command -v bd /dev/null; then echo ✓ Installed via npm elif command -v go /dev/null; then echo npm install failed, trying go install... CGO_ENABLED1 GOFLAGS-tagsgms_pure_go go install github.com/steveyegge/beads/cmd/bdlatest export PATH$PATH:$HOME/go/bin echo ✓ Installed via go install else echo ✗ Installation failed - neither npm nor go available exit 1 fi fi # Verify and show version bd versionError installing bd: HTTP 404package.json 中的版本与 GitHub Release 不匹配已发布的 npm 包通常不会出现。可检查可用版本并指定安装npm view beads/bd versionsnpm install -g beads/bd0.21.5注意当前仓库 npm 包版本为1.2.2请以实际发布的版本号为准。Binary not found after extraction平台检测可能失败。检查node -e console.log(require(os).platform(), require(os).arch())正常输出类似linux x64。也可对照 npm-package/scripts/postinstall.js 中的平台映射表确认组合是否受支持例如android在集成测试中仅声明了arm64架构见 npm-package/test/integration.test.js 的supportedPlatforms。安装缓慢二进制约 17MB多数网络下几秒即可完成。若持续缓慢可考虑切换 npm registry 镜像缓存安装如果 Claude Code for Web 支持为什么用原生二进制而不是 WASM该 npm 包包装的是原生bd 二进制而非 WebAssembly原因在于✅完整的 SQLite 支持无需自定义 VFS 或兼容层✅全部功能可用与独立版 bd 100% 功能对齐✅更好的性能原生速度无 WASM 运行时开销✅更简单的维护单一二进制构建无 WASM 专属代码✅更快的安装一次二进制下载而非 WASM 编译完整示例带错误处理的 SessionStart Hook#!/bin/bash # .claude/hooks/session-start.sh set -e # Exit on error echo Setting up bd (beads issue tracker)... # Install bd globally if ! command -v bd /dev/null; then echo Installing beads/bd from npm... npm install -g beads/bd --quiet else echo bd already installed fi # Verify installation if bd version /dev/null; then echo ✓ bd $(bd version) else echo ✗ bd installation failed exit 1 fi # Initialize if needed if [ ! -d .beads ]; then echo Initializing bd in project... bd init --quiet else echo bd already initialized fi # Show ready work echo echo Ready work: bd ready --limit 5 echo echo ✓ bd is ready! Use bd --help for commands.替代方案作为项目依赖纳入版本控制如果希望把 bd 作为项目依赖跟踪而非全局安装可在package.json中声明{ devDependencies: { beads/bd: ^0.21.5 }, scripts: { bd: bd, ready: bd ready, postinstall: bd init --quiet || true } }然后通过 npm scripts 或 npx 使用npm run ready npx bd create New issue【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
