@faapi/faapi 2.0.1 → 3.1.0

package/dist/index.d.ts

@@ -177,6 +177,152 @@ interface ResponseConfig {
         message: string;
     }) => unknown;
 }
+/**
+ * model 级配置（Phase 3.5）
+ *
+ * 挂在 provider 下的单个 model 配置，model 特定字段透传给 LLM API
+ * （覆盖 provider 级同名字段）。空对象 `{}` 表示用 provider 级默认。
+ *
+ * ```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 {
+    /**
+     * LLM 提供方标识（如 'openai' / 'anthropic'）
+     *
+     * Phase 3.2 的 provider 模块按此值选择对应的 LLM 适配器。
+     */
+    provider: string;
+    /**
+     * API key（从 `process.env` 读取，避免硬编码）
+     *
+     * 如 `process.env.OPENAI_API_KEY`。
+     */
+    apiKey?: string;
+    /**
+     * API 基础 URL（可选，用于 OpenAI 兼容 API 如 Azure OpenAI / 中转服务）
+     *
+     * 未设置时用 provider 对应的官方默认值（如 'https://api.openai.com/v1'）。
+     */
+    baseURL?: string;
+    /**
+     * 该 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，Phase 3.5 LLM 配置改为嵌套级联）
+ *
+ * 提供 agent 子系统的全局默认值，所有字段均可选，未设置时用框架默认值。
+ * agent 自身 `config.maxTurns` / `config.model` 优先于全局配置。
+ *
+ * ```ts
+ * import type { FaapiConfig } from '@faapi/faapi';
+ * export default {
+ *   agent: {
+ *     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,
+ *   },
+ * } satisfies FaapiConfig;
+ * ```
+ *
+ * 详见 `src/config/configTypes.md` agent 配置块章节。
+ */
+interface AgentConfig {
+    /**
+     * 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` 函数仍可手动实现。
+     */
+    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）
+     *
+     * Phase 2.3 的 `agent` 参数注入暂返回 `undefined`，Phase 3.x 的 @faapi/agent 插件
+     * 读取此值从 [agentRegistry](../injection/agentRegistry.md) 查找对应 agent 元数据，
+     * 注入 `AgentHandle`（含可调用 `run`）。
+     */
+    defaultAgent?: string;
+    /**
+     * 默认最大对话轮数（覆盖 agent 自身 `config.maxTurns`，agent 自身配置优先）
+     *
+     * Phase 3.3 的 reactLoop 使用此值作为递归深度防护。
+     */
+    maxTurns?: number;
+    /**
+     * agent 调用 agent 的最大递归深度（防护无限递归，Phase 3.3 reactLoop 使用）
+     *
+     * 默认值由 Phase 3.x 的 @faapi/agent 插件定义（如 3）。
+     */
+    maxAgentDepth?: number;
+}
 /**
  * faapi 配置文件类型
  *
@@ -305,6 +451,37 @@ interface FaapiConfig {
      * ```
      */
     plugins?: PluginDeclaration[];
+    /**
+     * agent 子系统全局配置（Phase 2.4）
+     *
+     * 提供 agent 子系统的全局默认值：LLM 提供方、默认 agent、
+     * 最大对话轮数、agent 调用 agent 的最大递归深度。
+     *
+     * agent 自身 `config.maxTurns` / `config.model` 优先于全局配置。
+     * tool 引用列表只在每个 agent 自身的 `config.tools` 里声明（无全局共享 defaultTools）。
+     *
+     * ```ts
+     * import type { FaapiConfig } from '@faapi/faapi';
+     * export default {
+     *   agent: {
+     *     llms: {
+     *       openai: {
+     *         provider: 'openai',
+     *         apiKey: process.env.OPENAI_API_KEY,
+     *         models: { 'gpt-4o': {} },
+     *       },
+     *     },
+     *     defaultLlm: 'openai',
+     *     defaultAgent: 'researcher',
+     *     maxTurns: 10,
+     *     maxAgentDepth: 3,
+     *   },
+     * } satisfies FaapiConfig;
+     * ```
+     *
+     * 详见 `src/config/configTypes.md` agent 配置块章节。
+     */
+    agent?: AgentConfig;
     /**
      * 扩展 ctx：在每次请求创建上下文后调用，可挂载自定义方法（如 ctx.xml、ctx.stream）
      *
@@ -654,6 +831,439 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
     mergedAllTypes: Map<string, HandlerTypeInfo>;
 };
 
+/**
+ * Agent 的 LLM 可见核心字段
+ *
+ * 描述"agent 是什么"——LLM 真正需要消费的字段,**不含**代码本体加载细节
+ * (filePath / hasRun)。文件型 agent 与 DB-driven skill 都实现此接口。
+ *
+ * - 文件型 agent:由 [AgentMetadata](./extractAgentMetadata.md) 继承扩展,
+ *   额外含 `filePath` / `hasRun`(代码本体加载用)
+ * - DB-driven skill:业务方 plugin 从 DB 字段映射到本接口即可,无需填占位值
+ *   (skill 无源文件,不走 `loadAgentModule`,自然不读 filePath / hasRun)
+ *
+ * `@faapi/agent` 子包的 `Agent` 类、`agentRegistry` 查询入口、`asTool` 包装
+ * 都消费 `AgentCore`,实现"agent 与 skill 走同一运行时链路"。
+ */
+interface AgentCore {
+    /** agent 名(`@agent` JSDoc 覆盖值 或 目录推导值) */
+    name: string;
+    /** JSDoc 描述(agent 描述,对 LLM 可见),无 JSDoc 或 JSDoc 无自由文本时为 `undefined` */
+    description?: string;
+    /** 系统提示词(config 块字面量提取),无/非字面量时为 `undefined` */
+    systemPrompt?: string;
+    /** agent 显式声明可用的 tool 引用列表(config 块字面量提取),无/含非字面量元素时为 `undefined` */
+    tools?: string[];
+    /** 可调用的其他 agent 名列表(config 块字面量提取),无/含非字面量元素时为 `undefined` */
+    agents?: string[];
+    /** LLM 模型名(config 块字面量提取),无/非字面量时为 `undefined` */
+    model?: string;
+    /** 最大对话轮数(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 提取字段合并。
+ * 与 [ToolPathMeta](./extractToolMetadata.md) 对称。
+ */
+interface AgentPathMeta {
+    /** 目录推导的 agent 名(如 `researcher`) */
+    name: string;
+    /** 源码相对路径(如 `src/agents/researcher/handler.ts`) */
+    filePath: string;
+    /** 是否导出 `run` 函数(scanAgents 正则检测) */
+    hasRun: boolean;
+}
+
+/**
+ * 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 提取字段
+ * (JSDoc 描述、`@tool` 覆盖名、第一个参数 interface 名)。
+ *
+ * 字段来源:
+ * - `name` — `@tool` JSDoc 覆盖值,或 `pathMeta.name`(路径推导)
+ * - `description` — JSDoc 注释块自由文本(对 LLM 可见)
+ * - `filePath` / `functionName` — 由 `pathMeta` 透传
+ * - `inputTypeName` — 第一个参数的 TypeReference 名(供 [extractTypeInfo](./extractHandlerTypes.md) 生成 zod schema)
+ */
+interface ToolMetadata extends ToolCore {
+    /** 第一个参数的 interface/type 名(用于生成 zod schema),
+     *  无参数/参数无类型标注/参数为内联类型字面量时为 `undefined` */
+    inputTypeName?: string;
+    /** 源码相对路径(从 `pathMeta` 透传) */
+    filePath: string;
+    /** 源码中的导出函数名(从 `pathMeta` 透传,AST 定位用,不受 `@tool` 覆盖影响) */
+    functionName: string;
+}
+/**
+ * 路径推导的 tool 元数据(由 [scanTools](../tools/scanTools.ts) 计算)
+ *
+ * 透传到 [ToolMetadata](./extractToolMetadata.ts) 输出,与 AST 提取字段合并。
+ */
+interface ToolPathMeta {
+    /** 路径推导的 tool 名(如 `weather.getWeather`) */
+    name: string;
+    /** 源码相对路径(如 `src/tools/weather/handler.ts`) */
+    filePath: string;
+}
+
+/**
+ * 按名查找单个 agent 的 LLM 可见元数据
+ *
+ * 返回 [AgentCore](../ast/extractAgentMetadata.md) 字段(name / description /
+ * systemPrompt / tools / agents / model / maxTurns),**不含** `filePath` / `hasRun`。
+ *
+ * skill fallback:先查 [skillRegistry](./skillRegistry.ts) 的 `getSkill`,
+ * 命中返回 skill 元数据(运行时业务方动态注册的 DB-driven skill);
+ * 未命中查文件 registry。
+ *
+ * 用于 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` 函数。
+ *
+ * **不 fallback 到 skillRegistry**——DB skill 无源文件,不走 `loadAgentModule`。
+ * 调用方需先判断 `entry?.hasRun` 再决定是否加载 handler.js。
+ *
+ * @param name agent 名
+ * @returns `AgentMetadata` 或 `undefined`（未注册 / DB skill 无文件）
+ */
+declare function getAgentEntry(name: string): AgentMetadata | undefined;
+/**
+ * agent 包装为 tool 的描述符
+ *
+ * 与 [ToolMetadata](../ast/extractToolMetadata.md) 平行结构，供 reactLoop 把
+ * agent 当作 tool 发给 LLM。reactLoop 按 `kind` 字段路由执行：
+ * - `'tool'` → `loadToolModule` 加载 handler 函数
+ * - `'agent'` → `loadAgentModule` 加载 agent handler + 递归 reactLoop
+ *
+ * `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 递归） */
+    kind: 'agent';
+    /** tool 名（默认 `agent.<agentName>`，避免与常规 tool 冲突） */
+    name: string;
+    /** agent 名（不含前缀，用于按名查找 agent 元数据） */
+    agentName: string;
+    /** 描述（对 LLM 可见，来自 `agent.description`），无 JSDoc 描述时为 `undefined` */
+    description?: string;
+    /** agent LLM 可见元数据引用（reactLoop 取 `systemPrompt` / `model` / `maxTurns`） */
+    metadata: AgentCore;
+}
+/**
+ * 解析 agent 可用 tool 集合
+ *
+ * 只返回 agent 显式声明的 tool（agent config 块的 `tools` 字段）。
+ * `resolveAgentTools` 只关心 agent 自身显式声明的部分，职责单一。
+ * sub-agent 的合并由 `@faapi/agent` 的 `Agent.buildToolDefinitions` 在更上层完成（按 `name` 去重）。
+ *
+ * agent 必须显式声明用哪些 tool，显式优于隐式。
+ *
+ * skill fallback:通过 [getAgent](#getAgent) 自动发现 DB-driven skill,
+ * skill 的 `tools` 字段同样会被解析。DB skill 引用的 tool 必须在 toolRegistry
+ * 注册（文件型 tool 或未来 DB-driven tool）。
+ *
+ * `tools` 中未在 toolRegistry 找到的 tool 名静默跳过（tool 可选可用，不强制存在）。
+ *
+ * 跨注册表依赖 [toolRegistry](./toolRegistry.ts) 的 `getTool`，
+ * 两个注册表由 `createAppBase` 在同一启动阶段水合。
+ *
+ * @param name agent 名
+ * @returns `ToolMetadata[]`（agent 未注册返回空数组）
+ */
+declare function resolveAgentTools(name: string): ToolMetadata[];
+/**
+ * 解析 agent 可调用的子 agent 集合
+ *
+ * 读 `agent.agents` 字段（[extractAgentMetadata](../ast/extractAgentMetadata.md)
+ * 提取的 `config.agents` 字面量列表），按名查找已注册 agent。
+ *
+ * skill fallback:通过 [getAgent](#getAgent) 自动发现 DB-driven skill。
+ * 父 agent 可以在 `agents` 列表里引用 DB skill 名,递归调用走相同链路。
+ *
+ * 返回 `AgentCore[]`(LLM-facing 字段,供 `@faapi/agent` 子包包装为
+ * `AgentToolDescriptor` 发给 LLM)。加载 sub-agent handler.js 执行 `run` 函数
+ * 由 `@faapi/agent` 子包通过 [getAgentEntry](#getAgentEntry) 单独获取。
+ *
+ * reactLoop 组装 LLM tool 列表：
+ * ```ts
+ * const tools = [
+ *   ...resolveAgentTools(name),                                    // 常规 tool
+ *   ...resolveSubAgents(name).map((a) => asTool(a.name)!),        // agent-as-tool
+ * ];
+ * ```
+ *
+ * @param name agent 名
+ * @returns `AgentCore[]`（`agents` 未设置 / agent 未注册返回空数组）
+ */
+declare function resolveSubAgents(name: string): AgentCore[];
+
+/**
+ * 加载后的 agent 模块
+ *
+ * 与 [ToolModule](./loadToolModule.md) 对称——agent 的代码本体只有可选的 `run` 函数
+ * (自定义 agent 运行逻辑,替代默认 reactLoop)。
+ *
+ * > `config` 字段已移除——`AgentMetadata` 已含 AST 提取的字面量字段
+ * > (systemPrompt / tools / agents / model / maxTurns),`AgentModule.config`
+ * > 原本用于运行时拿到完整 config 对象(含动态字段),但 `executeSubAgent`
+ * > 拿到 `mod.config` 后从不读取(run 函数在自己模块内直接引用 config 变量),
+ * > 属于死链路,故移除。
+ *
+ * `AgentMetadata`（从 `faapi-agents.js` 水合）已含字面量字段,本模块仅用于
+ * 在运行时拿到 `run` 函数引用。
+ */
+interface AgentModule {
+    /**
+     * 自定义 agent 运行函数（可选）
+     *
+     * `hasRun` 为 true 时一定为 function；为 false 时为 `undefined`。
+     * 调用方式由 `@faapi/agent` 子包的 Agent 类定义（Phase 3.x）。
+     */
+    run: ((...args: unknown[]) => unknown) | undefined;
+}
+/**
+ * 动态 import agent handler 文件并提取 `run` 导出
+ *
+ * Dev 按需编译模式（Vite 风格）：先 `ensureCompiled` 确保产物存在再 import,
+ * 避免 import 不存在的文件污染 Vite SSR 内部状态（详见 [loadRouteModule](./loadRouteModule.md)）。
+ * Prod 模式：产物在 build 阶段已固化，直接 import，失败即报错。
+ *
+ * 与 [loadToolModule](./loadToolModule.md) 的差异：
+ * - tool 按 `functionName` 提取单个函数（校验为 function）
+ * - 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 hasRun 是否应提取 run 导出（来自 `AgentMetadata.hasRun`）
+ * @param rootDir 项目根目录（按需编译模式用，可选）
+ */
+declare function loadAgentModule(filePath: string, hasRun: boolean, rootDir?: string): Promise<AgentModule>;
+
+/**
+ * 加载后的 tool 模块
+ *
+ * 与 `RouteModule` 对称——`functionName` 替代 `method`(tool 没有HTTP方法维度)。
+ * `handler` 是从模块解析出的 tool 函数,可直接调用。
+ */
+interface ToolModule {
+    /** tool 函数(已校验为 function 类型) */
+    handler: (...args: unknown[]) => unknown;
+    /** 源码导出名(如 `getWeather`,用于日志/调试,与 `method` 对应) */
+    functionName: string;
+}
+/**
+ * 动态 import tool handler 文件并提取指定函数名的导出
+ *
+ * Dev 按需编译模式(Vite 风格):先 `ensureCompiled` 确保产物存在再 import,
+ * 避免 import 不存在的文件污染 Vite SSR 内部状态(详见 [loadRouteModule](./loadRouteModule.md))。
+ * Prod 模式:产物在 build 阶段已固化,直接 import,失败即报错。
+ *
+ * 错误传递:
+ * - 编译失败 → 抛 "Failed to compile tool module"
+ * - import 失败 → 抛 "Failed to load tool module"
+ * - 导出不是函数 → 抛 "does not export a valid function"
+ *
+ * @param filePath tool handler 文件的绝对路径(产物形式,如 `dist/tools/weather/handler.js`)
+ * @param functionName 源码导出函数名(如 `getWeather`,由 `ToolManifest.functionName` 提供)
+ * @param rootDir 项目根目录(按需编译模式用,可选)
+ */
+declare function loadToolModule(filePath: string, functionName: string, rootDir?: string): Promise<ToolModule>;
+
+/**
+ * 加载后的 tool schema 模块
+ *
+ * 与 [ToolModule](./loadToolModule.md) 对称——`schema` 替代 `handler`。
+ *
+ * `schema` 是 `unknown` 类型——faapi 核心不依赖 zod（zod 是 peerDep），
+ * `zod.js` 由业务方安装的 zod 创建，`@faapi/agent` 负责断言为 zod schema 后
+ * 调 `z.toJSONSchema` / `safeParse`。
+ */
+interface ToolSchemaModule {
+    /** zod schema 对象（由业务方安装的 zod 创建） */
+    schema: unknown;
+    /** schema 导出名（如 `WeatherInputSchema`，用于日志/调试） */
+    schemaName: string;
+}
+/**
+ * 动态加载 tool 的 zod.js schema 模块
+ *
+ * 与 [loadToolModule](./loadToolModule.md) 对称——一个加载 handler.js（tool 函数），
+ * 一个加载 zod.js（tool schema）。
+ *
+ * 行为：
+ * - `tool.inputTypeName` 为 `undefined` → 返回 `undefined`（无 schema，用自由 schema）
+ * - zod.js 文件不存在 → 返回 `undefined`（schema 可选，缺失用自由 schema）
+ * - import 失败 / 导出名不匹配 → 返回 `undefined`
+ *
+ * 与 route schema 不同（route schema 缺失抛 `InternalError`），tool schema 是可选的——
+ * `@faapi/agent` 的 `resolveToolSchema` 未提供时用自由 schema `{ type: 'object' }`，
+ * LLM 自由传参，handler 内部自行处理参数合法性。
+ *
+ * @param tool tool 元数据（含 `filePath` + `inputTypeName`）
+ * @param rootDir 项目根目录（用于计算 zod.js 绝对路径，`tool.filePath` 是相对路径时拼接）
+ */
+declare function loadToolSchema(tool: ToolMetadata, rootDir?: string): Promise<ToolSchemaModule | undefined>;
+
+/**
+ * 按全名查找单个 tool
+ *
+ * @param tool 全名（如 `weather.getWeather`）
+ * @returns `ToolMetadata` 或 `undefined`（未注册）
+ */
+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 工厂注册表（单例）
+ *
+ * 让 `@faapi/agent` 插件在启动时注册「请求级 agent handle 工厂」，
+ * [injectParams](./injectParams.md) 在 `agent` 参数注入时调工厂拿到 `AgentHandle` 实例。
+ *
+ * 解耦设计：faapi 核心不依赖 `@faapi/agent`——核心只提供注册 / 查询点，
+ * 工厂返回 `unknown`，具体类型由 `@faapi/agent` 的 `AgentHandle` 接口定义。
+ *
+ * 详见 [agentHandle.md](./agentHandle.md)。
+ */
+/** agent handle 工厂函数（由 `@faapi/agent` 插件注册） */
+type AgentHandleFactory = (ctx: FaapiContext) => unknown;
+/**
+ * 注册 agent handle 工厂
+ *
+ * 由 `@faapi/agent` 插件在 `setup()` 时调用，传入创建 `AgentHandle` 的工厂函数。
+ * 二次注册覆盖第一次（与 `hydrateAgentRegistry` 全量替换同构）。
+ *
+ * 传入 `null` 等效于 [clearAgentHandleFactory](#clearAgentHandleFactory)。
+ *
+ * @param factory 工厂函数或 `null`（清理）
+ */
+declare function registerAgentHandleFactory(factory: AgentHandleFactory | null): void;
+/**
+ * 清空工厂注册（app close / 测试清理时调用）
+ *
+ * 与 `clearAgentRegistry` / `clearToolRegistry` 对称，避免测试间状态泄漏。
+ */
+declare function clearAgentHandleFactory(): void;
+
 /**
  * 加载 faapi 配置文件
  *
@@ -699,7 +1309,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;
@@ -822,10 +1433,14 @@ interface AppBase {
     inject(options?: InjectOptions): Promise<InjectResponse>;
 }
 
-/** dev 应用接口（AppBase + reloadRoutes 热替换） */
+/** dev 应用接口（AppBase + reloadRoutes/reloadTools/reloadAgents 热替换） */
 interface DevApp extends AppBase {
     /** 重新水合路由清单 + 清 schema 缓存 + 更新 server 路由引用（dev 热替换用） */
     reloadRoutes(): Promise<void>;
+    /** 重新扫描 tools + 重生成 faapi-tools.js + 清缓存（dev 热替换用） */
+    reloadTools(): Promise<void>;
+    /** 重新扫描 agents + 重生成 faapi-agents.js + 清缓存（dev 热替换用） */
+    reloadAgents(): Promise<void>;
 }
 /**
  * dev 模式应用启动 API
@@ -872,4 +1487,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { 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, LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, collectRouteSchemaSources, createProdApp as createApp, createDevApp, createProdApp, createProgram, extractTypeInfo, getApp, getInputTypeForMethod, invalidateProgramCache, loadConfig, loadEnv, 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 };