#Target 与产物

先用Target 与能力地图选择表面。 生成的宿主矩阵记录功能支持及证据。 本页描述实际输出，以及下游工具消费的对象。

#复合插件根目录

agent-bundle build 写出一个组合产物根目录，默认是 artifact/。 output.distPath 或 CLI --output 可以移动根目录，但不会重新设计内部布局。 五种内置投影是 amp、claude、codex、cursor 和 portable。

省略 targets 时只选择 portable。 显式选择可以组合内置投影，但编写的组件必须符合兼容性规则。 target 顺序不改变结果。plugin、web、npm 和浏览器展示 profile 不是额外的内置 target。

以下是组合布局示意，不承诺空插件也会输出每个文件。 实际可执行名称及包含的组件以生成清单为准。

artifact/
├── .amp/plugins/<name>/
│   ├── index.js                       # 原生 Amp 工厂
│   ├── skills/                        # 显式注册的 Skills
│   └── hooks/                         # 映射回调的可执行支持
├── .claude-plugin/plugin.json
├── .claude-plugin/marketplace.json
├── .codex-plugin/plugin.json
├── .codex-plugin/hooks.json
├── .codex-plugin/mcp.json
├── .agents/plugins/marketplace.json
├── .cursor-plugin/plugin.json
├── .cursor-plugin/hooks.json
├── .cursor-plugin/mcp.json
├── .mcp.json                          # Claude MCP 文档
├── plugin.json                        # portable 清单
├── mcp.json                           # portable MCP 文档
├── hooks/hooks.json                   # Claude hook 文档
├── hooks/                             # 编译后的宿主绑定 wrapper/worker
├── mcp/                               # 编译后的 MCP 入口及 worker
├── bin/                               # 生成 CLI / 配置的 web 命令
├── skills/, commands/, rules/
├── scripts/, assets/, mcp-apps/
├── INSTALL.md
├── install.mjs                        # 所选 Cursor/portable 安装路径
├── agent-bundle.manifest.json
└── agent-bundle.compile-evidence.json

根目录共享组件只输出一次。 Amp 目录插件把已注册的 Skills 和执行支持保留在自身嵌套目录中，以保证安装副本自包含。 因此，原生 Amp 安装根并不是组合产物根。

纯静态 Skills 插件不需要空 MCP 服务器，也不需要 Flight/state 进程。 当另一个所选宿主在约定 fallback 路径上有内容时，某些空原生 hook/MCP 文档是有意设置的发现隔离屏障。 不要把它们当作未使用文件删除。

#各宿主从哪里读取文档

有效的单 target 与多 target 选择使用稳定路径。 Codex 和 Cursor 通过显式指针避免读取其他投影的 fallback 文档。 第三方 portable 客户端可能有不同优先级和支持子集；应查阅宿主矩阵中的独立记录， 而不是把本表当作其原生布局。

#Hook 包装器

编译 hook wrapper 绑定所选宿主的 codec 与契约。 同一份 hook 源码因此可能生成多个 wrapper。 配置声明的 hook 只到达一个宿主时使用普通名称，到达多个宿主时使用宿主限定名称。 约定语义事件和独立 worker 同样记录在 executables.hooks 中。

使用 hooks list 和清单，不要自己构造 wrapper 文件名。 原生事件、payload 来源、matcher 与返回语义见事件矩阵。 显式 targets 和受支持的事件 requires 声明影响选择，但都不能制造宿主无法表达的事件或决定。

#编译表面

生成的 MCP 入口、脚本、CLI bin 和浏览器 App 归属于组合选择，不会为每个宿主重新构建成互不相关的应用。 Agent Document renderer 与浏览器 App 编译使用不同环境。

Amp 的 MCP 投影属于 Skill。 当前适配器允许与恰好一个捆绑 Skill 关联的、受支持的远程服务器及全局可解析命令服务器； 对于没有受支持原生路径/cwd 契约的编译器自有本地 MCP 入口，则予以拒绝。 把 Amp 列为 target，不会使普通本地生成 MCP starter 自动兼容 Amp。

配置 web 表面后，即使没有手写 CLI 命令，框架也会向 bin/<plugin>.mjs 加入自有 web 命令。 它是声明的 MCP App 的本地浏览器宿主，不是 web 输出 target、另一份生成的 web/ 应用， 也不是绕过 App 同意机制的许可。

#一个根目录，一套字节

Skills 由所选 targets 共享。宿主扩展若改变生成的 Skill 内容，仍可能触发真正的 AB4103 冲突。 明确拒绝，比交付一个行为取决于谁先发现它的组合更安全。

#根目录可直接分发

复制组合产物不需要逐宿主重新编译。 它包含生成的安装说明和必要安装支持。 npm 分发仍需要基于生成 npm 根目录的 npm 打包步骤；目录构建不等于已经生成 tarball。

框架的 install --from 从组合根解析所选原生位置。 消费者可以遵循 INSTALL.md 而不安装编译器。 插件还可通过 agent-bundle/install 提供薄包绑定 bin；它是显式选择，不会为每个包自动生成。

启用包输出时，dist/ 是完整 npm 根：已校验组合产物的副本、package.json、标准包文档，以及声明的包专用入口。 生成路由 CLI 原样复制，并由 bin/<name>.mjs 引用；手写包 bin 则编译为 bin/<name>.js。 tarball 内不要求嵌套 artifact/。 prepack、实际 npm pack 与安装 bin 的证明见交付。 npm 安装不会自动将插件注册到宿主。

#agent-bundle.manifest.json

当前封闭产物契约为 manifestVersion: 6。 它是构建应用的索引，不是另一份需要插件作者维护的文件。

对于编译或预构建 MCP 服务器，规范启动参数区分产物引用与字面值。 字面值带斜杠并不意味着它是可重定位产物路径。 启动器只在正确边界展开受支持的声明占位符。

web.apps 记录包含 App 身份、服务器关联、允许能力及可选 opening tool/input。 启动选择来自对应 executable/projection 记录。 不要从浏览器 profile 推导启动，也不要把 entry、args 和 env 再加到每个 web App 中。 精确字段定义见产物清单。

原生文档与规范清单都由编译器生成。 结构校验、规范表示、引用文件检查与内容摘要承担不同职责；仅解析清单的 reader 不一定正在运行全部产物校验。 使用适当的公开验证命令，不要改写 digest 来认可被修改的输出。

持久化的 agent-bundle.compile-evidence.json 把编译器证据绑定到输出字节。 摘要一致不等于对反射加载或未分析运行时加载的通用证明。 编译器无法建立自包含证据的地方，仍需要剩余检查和预构建依赖声明。 参见校验。

#版本与修订

收集证据时，区分源码包版本、构建产物版本、已安装产物版本和实际运行服务器版本。 installed-host 证明比较相关观测；缺失的观测不能被编造。

adapter revision 与 observed native-host version 描述的契约不同于插件自己的 release version。 compiler record 的形状也独立版本化。 不要只更新私有 manifest reader，而不更新生成其输入的编译器。 使用兼容的公开 compiler/runtime/lifecycle 包组合，并验证实际交付物。

prepack 检查适用的 package/manifest 版本与依赖证据。 内联进生成 JavaScript 的依赖不会自动变成消费者运行依赖； 预构建 payload、声明文件和受支持安装脚本则可能证明真实需求。

#下一步

• 能力地图：受支持 targets、功能导航和证明边界。
• 产物清单：精确字段与规范所有权。
• 编译器架构：实现阶段与读取方。
• 产物校验：交付根目录上的检查。
• 宿主安装：scope、所有权、替换与移除。
• 运行环境：执行假设与可写状态。