@faapi/faapi 6.30.0 → 6.32.0

package/dist/index.d.ts

@@ -1,11 +1,8 @@
-import { A as AppRegistries, F as FaapiContext, T as TaskClient, L as LogConfig, a as TaskFailedHandler, b as TaskQueueDeps, c as TaskQueue, d as TaskDriver, e as TaskRegistry, f as TaskManifest, g as ToolMetadata, h as AgentCore, i as AgentMetadata, C as CreateLoggerOptions, j as Logger } from './contextTypes-DhagvRH_.js';
-export { k as AgentHandleFactory, l as AgentHandleStore, m as AgentPathMeta, n as AgentRegistry, o as AgentToolDescriptor, p as FaapiContextConfig, q as FaapiTaskMeta, r as FailOptions, s as LogEntry, t as LogLevel, u as LogSink, S as SkillRegistry, v as SseEvent, w as SseOptions, x as SseWriter, y as TaskContext, z as TaskDriverJob, B as TaskDriverProcess, D as TaskDriverRecord, E as TaskFailedInfo, G as TaskJob, H as TaskJobStatus, I as TaskMetadata, J as TaskModule, K as TaskRegistriesSnapshot, M as TaskRegistriesView, N as ToolCore, O as ToolPathMeta, P as ToolRegistry, Q as createAppRegistries, R as createTaskRegistriesView, U as createTaskRegistry } from './contextTypes-DhagvRH_.js';
-import { F as FaapiMiddleware, R as RouteManifest, C as CorsOptions, H as HelmetOptions, I as InjectorMap, W as WsRouteManifest } from './routeTypes-0rwuIws-.js';
-export { a as Injector, b as RouteInfo, c as RouteInputSchema, d as RouteOutputSchema, e as RouteParamSchema, f as cors, h as helmet } from './routeTypes-0rwuIws-.js';
-import * as node_http from 'node:http';
-import { Server, IncomingMessage, ServerResponse } from 'node:http';
-import { Socket } from 'node:net';
+import { F as FaapiMiddleware, R as RouteManifest, W as WsRouteManifest, T as TaskQueueDeps, a as TaskQueue, b as TaskDriver, c as TaskRegistry, d as TaskManifest, A as AgentCore, e as AgentMetadata, f as ToolMetadata, g as FaapiContext, h as FaapiConfig, L as LogConfig, C as CreateLoggerOptions, i as Logger, j as AppRegistries, k as TaskClient } from './contextTypes-WKsf3cCE.js';
+export { l as AgentConfig, m as AgentHandleFactory, n as AgentHandleStore, o as AgentPathMeta, p as AgentRegistry, q as AgentToolDescriptor, r as CorsOptions, s as FaapiContextConfig, t as FaapiPlugin, u as FaapiTaskMeta, v as FailOptions, H as HelmetOptions, I as Injector, w as InjectorMap, x as LifecycleContext, y as LifecycleHooks, z as LlmChannelStore, B as LlmComplete, D as LlmCompleteOptions, E as LlmConfig, G as LlmModelConfig, J as LogEntry, K as LogLevel, M as LogSink, P as PluginContext, N as PluginDeclaration, O as RequestHandler, Q as ResponseConfig, S as RouteInfo, U as RouteInputSchema, V as RouteOutputSchema, X as RouteParamSchema, Y as SkillRegistry, Z as SseEvent, _ as SseOptions, $ as SseWriter, a0 as TaskBullMqOptions, a1 as TaskConfig, a2 as TaskContext, a3 as TaskDriverJob, a4 as TaskDriverProcess, a5 as TaskDriverRecord, a6 as TaskFailedHandler, a7 as TaskFailedInfo, a8 as TaskJob, a9 as TaskJobStatus, aa as TaskMetadata, ab as TaskModule, ac as TaskPgBossOptions, ad as TaskRegistriesSnapshot, ae as TaskRegistriesView, af as ToolCore, ag as ToolPathMeta, ah as ToolRegistry, ai as UpgradeHandler, aj as cors, ak as createAppRegistries, al as createTaskRegistriesView, am as createTaskRegistry, an as helmet } from './contextTypes-WKsf3cCE.js';
 import ts from 'typescript';
+import { Server } from 'node:http';
+import 'node:net';
 
 type LoggerFn = (messageOrObj: string | Record<string, unknown>, message?: string) => void;
 interface LoggerOptions {
@@ -35,758 +32,6 @@ interface LoggerOptions {
  */
 declare function logger(options?: LoggerOptions): FaapiMiddleware;
 
-/** HTTP 请求 handler 类型 */
-type RequestHandler = (req: IncomingMessage, res: ServerResponse) => void;
-/** WebSocket 升级 handler 类型 */
-type UpgradeHandler = (req: IncomingMessage, socket: Socket, head: Buffer) => void;
-/**
- * 插件上下文：插件 setup 函数接收的框架能力
- *
- * 插件通过 ctx 访问路由、服务器实例等，不需要直接依赖框架内部模块。
- *
- * 插件可通过 `wrapHandler` / `wrapUpgradeHandler` 在 server.listen 之前包装请求处理逻辑，
- * 用于集成其他框架（如 Next.js）：`/api/*` 走 faapi，其余走被集成框架。
- */
-interface PluginContext {
-    /** 项目根目录 */
-    rootDir: string;
-    /** app 级注册表（tool/agent/skill/agentHandle 实例，随 app 生命周期） */
-    registries: AppRegistries;
-    /** 当前路由清单（setup 时的快照，reloadRoutes 后不会更新；需最新路由用 getRoutes()） */
-    routes: RouteManifest;
-    /** 获取最新路由清单（reloadRoutes 后返回更新后的数组） */
-    getRoutes: () => RouteManifest;
-    /** HTTP 服务器实例（未 listen） */
-    server: Server;
-    /** 自定义业务配置（faapi.config.ts 中的自定义 key） */
-    config: Record<string, unknown>;
-    /** 插件选项（来自声明中的 options 字段或元组第二个元素） */
-    options?: unknown;
-    /**
-     * 注册 HTTP handler 包装函数（在 server.listen 之前应用，按注册顺序嵌套）
-     *
-     * 包装函数接收原始 handler，返回新的 handler。多个包装器按注册顺序嵌套：
-     * finalHandler = wrap1(wrap2(originalHandler))
-     *
-     * 典型场景：集成 Next.js，`/api/*` 走 faapi，其余走 Next.js getRequestHandler。
-     */
-    wrapHandler?: (fn: (original: RequestHandler) => RequestHandler) => void;
-    /**
-     * 注册 WS upgrade handler 包装函数（在 server.listen 之前应用，按注册顺序嵌套）
-     *
-     * 包装函数接收原始 upgrade handler（可能为 undefined，表示 faapi 无 WS 路由），
-     * 返回新的 upgrade handler。多个包装器按注册顺序嵌套。
-     *
-     * 典型场景：faapi WS 路由走 original，其余走 Next.js HMR。
-     */
-    wrapUpgradeHandler?: (fn: (original: UpgradeHandler | undefined) => UpgradeHandler) => void;
-}
-/**
- * faapi 插件接口
- *
- * 插件是一个对象，包含 name 和 setup 函数。
- * 框架在 server 创建后、listen 之前按声明顺序加载插件，调用 setup(ctx)。
- *
- * 插件可通过 ctx.wrapHandler / ctx.wrapUpgradeHandler 包装请求处理逻辑，
- * 用于集成其他框架（如 Next.js）。
- *
- * ```ts
- * import type { FaapiPlugin, PluginContext } from '@faapi/faapi';
- *
- * export default {
- *   name: 'my-plugin',
- *   setup(ctx: PluginContext) {
- *     console.log(`Plugin loaded, ${ctx.routes.length} routes found`);
- *   },
- * } satisfies FaapiPlugin;
- * ```
- */
-interface FaapiPlugin {
-    /** 插件名称（用于去重和日志） */
-    name: string;
-    /** 插件初始化函数，在 server 创建后、listen 之前调用 */
-    setup: (ctx: PluginContext) => Promise<void> | void;
-}
-/**
- * 插件声明：用户在 faapi.config.ts 的 plugins 字段中使用
- *
- * 支持三种形式：
- * - 包名字符串：`'@faapi/schema'`
- * - 带选项的元组：`['@faapi/schema', { stdio: true }]`
- * - 完整声明对象：`{ package: '@faapi/schema', enable: true }`
- * - 本地路径：`{ path: './my-plugin' }`
- */
-type PluginDeclaration = string | [string, unknown] | {
-    package: string;
-    enable?: boolean;
-    options?: unknown;
-} | {
-    path: string;
-    enable?: boolean;
-    options?: unknown;
-};
-
-interface CompressionOptions {
-    /**
-     * 最小压缩字节数，body 低于该值不压缩（小 payload 压缩后反而变大）
-     * @default 1024
-     */
-    threshold?: number;
-}
-
-interface EtagOptions {
-    /**
-     * 生成弱 ETag（`W/"<hash>"`）。弱校验器允许压缩等表示差异下的 304 协商，
-     * 与 compression 中间件配合正确；强 ETag 需对每个表示（编码）单独生成
-     * @default true
-     */
-    weak?: boolean;
-}
-
-interface Http2Options {
-    key?: string;
-    cert?: string;
-}
-
-/**
- * 生命周期钩子
- *
- * 执行时序:onBoot(.listen 调用前)→ server.listen → listen 回调内 onReady → 运行期 onError → 关闭时 onClose
- */
-interface LifecycleHooks {
-    /**
-     * 服务器 listen 之前调用(启动校验钩子)
-     *
-     * 时机:`app.listen()` 内、`server.listen` 调用之前——server 已创建但未监听
-     * (`server.listening === false`),路由/tool/agent 清单已水合、插件已加载。
-     *
-     * 适合启动校验(环境变量、下游依赖可达性)、DB 迁移等**失败即不该暴露端口**的逻辑:
-     * 钩子抛错 → `listen()` 以原始错误 reject,`server.listen` 不会被调用,端口不暴露。
-     *
-     * 与 onReady 的差异:onReady 在 listen 回调内执行,失败时端口已开,
-     * 存在"接受连接但不服务"的窗口——启动校验请用 onBoot,资源初始化用 onReady。
-     */
-    onBoot?: (ctx: LifecycleContext) => Promise<void> | void;
-    /** 服务器启动后调用（适合初始化数据库连接等） */
-    onReady?: (ctx: LifecycleContext) => Promise<void> | void;
-    /** 服务器关闭时调用（适合清理资源、优雅关闭） */
-    onClose?: (ctx: LifecycleContext) => Promise<void> | void;
-    /**
-     * 请求错误已被处理为响应后调用(参考 Fastify onError 语义)
-     *
-     * 时机:handler 抛错 → 全局中间件 try/catch(若有) → 框架内置 formatErrorResponse 兜底
-     *      → 响应发出后 → onError 触发副作用
-     *
-     * 职责:日志上报、告警、链路追踪等副作用。**不修改、不替换已生成的响应**。
-     * 自身抛错会被捕获并忽略,不影响响应已发送的事实。
-     *
-     * 与全局错误中间件的区别:
-     * - 全局错误中间件:把 error 翻译成 Response(主入口,决定响应内容)
-     * - onError:响应发出后的副作用(不能改响应)
-     */
-    onError?: (error: unknown, ctx: FaapiContext) => Promise<void> | void;
-}
-/**
- * pg-boss 驱动选项（透传给 @faapi/task-pgboss）
- *
- * 主包不依赖 pg-boss，这里只声明常用连接字段的透传形状；完整项见 pg-boss 文档
- * （ConstructorOptions）。
- */
-interface TaskPgBossOptions {
-    /** PostgreSQL 连接串（如 `postgres://localhost:5432/app`） */
-    connectionString?: string;
-    /** 其余 pg-boss ConstructorOptions 字段原样透传 */
-    [key: string]: unknown;
-}
-/**
- * BullMQ 驱动选项（透传给 @faapi/task-bullmq）
- */
-interface TaskBullMqOptions {
-    /** Redis 连接配置（透传给 Queue / Worker 的 connection） */
-    connection?: {
-        host?: string;
-        port?: number;
-        password?: string;
-        db?: number;
-        [key: string]: unknown;
-    };
-    /** 队列名前缀（默认 `faapi`——同一 Redis 下多个 faapi 应用隔离用） */
-    prefix?: string;
-}
-/**
- * 任务子系统配置
- *
- * 任务队列由持久化驱动承载（内置 memory 驱动已移除）：存在任务清单
- * （`src/tasks/` 下的 task.ts）时必须显式配置 `driver`，否则启动报错；
- * 无任务清单的项目不加载驱动（零任务项目无需安装驱动子包）。
- */
-interface TaskConfig {
-    /**
-     * 队列驱动：'pgboss'（@faapi/task-pgboss，Postgres）| 'bullmq'（@faapi/task-bullmq，Redis）
-     *
-     * 有任务清单时必填；也可在编程式场景传入自定义 TaskDriver 实例
-     */
-    driver?: 'pgboss' | 'bullmq';
-    /** `driver: 'pgboss'` 时的选项（透传给 @faapi/task-pgboss） */
-    pgboss?: TaskPgBossOptions;
-    /** `driver: 'bullmq'` 时的选项（透传给 @faapi/task-bullmq） */
-    bullmq?: TaskBullMqOptions;
-    /**
-     * 是否启动任务队列（默认 true）
-     *
-     * 多实例部署时可在非 worker 节点设 `FAAPI_TASKS_DISABLED=1` 或 `task.enabled: false`，
-     * API 节点照常入队（入队能力保留），但不消费执行。
-     */
-    enabled?: boolean;
-    /** 优雅停机时等待在跑任务的最长时间（毫秒，默认 10000；超时 abort） */
-    shutdownTimeoutMs?: number;
-    /**
-     * 任务执行失败/取消钩子——每次 process 抛错后触发（含将重试的失败），
-     * `info.willRetry` 按任务 meta.retries 推算、`info.cancelled` 标记框架终止；
-     * 用于告警/死信上报等副作用，自身抛错被忽略
-     */
-    onFailed?: TaskFailedHandler;
-}
-/**
- * 生命周期上下文
- */
-interface LifecycleContext {
-    /** 项目根目录 */
-    rootDir: string;
-    /** 当前路由清单 */
-    routes: RouteManifest;
-    /** 服务器实例（onBoot 钩子触发时已创建但未监听，`listening === false`） */
-    server: node_http.Server;
-    /** app 级注册表——skill 等运行时动态注册路径（`registries.skill.upsert(...)`） */
-    registries: AppRegistries;
-    /** 任务客户端——onBoot/onReady 中投递异步任务（`tasks.enqueue(name, payload)`） */
-    tasks: TaskClient;
-}
-/**
- * 统一响应包装配置
- *
- * 配置后,框架自动:
- * - 成功响应:handler return 非 Response 的值时,用 ok 函数包裹
- * - 错误响应:ctx.fail() 用 fail 函数包装 body
- *
- * 未配置 response 时,使用框架默认实现:
- * - ok: (data) => ({ data })
- * - fail: ({ status, code, message }) => 省略的字段不放入 error 对象
- *
- * ```ts
- * import type { FaapiConfig } from '@faapi/faapi';
- * export default {
- *   response: {
- *     // 自定义成功包装(默认 { data })
- *     ok: (data) => ({ code: 0, data }),
- *     // 自定义错误包装(默认 { error: { message, ...code?, ...status? } })
- *     fail: ({ status, code, message }) => ({ error: { code, message } }),
- *   },
- * } satisfies FaapiConfig;
- * ```
- */
-interface ResponseConfig {
-    /**
-     * 成功响应包装函数
-     *
-     * handler return 非 Response 的值时调用。
-     * 默认: (data) => ({ data })
-     */
-    ok?: (data: unknown) => unknown;
-    /**
-     * 错误响应包装函数
-     *
-     * ctx.fail() 调用时使用,接收 { status?, code?, message }。
-     * status 和 code 均可能为 undefined(用户调用 ctx.fail 时省略则不传),
-     * 默认实现只把非 undefined 的字段放入 error 对象。
-     */
-    fail?: (error: {
-        status?: number;
-        code?: string;
-        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'`）。
- * 无全局默认 provider——每次 `agent.run/stream` 调用通过 `options.model`（llms key /
- * `provider/model` / 纯 model 名）或 `options.provider`（外部 provider）显式指定。
- *
- * 由 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>;
-    /**
-     * LLM 请求超时（毫秒，可选——未设置时无超时）
-     *
-     * provider 层用 `AbortSignal.timeout` 实现，与 run-level 的 `signal` 组合生效。
-     * 超时触发抛 `LLMProviderError`（message 含 timed out），计入重试（429/5xx/网络错误同策略）。
-     */
-    timeoutMs?: number;
-    /**
-     * 429 / 5xx / 网络错误的最大重试次数（默认 2，设 0 关闭重试）
-     *
-     * 退避策略：优先尊重响应的 `Retry-After` 头（秒，封顶 30s），否则指数退避
-     * 500ms * 2^attempt。4xx 其他状态（400/401 等）是确定性错误，不重试。
-     * 流式请求仅在「连接建立前」重试，流开始输出后中断不重试。
-     */
-    maxRetries?: number;
-    /**
-     * 其他透传参数（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 / 默认 provider——`agent.run/stream` 每次调用必须显式传
- * `options.agent`（agent 名）和 `options.model` / `options.provider`（LLM 定位）；
- * agent 自身 `config.maxTurns` / `config.model` 优先于全局配置，其中 `config.model`
- * 在调用未传 `options.model` 时作为缺省 key 参与 llms 解析。
- *
- * ```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 } },
- *       },
- *     },
- *     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)）。
-     *
-     * 可选——未设置时插件仍注册 agent handle 工厂（外部 provider 模式），
-     * `agent.run/stream` 需通过 `options.provider` 传入外部 provider 才能调用 LLM。
-     */
-    llms?: Record<string, LlmConfig>;
-    /**
-     * 默认最大对话轮数（覆盖 agent 自身 `config.maxTurns`，agent 自身配置优先）
-     *
-     * Phase 3.3 的 reactLoop 使用此值作为递归深度防护。
-     */
-    maxTurns?: number;
-    /**
-     * agent 调用 agent 的最大递归深度（防护无限递归，Phase 3.3 reactLoop 使用）
-     *
-     * 默认值由 Phase 3.x 的 @faapi/agent 插件定义（如 3）。
-     */
-    maxAgentDepth?: number;
-    /**
-     * 启用 tracing 的全局默认值（默认 false——opt-in,不开启零开销）
-     *
-     * 开启时 `agent.run()` / `agent.stream()` 返回的 `result.trace` /
-     * `chunk.traceEvent` 填充结构化调用明细（按轮次组织的 LLM 调用、tool 调用、
-     * sub-agent 嵌套调用事件,含 timing 与 token 用量）。
-     *
-     * 三层覆盖优先级：`AgentRunOptions.enableTracing` > agent 自身配置 >
-     * 此全局配置 > 默认 `false`。
-     *
-     * tracing 采集每轮 LLM 消息快照与 tool 明细,有真实内存/CPU 开销——
-     * 需要观测的端点显式开启：
-     *
-     * ```ts
-     * import type { FaapiConfig } from '@faapi/faapi';
-     * export default {
-     *   agent: {
-     *     enableTracing: true, // 全局开启;单次调用可用 run(input, { enableTracing: true }) 覆盖
-     *     llms: { openai: { provider: 'openai', apiKey: '...', models: { 'gpt-4o': {} } } },
-     *   },
-     * } satisfies FaapiConfig;
-     * ```
-     *
-     * 详见 `@faapi/agent` 的 [trace](../../agent/src/trace.md) 文档。
-     */
-    enableTracing?: boolean;
-    /**
-     * 发送给 LLM 的历史 token 预算（近似估算，未设置 = 不裁剪）
-     *
-     * 多轮 tool 循环中对话历史只增不减，大 tool 结果会撑爆模型上下文窗口导致
-     * 下一轮 400。超预算时从最旧的轮组开始裁剪（system 与初始 user 保留、
-     * tool 配对不拆散），只作用于发给 LLM 的消息副本。详见 @faapi/agent 的
-     * reactLoop 文档历史裁剪章节。
-     */
-    maxHistoryTokens?: number;
-    /**
-     * 执行守卫（authHooks，见 @faapi/agent 的 authHooks 文档）
-     *
-     * 每次 tool / sub-agent 执行前调用（`agent-x` 派发名称为 sub-agent 递归）。
-     * 三种返回：`void` 放行；`{ error }` 拒绝（不执行，error 回传 LLM 调整策略）；
-     * `{ args }` 改写后放行（多租户场景强制注入可信值，不信 LLM 传入的标识参数）。
-     *
-     * ctx 为请求上下文透传（`Partial<FaapiContext>`，框架零读取）：HTTP 请求是完整
-     * ctx，任务内组装 Agent 时业务方显式传窄对象（如鉴权硬闸需要的
-     * `{ currentUserId }`），编程式直调为 undefined。
-     *
-     * 典型用法：中间件解析 `ctx.workspace` 后在此校验/强制改写 `args.workspaceId`。
-     */
-    beforeToolCall?: (name: string, args: Record<string, unknown>, ctx: Partial<FaapiContext> | undefined) => void | {
-        error: string;
-    } | {
-        args: Record<string, unknown>;
-    };
-    /**
-     * 审计钩子（authHooks）：tool / sub-agent 成功返回后调用，返回值忽略。
-     * 用于日志/审计/计量；异常路径不调用。
-     */
-    afterToolCall?: (name: string, args: Record<string, unknown>, result: unknown, ctx: Partial<FaapiContext> | undefined) => void;
-    /**
-     * 可见性过滤（authHooks）：LLM 可见 tools 清单组装完成后调用，
-     * 返回过滤后的数组（含 agent-as-tool 项）。每次 agent.run / stream 生效——
-     * 无权 tool 不进 LLM 视野，比执行时拒绝省一轮 LLM 调用。
-     *
-     * tools 为 OpenAI chat completions 规范形（`type: 'function'` +
-     * `function: { name, description?, parameters? }`），按 `tool.function.name` 过滤。
-     */
-    filterTools?: (tools: Array<{
-        type: 'function';
-        function: {
-            name: string;
-            description?: string;
-            parameters?: Record<string, unknown>;
-        };
-    }>, ctx: Partial<FaapiContext> | undefined) => Array<{
-        type: 'function';
-        function: {
-            name: string;
-            description?: string;
-            parameters?: Record<string, unknown>;
-        };
-    }>;
-}
-/**
- * faapi 配置文件类型
- *
- * 在项目根目录创建 faapi.config.ts：
- * ```ts
- * import type { FaapiConfig } from '@faapi/faapi';
- * export default {
- *   cors: { origin: '*' },
- * } satisfies FaapiConfig;
- * ```
- *
- * 自定义业务配置（任意 key）：
- * ```ts
- * import type { FaapiConfig } from '@faapi/faapi';
- * export default {
- *   cors: { origin: '*' },
- *   // 通过 process.env.XXX 读取 .env 文件加载的环境变量
- *   db: { host: process.env.DB_HOST ?? 'localhost', port: 5432 },
- * } satisfies FaapiConfig;
- * ```
- *
- * 多环境差异通过 `.env` 系列文件实现（见 `loadEnv`）：
- * - `.env` / `.env.local` / `.env.{env}` / `.env.{env}.local`
- * - 环境由 `NODE_ENV > 'development'` 决定
- *
- * 框架元信息通过环境变量配置（不放在 config 内）：
- * - `PORT`：服务端口，默认 3000
- * - `FAAPI_DIST`：产物输出目录，dev 固定为 `.faapi`（不可修改），prod 默认为 `dist`（可通过 `--dist` 修改）
- */
-interface FaapiConfig {
-    /** CORS 配置，false 禁用 */
-    cors?: CorsOptions | boolean;
-    /** 生命周期钩子 */
-    lifecycle?: LifecycleHooks;
-    /** 安全头配置，false 禁用 */
-    helmet?: HelmetOptions | boolean;
-    /**
-     * 响应压缩（gzip/deflate/br 协商），默认关闭。
-     * Vary: Accept-Encoding 自动附加；SSE/流式响应跳过，详见 middleware/compression.md
-     */
-    compression?: CompressionOptions | boolean;
-    /**
-     * ETag/304 条件请求协商（GET/HEAD 2xx 弱 ETag），默认关闭。
-     * handler 显式 ctx.setETag() 时不覆盖，详见 middleware/etag.md
-     */
-    etag?: EtagOptions | boolean;
-    /** 请求体大小限制（字节），默认 10MB（10 * 1024 * 1024） */
-    bodyLimit?: number;
-    /**
-     * 日志全局配置——唯一日志配置入口，业务日志与请求日志同管道（egg 模型，
-     * 详见 logger/logger.md；`config.logger` 独立配置已废除）
-     *
-     * - `false`：全部静默（含 error 与请求日志，测试降噪）
-     * - `true` / 缺省：console 输出（consoleLevel 默认 'info'），管道不过滤
-     * - `LogConfig`：`dir` egg 风格文件输出（app.log 全量 + error.log 仅 error，
-     *   splitByLevel 按级别四文件）或 `sink` 自定义管道接管（接 pino/winston），
-     *   两者互斥；`level` 管道阈值（不配不过滤）、`consoleLevel` console 出口阈值
-     *   （不配 'info'，false 关 console）；请求日志无条件并入（`accessLog: false` 关闭）
-     *
-     * 生效范围：`ctx.log` / 参数注入 `log` / `createLogger` / `taskCtx.log` /
-     * 请求日志中间件。日志全局配置是进程级资源，多 app 同进程时后启动覆盖先启动。
-     *
-     * ```ts
-     * export default {
-     *   log: {
-     *     // 方式一：egg 风格文件输出（请求日志自动并入）
-     *     dir: 'logs',
-     *     // 方式二：自定义管道接管
-     *     // sink: (entry) => pinoLogger[entry.level]({ scope: entry.scope, ...entry.fields }, entry.message),
-     *   },
-     * } satisfies FaapiConfig;
-     * ```
-     */
-    log?: LogConfig | boolean;
-    /** HTTP/2 配置，false 禁用（默认 http/1.1） */
-    http2?: Http2Options | boolean;
-    /**
-     * 是否信任反向代理头（X-Forwarded-For），默认 false
-     *
-     * - `true`：`ctx.ip` 取 `x-forwarded-for` 第一个 IP——部署在 nginx/CDN 等受信任
-     *   反向代理之后时开启
-     * - `false`（默认）：直取 socket 地址。客户端直连时 XFF 可被任意伪造，
-     *   安全默认不信任（同时影响 HTTP 与 WS 握手的 `ctx.ip`）
-     */
-    trustedProxy?: boolean;
-    /**
-     * 统一响应包装配置
-     *
-     * 配置后,框架自动包裹 handler 返回值:
-     * - 成功响应:handler return 非 Response → 用 ok 函数包裹(默认 `{ data }`)
-     * - 错误响应:ctx.fail() 用 fail 函数包装(默认 `{ error: { message, ...code? } }`)
-     *
-     * 未配置 response 时,使用框架默认实现(见 ResponseConfig)。
-     * 配置 response 后,ok/fail 各字段均可选,按需覆盖。
-     *
-     * ```ts
-     * import type { FaapiConfig } from '@faapi/faapi';
-     * export default {
-     *   response: {
-     *     ok: (data) => ({ code: 0, data }),
-     *     fail: ({ status, code, message }) => ({ error: { code, message } }),
-     *   },
-     * } satisfies FaapiConfig;
-     * ```
-     *
-     * 详见 `src/config/configTypes.md` 统一响应包装章节。
-     */
-    response?: ResponseConfig;
-    /**
-     * 全局中间件：对所有路由（HTTP + WebSocket 握手）生效
-     *
-     * 执行顺序：全局中间件在最外层，目录中间件在内层，handler 最内层。
-     * 全局中间件拦截（返回 Response）则目录中间件和 handler 不执行。
-     * 全局中间件塞入 ctx 的值，目录中间件和 handler 可读取。
-     *
-     * 与 CORS 的关系：CORS 由 `cors` 字段配置，全局中间件在 CORS 之后执行。
-     *
-     * ```ts
-     * import type { FaapiConfig, FaapiMiddleware } from '@faapi/faapi';
-     *
-     * const requestId: FaapiMiddleware = async (ctx, next) => {
-     *   ctx.requestId = crypto.randomUUID();
-     *   await next();
-     * };
-     *
-     * export default {
-     *   middlewares: [requestId],
-     * } satisfies FaapiConfig;
-     * ```
-     *
-     * 详见 `src/middleware/README.md` 全局中间件章节。
-     */
-    middlewares?: FaapiMiddleware[];
-    /**
-     * 全局注入器：对所有路由的 handler 参数注入生效
-     *
-     * 合并规则：`{ ...全局注入器, ...目录注入器 }`，目录注入器覆盖全局同名。
-     * 全局注入器独立于中间件链，仅提供依赖（db、redis 等），不参与请求流程。
-     *
-     * ```ts
-     * import type { FaapiConfig, InjectorMap } from '@faapi/faapi';
-     *
-     * export default {
-     *   injectors: {
-     *     db: () => getDbConnection(),
-     *     redis: () => getRedis(),
-     *   },
-     * } satisfies FaapiConfig;
-     * ```
-     *
-     * 详见 `src/middleware/README.md` 全局注入器章节。
-     */
-    injectors?: InjectorMap;
-    /**
-     * 插件：应用级扩展，在 server 启动后、onReady 之前按声明顺序加载
-     *
-     * 与中间件的区别：中间件拦截每个请求，插件在启动时初始化（如启动后台服务、注册协议等）
-     *
-     * ```ts
-     * import type { FaapiConfig } from '@faapi/faapi';
-     * export default {
-     *   plugins: [
-     *     '@faapi/schema',                          // 包名
-     *     ['@faapi/schema', { stdio: true }],        // 带选项
-     *     { package: '@faapi/schema', enable: true }, // 完整声明
-     *     { path: './my-plugin' },                    // 本地路径
-     *   ],
-     * } satisfies FaapiConfig;
-     * ```
-     */
-    plugins?: PluginDeclaration[];
-    /**
-     * agent 子系统全局配置（Phase 2.4）
-     *
-     * 提供 agent 子系统的全局配置：LLM 提供方、最大对话轮数、
-     * agent 调用 agent 的最大递归深度。
-     *
-     * 无全局默认 agent / 默认 provider——`agent.run/stream` 每次调用显式传
-     * `options.agent` + `options.model` / `options.provider`。
-     * 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': {} },
-     *       },
-     *     },
-     *     maxTurns: 10,
-     *     maxAgentDepth: 3,
-     *   },
-     * } satisfies FaapiConfig;
-     * ```
-     *
-     * 详见 `src/config/configTypes.md` agent 配置块章节。
-     */
-    agent?: AgentConfig;
-    /**
-     * 任务子系统全局配置（队列驱动、启停、停机超时）
-     *
-     * ```ts
-     * import type { FaapiConfig } from '@faapi/faapi';
-     * export default {
-     *   task: { enabled: true, shutdownTimeoutMs: 10_000 },
-     * } satisfies FaapiConfig;
-     * ```
-     *
-     * 详见 `src/task/README.md`。
-     */
-    task?: TaskConfig;
-    /**
-     * 扩展 ctx：在每次请求创建上下文后调用，可挂载自定义方法（如 ctx.xml、ctx.stream）
-     *
-     * 类型增强：用户通过 `declare module '@faapi/faapi'` 扩展 FaapiContext 接口获得类型提示
-     *
-     * ```ts
-     * // faapi.config.ts
-     * declare module '@faapi/faapi' {
-     *   interface FaapiContext {
-     *     xml(data: string): Response;
-     *   }
-     * }
-     * export default {
-     *   extendContext(ctx) {
-     *     ctx.xml = (data) => new Response(data, { headers: { 'Content-Type': 'application/xml' } });
-     *   },
-     * } satisfies FaapiConfig;
-     * ```
-     */
-    extendContext?: (ctx: FaapiContext) => void;
-    /**
-     * 自定义业务配置（任意 key）
-     *
-     * 用户可以在这里放数据库连接、Redis 配置等
-     * 通过 ctx.config 访问
-     *
-     * ```ts
-     * export default {
-     *   db: { host: 'localhost', port: 5432 },
-     *   redis: { host: '127.0.0.1', port: 6379 },
-     * } satisfies FaapiConfig;
-     * ```
-     */
-    [key: string]: unknown;
-}
-
 /**
  * WebSocket Handler 类型定义与 socket 封装
  *
@@ -1299,31 +544,44 @@ interface ToolSchemaModule {
  * 计算 tool 的 zod.js 绝对路径（纯路径计算，无 fs 访问）
  *
  * 与 [loadToolSchema](./loadToolSchema.ts) 内部使用的路径逻辑同源（共享 `getDist()`），
+/**
+ * zod.js 定位的最小来源结构——`ToolMetadata` 与 `AgentMetadata`（派发入参 schema
+ * 声明场景）均满足，加载器无需感知来源差异
+ */
+interface SchemaSourceRef {
+    /** 源码/产物相对路径（与 zod.js 同级，推导 zod.js 路径用） */
+    filePath: string;
+    /** schema 类型名（`undefined` = 无 schema 声明） */
+    inputTypeName?: string;
+}
+/**
+ * 计算 zod.js 的绝对路径（纯路径计算，无 fs 访问）
+ *
+ * 与 [loadToolSchema](./loadToolSchema.ts) 内部使用的路径逻辑同源（共享 `getDist()`），
  * 供 `@faapi/agent` 的跨请求 schema 缓存用作缓存键 + mtime 校验目标。
  *
- * @param tool tool 元数据（含 `filePath`）
- * @param rootDir 项目根目录（`tool.filePath` 是相对路径时拼接）
+ * @param ref schema 来源元数据（tool / agent 均可，含 `filePath`）
+ * @param rootDir 项目根目录（`ref.filePath` 是相对路径时拼接）
  */
-declare function getToolSchemaPath(tool: ToolMetadata, rootDir?: string): string;
+declare function getToolSchemaPath(ref: SchemaSourceRef, rootDir?: string): string;
 /**
- * 动态加载 tool 的 zod.js schema 模块
+ * 动态加载 zod.js schema 模块（tool input 与 agent 派发入参共用）
  *
  * 与 [loadToolModule](./loadToolModule.md) 对称——一个加载 handler.js（tool 函数），
- * 一个加载 zod.js（tool schema）。
+ * 一个加载 zod.js（schema 模块）。tool 的 zod.js 与 handler.js 同级；agent 声明
+ * `Input` 时同样生成同级 zod.js（见 generateAgentArtifacts），同一加载器服务两类来源。
  *
  * 行为：
- * - `tool.inputTypeName` 为 `undefined` → 返回 `undefined`（无 schema，用自由 schema）
- * - zod.js 文件不存在 → 返回 `undefined`（schema 可选，缺失用自由 schema）
+ * - `ref.inputTypeName` 为 `undefined` → 返回 `undefined`（无 schema 声明）
+ * - zod.js 文件不存在 → 返回 `undefined`（schema 缺失，调用方按各自语义处理——
+ *   tool 用自由 schema `{ type: 'object' }`；agent 派发入参在声明了 `inputTypeName`
+ *   时视为产物异常，由 `@faapi/agent` 侧显式抛错）
  * - 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` 是相对路径时拼接）
+ * @param ref schema 来源元数据（tool / agent 均可，含 `filePath` + `inputTypeName`）
+ * @param rootDir 项目根目录（用于计算 zod.js 绝对路径，`ref.filePath` 是相对路径时拼接）
  */
-declare function loadToolSchema(tool: ToolMetadata, rootDir?: string): Promise<ToolSchemaModule | undefined>;
+declare function loadToolSchema(ref: SchemaSourceRef, rootDir?: string): Promise<ToolSchemaModule | undefined>;
 
 /**
  * 按名查找单个 agent 的 LLM 可见元数据（默认实例）
@@ -1768,4 +1026,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type AgentConfig, AgentCore, AgentMetadata, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, CreateLoggerOptions, type CronScheduler, type DevApp, type FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, HelmetOptions, type InjectOptions, type InjectResponse, InjectorMap, InternalError, LLM_TOOL_NAME_PATTERN, type LifecycleContext, type LifecycleHooks, type LlmConfig, type LlmModelConfig, LogConfig, Logger, type LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SUB_AGENT_TOOL_PREFIX, SchemaExtractionError, TASK_PATTERNS, type TaskBullMqOptions, TaskClient, type TaskConfig, TaskDriver, TaskFailedHandler, TaskManifest, type TaskPgBossOptions, TaskQueue, TaskRegistry, ToolMetadata, type ToolModule, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, configureLogging, createProdApp as createApp, createCronScheduler, createDevApp, createLogger, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, flushLogging, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, logger, readResource, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, subAgentToolName, upsertSkill };
+export { AgentCore, AgentMetadata, type ProdApp as App, AppRegistries, type CreateAppOptions, CreateLoggerOptions, type CronScheduler, type DevApp, FaapiConfig, FaapiContext, FaapiError, FaapiMiddleware, type HandlerTypeInfo, type InjectOptions, type InjectResponse, InternalError, LLM_TOOL_NAME_PATTERN, LogConfig, Logger, type LoggerOptions, MethodNotAllowedError, ModuleLoadError, type ProdApp, type PropertyType, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SUB_AGENT_TOOL_PREFIX, SchemaExtractionError, type SchemaSourceRef, TASK_PATTERNS, TaskClient, TaskDriver, TaskManifest, TaskQueue, TaskRegistry, ToolMetadata, type ToolModule, type ToolSchemaModule, type TypeConstraint, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, configureLogging, createProdApp as createApp, createCronScheduler, createDevApp, createLogger, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, flushLogging, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, logger, readResource, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, subAgentToolName, upsertSkill };