#交付捆绑包

有两种分发形式，它们包含同一份编译后的插件：

两者都不需要手写逐宿主重新打包器。npm 仍然需要正常的打包步骤； 该步骤必须针对生成的包根执行，而不是源码项目或另一份应用实现。

下面的 npx --no-install 命令运行已经安装在开发项目中的编译器，刻意避免按未限定的 agent-bundle 名称下载包。支持的预览或正式版本选择方式见框架安装。

#流水线

要从源码仓库直接安装，可配置编译器生成仓库根目录市场清单：

export default defineConfig({
  plugin: { name: 'my-plugin' },
  targets: ['cursor', 'portable'],
  marketplace: true,
  output: { distPath: 'artifact', repositoryMarketplace: true },
});

构建后提交 artifact/ 和 .cursor-plugin/marketplace.json（对于被忽略的生成文件，使用 git add -f）。根目录市场指向 ./artifact；插件清单、脚本、技能和安装器均由 Agent Bundle 生成，使用者无需构建。选择 Claude 和 Codex 时，同一选项也会生成 .claude-plugin/marketplace.json 和 .agents/plugins/marketplace.json。 CI 只需构建、校验并提交输出。

npx --no-install agent-bundle build --output artifact
npx --no-install agent-bundle validate --artifact artifact --strict

源码 validate 对编辑和类型检查很有用，但不能代替校验交付物。 validate --artifact 不需要源码项目。安装是独立的操作者动作，构建插件不应把它注册到全局宿主。

#根目录如何编译

编译器发现应用、解析所选宿主投影、编译所需浏览器和服务器入口，并组装成一棵已校验的树。 共享路径的字节必须兼容，宿主不能意外发现另一个宿主的组件。

可执行文件、启动参数以及所属服务器或 App 由生成清单确定，不应由消费者探测文件名来重建。 不要从原生 mcp.json 的第一个参数推断服务器命令，不要猜测 artifact/<host>/ 目录， 也不要在编译后重命名生成的可执行文件。 进阶编译细节见架构和产物校验。

#根目录里发布了什么

组合产物包含所选原生清单、共享组件文件、编译入口、agent-bundle.manifest.json、持久化编译证据， 以及适用时生成的 INSTALL.md。它使用插件的真实名称，而不是消费者需要替换的模板名称。 输出布局见项目结构。

组合根不一定等于宿主的原生安装根。 Amp 目录插件位于 .amp/plugins/<name>/， 其他内置原生投影从组合根读取各自清单。框架的清单感知 install --from 接受组合根， 并解析所选宿主的布局。使用生成的说明，不要要求最终用户理解嵌套目录结构。

选择 cursor 或 portable 会包含宿主安装所述的独立 install.mjs 路径。 它是一种有明确说明的安装机制，不代表每个 portable 客户端都支持所有原生钩子或 App 能力。

把交付代码视为不可变内容。可写框架状态独立于安装代码目录解析。 领域数据，包括刷新后的会话和应用数据库，需要明确的应用自有位置与迁移策略。 不要把真实凭据、可变缓存或操作者数据打包成 assets。

#面向 npm 的那一半

对于启用了包输出的项目，例如 MCP starter，dist/ 包含完整 npm 根：原样复制的已校验产物、 生成的 package.json、标准包文档及声明的包专用 bin 或库输出。 Tarball 内不会再嵌套一层 artifact/。

生成式路由 CLI 的 package.json.bin 直接指向产物中的 bin/<name>.mjs， 操作表面与产物 CLI 相同，包括声明后的 web。 显式手写的包 bin 则编译为 bin/<name>.js；它们是不同入口种类，不是同一路由 CLI 的两份版本。

先运行框架门禁，再打包生成目录：

npx --no-install agent-bundle prepack --json
npm pack ./dist --ignore-scripts

prepack 执行发布构建，并校验 dry-run 包清单、入口路径、产物摘要、版本及声明的运行时依赖。 第二条命令创建实际 tarball。这里的 --ignore-scripts 防止打包期间的脚本再次构建另一种产物； 它不表示消费者安装时也会忽略安装脚本。

检查生成的 dist/package.json、bin / exports 和 tarball 文件清单。 不要手改生成清单；修改手写的包或配置输入，再重新构建。 minimal 与 mcp-server starter 是私有开发包；有意进行公开发布时，还需要合适的包元数据， 并移除它们的 private: true。cli-tool starter 脚手架产出即可发布。本指南不会自动发布任何 内容。

以构建目录分发的静态插件不需要为了原生安装而虚构一个库或可执行入口。 选择 npm 分发及其可选入口时，请阅读包入口。

#消费者安装脚本与依赖

构建工具不会自动成为运行时依赖。自包含的生成式 JavaScript 不应依赖源码检出、workspace 别名， 或要求消费者安装编译器。预构建 payload 或明确保留的消费者安装脚本可能确实需要运行时依赖； 应准确声明，而不是为了缩小包体积就把普通生成入口的依赖 externalize。

不要意外把相对源码路径的 shell 脚本带入安装包。包构建器支持有界的已记录脚本形式重定位， 并会诊断不支持的形式。如果消费者安装只有加 --ignore-scripts 才能通过， 就没有证明承诺的安装生命周期。测试有副作用的脚本时使用隔离 fixture， 不要使用真实凭据或全局宿主配置。

#可选的包绑定安装器

要给消费者提供 my-plugin-install install <host>，声明一个包专用 bin，并把实现委托给公开框架入口。 将该入口合并到现有配置，不要覆盖无关条目：

import { 
const defineConfig: (config: AgentBundleConfig | ConfigFactory) => AgentBundleConfig | ConfigFactorydefineConfig } from 'agent-bundle/config';

export default 
function defineConfig(config: AgentBundleConfig | ConfigFactory): AgentBundleConfig | ConfigFactorydefineConfig({
  
AgentBundleConfig.plugin: AgentBundlePluginConfigplugin: { 
AgentBundlePluginConfig.name: stringname: 'my-plugin', 
AgentBundlePluginConfig.description?: string | undefineddescription: 'Project tools for an agent.' },
  
AgentBundleConfig.targets?: string[] | undefinedtargets: ['claude', 'codex', 'cursor'],
  
AgentBundleConfig.bin?: AgentBundleBinConfig | undefinedbin: { 'my-plugin-install': './src/install-bin.ts' },
});

// src/install-bin.ts
import { fileURLToPath } from 'node:url';
import { runInstallCli } from 'agent-bundle/install';

export const main = (argv: readonly string[]): Promise<number> =>
  runInstallCli(argv, {
    from: fileURLToPath(new URL('..', import.meta.url)),
    name: 'my-plugin-install',
  });

父目录绑定指向 npm 根中输出后的 bin/ 入口。 运行构建或安装后的形式，不要把直接运行源码文件当作安装证明。 包构建会打包生命周期实现，消费者无需仅为使用该 bin 而安装编译器。

这是显式启用的入口，不是自动添加到每个插件中的安装器。 它复用 install、uninstall 和 doctor，只绑定一次包根。 不需要消费者自有的 argv parser、原生配置合并器、根目录搜索循环或私有框架导入。 支持的 flag 和作用域见宿主安装。

#证明安装后的包

在全新的临时消费者目录中安装实际 tarball，测试它声明的 bin 或指定 MCP 服务器。 移动或删除源码 fixture，使用不同工作目录，并提供独立可写状态根。 确认预期工具和代表性结果。直接启动源码树中 artifact/ 的测试有价值，但不是 npm 安装测试。

validate --artifact 等仅面向产物的命令应接收纯组合产物。 清单感知的 install --from 也接受 npm 根，并在宿主所有权比较中排除 npm 专用元数据。 不要仅因为两种根目录都含有 agent-bundle.manifest.json 就互换使用。

使用公开的打包测试辅助函数和规范清单， 不要把私有安装器或原生文档 parser 复制进插件测试 harness。 原生账号授权与宿主执行仍然需要单独限定证据。

#显式安装

消费者遵循交付的 INSTALL.md，或者调用插件明确提供的包绑定安装器。 已经安装编译器的开发者可以使用：

npx --no-install agent-bundle install claude --from artifact --scope user

只选择预期的宿主与作用域。安装 npm 包不等于注册宿主插件；框架 build/prepack 不代表同意修改宿主。 只读 doctor 和卸载计划的行为见宿主安装。

#本章内容

• 产物校验：源码检查、产物检查与宿主校验器。
• 宿主安装：原生根、作用域、凭据、替换和移除。
• 预览包：当前开发分发通道。