#产物清单

agent-bundle.manifest.json 位于 agent-bundle build 输出的组合插件根目录顶层（根目录布局见 Target 与产物）。它是产物的索引：一份文档记录了被编译的应用身份、编译后的 路由图、被选中的宿主投影及每个投影派生出的宿主文档、根目录能启动的每一个可执行文件，以及根目录如何分发。 每个消费者，install、uninstall、doctor、serve-app、mcp、hooks、eval --artifact、inspect、 Workbench 与 npm prepack 门禁，都只读这一个文件来了解根目录包含什么。它们都不会去探测 .claude-plugin/plugin.json、.mcp.json 或目录布局。

#契约

#由谁写入

agent-bundle build，别无他者。文档中的一切都是派生的：作者声明 agent-bundle.config.ts（元数据、 targets、钩子、MCP 服务器、脚本、市场）与约定文件系统（src/mcp/**、src/cli/**、src/hooks/**、 src/events/**、src/scripts/**），构建则从规范化模型、编译后的路由图、组合计划以及它输出的文件写出清单。 Amp 的 index.js 入口，以及 Claude、Codex、Cursor 与 portable 的插件清单、市场、MCP 与钩子文档，和清单在同一次 构建中由同一个编译模型序列化而成。每份宿主文档都是带摘要固定的 files[] 行，因此手工编辑会使产物摘要校验 失败。文件中没有任何可手工编辑的内容：修改配置或源码，然后重新构建。

#由谁读取

#公开契约

顶层有九个必填键，application、compiler、distribution、executables、files、 manifestVersion、projections、routes、runtime，外加可选的 web，恰在配置向 <plugin> web 暴露了 App 时出现。安装、诊断、服务或列出根目录的消费者 （install、doctor、serve-app、mcp、hooks、inspect 摘要）只读这份契约。编译器运行事实 在 compiler 下，并单独版本化。

#runtime、manifestVersion

#application

应用身份，只记录一次且与宿主无关。它是 install、doctor 与 uninstall 作用的对象；宿主插件清单与 这一行在同一次构建中由同一个编译模型序列化而成。

#files[]

除清单自身外的每个输出文件，按 path 排序。每行的源输入出处在 compiler.provenance，不在这里。

install 与 doctor --from 把这些行用作权威产物清点。它们直接读取每个列出的路径， 按 sha256 校验字节，并在不枚举根目录的情况下将其计入回执内容哈希。清单文件自身以及 操作员放在旁边的 .env 或 .env.local 也会被复制并哈希；未列出的文件会被忽略。 当工具从已构建根目录派生变体（例如 Workbench 开发安装）时，它会重新索引该变体的清单， 因为这份清单仍是安装器复制和哈希的清点依据。重新索引只会重新测量、添加或移除非编译行 （被改写的宿主 MCP 文档、安装标记）。bundle 行与 agent-bundle.compile-evidence.json 会被拒绝： 证据记录描述的是编译器产出的编译字节，只有重新构建才会产生新的记录，而校验器会让证据描述了 其他字节的工件失败（AB6039）。

#projections[]

每个所选宿主一行，按 host 排序。target 选择投影；它们不是身份。

documents 有五个可选键，每个键只在投影输出了对应文件时出现：

#routes

产物据以构建的编译后路由图，应用 IR，与宿主无关。它与 Workbench 路由目录展示的是同一次编译器遍历的 同一份投影；只是缺少 Workbench 仅用于展示的字段。

每条路由行的形状相同：

routes.cli.commands[] 的一行，按拼接后的 path 排序：

#executables

产物能启动的每一个进程，以及它的 Flight worker（如果有）。每个 hosts[] 列表与每个 host 都指向一行 projections[]。

#distribution

#web

唯一的可选根键。恰当配置中的 web 暴露了至少一个 targets 与所选投影相交的 App 时出现；<plugin> web、agent-bundle dev 的 /web/<server>/<app> 与 doctor 读取它，绝不会从 src/** 重新发现 App。

#编译器记录（compiler，recordVersion）

编译器运行的操作记录。由 recordVersion 独立于 manifestVersion 版本化：这里的变更不是消费者读取的产物契约变更。该对象恰有七个键，全部必填：adapters、agentSkills、producer、project、provenance、recordVersion、validation。

#compiler.project

#compiler.adapters[]

#compiler.provenance[]

#跨分节规则

读取方在接受文档之前会强制这些规则：

• compiler.project.configPath 是一条 compiler.project.sourceInputs 记录，其哈希为 compiler.project.configDigest，且 compiler.project.revision 是 compiler.project.sourceInputs 的摘要。
• compiler.provenance 的路径等于 files[] 的路径，且每条出处的 sourceInputs 路径都是 compiler.project.sourceInputs 路径。
• compiler.adapters 的宿主等于 projections[] 的宿主。
• 每个指针，projections[].documents.*、executables.*[].path 与 worker、 executables.mcpServers[].launch.entry 与 .worker、executables.mcpServers[].apps[].path、 distribution.install.*，都指向一行 files[]。
• executables.mcpServers[].launch 恰在 kind 为 compiled 或 prebuilt 时出现；每个 kind 为 artifact 的 launch.args[] 项都指向一行 files[] 或根下的一个目录。
• 每个 web.apps[].server 都指向一行携带 launch 的 executables.mcpServers[]。
• 每个 hosts[] 项与每个 hooks[].host 都指向一行 projections[]。
• 每个 distribution.payloads[].name 目录下至少有一行 kind 为 prebuilt 的 files[]。
• compiler.validation.projections[] 的宿主等于 projections[] 的宿主。
• executables.scripts[].rendered.routeId 指向一条 routes.scripts[] 路由。
• distribution.channels 恰当 compiler.project.packageName 存在时包含 npm。

#一份精简示例

一个只为 claude 构建的根目录，来自带有一个生成式 MCP 服务器、一个 MCP App、一个事件路由与一个路由式 CLI 的插件。摘要已省略；键按规范（排序后的）顺序出现。

{
  "application": { "id": "hauler", "name": "cargo-hauler", "version": "1.4.2" },
  "compiler": {
    "adapters": [
      { "adapterRevision": "…", "host": "claude", "observedVersion": "2.1.260",
        "schemas": [{ "name": "plugin", "revision": "…", "sha256": "…" }] }
    ],
    "agentSkills": { "schemaSha256": "…", "sourceRevision": "…", "specification": "…" },
    "producer": { "name": "agent-bundle", "version": "0.9.0" },
    "project": {
      "configDigest": "…", "configPath": "agent-bundle.config.ts", "modelDigest": "…",
      "packageName": "cargo-hauler", "packageVersion": "1.4.2", "revision": "…",
      "sourceInputs": [{ "path": "agent-bundle.config.ts", "sha256": "…" }]
    },
    "provenance": [
      { "path": ".claude-plugin/plugin.json", "sourceInputs": ["agent-bundle.config.ts"] }
    ],
    "recordVersion": 1,
    "validation": {
      "artifact": { "status": "passed" },
      "projections": [{ "host": "claude", "status": "passed" }],
      "source": { "status": "passed" }
    }
  },
  "distribution": {
    "channels": ["local", "npm"],
    "install": { "instructions": "INSTALL.md" },
    "payloads": []
  },
  "executables": {
    "bins": [
      { "hosts": ["claude"], "name": "cargo-hauler", "path": "bin/cargo-hauler.mjs",
        "worker": "bin/cargo-hauler-flight.mjs" }
    ],
    "hooks": [
      { "event": "afterTool", "host": "claude", "id": "hook:event-route:tool-after",
        "kind": "event-route", "name": "event-route-tool-after",
        "path": "hooks/event-route-tool-after-….mjs",
        "routeId": "event:tool/after" }
    ],
    "mcpServers": [
      { "apps": [
          { "id": "mcp-app:hauler:dashboard", "name": "dashboard",
            "path": "mcp-apps/dashboard.html", "resourceUri": "ui://hauler/dashboard" }
        ],
        "hosts": ["claude"], "id": "mcp:hauler", "kind": "compiled",
        "launch": {
          "args": [
            { "kind": "literal", "value": "--config" },
            { "kind": "artifact", "path": "config/hauler.json" }
          ],
          "entry": "mcp/mcp-hauler-….mjs",
          "env": { "HAULER_CACHE": "agent-bundle:path:plugin-data/cache" },
          "worker": "mcp/mcp-hauler-…-flight.mjs" },
        "name": "hauler", "transport": "stdio" }
    ],
    "scripts": []
  },
  "files": [
    { "bytes": 412, "kind": "generated", "path": ".claude-plugin/plugin.json",
      "sha256": "…" }
  ],
  "manifestVersion": 6,
  "projections": [
    { "builtInHost": "claude",
      "documents": { "hooks": "hooks/hooks.json", "marketplace": ".claude-plugin/marketplace.json",
        "mcp": ".mcp.json", "plugin": ".claude-plugin/plugin.json" },
      "host": "claude", "marketplace": { "name": "cargo-hauler-marketplace" } }
  ],
  "routes": {
    "cli": {
      "commands": [
        { "aliases": [], "exitCode": "result", "options": [], "path": ["status"],
          "routeId": "cli:status" }
      ],
      "mode": "generated",
      "routes": [
        { "id": "cli:status", "kind": "cli", "provenance": { "kind": "conventional" },
          "source": "src/cli/status.tsx" }
      ]
    },
    "digest": "…",
    "events": [
      { "event": "tool/after", "id": "event:tool/after", "kind": "event-route",
        "execution": { "fallback": "none", "runtime": "shared" },
        "provenance": { "kind": "conventional" }, "source": "src/events/tool/after.tsx" }
    ],
    "layouts": [], "providers": [], "scripts": [],
    "servers": [
      { "id": "mcp:hauler", "mode": "generated", "name": "hauler",
        "routes": [
          { "id": "tool:hauler/status", "kind": "tool", "provenance": { "kind": "conventional" },
            "serverId": "mcp:hauler", "source": "src/mcp/hauler/status.tsx" }
        ] }
    ]
  },
  "runtime": { "node": "22.12.0" }
}

#Schema 与编程访问

该契约以 JSON Schema（draft 2020-12，每一层都是 additionalProperties: false）随包发布在 agent-bundle/schemas/agent-bundle.manifest.schema.json，agent-bundle 入口点把它导出为 artifactManifestSchema，旁边是 validateArtifactManifestSchema。TypeScript 类型、严格解析器与 schema 互相测试，因此其中一个接受的文档另外两个也接受。

同一入口点导出读取方：

类型（ArtifactManifest、ArtifactManifestCompiler、ArtifactManifestCompilerAdapter、 ArtifactManifestProvenance、ArtifactManifestProjection、ArtifactManifestExecutables……）见生成的 类型 API。

#保留键

这些键属于设计的一部分，但不会输出，v6 读取方会像对待任何未知键一样拒绝它们。在此列出，是为了让消费者 不要自创拼写：

#版本规则

版本 6 将事件 execution.preflight 改名为 execution.handler，并移除旧 execution.providers 选择字段。

每个根目录携带两个版本号。键在每一层都是封闭的，因此可选并不等于向后兼容：版本 N 的读取方会拒绝 任何它不认识的键或枚举值（精简的 web 读取方在读取任何切片之前就先拒绝版本不匹配）。

• manifestVersion 为消费者读取的公开契约版本化（application、files[]、runtime、 projections[]、routes、executables、distribution）。旧的封闭读取方会拒绝的任何变更 都会使其递增，新增、重命名或删除一个公开契约键（无论是否可选），或更改读取方封闭的枚举值集合。 同一版本内键清单冻结。读取方拒绝任何其他 manifestVersion。版本 5 新增 routes.cli.commands[].projection.input（"json"）。版本 4 新增 projections[].documents.entry 与 amp 内置宿主。版本 3 标记 npm 根目录保留清单所拥有的 字节与可执行文件这一规范保证；版本 2 已预留同样的 distribution.install 指针形状。版本 2 把 targets[] 重命名为 projections[]，把过去由 agent-bundle.hooks.json 承载的钩子行移入 executables.hooks[] 并删除了 该文件，并新增了 application、routes、executables、distribution 与 projections[].documents。
• compiler.recordVersion 按同样规则为编译器记录的键版本化（producer、project、 provenance[]、adapters[]、agentSkills、validation）。只改这些事实的内部编译器重构会递增 recordVersion，而不会迫使 manifestVersion 递增。读取方拒绝任何其他 recordVersion。当前值为 1。

请用 manifestVersion 与文档一致的框架版本读取产物；无论哪个方向的不一致都意味着重新构建，而不是回退。

#诊断

全部说明见诊断参考。

#下一步

• 编译器架构：应用层、投影层与产物层，本文件记录的正是它们的输出。
• Target 与产物：清单所索引的根目录。
• 产物校验：读取它的那些检查。
• 宿主安装：install 与 doctor 如何使用它。