安装

环境要求

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

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

从预览通道安装

包通过 pkg.pr.new 分发，而不是 npm 注册表。请安装 CI 为每个 pull request 以及 main 最新提交发布的预览包：

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 包中。

预览脚手架从共享 commit SHA 推导 compiler/runtime 配对。因此，对需要 runtime 的模板显式传入 --framework-version 时，必须使用精确的 pkg.pr.new compiler URL，或使用相邻的本地 agent-bundle.tgz 与 agent-bundle-runtime.tgz。

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`。

agent-bundle 与 @agent-bundle/runtime 接受相同的 React ^19.2.0 版本范围。runtime 对 React 和 React DOM 声明同一个范围，因此全新的 npm 安装可以选择一组匹配版本，无需预先安装 React，也无需绕过 peer 检查。路由式脚手架仍会有意固定一组已验证的 React/React DOM 版本：生成的项目由此保持可复现，提交后的 lockfile 会继续保留这组版本。

出于同样的原因，@agent-bundle/runtime 将 zod 声明为 ^4.6.4 peer 依赖而非普通依赖：路由和状态定义会把 Zod schema 传过 runtime 的 API，而 Zod 4 会按 minor 版本给 schema 类型打标记。因此嵌套的 zod@4.5.x 无法接受来自 zod@4.6.x 的消费方 schema（Type '6' is not assignable to type '5'）。同一 minor 的两份安装仍能通过类型检查；peer 的作用是让项目与 runtime 解析到同一份副本，并停留在兼容的 minor 上。仍将直接依赖固定在 zod@4.5.x、或任何低于 4.6.4 的版本的现有项目，必须先升级该依赖再安装此 runtime，否则 npm 会以 ERESOLVE 拒绝所需的 peer。

固定 Version Packages commit

合并 Version Packages 会提升仓库内版本，并通过 pkg.pr.new 发布结果 commit。消费者仍然固定 merge SHA：

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

@agent-bundle/runtime 使用相同的 SHA。预览 scaffolder 会自动推导同 SHA 的 compiler 与 runtime 配对。不需要 npm 注册表凭据。

验证安装

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

validate 检查项目源码。构建出产物之后，改用 validate --artifact artifact 检查已构建的插件根目录，也就是所有所选宿主安装的那一个目录，此时完全不需要项目源码。

下一步：快速开始。

#安装

#环境要求

#从预览通道安装

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

#可选依赖

#固定 Version Packages commit