Beads 项目 npm 包发布指南beads/bd 的发布全流程与源码级解析【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本文以仓库内 npm-package/PUBLISHING.md 为主干系统讲解 Beads 项目如何将beads/bd这个包装原生二进制的 npm 包发布到 npm Registry从账号与组织准备、登录鉴权、版本对齐、本地测试到首次与增量发布、常见错误排障以及未来的 GitHub Actions 自动化方案。文中同时结合 npm-package/package.json、npm-package/scripts/postinstall.js 与 npm-package/TESTING.md 等源码解释发布一个能自动下载原生二进制的 npm 包背后完整的技术链路。读完本文你将掌握beads/bd的完整发布操作清单、版本同步规则与排障方法并能独立维护该包的后续版本迭代。一、理解要发布的对象beads/bd 是一个二进制包装包beads/bd并不是一个纯 JavaScript 实现而是一个CLI 包装包它本身只有约几十 KB 的胶水代码CLI 包装器 postinstall 下载脚本真正干活的是从 GitHub Releases 下载的 bd 原生二进制。因此发布这个包与发布普通 npm 包有一个关键差异——发布的版本必须与上游二进制发布版本严格一致否则用户安装后会因为二进制下载失败而无法使用。从 npm-package/package.json 可以看到包的核心元数据{ name: beads/bd, version: 1.2.2, description: Beads issue tracker - lightweight memory system for coding agents with native binary support, main: bin/bd.js, bin: { bd: bin/bd.js }, scripts: { postinstall: node scripts/postinstall.js, test: node scripts/test.js, test:integration: node test/integration.test.js, test:all: npm test npm run test:integration }, engines: { node: 14.0.0 }, os: [darwin, linux, win32, android], cpu: [x64, arm64], files: [bin/, scripts/, README.md, LICENSE] }几个直接影响发布流程的字段bin字段将bd命令映射到bin/bd.js这是用户安装后能直接执行bd命令的入口scripts.postinstallnpm install完成后自动执行的二进制下载钩子是整个包能否正常工作的关键engines/os/cpu声明了包支持的 Node 版本与平台架构npm 在安装时会据此给出兼容性提示files字段限定发布到 npm 的文件白名单bin/、scripts/、README.md、LICENSE避免把无关文件打包进 tarball。发布前建议对照 npm-package/LAUNCH.md 中记录的历史发布清单包结构、postinstall 脚本、本地测试、文档逐项确认再进入下面的正式流程。二、前置条件账号、组织与发布权限根据原文档发布beads/bd需要满足两个前置条件npm 账号在 npmjs.com 注册一个账号支持 2FA 时建议开启后续登录与发布均需 OTP 验证beads组织包名带有 scopebeads因此必须存在beads这个 npm organization且当前账号是组织成员并拥有publish 权限。两种途径满足该条件若组织尚不存在创建它若已存在请组织所有者将你的账号添加为成员并授予发布权限。需要特别说明的是beadsscope 下的包默认是私有发布的首次发布必须显式指定--access public否则发布命令会因私有权限约束而失败详见下文首次发布。三、发布前的环境准备登录、鉴权与组织创建1. 登录 npmnpm login执行后 npm 会依次提示输入Username用户名Password密码Email邮箱OTP若账号启用了 2FA会要求输入一次性验证码2. 验证鉴权状态npm whoami该命令应输出你的 npm 用户名。若输出为空或报错说明尚未登录成功需要回到上一步重新登录。这一步是发布前最便宜的一次体检强烈建议每次发布前都执行。3. 创建组织仅在需要时如果beads组织尚不存在可通过命令行创建npm org create beads也可以在 npm 网站的组织创建页面手动操作https://www.npmjs.com/org/create。创建完成后用npm org ls beads可以查看组织成员及各自角色member/owner确认自己的账号具备发布权限。四、正式发布流程步骤 1同步版本号关键步骤package.json中的version必须与 Beads 的发布版本一致。以 npm-package/package.json 当前记录为例版本为1.2.2则期望 GitHub Releases 上存在v1.2.2标签及其对应平台的二进制资产。修改版本号有两种方式# 方式一npm version 自动递增并打 tag npm version patch # 或 minor、major # 方式二手动编辑 package.json 中的 version 字段为什么版本号如此重要因为 npm-package/scripts/postinstall.js 中下载二进制时直接读取package.json的version字段来拼接下载 URL// 从 package.json 读取版本决定下载哪个 release const packageJson require(../package.json); const VERSION packageJson.version; ... const archiveName beads_${releaseVersion}_${platformName}_${archName}.${archiveExt}; const downloadUrl https://github.com/gastownhall/beads/releases/download/v${releaseVersion}/${archiveName};也就是说npm 包版本号、GitHub Release 标签如v1.2.2、二进制版本号三者必须严格同步——只要 npm 版本号与 GitHub Release 不匹配postinstall 就会 404安装直接失败。步骤 2本地测试包发布前必须在本地完整验证包的可用性原文档给出的验证路径是# 从 npm-package 目录执行单元冒烟测试 npm test # 本地链接测试模拟全局安装 npm link # 验证全局安装后的 bd 命令可用 bd version这里的测试体系可以更进一步。除了npm test由 npm-package/scripts/test.js 实现对bd version与bd --help做冒烟验证仓库还提供了完整的集成测试# 端到端集成测试约 30~60 秒需要联网下载二进制 npm run test:integration # 或一次性跑全部测试 npm run test:all集成测试脚本 npm-package/test/integration.test.js 覆盖 5 个测试套件测试套件验证内容Test 1 包安装npm pack打包、在隔离环境全局安装、二进制落盘正确Test 2 二进制功能bd version、bd --help输出符合预期Test 3 基础工作流bd init、bd create、bd list、bd show、bd update、bd close、bd ready全链路Test 4 Claude Code for Web 模拟会话 1 建 issue → 导出 JSONL → 删除数据库 → 会话 2 用--from-jsonl恢复并验证数据不丢失Test 5 平台检测校验当前平台/架构受支持、二进制 URL 构造正确其中 Test 4 模拟的正是Claude Code for Web 每次会话都是全新环境的真实场景先bd init并创建 issue显式执行bd export -o .beads/issues.jsonl生成交接文件删除除 JSONL 外的所有本地数据库状态再以bd init --quiet --from-jsonl重建数据库并断言 issue 全部恢复。这套测试是发布前最有力的安全网。步骤 3发布到 npm首次发布scoped 包默认私有必须显式声明公开npm publish --access public后续发布组织与公开权限已配置好npm publish执行发布前可以先用npm pack --dry-run预览将被打包进 tarball 的文件清单确认files白名单生效、没有误打包大文件或敏感文件。步骤 4验证发布结果发布成功后验证两个层面包页面检查访问https://www.npmjs.com/package/beads/bd确认版本号、描述、README 渲染正常。真实安装验证最重要的一步# 全局安装刚发布的版本 npm install -g beads/bd # 验证命令可用且版本正确 bd version由于 npm 的 CDN 分发存在延迟刚发布后立刻安装偶尔会拿到旧缓存可等待几分钟后重试。五、一次标准发布工作流Checklist综合原文档的发布工作流小节一次完整的版本发布按以下顺序执行等待 GitHub Release确认新版本已作为 Release 发布在 GitHub且包含各平台二进制资产否则 postinstall 下载将 404更新 package.json 版本把npm-package/package.json的version改为与 GitHub Release 完全一致的版本号可用npm version patch|minor|major或手动编辑本地测试运行npm install触发 postinstall 验证二进制下载、npm test条件允许时再跑npm run test:integration确认二进制能正确下载并执行发布首次执行npm publish --access public此后执行npm publish验证npm install -g beads/bd后执行bd version确认装到的是新版本。六、发布自动化未来方案原文档指出发布流程未来可通过 GitHub Actions 在 Release 发布时自动执行。文档中给出的工作流模板如下# .github/workflows/publish-npm.yml name: Publish to npm on: release: types: [published] jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-nodev3 with: node-version: 18 registry-url: https://registry.npmjs.org - run: cd npm-package npm publish --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}实现要点以release: published为触发器与发布工作流第 1 步自然衔接通过registry-urlNODE_AUTH_TOKEN完成 CI 环境下的 npm 鉴权token 需在仓库 Secrets 中配置在 CI 中发布有一个细节值得注意npm-package/scripts/postinstall.js 末尾检测到process.env.CI时会跳过二进制下载Skipping binary download in CI environment因此 CI 中不会重复下载二进制发布动作本身很轻量。不过这也意味着 CI 发布前若想验证二进制下载需要在非 CI 环境下完成。更完整的 CI 测试矩阵可参考 npm-package/TESTING.md 中给出的test-npm-package.yml在 ubuntu / macos / windows 三平台 × Node 18/20 矩阵上分别跑npm test与npm run test:integration发布自动化可以与此测试矩阵组合成完整的发布流水线。七、常见错误排障错误 1EEXIST: package already published尝试发布一个已经存在于 Registry 的版本号。解决方法是递增版本号后重新发布npm version patch npm publish错误 2ENEEDAUTH: need auth当前终端没有有效的 npm 登录态。解决npm login npm whoami # 确认登录成功错误 3E403: forbidden账号没有beads组织的发布权限。三种处置路径创建beads组织若不存在请组织所有者将你的账号加入组织并授予 publish 权限将包名改为你拥有权限的名字会破坏现有用户安装路径一般不建议。错误 4postinstall 阶段二进制下载失败这是beads/bd特有的错误。原因几乎总是package.json的 version 与 GitHub Release 不匹配或该 Release 缺少对应的平台二进制资产。排查方法核对npm-package/package.json的version与 GitHub Release 标签v{VERSION}是否一致核对 Release 中是否包含beads_{VERSION}_{platform}_{arch}.{ext}形式的资产文件检查网络连通性发布前可在本地直接 curl 一下下载 URL 验证可访问性。从 npm-package/scripts/postinstall.js 的源码看该脚本在下载、解压、验证失败时都会给出明确的错误提示并附上三条人工兜底建议从 Releases 手动下载、使用官方安装脚本、提交 issue。另外脚本内部对两类平台差异做了专门处理可作为排查参考Windows 文件锁下载完成后 Windows 可能短暂占用文件句柄脚本会先轮询等待文件可访问waitForFileAccess最长 30 秒解压使用 PowerShellExpand-Archive并对being used by another process、Access is denied、EBUSY等锁错误做指数退避重试最多 5 次Unix 可执行权限解压后对非 Windows 平台执行chmod 0o755确保bd可直接执行。安装链路本身也带有自校验下载解压后会执行bd version验证二进制可用失败则视为安装失败并退出非零码。八、版本同步原则三个版本号必须一致这是维护beads/bd最核心的一条纪律。每次发布都必须保持三处同步同步项示例不一致的后果npm-package/package.json的version1.2.2postinstall 拼接出错误的下载 URL安装失败GitHub Release 标签v1.2.2同上Beads 二进制版本1.2.2安装成功但功能与声明版本不符易造成混淆postinstall 下载 URL 的完整格式为对应源码 npm-package/scripts/postinstall.jshttps://github.com/gastownhall/beads/releases/download/v{VERSION}/beads_{VERSION}_{platform}_{arch}.{ext}其中{platform}取自 darwin / linux / windows / android{arch}为 amd64 / arm64{ext}在 Windows 上为zip、其余平台为tar.gz。九、发布前最终核对清单综合原文档与仓库测试规范npm-package/TESTING.md发布前建议逐项核对npm whoami已返回正确账号且具备beads组织 publish 权限GitHub Releasev{VERSION}已发布且包含各平台二进制资产npm-package/package.json的 version 与 Release 标签完全一致npm test通过版本与帮助命令冒烟npm run test:integration通过安装、工作流、JSONL 会话模拟、平台检测全覆盖npm pack --dry-run确认 tarball 只包含bin/、scripts/、README.md、LICENSE等白名单文件首次发布使用npm publish --access public后续使用npm publish发布后npm install -g beads/bd bd version真实安装验证一次。结语beads/bd的发布本质上是一个版本联动工程npm 包只是薄薄一层包装真正的能力来自原生二进制因此发布动作的核心不是npm publish那一条命令而是npm 版本号 ↔ GitHub Release ↔ 二进制版本的严格对齐以及发布前对 postinstall 下载链路、CLI 包装器、基础工作流的完整回归。本文给出的流程、清单与排障方法配合 npm-package/PUBLISHING.md、npm-package/TESTING.md、npm-package/scripts/postinstall.js 与 npm-package/test/integration.test.js 等文件足以支撑任何维护者独立完成一次可靠的版本发布。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考