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 的产物。

      介绍快速开始
      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 在回环地址上提供开发者 Workbench：诊断、产物树、带原始协议轨迹的 MCP playground，以及钩子 playground。

      🔬

      以证据驱动的测试

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

      📊

      评估

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

      📦

      每个 target 都能独立交付

      已构建的 target 目录就是你安装的那个单位——它自带宿主清单与生成的 INSTALL.md。旁边的产物根目录保存着 agent-bundle.manifest.json，即校验、MCP、钩子与评测所读取的 SHA-256 记录。

      你写下什么，得到什么

      输入是一份配置文件加一棵按约定组织的 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 服务器与脚本都按约定被发现。只有钩子需要声明，因为处理器必须绑定到某个事件。

      编译器输出

      Claude Code
      Codex
      Portable
      artifact/claude/
      artifact/claude/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── .mcp.json
├── hooks/
│   ├── hooks.json
│   └── session-start-….mjs
├── mcp/mcp-status-….mjs
├── scripts/check-service.mjs
├── skills/release-review/
│   ├── SKILL.md
│   └── references/policy.md
└── INSTALL.md

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

      从源码到已安装的插件

      描述

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

      开发

      agent-bundle dev 在每次变更时重新构建，并在回环地址上提供开发者 Workbench：诊断、Skill 文档、带来源信息的产物树，以及驱动输出的 MCP 服务器与钩子包装脚本的 playground。

      证明

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

      交付

      agent-bundle build 校验项目并为每个 target 写出一个目录。校验 依据清单检查产物，安装则走每个宿主自己的安装路径。

      一份源码，所有宿主

      Target输出内容安装方式
      claudeClaude Code 插件布局，含插件清单与本地 marketplace 清单。claude plugin marketplace add 与 claude plugin install，或 agent-bundle install claude。
      codexCodex 插件布局，含插件清单与本地 marketplace 清单。codex plugin marketplace add 与 codex plugin add，或 agent-bundle install codex。
      cursorCursor 插件布局。生成的 install.mjs，或 agent-bundle install cursor。
      portableAgent Plugins 开放标准——Skill 与 MCP 服务器——Cursor、Codex、VS Code、GitHub Copilot、Kiro 与 ChatGPT 原生读取。生成的 install.mjs。
      plugin一个多宿主捆绑包，在共享的组件目录之上同时携带 Claude、Codex 与 Cursor 清单。install.mjs 或任一宿主 CLI。

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

      从这里开始

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