Beads 项目 npm 包发布指南：@beads/bd 的发布全流程与源码级解析

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.postinstall：npm install完成后自动执行的二进制下载钩子，是整个包能否正常工作的关键；
• engines/os/cpu：声明了包支持的 Node 版本与平台架构，npm 在安装时会据此给出兼容性提示；
• files字段：限定发布到 npm 的文件白名单（bin/、scripts/、README.md、LICENSE），避免把无关文件打包进 tarball。

发布前建议对照 npm-package/LAUNCH.md 中记录的历史发布清单（包结构、postinstall 脚本、本地测试、文档）逐项确认，再进入下面的正式流程。

二、前置条件：账号、组织与发布权限

根据原文档，发布@beads/bd需要满足两个前置条件：

1. npm 账号：在 npmjs.com 注册一个账号（支持 2FA 时建议开启，后续登录与发布均需 OTP 验证）；
2. @beads组织：包名带有 scope（@beads），因此必须存在@beads这个 npm organization，且当前账号是组织成员并拥有publish 权限。两种途径满足该条件：
   • 若组织尚不存在，创建它；
   • 若已存在，请组织所有者将你的账号添加为成员并授予发布权限。

需要特别说明的是，@beadsscope 下的包默认是私有发布的，首次发布必须显式指定--access public，否则发布命令会因私有权限约束而失败（详见下文"首次发布"）。

三、发布前的环境准备：登录、鉴权与组织创建

1. 登录 npm

npm 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 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）

综合原文档的"发布工作流"小节，一次完整的版本发布按以下顺序执行：

1. 等待 GitHub Release：确认新版本已作为 Release 发布在 GitHub，且包含各平台二进制资产（否则 postinstall 下载将 404）；
2. 更新 package.json 版本：把npm-package/package.json的version改为与 GitHub Release 完全一致的版本号（可用npm version patch|minor|major或手动编辑）；
3. 本地测试：运行npm install（触发 postinstall 验证二进制下载）、npm test，条件允许时再跑npm run test:integration，确认二进制能正确下载并执行；
4. 发布：首次执行npm publish --access public，此后执行npm publish；
5. 验证：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/checkout@v3 - uses: actions/setup-node@v3 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-url+NODE_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），发布自动化可以与此测试矩阵组合成完整的发布流水线。

七、常见错误排障

错误 1：EEXIST: package already published

尝试发布一个已经存在于 Registry 的版本号。解决方法是递增版本号后重新发布：

npm version patch npm publish

错误 2：ENEEDAUTH: need auth

当前终端没有有效的 npm 登录态。解决：

npm login npm whoami # 确认登录成功

错误 3：E403: forbidden

账号没有@beads组织的发布权限。三种处置路径：

• 创建@beads组织（若不存在）；
• 请组织所有者将你的账号加入组织并授予 publish 权限；
• 将包名改为你拥有权限的名字（会破坏现有用户安装路径，一般不建议）。

错误 4：postinstall 阶段二进制下载失败

这是@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最核心的一条纪律。每次发布都必须保持三处同步：

postinstall 下载 URL 的完整格式为（对应源码 npm-package/scripts/postinstall.js）：

https://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），发布前建议逐项核对：

1. npm whoami已返回正确账号，且具备@beads组织 publish 权限；
2. GitHub Releasev{VERSION}已发布且包含各平台二进制资产；
3. npm-package/package.json的 version 与 Release 标签完全一致；
4. npm test通过（版本与帮助命令冒烟）；
5. npm run test:integration通过（安装、工作流、JSONL 会话模拟、平台检测全覆盖）；
6. npm pack --dry-run确认 tarball 只包含bin/、scripts/、README.md、LICENSE等白名单文件；
7. 首次发布使用npm publish --access public，后续使用npm publish；
8. 发布后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