For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/zh/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/zh/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/zh/guide/distribution/preview-packages.md.
  • 简体中文
  • 预览包

    目前尚未向 npm 发布任何内容,这是刻意为之。现有的包名只是占位符,npm 发布被推迟到最终包名确定之后。 在那之前,pkg.pr.new 就是发布通道:每次 CI 的 package-preview 运行都会把全部三个可发布的工作区包 以真实、可安装的 tarball 形式发布到一个按 commit SHA 与 pull request 索引的免费持续发布注册表。

    安装命令与 runtime 配对规则在安装中。本页讲的是通道本身:预览包从哪里来、 你能信任它到什么程度,以及固定版本究竟保证了什么。

    预览包从哪里来

    .github/workflows/package-preview.yml 在一次完整构建之后运行 pnpm preview:publish,覆盖每个 pull request 与每次推送到 main。它以 --previewVersion --peerDeps --no-compact --no-template 发布 packages/agent-bundlepackages/rsc-runtimepackages/create-agent-bundle

    针对 main 推送的运行使用逐提交的并发分组,因此相互重叠的推送不会取消彼此,每个 main 提交都有 一份可安装的快照。PR 的运行则会取消同一个 PR 中被取代的构建,因为只有 PR 的最新一次预览才有意义。

    PR 或提交上的「Publish pkg.pr.new preview」检查会链接到该次构建的确切 URL。预览包由发布门禁所校验的 同一份 pnpm build 输出构建而来——但它们不是 npm 正式版本,并且携带预览版本号。

    固定版本,以及一条历史遗留注意事项

    配对规则与安装命令在安装中;有两个细节属于通道本身。

    PR 引用会解析到该 PR 最近一次发布的预览,因此 @1 表示「PR #1 最新一次构建」,而不是某个固定 提交。短 SHA 永远不会移动,这正是 lockfile 应当携带它的原因。

    在 peer 改写落地(PR #46)之前发布的预览包仍携带原始的 agent-bundle@^0.1.0 peer 范围,因此用 npm 配对安装那些较早的 SHA 仍然需要 --legacy-peer-deps。更新的预览包用原生 npm 即可安装。

    脚手架发布在同一条通道上,其设计意图是直接运行而不是安装:

    npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@<sha-or-pr> my-plugin

    脚手架生成的项目会把 agent-bundle 固定到脚手架自身所来自的那个提交的预览版本,因此上述配对规则的 两侧会自动成立。

    首个 npm 版本发布后会发生什么变化

    首个 npm 版本将使用 npm package provenance:发布步骤会导出 NPM_CONFIG_PROVENANCE=true,并在 changeset publish 之前运行打包发布门禁。 publishConfig.provenance 已经设置好了。

    在启用这条路径之前,发布负责人必须解决两件事:最终的包名与许可证,以及 agent-bundle 仓库层面的 "access": "restricted" 策略——目前它并没有被 publishConfig.access 覆盖。

    pnpm release 会在发布之前运行发布门禁 —— pnpm pack:dry-runpnpm audit:releasepnpm test:packed:release。该门禁仅用于发布,并不替代日常的 pnpm check 交付门禁。

    下一步

    • 安装 —— 确切的安装与配对命令。
    • 产物校验 —— 这些预览包所经过的 prepack 清单门禁。