#介绍

Agent Bundle 是用于构建智能体宿主插件的元框架。工具、Skills、钩子和视图只编写一次。 框架发现约定位置的源码，构建可执行入口，并生成所选宿主需要的清单。

从快速开始入手：创建项目，添加一个工具，在 Workbench 中查看渲染结果， 再测试它。不需要先编写 MCP 服务器，也不需要先理解编译器内部架构。 编译器和 Workbench 需要 Node.js 22.19 或更高版本。

#它解决的问题

宿主（host）是加载插件的应用，例如 Claude Code、Codex、Cursor 或实验性 Amp。 MCP 服务器通过 Model Context Protocol 暴露工具、资源和提示。 MCP App 是与 MCP 资源或工具关联的浏览器视图。它们是系统中的不同部分，而不是应用的三个别名。

手写复合插件容易积累彼此独立的工具注册表、原生钩子包装器、CLI 处理器、浏览器消息协议和安装脚本。 Agent Bundle 负责这些集成边界，让应用代码专注于插件本身的功能。

它与约定式应用框架最重要的相似之处是：文件声明路由。

src/mcp/status/tools/hello.tsx
                 ↓
       hello tool on the status server
                 ↓
  generated MCP entry · Workbench · tests

添加同目录的 CLI 投影，即可把同一个操作暴露为命令。需要交互式浏览器视图时再添加 App。 两者都不要求重新实现这个操作。

#配置负责什么

约定式项目只需要一份小型 agent-bundle.config.ts：

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'],
});

插件名是宿主使用的标识，npm 包名可以不同。发布版本来自 package.json。 选择 target 不意味着要在配置中重复声明源码树。 自定义 MCP 服务器、远程端点、预构建 payload 和包入口仍然受支持，适用于约定无法覆盖的场景； 它们不是编写第一个工具的必需步骤。

targets 选择投影：amp、claude、codex、cursor 或 portable；省略时只选择 portable。 选中了某个宿主，不代表它支持所有组件或实时开发功能。 添加宿主专属能力前，请查看宿主能力。

#编写模型

静态 Skills 插件不需要 React runtime 或 MCP 服务器。 普通钩子可以使用公开的钩子契约，不必使用 JSX。 Provider、状态和浏览器 App 都是可选能力，而不是每个项目都要复制的样板。

框架负责发现、宿主转换、执行基础设施、开发工具和打包。 插件仍然负责自己的领域服务、授权规则、数据模型与工作流。 不需要把调度器、数据库或登录流程改造成框架子系统。

#证据，而不是感觉

使用脚手架的 check 命令运行完整的确定性测试流程。 路由测试证明应用行为；打包后的进程测试进一步检查已安装的可执行文件；原生宿主测试检查宿主集成。 这些是不同的结论。需要扩展 starter 以外的覆盖范围时，请阅读测试。

#下一步

• 快速开始：从一个工具文件走到可见结果和测试。
• 项目结构：复合插件的源码，以及源码、生成文件、npm 包和可写状态根目录的区别。
• 交付捆绑包：构建、校验、打包生成的 npm 根目录，并显式安装。

安装说明框架预览通道。 编写和编译器架构是详细参考， 不是让第一个插件工作的前置知识。