#配置模型

项目根目录下的 agent-bundle.config.ts 就是全部的声明式表面。它是一个小而扁平的对象，保存项目标识、 target 选择，以及任何单个路由文件都无法拥有的策略。所有结构性的内容，存在哪些 Skill、存在哪些 MCP 路由、发布哪些脚本，都来自 src/ 约定，除非你在这里覆盖它。

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.description?: string | undefineddescription: 'Evidence-backed project tools.', 
AgentBundlePluginConfig.name: stringname: 'my-plugin' },
  
AgentBundleConfig.targets?: string[] | undefinedtargets: ['portable', 'codex', 'claude'],
});

defineConfig 是一个恒等辅助函数：它的存在是为了给对象加上类型，而不是变换它。

#项目标识

plugin 声明宿主所看到的插件身份：

package.json 对发布标识具有权威性。没有有效包版本号的发布构建会被直接拒绝（AB4013）， 而不是打包开发期回退值。插件代码通过 agent-bundle/meta 读取自身标识，而不是手工维护一个版本模块。

#Targets

targets 选择构建铺进 artifact/（或 output.distPath）复合根目录的宿主投影：

Amp 插件嵌套在 .amp/plugins/ 下；其他宿主清单各自位于自己的点目录中，skills/、hooks/、mcp/、 scripts/、bin/ 与 assets/ 只输出一份并共享。省略 targets 时构建只输出 portable 投影。顺序无关紧要， ['codex', 'claude'] 与 ['claude', 'codex'] 产生完全相同的字节，而其他任何名称（包括 plugin）都是未知 target（AB4100）。

可移植标准只打包 Skills 与 MCP 服务器，因此规则、命令与钩子在该 target 上是诚实地不可用，而不是被 悄悄丢弃。Claude Code 只能通过 CLI 转译消费该标准，这正是它仍需要专属 target 的原因。

#完整表面

宿主作用域的扩展键，claude、codex、cursor、portable，由各个 target 适配器通过声明合并贡献，因此 宿主专属取值留在自己的适配器中，而不会泄漏进编译器核心。普通项目完全不需要任何扩展键。

#宿主作用域声明

每个宿主键都是可选的，其中的每个字段也都是可选的。claude 与 codex 扩展自共享的 AgentBundleHostConfig，它唯一的字段 nativeHooks 指向一份由项目编写、target 原生的钩子文档 （hooks.json），适配器会校验它并与编译出的钩子合并。对 Claude Code 而言，固定的 schema 接纳文档化的 处理器契约：固定的 2.1.260 宿主认识的每个钩子事件（即参考文档列出的全部事件，包括需要 2.1.251 的 PreModelSwitch 与 PostModelSwitch）、五种处理器类型（command、http、mcp_tool、prompt、 agent）、各类型自己的字段（args、async、shell、url、headers、server、tool、input、 prompt、model 等）以及公共字段 if、once、statusMessage 与 timeout；未知键、属于另一种处理器 类型的字段，以及参考文档明确排除的事件上的 prompt/agent/http 处理器都会被拒绝。编译器自身仍只输出 shell 形式的 command 处理器。各适配器拥有的字段如下：

Cursor 插件的其余一切都从跨宿主模型推导。宿主参考中的宿主能力表 记录了每个被固定的宿主版本实际认可其中哪些表面。

其中四个块共享的五个描述字段，author、homepage、keywords、license 与 repository，不必重复声明。 每个字段默认取项目 package.json 中的同名字段，plugin.metadata 一次性覆盖所有宿主，而宿主块对自己的产物 仍然优先。把字段写成 null 即可让共享值不出现：写在 plugin.metadata 中表示不共享，写在某个宿主块中则只让 该值不进入那一份清单。解析顺序以及编译器读取的两种 package.json 形状，见 配置。

有两个 Claude Code 表面值得细看，因为它们的契约比名字所暗示的更窄：

• claude.lspServers：只要 claude 在选中的投影之中，就输出为根目录的 .lsp.json。路径 token 只在 command、args、env 与 workspaceFolder 中展开。agent-bundle 不包含语言服务器二进制文件，请单独安装它，以确保所声明的命令位于 PATH 上。Codex、Cursor 与 可移植格式不会收到这份配置。
• claude.settings：输出为插件根目录的 settings.json，Claude Code 会在插件启用时应用它。 被固定的契约只支持 agent 与 subagentStatusLine；任何其他键都会被拒绝，而不是发出一个 Claude Code 会悄悄忽略的默认值。这里不展开任何路径 token，因为 settings.json 不在宿主的占位符 替换表中。在插件 agents/ 组件仍被推迟期间，声明 agent 还会触发一条警告：被引用的 agent 必须 通过其他方式抵达插件根目录，例如预构建 payload。

#运行时下限

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.description?: string | undefineddescription: 'Evidence-backed project tools.', 
AgentBundlePluginConfig.name: stringname: 'my-plugin' },
  
AgentBundleConfig.runtime?: AgentBundleRuntimeConfig | undefinedruntime: { 
AgentBundleRuntimeConfig.node: string
Minimum supported Node.js version in major.minor[.patch] form.node: '24.0' },
  
AgentBundleConfig.targets?: string[] | undefinedtargets: ['portable'],
});

生成的可执行文件默认以 Node.js 22.12 及以上为目标。runtime.node 抬高这个下限，它永远无法降低， 所选下限会以 runtime.node 记录在产物清单中。

#JSX 意味着渲染

结构存在于配置与约定中；JSX 只出现在真正需要渲染的地方。一个渲染路由就是一个同步或异步默认导出的 Server Component：它完成工作并返回 Agent.* 节点，并且只有在需要 host、session、actor、workspace、 capability 或 state 上下文时才调用 await agent()。不存在公开的 execute/render 分裂，普通 .ts 路由也绝不会被包进 React 行为里。两种事件形式使用相同的规范文件路径：.ts 返回轻量决定， .tsx 渲染 JSX，.ts 处理器可通过 ctx.render() 请求独立的 .view.tsx 视图。工具处理器可以使用 defineTool 获得类型推断。

#路由契约（Application IR）

编译后的图记录与宿主无关的路由身份和声明的元数据。 字面量 config.inputJsonSchema 创建冻结的 RouteContract，id 为 contract:<route-module>#inputJsonSchema，包含 origin: { module, binding: 'inputJsonSchema' }、input，以及 routes 中的路由 id。 路由通过 route.contract 引用它。没有输入元数据时，graph.contracts 字段缺席。

检查和 Workbench 读取这些数据而不执行 schema 代码。导入运行时 schema 不会创建共享静态契约。 生成的 TypeScript 类型和运行时校验使用真实 schema 导出。参见 输入元数据。

#可编写的表面

• Skills：Markdown Skill、它们的资源，以及渲染式 Skill 源码。
• 钩子：七个规范生命周期事件与工具选择器。
• MCP 服务器与 MCP App：生成式路由服务器、手写 stdio 入口与浏览器 App。
• 脚本与资源：产物脚本与静态文件。
• 包入口：bin、lib、路由式 CLI 与打包器逃生舱。

一条路由如何同时变成 MCP、CLI 与钩子，以及编译器今天仍在哪些地方重复，见 编译器架构。

处理函数和组件可以直接返回结果，也可以返回 Promise。编译器检查导出声明；生成的运行时检查值是否可调用并等待结果。运行时也会等待 mapInput，然后由原始输入 schema 执行一次验证。