#配置模型

项目根目录下的 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 对发布标识具有权威性。声明的 plugin.version 与之不一致时会报告 AB4008 警告； 而任何地方都没有版本号的发布构建会被直接拒绝（AB4013），而不是打包开发期回退值。插件代码通过 agent-bundle/meta 读取自身标识，而不是手工维护一个版本模块。

#Targets

targets 选择构建要输出的产物布局：

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

#完整表面

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

#宿主作用域声明

每个宿主键都是可选的，其中的每个字段也都是可选的。claude 与 codex 扩展自共享的 AgentBundleHostConfig，它唯一的字段 nativeHooks 指向一份由项目编写、target 原生的钩子文档 （hooks.json），适配器会校验它并与编译出的钩子合并。各适配器拥有的字段如下：

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

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

• claude.lspServers —— 由 claude target 以及 plugin 的 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 只出现在真正需要渲染的地方。一个可执行路由就是一个 async 默认导出的 Server Component：它完成工作并返回 Agent.* 节点，并且只有在需要 host、session、actor、workspace、 capability 或 state 上下文时才调用 await agent()。不存在公开的 execute/render 分裂，普通 .ts 路由也绝不会被包进 React 行为里。

#可编写的表面

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