For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/zh/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/zh/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/zh/index.md.
跳至主要内容
agent-bundle
  • 简体中文
      • agent-bundle
      一份带类型的配置，适配所有 Agent 宿主

      一次性描述 Skill、钩子、MCP 服务器与脚本，编译出 Claude Code、Codex、Cursor 与实验性 Amp 可安装的产物。

      介绍快速开始
      agent-bundle 徽标agent-bundle 徽标
      🧩

      一份带类型的配置

      单个 agent-bundle.config.ts 承载项目身份、target 选择与策略。配置没说的部分由 src/ 约定补齐；两者描述同一件事时，配置始终优先。

      📚

      Skill

      每个 Skill 一个目录，包含 SKILL.md 与自己的资源；无需声明即可被发现，并按固定版本的 Agent Skills 规范校验。

      🪝

      生命周期钩子

      从 sessionStart 到 workspaceOpen 共七种事件，用 TypeScript 写一次，编译成每个宿主实际拉起的包装脚本。

      🔌

      MCP 服务器与 MCP App

      手写的 stdio 服务器，或每个 tool、resource、prompt 各占一个模块的生成式服务器。浏览器端 MCP App 编译为自包含的 HTML。

      📜

      脚本、静态资源与包入口

      普通脚本或渲染式脚本、逐字节复制的静态资源，以及从同一项目输出的 CLI bin 或库入口，一次构建，两份输出。

      🖥️

      本地 Workbench

      agent-bundle dev 在回环地址上提供一棵应用树与路由工作区，带渲染结果、调用轨迹、诊断，以及高级协议与产物工具。

      🔬

      以证据驱动的测试

      路由、协议、CLI、打包与宿主安装等各级证明，把“能构建”变成可复核的证据；某一级别的通过绝不会被当作另一级别的收据来报告。

      📊

      评估

      评估套件具有通过、失败与不确定三种语义，针对真实输出的产物运行，而不是它的模拟品。

      📦

      一个根目录，所有宿主

      产物根目录就是你安装的那个单位，每个所选宿主的清单各自放在自己的点目录中，共用同一套 Skill、钩子与 MCP 入口，旁边是生成的 INSTALL.md 与 agent-bundle.manifest.json，即 install、doctor、校验、MCP、钩子与评测所读取的产物索引。

      你写下什么，得到什么

      输入是一份配置文件加一棵按约定组织的 src/ 目录树。输出是一个复合插件根目录：每个所选宿主的清单 各自位于自己的点目录中，覆盖在共享的组件目录之上，外加生成的包装脚本、用捆绑包真实名称写成的 安装说明，以及整个产物据以校验的 agent-bundle.manifest.json。所有宿主安装的都是这同一个目录。

      你写下

      agent-bundle.config.ts
      import { defineConfig } from 'agent-bundle/config';

export default defineConfig({
  plugin: {
    name: 'release-tools',
    description: 'Release-readiness checks.',
  },
  hooks: {
    sessionStart: {
      handler: './src/hooks/session-start.ts',
    },
  },
  targets: ['claude', 'codex', 'portable'],
});
      src/
      src/
├── skills/release-review/
│   ├── SKILL.md
│   └── references/policy.md
├── hooks/session-start.ts
├── mcp/status.ts
└── scripts/check-service.ts

      Skill、MCP 服务器与脚本都按约定被发现。只有钩子需要声明，因为处理器必须绑定到某个事件。

      编译器输出

      artifact/
      artifact/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── .codex-plugin/
│   ├── plugin.json
│   ├── hooks.json
│   └── mcp.json
├── .agents/plugins/marketplace.json
├── .mcp.json
├── plugin.json
├── mcp.json
├── hooks/
│   ├── hooks.json
│   ├── session-start-….claude.mjs
│   ├── session-start-….codex.mjs
│   └── hooks-flight.mjs
├── mcp/
│   ├── mcp-status-….mjs
│   └── mcp-status-…-flight.mjs
├── scripts/check-service.mjs
├── skills/release-review/
│   ├── SKILL.md
│   └── references/policy.md
├── INSTALL.md                       # 每个所选宿主一节
├── install.mjs                      # portable 与 Cursor 的安装器
└── agent-bundle.manifest.json       # 产物索引：身份、投影、可执行文件、摘要

      每个所选宿主都把这同一个目录当作自己的插件根目录来读取：Claude Code 找到 .claude-plugin/、 hooks/hooks.json 与 .mcp.json；Codex 找到 .codex-plugin/ 与 .agents/ 下的 marketplace； Agent Plugins 客户端找到 plugin.json 与 mcp.json。Skill、编译后的 MCP 入口与脚本只输出一次， 从不按宿主复制。

      Agent Plugins 开放标准没有钩子这一表面。上面的钩子没有声明 targets，因此只继承所选 target 中支持钩子的 那些，claude 与 codex，并为它到达的每个宿主各编译一次，所以这里出现两个包装脚本。portable 会被跳过且不产生诊断；若显式写出 targets: ['portable']，构建时则会得到 AB4204。

      生成的包装脚本文件名带有一段短摘要，摘要来自编译它的声明，而非文件内容。agent-bundle.manifest.json 记录每个输出文件及其 SHA-256，因此后续校验比对的是真实字节，而不是检查某个路径是否存在。

      从源码到已安装的插件

      描述

      编写 agent-bundle.config.ts，把 Skill、钩子、MCP 路由与脚本放到 src/ 下。 agent-bundle inspect 会展示归一化后的模型，让你确认哪些文件是按约定被发现的、哪些是由配置声明的。

      开发

      agent-bundle dev 在每次变更时重新构建，并在回环地址上提供开发者 Workbench：在一棵 Application 树中选择任意插件表面，运行可执行 叶子，检视渲染结果，并跟随调用轨迹与诊断。

      证明

      用彼此区分的证明级别针对产物做测试，从路由单元测试一直到通过真实宿主 CLI 安装的捆绑包，并运行结果为通过、失败或不确定的评估。

      交付

      agent-bundle build 校验项目并写出一个复合插件根目录。校验 依据清单检查产物，安装则让每个宿主自己的安装路径指向这同一个 根目录。

      一份源码，所有宿主

      targets 选择这一个根目录承载哪些宿主投影；省略它时根目录只承载 portable。实验性 Amp 读取嵌套目录插件； 其他行读取组合根目录。

      Target为根目录添加的内容安装方式
      amp.amp/plugins/<name>/index.js、显式注册的捆绑 Skill、PluginAPI 事件回调与 Skill 范围 MCP。实验性：已核对契约，运行时未验证。把生成目录复制到项目/系统根，或运行 agent-bundle install amp --from artifact。现场激活需要 Amp 账号，CI 中未证明。
      claude.claude-plugin/plugin.json 与本地 marketplace.json，以及 hooks/hooks.json 与 .mcp.json。claude plugin marketplace add 与 claude plugin install，或 agent-bundle install claude --from artifact。
      codex.codex-plugin/plugin.json 及其旁边的 hooks.json 与 mcp.json，以及 .agents/plugins/marketplace.json。codex plugin marketplace add 与 codex plugin add，或 agent-bundle install codex --from artifact。
      cursor.cursor-plugin/plugin.json 及其旁边的 hooks.json 与 mcp.json。生成的 install.mjs，或 agent-bundle install cursor --from artifact。
      portableAgent Plugins 开放标准，覆盖 Skill 与 MCP 服务器的 plugin.json 与 mcp.json，由 Cursor 原生读取。宿主参考记录了针对它核对过的其他客户端，兼容、部分兼容与不兼容，以及每个客户端各自加载与不加载的界面。生成的 install.mjs。

      各宿主能加载的内容不同，编译器会在构建时明确指出：你为某个 target 选择了它无法表达的表面，就会得到一条 被报告的诊断，绝不会被悄悄省略。唯一有意为之的例外是没有自己的 targets 的钩子：它只继承支持钩子的 宿主，正如上面的目录树所示，而不是让构建失败。两个所选宿主若要以不同字节写出同一路径，就无法共用 一个根目录，构建会以 AB4103 明确指出。每条诊断都有稳定的 AB 代码，记录在 诊断参考中。

      从这里开始

      • 安装：运行要求与 create-agent-bundle 脚手架。
      • 快速开始：从配置到已安装插件的完整项目。
      • 示例：可运行的产品，从 Skill 起步项目、钩子与脚本轨迹、交互式 MCP App 到一个完整的媒体管理插件，外加两个进阶组合参考。
      • Type API：为每个公开 agent-bundle 导出生成的参考。