@faapi/faapi 3.0.0 → 3.2.0

package/dist/index.d.ts

@@ -178,13 +178,48 @@ interface ResponseConfig {
     }) => unknown;
 }
 /**
- * LLM 提供方配置（Phase 2.4）
+ * model 级配置（Phase 3.5）
  *
- * 定义如何连接 LLM 服务（OpenAI 兼容 API），由 Phase 3.2 的 `@faapi/agent` 插件读取。
- * 支持 `provider` 标识 + OpenAI 兼容字段（apiKey / model / baseURL），
- * 额外字段透传给 LLM API（如 temperature / max_tokens）。
+ * 挂在 provider 下的单个 model 配置，model 特定字段透传给 LLM API
+ * （覆盖 provider 级同名字段）。空对象 `{}` 表示用 provider 级默认。
  *
- * `model` 是默认模型，agent 自身 `config.model` 可覆盖。
+ * ```ts
+ * models: {
+ *   'gpt-4o': {},                            // 用 provider 级默认
+ *   'gpt-4o-mini': { temperature: 0.5 },     // 覆盖 temperature
+ * }
+ * ```
+ */
+interface LlmModelConfig {
+    [key: string]: unknown;
+}
+/**
+ * LLM provider 配置（Phase 2.4，Phase 3.5 改为嵌套级联结构）
+ *
+ * 嵌套级联：provider 在外层，model 在 `models` 下挂多个。
+ * provider 级字段（`apiKey` / `baseURL`）共享给所有 model；
+ * model 级字段在 `models[modelName]` 里覆盖 provider 级同名字段。
+ *
+ * `config.agent.llms` 的 key 是 provider 名（如 `'openai'` / `'anthropic'`），
+ * `config.agent.defaultLlm` 指定默认 provider key（不传时用 `llms` 第一个 key）。
+ *
+ * 由 Phase 3.2 的 `@faapi/agent` 插件读取，调 `createProvider` 创建实例存 Map。
+ *
+ * ```ts
+ * llms: {
+ *   openai: {
+ *     provider: 'openai',
+ *     apiKey: process.env.OPENAI_API_KEY,
+ *     baseURL: 'https://api.openai.com/v1',
+ *     models: { 'gpt-4o': {}, 'gpt-4o-mini': { temperature: 0.5 } },
+ *   },
+ *   anthropic: {
+ *     provider: 'anthropic',
+ *     apiKey: process.env.ANTHROPIC_API_KEY,
+ *     models: { 'claude-3-5-sonnet': {} },
+ *   },
+ * }
+ * ```
  */
 interface LlmConfig {
     /**
@@ -199,10 +234,6 @@ interface LlmConfig {
      * 如 `process.env.OPENAI_API_KEY`。
      */
     apiKey?: string;
-    /**
-     * 默认模型（如 'gpt-4o'），agent 自身 `config.model` 优先
-     */
-    model?: string;
     /**
      * API 基础 URL（可选，用于 OpenAI 兼容 API 如 Azure OpenAI / 中转服务）
      *
@@ -210,14 +241,24 @@ interface LlmConfig {
      */
     baseURL?: string;
     /**
-     * 其他透传参数（如 temperature / max_tokens / top_p）
+     * 该 provider 下挂的 model 列表（key 是 model 名）
+     *
+     * handler 通过 `agent.run(input, { model: 'gpt-4o' })` 切换 model,
+     * 框架按 model 名在所有 provider 的 `models` 里查找定位 provider（详见
+     * [agentHandle](../../agent/src/agentHandle.md) 的 Run-level 覆盖优先级表）。
+     * model 级字段（如 `temperature`）覆盖 provider 级同名字段。
+     */
+    models: Record<string, LlmModelConfig>;
+    /**
+     * 其他透传参数（provider 级，如 temperature / top_p / max_tokens）
      *
      * 这些字段原样传给 LLM API，由 provider 适配器处理。
+     * model 级 `models[modelName]` 的同名字段优先。
      */
     [key: string]: unknown;
 }
 /**
- * agent 子系统全局配置（Phase 2.4）
+ * agent 子系统全局配置（Phase 2.4，Phase 3.5 LLM 配置改为嵌套级联）
  *
  * 提供 agent 子系统的全局默认值，所有字段均可选，未设置时用框架默认值。
  * agent 自身 `config.maxTurns` / `config.model` 优先于全局配置。
@@ -226,11 +267,17 @@ interface LlmConfig {
  * import type { FaapiConfig } from '@faapi/faapi';
  * export default {
  *   agent: {
- *     llm: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' },
+ *     llms: {
+ *       openai: {
+ *         provider: 'openai',
+ *         apiKey: process.env.OPENAI_API_KEY,
+ *         models: { 'gpt-4o': {}, 'gpt-4o-mini': { temperature: 0.5 } },
+ *       },
+ *     },
+ *     defaultLlm: 'openai',
  *     defaultAgent: 'researcher',
  *     maxTurns: 10,
  *     maxAgentDepth: 3,
- *     defaultTools: ['weather.getWeather'],
  *   },
  * } satisfies FaapiConfig;
  * ```
@@ -239,11 +286,22 @@ interface LlmConfig {
  */
 interface AgentConfig {
     /**
-     * LLM 提供方配置（Phase 3.2 由 @faapi/agent 插件使用）
+     * LLM provider 配置映射（Phase 3.5 改为嵌套级联结构，key 是 provider 名）
+     *
+     * 值是 [LlmConfig]（含 `models`）。plugin setup 时遍历每个 LlmConfig 调
+     * `createProvider` 创建实例存 Map，handler 通过 `agent.run(input, { model })`
+     * 切换 provider + model（详见 [agentHandle](../../agent/src/agentHandle.md)）。
      *
      * 未设置时 Phase 3.x 插件无法调用 LLM，agent 的 `run` 函数仍可手动实现。
      */
-    llm?: LlmConfig;
+    llms?: Record<string, LlmConfig>;
+    /**
+     * 默认 provider key（Phase 3.5）
+     *
+     * `agent.run` 不传 `options.model` 时用此 key 对应的 provider 实例。
+     * 未设置时用 `llms` 的第一个 key（`Object.keys(llms)[0]`）。
+     */
+    defaultLlm?: string;
     /**
      * 默认 agent 名，用于 `agent` 参数注入（[injectParams](../injection/injectParams.md) Phase 2.3）
      *
@@ -252,13 +310,6 @@ interface AgentConfig {
      * 注入 `AgentHandle`（含可调用 `run`）。
      */
     defaultAgent?: string;
-    /**
-     * 默认 tool 列表，所有 agent 都可用（无需在每个 agent 的 `tools` 重复声明）
-     *
-     * 与 agent 自身 `tools` 合并（都加入可用 tool 集合，去重）。
-     * 由 `@faapi/agent` 插件在 setup 时合并到 agent 的 tool 引用列表。
-     */
-    defaultTools?: string[];
     /**
      * 默认最大对话轮数（覆盖 agent 自身 `config.maxTurns`，agent 自身配置优先）
      *
@@ -271,6 +322,31 @@ interface AgentConfig {
      * 默认值由 Phase 3.x 的 @faapi/agent 插件定义（如 3）。
      */
     maxAgentDepth?: number;
+    /**
+     * 启用 tracing 的全局默认值（默认 true）
+     *
+     * 开启时 `agent.run()` / `agent.stream()` 返回的 `result.trace` /
+     * `chunk.traceEvent` 填充结构化调用明细（按轮次组织的 LLM 调用、tool 调用、
+     * sub-agent 嵌套调用事件,含 timing 与 token 用量）。
+     *
+     * 三层覆盖优先级：`AgentRunOptions.enableTracing` > agent 自身配置 >
+     * 此全局配置 > 默认 `true`。
+     *
+     * 业务方在生产主路径（高 QPS 端点）显式设 `false` 关闭以零开销运行：
+     *
+     * ```ts
+     * import type { FaapiConfig } from '@faapi/faapi';
+     * export default {
+     *   agent: {
+     *     enableTracing: false,
+     *     llms: { openai: { provider: 'openai', apiKey: '...', models: { 'gpt-4o': {} } } },
+     *   },
+     * } satisfies FaapiConfig;
+     * ```
+     *
+     * 详见 `@faapi/agent` 的 [trace](../../agent/src/trace.md) 文档。
+     */
+    enableTracing?: boolean;
 }
 /**
  * faapi 配置文件类型
@@ -403,19 +479,25 @@ interface FaapiConfig {
     /**
      * agent 子系统全局配置（Phase 2.4）
      *
-     * 提供 agent 子系统的全局默认值：LLM 提供方、默认 agent、默认共享 tool、
+     * 提供 agent 子系统的全局默认值：LLM 提供方、默认 agent、
      * 最大对话轮数、agent 调用 agent 的最大递归深度。
      *
      * agent 自身 `config.maxTurns` / `config.model` 优先于全局配置。
-     * `defaultTools` 与 agent 自身 `tools` 合并（去重）。
+     * tool 引用列表只在每个 agent 自身的 `config.tools` 里声明（无全局共享 defaultTools）。
      *
      * ```ts
      * import type { FaapiConfig } from '@faapi/faapi';
      * export default {
      *   agent: {
-     *     llm: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' },
+     *     llms: {
+     *       openai: {
+     *         provider: 'openai',
+     *         apiKey: process.env.OPENAI_API_KEY,
+     *         models: { 'gpt-4o': {} },
+     *       },
+     *     },
+     *     defaultLlm: 'openai',
      *     defaultAgent: 'researcher',
-     *     defaultTools: ['weather.getWeather'],
      *     maxTurns: 10,
      *     maxAgentDepth: 3,
      *   },
@@ -775,47 +857,65 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
 };
 
 /**
- * Agent 完整元数据
+ * Agent 的 LLM 可见核心字段
  *
- * 由 [extractAgentMetadata](./extractAgentMetadata.md) 产出，合并路径推导字段
- * (来自 [scanAgents](../agents/scanAgents.md) 的 `AgentManifest`)与 AST 提取字段
- * (JSDoc 描述、`@agent` 覆盖名、config 块字段)。
+ * 描述"agent 是什么"——LLM 真正需要消费的字段,**不含**代码本体加载细节
+ * (filePath / hasRun)。文件型 agent 与 DB-driven skill 都实现此接口。
  *
- * 与 [ToolMetadata](./extractToolMetadata.md) 对称——一个从函数导出提取 JSDoc + 参数类型，
- * 一个从 config 导出提取 JSDoc + 配置块。
+ * - 文件型 agent:由 [AgentMetadata](./extractAgentMetadata.md) 继承扩展,
+ *   额外含 `filePath` / `hasRun`(代码本体加载用)
+ * - DB-driven skill:业务方 plugin 从 DB 字段映射到本接口即可,无需填占位值
+ *   (skill 无源文件,不走 `loadAgentModule`,自然不读 filePath / hasRun)
  *
- * 字段来源：
- * - `name` — `@agent` JSDoc 覆盖值，或 `pathMeta.name`(目录推导)
- * - `filePath` / `hasConfig` / `hasRun` — 由 `pathMeta` 透传
- * - `description` — JSDoc 注释块自由文本(对 LLM 可见)
- * - `systemPrompt` / `tools` / `agents` / `model` / `maxTurns` — config 块字面量提取
+ * `@faapi/agent` 子包的 `Agent` 类、`agentRegistry` 查询入口、`asTool` 包装
+ * 都消费 `AgentCore`,实现"agent 与 skill 走同一运行时链路"。
  */
-interface AgentMetadata {
+interface AgentCore {
     /** agent 名(`@agent` JSDoc 覆盖值 或 目录推导值) */
     name: string;
-    /** JSDoc 描述(agent 描述，对 LLM 可见)，无 JSDoc 或 JSDoc 无自由文本时为 `undefined` */
+    /** JSDoc 描述(agent 描述,对 LLM 可见),无 JSDoc 或 JSDoc 无自由文本时为 `undefined` */
     description?: string;
-    /** 源码相对路径(从 `pathMeta` 透传) */
-    filePath: string;
-    /** 是否导出 config 块(从 `pathMeta` 透传) */
-    hasConfig: boolean;
-    /** 是否导出 run 函数(从 `pathMeta` 透传) */
-    hasRun: boolean;
-    /** 系统提示词(config 块字面量提取)，无/非字面量时为 `undefined` */
+    /** 系统提示词(config 块字面量提取),无/非字面量时为 `undefined` */
     systemPrompt?: string;
-    /** agent 显式声明可用的 tool 引用列表(config 块字面量提取)，无/含非字面量元素时为 `undefined` */
+    /** agent 显式声明可用的 tool 引用列表(config 块字面量提取),无/含非字面量元素时为 `undefined` */
     tools?: string[];
-    /** 可调用的其他 agent 名列表(config 块字面量提取)，无/含非字面量元素时为 `undefined` */
+    /** 可调用的其他 agent 名列表(config 块字面量提取),无/含非字面量元素时为 `undefined` */
     agents?: string[];
-    /** LLM 模型名(config 块字面量提取)，无/非字面量时为 `undefined` */
+    /** LLM 模型名(config 块字面量提取),无/非字面量时为 `undefined` */
     model?: string;
-    /** 最大对话轮数(config 块字面量提取)，无/非字面量时为 `undefined` */
+    /** 最大对话轮数(config 块字面量提取),无/非字面量时为 `undefined` */
     maxTurns?: number;
 }
+/**
+ * Agent 完整元数据(文件型 agent)
+ *
+ * 继承 [AgentCore](./extractAgentMetadata.md) 的 LLM 字段,额外扩展**代码本体加载细节**:
+ * - `filePath` — `loadAgentModule` 加载 `handler.js` 产物提取 `run` 函数用
+ * - `hasRun` — 是否导出 `run` 函数(`Agent.executeSubAgent` 据此决定走自定义 run
+ *   还是默认 reactLoop)
+ *
+ * DB-driven skill 不实现此接口(无源文件,无需加载),只实现 `AgentCore`。
+ *
+ * 由 [extractAgentMetadata](./extractAgentMetadata.md) 产出,合并路径推导字段
+ * (来自 [scanAgents](../agents/scanAgents.md) 的 `AgentManifest`)与 AST 提取字段
+ * (JSDoc 描述、`@agent` 覆盖名、config 块字段)。
+ *
+ * 字段来源：
+ * - `name` — `@agent` JSDoc 覆盖值,或 `pathMeta.name`(目录推导)
+ * - `filePath` / `hasRun` — 由 `pathMeta` 透传
+ * - `description` — JSDoc 注释块自由文本(对 LLM 可见)
+ * - `systemPrompt` / `tools` / `agents` / `model` / `maxTurns` — config 块字面量提取
+ */
+interface AgentMetadata extends AgentCore {
+    /** 源码相对路径(从 `pathMeta` 透传),`loadAgentModule` 据此加载 `handler.js` 提取 `run` */
+    filePath: string;
+    /** 是否导出 `run` 函数(从 `pathMeta` 透传),`Agent.executeSubAgent` 据此选择自定义 run / 默认 reactLoop */
+    hasRun: boolean;
+}
 /**
  * 路径推导的 agent 元数据(由 [scanAgents](../agents/scanAgents.ts) 计算)
  *
- * 透传到 [AgentMetadata](./extractAgentMetadata.ts) 输出，与 AST 提取字段合并。
+ * 透传到 [AgentMetadata](./extractAgentMetadata.ts) 输出,与 AST 提取字段合并。
  * 与 [ToolPathMeta](./extractToolMetadata.md) 对称。
  */
 interface AgentPathMeta {
@@ -823,14 +923,37 @@ interface AgentPathMeta {
     name: string;
     /** 源码相对路径(如 `src/agents/researcher/handler.ts`) */
     filePath: string;
-    /** 是否导出 config 块(scanAgents 正则检测) */
-    hasConfig: boolean;
-    /** 是否导出 run 函数(scanAgents 正则检测) */
+    /** 是否导出 `run` 函数(scanAgents 正则检测) */
     hasRun: boolean;
 }
 
 /**
- * Tool 完整元数据
+ * Tool 的 LLM 可见核心字段
+ *
+ * 描述"tool 是什么"——LLM 真正需要消费的字段(发往 LLM 的 tool 定义只含
+ * `name` / `description` / input schema),**不含**代码本体加载细节
+ * (`filePath` / `functionName` / `inputTypeName`)。
+ *
+ * 与 [AgentCore](./extractAgentMetadata.md) 对称——LLM-facing 字段与代码加载
+ * 细节分离,便于未来扩展(如 DB-driven tool 只实现 `ToolCore` 即可)。
+ *
+ * `toolRegistry` 查询入口 / `@faapi/agent` 子包的 `buildToolDefinitions`
+ * 都消费 `ToolCore` 字段组装 LLM tool 列表。
+ */
+interface ToolCore {
+    /** tool 名(`@tool` JSDoc 覆盖值 或 路径推导值) */
+    name: string;
+    /** JSDoc 描述(tool 描述,对 LLM 可见),无 JSDoc 或 JSDoc 无自由文本时为 `undefined` */
+    description?: string;
+}
+/**
+ * Tool 完整元数据(文件型 tool)
+ *
+ * 继承 [ToolCore](./extractToolMetadata.md) 的 LLM 字段,额外扩展**代码本体加载细节**:
+ * - `filePath` — `loadToolModule` 加载 `handler.js` 产物定位函数用
+ * - `functionName` — 源码导出函数名(不受 `@tool` 覆盖影响,AST 定位 + 运行时 resolveExport 用)
+ * - `inputTypeName` — 第一个参数的 TypeReference 名(供 [extractTypeInfo](./extractHandlerTypes.md)
+ *   生成 zod schema;运行时 `resolveToolSchema` 据此定位 `zod.js`)
  *
  * 由 [extractToolMetadata](./extractToolMetadata.md) 产出,合并路径推导字段
  * (来自 [scanTools](../tools/scanTools.md) 的 `ToolManifest`)与 AST 提取字段
@@ -838,15 +961,11 @@ interface AgentPathMeta {
  *
  * 字段来源:
  * - `name` — `@tool` JSDoc 覆盖值,或 `pathMeta.name`(路径推导)
- * - `filePath` / `functionName` — 由 `pathMeta` 透传
  * - `description` — JSDoc 注释块自由文本(对 LLM 可见)
+ * - `filePath` / `functionName` — 由 `pathMeta` 透传
  * - `inputTypeName` — 第一个参数的 TypeReference 名(供 [extractTypeInfo](./extractHandlerTypes.md) 生成 zod schema)
  */
-interface ToolMetadata {
-    /** tool 名(`@tool` JSDoc 覆盖值 或 路径推导值) */
-    name: string;
-    /** JSDoc 描述(tool 描述,对 LLM 可见),无 JSDoc 或 JSDoc 无自由文本时为 `undefined` */
-    description?: string;
+interface ToolMetadata extends ToolCore {
     /** 第一个参数的 interface/type 名(用于生成 zod schema),
      *  无参数/参数无类型标注/参数为内联类型字面量时为 `undefined` */
     inputTypeName?: string;
@@ -868,12 +987,36 @@ interface ToolPathMeta {
 }
 
 /**
- * 按名查找单个 agent
+ * 按名查找单个 agent 的 LLM 可见元数据
+ *
+ * 返回 [AgentCore](../ast/extractAgentMetadata.md) 字段(name / description /
+ * systemPrompt / tools / agents / model / maxTurns),**不含** `filePath` / `hasRun`。
+ *
+ * 仅查文件 registry（编译期 `faapi-agents.js` 产物来源）。**不 fallback 到
+ * [skillRegistry](./skillRegistry.ts)**——skill 与 agent 职责正交不耦合,
+ * skill 由业务方 plugin 内部使用,不参与 agent 查询链路。
+ *
+ * 用于 LLM-facing 场景(`agents` 参数注入、`asTool` 描述、
+ * `resolveAgentTools` / `resolveSubAgents` 解析)。
+ * 加载 handler.js 执行 `run` 函数请用 [getAgentEntry](#getAgentEntry)。
  *
  * @param name agent 名（如 `researcher`，含 `@agent` 覆盖值）
+ * @returns `AgentCore` 或 `undefined`（未注册）
+ */
+declare function getAgent(name: string): AgentCore | undefined;
+/**
+ * 按名查找单个 agent 的完整元数据(含代码加载细节)
+ *
+ * 返回 [AgentMetadata](../ast/extractAgentMetadata.md) —— 继承 AgentCore
+ * 额外含 `filePath` / `hasRun`,供 `@faapi/agent` 子包 `loadAgentModule`
+ * 加载 handler.js 执行自定义 `run` 函数。
+ *
+ * 调用方需先判断 `entry?.hasRun` 再决定是否加载 handler.js。
+ *
+ * @param name agent 名
  * @returns `AgentMetadata` 或 `undefined`（未注册）
  */
-declare function getAgent(name: string): AgentMetadata | undefined;
+declare function getAgentEntry(name: string): AgentMetadata | undefined;
 /**
  * agent 包装为 tool 的描述符
  *
@@ -884,6 +1027,10 @@ declare function getAgent(name: string): AgentMetadata | undefined;
  *
  * `name` 加 `agent.` 前缀避免与常规 tool 冲突，reactLoop 据此识别 sub-agent 递归。
  * 不含 input schema——agent `run` 函数参数为开放式（任意 JSON），无类型约束。
+ *
+ * `metadata` 为 [AgentCore](../ast/extractAgentMetadata.md) 类型——reactLoop 只消费
+ * LLM-facing 字段(systemPrompt / model / maxTurns);加载 handler.js 执行 `run`
+ * 函数由 `@faapi/agent` 子包通过 [getAgentEntry](#getAgentEntry) 单独获取。
  */
 interface AgentToolDescriptor {
     /** 标识此 tool 实际是 agent（reactLoop 据此走 sub-agent 递归） */
@@ -894,19 +1041,20 @@ interface AgentToolDescriptor {
     agentName: string;
     /** 描述（对 LLM 可见，来自 `agent.description`），无 JSDoc 描述时为 `undefined` */
     description?: string;
-    /** agent 元数据引用（reactLoop 取 `systemPrompt` / `model` / `maxTurns` / `filePath` 等） */
-    metadata: AgentMetadata;
+    /** agent LLM 可见元数据引用（reactLoop 取 `systemPrompt` / `model` / `maxTurns`） */
+    metadata: AgentCore;
 }
 /**
  * 解析 agent 可用 tool 集合
  *
  * 只返回 agent 显式声明的 tool（agent config 块的 `tools` 字段）。
- * 不在此处合并全局 `defaultTools`——`defaultTools` 的合并由 `@faapi/agent` 的
- * `Agent.buildToolDefinitions` 在更上层完成（与 sub-agent 一起按 `name` 去重）。
  * `resolveAgentTools` 只关心 agent 自身显式声明的部分，职责单一。
+ * sub-agent 的合并由 `@faapi/agent` 的 `Agent.buildToolDefinitions` 在更上层完成（按 `name` 去重）。
  *
  * agent 必须显式声明用哪些 tool，显式优于隐式。
  *
+ * 通过 [getAgent](#getAgent) 查询文件型 agent,不 fallback 到 skillRegistry。
+ *
  * `tools` 中未在 toolRegistry 找到的 tool 名静默跳过（tool 可选可用，不强制存在）。
  *
  * 跨注册表依赖 [toolRegistry](./toolRegistry.ts) 的 `getTool`，
@@ -920,7 +1068,14 @@ declare function resolveAgentTools(name: string): ToolMetadata[];
  * 解析 agent 可调用的子 agent 集合
  *
  * 读 `agent.agents` 字段（[extractAgentMetadata](../ast/extractAgentMetadata.md)
- * 提取的 `config.agents` 字面量列表），按名查找已注册 agent。
+ * 提取的 `config.agents` 字面量列表），按名查找已注册文件型 agent。
+ *
+ * 不 fallback 到 skillRegistry——skill 不参与 sub-agent 递归,
+ * 父 agent 的 `agents` 列表只能引用文件型 agent 名。
+ *
+ * 返回 `AgentCore[]`(LLM-facing 字段,供 `@faapi/agent` 子包包装为
+ * `AgentToolDescriptor` 发给 LLM)。加载 sub-agent handler.js 执行 `run` 函数
+ * 由 `@faapi/agent` 子包通过 [getAgentEntry](#getAgentEntry) 单独获取。
  *
  * reactLoop 组装 LLM tool 列表：
  * ```ts
@@ -931,34 +1086,26 @@ declare function resolveAgentTools(name: string): ToolMetadata[];
  * ```
  *
  * @param name agent 名
- * @returns `AgentMetadata[]`（`agents` 未设置 / agent 未注册返回空数组）
+ * @returns `AgentCore[]`（`agents` 未设置 / agent 未注册返回空数组）
  */
-declare function resolveSubAgents(name: string): AgentMetadata[];
+declare function resolveSubAgents(name: string): AgentCore[];
 
 /**
  * 加载后的 agent 模块
  *
- * 与 [ToolModule](./loadToolModule.md) 对称——agent 不像 tool 只有一个 handler 函数,
- * 它导出 `config` 块（对象，含运行时可能动态求值的字段）和可选的 `run` 函数。
+ * 与 [ToolModule](./loadToolModule.md) 对称——agent 的代码本体只有可选的 `run` 函数
+ * (自定义 agent 运行逻辑,替代默认 reactLoop)。
  *
- * - `config`：agent 配置对象（含 systemPrompt / tools / agents / model / maxTurns 等，
- *   以及任何非字面量字段——AST 阶段仅提取字面量，动态值需运行时加载）
- * - `run`：自定义 agent 运行逻辑（可选，替代默认 reactLoop）
+ * > `config` 字段已移除——`AgentMetadata` 已含 AST 提取的字面量字段
+ * > (systemPrompt / tools / agents / model / maxTurns),`AgentModule.config`
+ * > 原本用于运行时拿到完整 config 对象(含动态字段),但 `executeSubAgent`
+ * > 拿到 `mod.config` 后从不读取(run 函数在自己模块内直接引用 config 变量),
+ * > 属于死链路,故移除。
  *
- * `AgentMetadata`（从 `faapi-agents.js` 水合）已含字面量字段，`loadAgentModule`
- * 用于在运行时拿到完整 config 对象（含动态字段）和 run 函数引用。
+ * `AgentMetadata`（从 `faapi-agents.js` 水合）已含字面量字段,本模块仅用于
+ * 在运行时拿到 `run` 函数引用。
  */
 interface AgentModule {
-    /**
-     * agent 配置对象（含运行时字段）
-     *
-     * `hasConfig` 为 true 时一定存在；为 false 时为 `undefined`。
-     * 可能是对象字面量（`export const config = {...}`）或函数返回值（`export function config() { return {...} }`）。
-     *
-     * 函数形式：本模块调用 `config()` 拿到返回值（无参调用，与 AST 阶段的字面量提取不同——
-     * 运行时可拿到动态求值结果）。
-     */
-    config: Record<string, unknown> | undefined;
     /**
      * 自定义 agent 运行函数（可选）
      *
@@ -968,7 +1115,7 @@ interface AgentModule {
     run: ((...args: unknown[]) => unknown) | undefined;
 }
 /**
- * 动态 import agent handler 文件并提取 `config` 和 `run` 导出
+ * 动态 import agent handler 文件并提取 `run` 导出
  *
  * Dev 按需编译模式（Vite 风格）：先 `ensureCompiled` 确保产物存在再 import,
  * 避免 import 不存在的文件污染 Vite SSR 内部状态（详见 [loadRouteModule](./loadRouteModule.md)）。
@@ -976,20 +1123,18 @@ interface AgentModule {
  *
  * 与 [loadToolModule](./loadToolModule.md) 的差异：
  * - tool 按 `functionName` 提取单个函数（校验为 function）
- * - agent 提取 `config`（对象或函数返回对象）和 `run`（函数，可选）
- * - agent 的 config 可能为函数形式（`export function config() { return {...} }`），
- *   本模块自动调用拿到返回值（与 AST 阶段仅提字面量不同——运行时拿动态值）
+ * - agent 只提取 `run`（函数，可选）——config 块字段已在 AST 阶段提取为字面量,
+ *   运行时无需再加载 config 对象
  *
  * 错误传递：
  * - 编译失败 → 抛 "Failed to compile agent module"
  * - import 失败 → 抛 "Failed to load agent module"
  *
  * @param filePath agent handler 文件的绝对路径（产物形式，如 `dist/agents/researcher/handler.js`）
- * @param hasConfig 是否应提取 config 导出（来自 `AgentMetadata.hasConfig`）
  * @param hasRun 是否应提取 run 导出（来自 `AgentMetadata.hasRun`）
  * @param rootDir 项目根目录（按需编译模式用，可选）
  */
-declare function loadAgentModule(filePath: string, hasConfig: boolean, hasRun: boolean, rootDir?: string): Promise<AgentModule>;
+declare function loadAgentModule(filePath: string, hasRun: boolean, rootDir?: string): Promise<AgentModule>;
 
 /**
  * 加载后的 tool 模块
@@ -1064,6 +1209,52 @@ declare function loadToolSchema(tool: ToolMetadata, rootDir?: string): Promise<T
  */
 declare function getTool(name: string): ToolMetadata | undefined;
 
+/**
+ * 水合 skill 注册表(全量替换)
+ *
+ * 业务方 plugin `lifecycle.onReady` 启动期调用:全量查 DB → 转 `AgentCore[]`
+ * → 调本函数灌入。与 `hydrateAgentRegistry` 同构,全量替换而非增量。
+ *
+ * 运行时增量更新场景(DB change stream)用 [upsertSkill](#upsertSkill) /
+ * [removeSkill](#removeSkill),不走本函数。
+ *
+ * @param skills 从 DB / 外部源加载并转好的 `AgentCore[]`
+ */
+declare function hydrateSkillRegistry(skills: AgentCore[]): void;
+/**
+ * 单条增改 skill(运行时增量)
+ *
+ * 监听 DB change stream 的 `insert` / `update` 事件时调用。
+ * `Map.set` 原子操作,并发安全(多请求同时 upsert 最后一次 wins)。
+ *
+ * 同名 skill 覆盖(更新),不重复累积。
+ *
+ * @param core skill 的 LLM 可见元数据
+ */
+declare function upsertSkill(core: AgentCore): void;
+/**
+ * 单条删除 skill(运行时增量)
+ *
+ * 监听 DB change stream 的 `delete` 事件时调用。
+ * 幂等:删除不存在的 name 静默无操作,不抛错。
+ *
+ * @param name skill 名
+ */
+declare function removeSkill(name: string): void;
+/**
+ * 按名查单个 skill
+ *
+ * @param name skill 名
+ * @returns `AgentCore` 或 `undefined`(未注册)
+ */
+declare function getSkill(name: string): AgentCore | undefined;
+/**
+ * 返回所有已注册 skill
+ *
+ * 返回副本,调用方修改不影响内部状态(与 `listAgents` / `listTools` 同构)。
+ */
+declare function listSkills(): AgentCore[];
+
 /**
  * agent handle 工厂注册表（单例）
  *
@@ -1140,7 +1331,8 @@ declare const ROUTE_NOT_FOUND = "ROUTE_NOT_FOUND";
 declare const METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED";
 declare const INTERNAL_ERROR = "INTERNAL_ERROR";
 declare const MODULE_LOAD_ERROR = "MODULE_LOAD_ERROR";
-type ErrorCode = typeof VALIDATION_ERROR | typeof ROUTE_NOT_FOUND | typeof METHOD_NOT_ALLOWED | typeof INTERNAL_ERROR | typeof MODULE_LOAD_ERROR;
+declare const PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE";
+type ErrorCode = typeof VALIDATION_ERROR | typeof ROUTE_NOT_FOUND | typeof METHOD_NOT_ALLOWED | typeof INTERNAL_ERROR | typeof MODULE_LOAD_ERROR | typeof PAYLOAD_TOO_LARGE;
 
 declare class FaapiError extends Error {
     readonly code: ErrorCode;
@@ -1317,4 +1509,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type AgentConfig, type AgentHandleFactory, type AgentMetadata, type AgentModule, type AgentPathMeta, type AgentToolDescriptor, type ProdApp as App, CorsOptions, type CreateAppOptions, type DevApp, type FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, HelmetOptions, type InjectOptions, type InjectResponse, InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LlmConfig, LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type ToolMetadata, type ToolModule, type ToolPathMeta, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, createProdApp as createApp, createDevApp, createProdApp, createProgram, extractTypeInfo, getAgent, getApp, getInputTypeForMethod, getTool, invalidateProgramCache, loadAgentModule, loadConfig, loadEnv, loadToolModule, loadToolSchema, registerAgentHandleFactory, resolveAgentTools, resolveSubAgents, resolveTypeNode };
+export { type AgentConfig, type AgentCore, type AgentHandleFactory, type AgentMetadata, type AgentModule, type AgentPathMeta, type AgentToolDescriptor, type ProdApp as App, CorsOptions, type CreateAppOptions, type DevApp, type FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, HelmetOptions, type InjectOptions, type InjectResponse, InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LlmConfig, type LlmModelConfig, LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type ToolCore, type ToolMetadata, type ToolModule, type ToolPathMeta, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, createProdApp as createApp, createDevApp, createProdApp, createProgram, extractTypeInfo, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadToolModule, loadToolSchema, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, upsertSkill };