安装

环境要求

Node.js 22.19 或更高版本，用于运行编译器与开发者 Workbench。
一个包管理器 —— npm、pnpm、yarn 与 bun 都可以；下面的示例使用 npm。

生成的可执行文件默认以 Node.js 22.12 及以上为目标。runtime: { node: '24.0' } 可以抬高这个下限（永远无法降低），所选下限会以 runtime.node 记录在产物清单中。

从预览通道安装

目前尚未向 npm 发布任何内容。这是刻意为之：现有的包名只是占位符，而 npm 上的 agent-bundle 这个名字当前属于一个无关项目。在首个正式版本发布之前，请安装 CI 为每个提交和每个 pull request 发布的预览包：

npm i -D https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@<sha-or-pr>

使用 PR 编号，或使用某个 package-preview 运行成功的提交 SHA —— 每个绿色的 main 提交都有一个。短 SHA 同样可用；对于 lockfile 与可复现的环境，SHA 是正确的形式，而 PR 编号则会跟踪该 pull request 的最新一次构建。

从同一个提交配对安装 runtime 包

带有路由模块的项目还需要 @agent-bundle/runtime，它发布在同一个通道：

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/agent-bundle@5685521
npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@5685521

两者必须来自同一个 SHA 或 PR 编号。agent-bundle 把 @agent-bundle/runtime 声明为可选 peer 依赖（runtime 包本身不声明 agent-bundle peer），发布过程（--peerDeps）会把 agent-bundle 预览包内部的这个 peer 范围改写为同一提交构建出的 runtime 精确预览版本，因此配对安装用原生 npm 即可完成。混用两个不同的 SHA 会按设计以 ERESOLVE 失败——需要检查的范围位于已安装的 agent-bundle 包中。

pnpm 与 yarn 接受同样的 URL（pnpm add <url>、yarn add agent-bundle@<url>）。

预览版本号形如 0.0.0-preview-<sha>。它们由发布门禁校验的同一份产物构建而来，但并不是 npm 正式版本。关于固定版本的细节以及预览包的来源，见 Preview packages。

可选依赖

只有在项目用到对应表面时才需要安装：

包	用于
`@agent-bundle/runtime`	路由模块、渲染式 Skill，以及渲染式 CLI 命令或脚本。生成的入口与你的代码以同样的方式导入它。
`@rstest/core`	运行框架测试 harness。它是可选 peer 依赖，因此从不测试路由的项目也不会安装它。
`react`	渲染路由模块并对其断言。同样是可选 peer 依赖。
`typescript`	`lib.dts` 声明生成，它会从项目中解析 `typescript`。

等到 npm 正式发布之后

下面这些命令是未来的安装路径。它们现在还不可用，因为尚未发布任何 npm 版本：

npm install --save-dev agent-bundle
npm create agent-bundle@latest my-plugin

首个 npm 版本将使用 npm package provenance。在发布负责人确定最终包名与许可证之前，pkg.pr.new 预览就是发布通道。

验证安装

npx agent-bundle --help
npx agent-bundle validate --root .

validate 检查项目源码。构建出产物之后，改用 validate --artifact <dir> 检查已构建的产物，此时完全不需要项目源码。

下一步：快速开始。

#安装

#环境要求

#从预览通道安装

#从同一个提交配对安装 runtime 包

#可选依赖

#等到 npm 正式发布之后