配置

概念模型——配置拥有什么、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'],
});

顶层字段

字段	类型	默认值
`plugin`	`{ name, description?, logo?, ... }`	必填。
`targets`	`string[]`	由适配器选择。
`skills`	`string[]`	`src/skills/*` 约定。
`hooks`	`Partial<Record<CanonicalHookEvent, ...>>`	`src/hooks/*` 约定。
`mcp`	`{ servers: Record<string, ...> }`	`src/mcp/*` 约定。
`scripts`	`Record<string, string \| { entry, targets? }>`	`src/scripts/*` 约定。
`assets`	`string[]`	根目录 `assets/` 约定。
`bin`	`false \| Record<string, string \| { entry }>`	`src/cli.ts` 约定。
`lib`	`false \| string \| { entry, dts? }`	`src/index.ts` 约定。
`routes`	路由图策略	由约定推导。
`output`	`{ distPath? }`	命令行下为 `artifact`；不带 `packageOutputs` 的 `build()` 下为 `dist`。
`runtime`	`{ node }`	Node 22.12。
`payload`	`Record<string, string \| { source, targets? }>`	无。
`state`	`false`	`src/state.ts` 约定。
`marketplace`	`boolean`	由适配器选择。
`dev`	`{ agentApi?, contracts?, runtime? }`	无。
`evals`	`{ include?, runsDir?, semanticGrader? }`	见下文。
`tools`	`{ rsbuild?, rspack? }`	无。

宿主作用域的扩展键（claude、codex、cursor、portable）由各 target 适配器通过对 AgentBundleConfigExtensions 的声明合并贡献。扩展值必须是严格的有限 JSON（AB4500），且宿主特定的值留在各自的适配器中，而不进入编译器核心。每个适配器所拥有的键的逐字段清单见宿主作用域声明。

生成的类型定义

配置是一份 TypeScript 契约，而不是运行时 schema：defineConfig 接受一个 AgentBundleConfig（或返回它的工厂函数），validateSource 则用结构化诊断强制执行本页的规则。下面这些精确形态在每次文档构建时由 TypeDoc 从包源码生成，因此不会与已发布的类型产生偏差。

字段	类型定义
整个配置	`AgentBundleConfig` · `defineConfig` · `ConfigFactory` · `ConfigFactoryContext`
`mcp`	`AgentBundleMcpConfig` · `AgentBundleMcpServer` · `AgentBundleMcpApp` · `McpTransport`
`payload`	`AgentBundlePayloadConfig` · `AgentBundlePayloadEntry` · `AgentBundlePrebuiltEntry`
`output`	`AgentBundleOutputConfig`
`runtime`	`AgentBundleRuntimeConfig`
`dev`	`AgentBundleDevConfig` · `AgentBundleDevContractsConfig` · `AgentBundleDevRuntimeConfig`
宿主扩展	`AgentBundleConfigExtensions` · `AgentBundlePortableConfig`
校验	`validateSource` · `validateModel` · `loadConfig`

plugin

字段	规则
`name`	必填。宿主原生的插件 slug，绝不是 npm 包名。
`description`	一句话，会写进生成的清单中。
`logo`	项目相对的图片路径。缺失、不是文件或位于项目之外报告 `AB4012`；在已构建产物中缺失或逃逸出部署树报告 `AB6025`。
`version`	已废弃。

package.json 对发布标识具有权威性。发布版本只在那里声明：与 package.json 不一致的 plugin.version 会报告 AB4008 警告，而任何地方都没有版本的发布构建会被 AB4013 拒绝，而不是交付 0.0.0-dev.<short-revision> 这个开发期回退值。该字段仅为兼容而保留，并将按照正常的破坏性变更策略移除。

hooks

键是七个标准事件：sessionStart、beforeTool、afterTool、stop、agentStart、agentStop、 workspaceOpen。值是一个条目或条目数组，每个条目要么是模块路径，要么是 { handler, tools?, targets?, timeout?, args? }。每个规范事件与工具选择器如何降级为宿主原生事件与匹配器，见生成的事件与钩子矩阵。

钩子结果契约完整地记录在钩子中。有一个字段值得在此重复，因为它很容易搞错：reason 是一个非空字符串，仅在拒绝 beforeTool、stop 或 agentStop 钩子时有效，而拒绝其中之一却不给出 reason 会失败。

output 与 runtime

output.distPath 是相对项目根目录的产物输出目录。命令行（build、prepack、dev）把它默认为 artifact，因为命令行同时运行包构建，而包构建拥有 dist/；编程式 build() 除非传入 packageOutputs: true，否则默认为 dist。逐次调用的 --output 标志优先，但同样受相同的项目根包含性检查约束；绝对或外部输出路径、形态无效的路径，或落入保留编译器命名空间的路径均不受支持（AB4707–AB4709）。

runtime.node 是 major.minor[.patch] 形式的最低 Node.js 版本。它只能抬高生成式可执行文件的默认下限，绝不能降低，且所选下限会作为 runtime.node 记录在产物清单中。这个下限本身在配置模型中介绍。

payload

键是产物根目录下的目标目录——一个位于编译器自有命名空间之外的安全单路径段——值是已经构建好的源目录。 payload 树按字节逐一复制，并且对编译器而言是不透明的：编译器无法改写其内部的同级引用，因此稳定的名字就是正确性契约。完整性仍然通过产物清单保持内容寻址。

evals

只接受三个键；其他一律拒绝。

字段	默认值	规则
`include`	`['evals/*/.eval.ts']`	非空的相对模式数组，且绝不逃逸出项目根目录。
`runsDir`	`.agent-bundle/runs`	项目根目录下的相对子目录。
`semanticGrader`	无	必须恰好包含 `harness` 与 `model`。`harness` 必须是 `'claude'`；`model` 必须是安全的模型标识符，而不是路径。

evals 块中的提供方凭据材料会被直接拒绝（EVAL_CREDENTIAL_REJECTED）—— Agent Bundle 复用宿主 CLI 已有的已登录会话。见安全。

import { const defineConfig: (config: AgentBundleConfig | ConfigFactory) => AgentBundleConfig | ConfigFactorydefineConfig } from 'agent-bundle/config';

export default function defineConfig(config: AgentBundleConfig | ConfigFactory): AgentBundleConfig | ConfigFactorydefineConfig({
  evals: {
    include: string[];
    runsDir: string;
    semanticGrader: {
        harness: string;
        model: string;
    };
}
evals: {
    include: string[]include: ['evals/**/*.eval.ts'],
    runsDir: stringrunsDir: '.agent-bundle/runs',
    semanticGrader: {
    harness: string;
    model: string;
}
semanticGrader: { harness: stringharness: 'claude', model: stringmodel: 'claude-sonnet-4-5' },
  },
  AgentBundleConfig.plugin: AgentBundlePluginConfigplugin: { AgentBundlePluginConfig.description?: string | undefineddescription: 'Evidence-backed project tools.', AgentBundlePluginConfig.name: stringname: 'my-plugin' },
  AgentBundleConfig.targets?: string[] | undefinedtargets: ['portable', 'claude'],
});

dev

仅用于开发、绝不会成为已构建产物一部分的设置。

字段	含义
`dev.agentApi`	从 `agent-bundle dev` 暴露那个经过认证、仅 loopback 的 Agent API。`--agent-api` / `--no-agent-api` 标志会覆盖它。
`dev.contracts.fixtures`	设置了 `dev.contracts` 时必填。项目相对路径的模块，其默认导出把路由 id 映射到契约夹具。声明 `dev.contracts` 会让 `agent-bundle dev` 从直接采用每个 epoch，改为以开发契约矩阵门控面向宿主的采用：检查失败的 epoch 仍会发布到 Workbench playground，但活跃的宿主连接与开发安装会保留最后一个通过的 epoch（`AB7211`）。块本身格式错误、夹具模块逃出项目根、无法加载或导出了错误的形状，则是 `AB7210`。
`dev.contracts.server`	矩阵要检查的 MCP 服务器。仅当项目恰好编译一个服务器时可省略。
`dev.runtime.provider`	开发期运行时 provider 模块。

tools

唯一的打包器逃生舱。两个片段都会以「最后但有界」的方式合并进框架合成的每一份打包器配置，并且产物不变式断言仍会在合并之后运行，因此破坏产物契约的逃生舱取值是一条硬性诊断，而不是一次无声的覆盖（AB472x）。

逃生舱在两份打包器引擎副本下执行：产物脚本、MCP 入口、钩子与包构建通过 Rslib 内嵌的 Rsbuild/Rspack 编译，而 MCP App 视图通过工作区固定的 @rsbuild/core 编译。绝不要基于导入的 @rspack/core 构造插件或执行 instanceof 检查——请使用传给 tools.rspack 变更函数的 utils 参数（(config, { rspack }) => ...），它总会交给你当前执行引擎自己的 rspack 对象。

#配置

#顶层字段

#生成的类型定义

#plugin

#hooks

#output 与 runtime

#payload

#evals

#dev

#tools

配置