@faapi/faapi 6.30.0 → 6.32.0

package/dist/{contextTypes-DhagvRH_.d.ts → contextTypes-WKsf3cCE.d.ts}

@@ -1,3 +1,7 @@
+import * as node_http from 'node:http';
+import { Server, IncomingMessage, ServerResponse } from 'node:http';
+import { Socket } from 'node:net';
+
 /**
  * Tool 的 LLM 可见核心字段
  *
@@ -130,6 +134,15 @@ interface AgentCore {
 interface AgentMetadata extends AgentCore {
     /** 源码相对路径(从 `pathMeta` 透传)——声明文件定位与清单可观测性用 */
     filePath: string;
+    /**
+     * 派发入参 schema 声明(handler.ts 顶层 `interface Input` / `type Input` 检测)
+     *
+     * 声明时为 `'Input'`——[generateAgentArtifacts](../cli/generateAgentArtifacts.md)
+     * 据此生成 agent 的 zod.js,`@faapi/agent` 派发该 agent 时用富 JSON Schema 替代
+     * 默认单字段 `input` 交接单并在执行前校验;未声明为 `undefined`,派发行为不变
+     * (完全向后兼容)。DB-driven skill 无源文件,恒为 `undefined`。
+     */
+    inputTypeName?: string;
 }
 /**
  * 路径推导的 agent 元数据(由 [scanAgents](../agents/scanAgents.ts) 计算)
@@ -353,67 +366,162 @@ interface LogConfig {
 }
 
 /**
- * 隔离执行器签名（taskQueue 按任务 meta.timeoutMs 调用；测试可注入 spy）
+ * faapi 中间件（洋葱模型）
+ *
+ * 单一 async 函数，通过 `await next()` 衔接前置/后置逻辑：
+ * - `await next()` 之前的代码：前置处理（鉴权、日志开始计时等）
+ * - `await next()` 之后的代码：后置处理（日志输出、响应修改等）
+ * - 不调用 `next()` 即拦截请求（如鉴权失败直接返回 Response）
+ * - `next()` 返回内层 Response，中间件可选择使用或替换
+ * - 返回 `Response`：作为响应返回（可用于拦截或错误处理）
+ * - 返回 `void`：使用 `await next()` 返回的内层响应
+ *
+ * 错误处理用 try/catch 包裹 `await next()`，而非独立的 error 钩子。
+ *
+ * 执行顺序（洋葱模型）：
+ * ```
+ * mw1.before → mw2.before → handler → mw2.after → mw1.after
+ * ```
+ *
+ * 示例 middlewares.ts：
+ * ```ts
+ * import type { FaapiMiddleware } from '@faapi/faapi';
+ *
+ * export default [
+ *   // 鉴权：不调 next() 即拦截
+ *   async (ctx, next) => {
+ *     const token = ctx.headers.get('authorization');
+ *     if (!token) return new Response('Unauthorized', { status: 401 });
+ *     ctx.user = await verifyToken(token);
+ *     await next();
+ *   },
+ *   // 日志：before/after 一体，闭包共享状态
+ *   async (ctx, next) => {
+ *     const start = Date.now();
+ *     await next();
+ *     console.log(`${ctx.method} ${ctx.path} ${Date.now() - start}ms`);
+ *   },
+ *   // 错误处理：try/catch 语义
+ *   async (ctx, next) => {
+ *     try {
+ *       await next();
+ *     } catch (err) {
+ *       return new Response(JSON.stringify({ error: String(err) }), { status: 500 });
+ *     }
+ *   },
+ * ] satisfies FaapiMiddleware[];
+ * ```
  */
-type TaskWorkerRunner = typeof runTaskInWorker;
-interface TaskWorkerOptions {
-    /** 任务产物模块绝对路径（`<dist>/tasks/<dir>/task.js`） */
-    taskModulePath: string;
-    payload: unknown;
-    /** signal 由执行器构造（abort/terminate 时触发），宿主只传 config 与 job 信息 */
-    taskCtx: {
-        config: unknown;
-        /**
-         * 产物 resources 目录绝对路径（纯字符串可结构化克隆）——经 workerData
-         * 传给入口在任务模块求值前播种全局读取根（内部字段，不进业务 taskCtx）
-         */
-        resourcesDir?: string;
-        job: {
-            id: string;
-            name: string;
-            attempt: number;
-        };
-    };
-    /** 单次执行超时（毫秒） */
-    timeoutMs: number;
+type FaapiMiddleware = (ctx: FaapiContext, next: () => Promise<Response>) => Promise<void | Response>;
+
+interface CorsOptions {
+    origin?: string | string[] | true;
+    methods?: string[];
+    allowedHeaders?: string[];
+    exposeHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+/**
+ * 创建 CORS 中间件（洋葱模型）
+ *
+ * - origin=true: 允许所有来源（反射请求的 Origin）
+ * - origin=string: 允许指定来源
+ * - origin=string[]: 允许多个来源
+ *
+ * OPTIONS 预检请求直接返回 204，不调用 next()。
+ */
+declare function cors(options?: CorsOptions): FaapiMiddleware;
+
+/**
+ * 轻量 LLM 补全通道规范类型
+ *
+ * `LlmComplete` / `LlmCompleteOptions` 是轻量补全通道（`@faapi/agent` 的
+ * `createLightComplete` 实现）的接口契约，规范类型由主包持有——`TaskContext.llm` /
+ * `TaskQueueDeps` / `LlmChannelStore` 等主包类型需引用，而主包不能反向依赖
+ * `@faapi/agent`（依赖方向 agent → 主包 peer）。`@faapi/agent` 实现并 re-export，
+ * 业务方统一从 `@faapi/agent` 导入标注。
+ *
+ * `onFailure` 的 error 参数在此层是 `Error`——具体错误类（`LLMProviderError` /
+ * `LLMTimeoutError`）由实现层抛出，业务方 `instanceof` 细分时从 `@faapi/agent`
+ * 导入类做窄化。
+ *
+ * 详见 [llmTypes.md](./llmTypes.md) 与 `@faapi/agent` 的 lightComplete.md。
+ */
+/** 轻量补全的调用级选项——传输策略（重试/超时/降级/留痕）按场景声明 */
+interface LlmCompleteOptions {
     /**
-     * 取消宽限期（毫秒）——两段式取消第一段发出 abort 信号后等待任务自行退出的
-     * 最长时间，超时未退出 `terminate()` 硬杀。来自 task meta `graceMs`，
-     * 未声明用 `KILL_GRACE_MS`（5s）；`0` 表示不留宽限期（判定取消即硬杀）
+     * 模型字符串 key（与 `agent.run` 的 `options.model` 同一解析规则）：
+     * llms key（如 `'openai'`）/ `provider/model` 一体化（如 `'openai/gpt-4o'`）/
+     * 纯 model 名（在所有 provider 的 `models` 里查找，唯一时命中）
+     *
+     * 缺省回落 `agent.llms` 第一个 provider 的第一个 model。
      */
-    graceMs?: number;
+    model?: string;
+    /** 可选 system 提示词（前置为 system 消息） */
+    system?: string;
+    /** 采样温度（0~2） */
+    temperature?: number;
+    /** 最大生成 token 数 */
+    maxTokens?: number;
     /**
-     * 注册表快照（纯数据，postMessage 结构化克隆传入，worker 内重建只读视图注入
-     * taskCtx.registries）——语义层从 `TaskRegistriesView` 生成，缺省为空视图
+     * 取消信号（透传到底层 HTTP 请求）
+     *
+     * abort 时抛 `AgentAbortError`——取消不是故障：不走 fallback、不触发 onFailure。
      */
-    registries?: TaskRegistriesSnapshot;
+    signal?: AbortSignal;
     /**
-     * 任务日志配置（纯数据，postMessage 传入，worker 内联重建日志器注入 taskCtx.log；
-     * 缺省时 taskCtx.log 为 undefined）：scope/fields 与进程内路径一致（`task:<name>`
-     * + jobId/task/attempt），level 为宿主侧生效的全局级别（worker 侧预过滤，
-     * 宿主 writeLogEntry 再次过滤；undefined = 宿主未配置阈值——文件管道默认全量，
-     * worker 侧同样不过滤）
+     * 本次调用超时（毫秒）
+     *
+     * 优先级：本字段 > 目标 provider 的 `LlmConfig.timeoutMs` > 框架默认 60s。
+     * 超时抛 `LLMTimeoutError`（计入重试，与 429/5xx/网络错误同策略）。
      */
-    log?: {
-        level?: LogLevel;
-        scope?: string;
-        fields?: Record<string, unknown>;
-    };
-    /** 外部取消信号（驱动停机超时 abort）——abort 同样触发两段式取消 */
-    externalSignal?: AbortSignal;
+    timeoutMs?: number;
     /**
-     * 进度回调：worker 内 `taskCtx.progress(value)` 的值经 `{ type: 'progress' }`
-     * 消息回传宿主（语义层记入 `TaskJob.progress`）；不传则进度消息被忽略
+     * 本次调用重试上限（429/5xx/网络错误/超时计入重试）
+     *
+     * 缺省回落 `LlmConfig.maxRetries`（默认 2，0 关闭）。
      */
-    onProgress?: (value: unknown) => void;
+    maxRetries?: number;
     /**
-     * 日志回调：worker 内 taskCtx.log 的条目经 `{ type: 'log' }` 消息回传宿主，
-     * 由语义层接 writeLogEntry 走统一管道（自定义 sink 同样覆盖隔离任务）；
-     * 不传则日志条目被忽略。宽限期（取消判定后）到达的条目不采纳（超时判定即终局）
+     * 降级值：传输失败（重试耗尽）时返回本值而不抛
+     *
+     * 「LLM 失败可降级不可静默」——fallback 命中且未声明 `onFailure` 时，
+     * 框架 `console.warn` 兜底留痕（错误消息含尝试次数）。
+     * 未声明时失败原样抛 `LLMProviderError`。
      */
-    onLog?: (entry: LogEntry) => void;
+    fallback?: string;
+    /**
+     * 失败钩子：重试耗尽后触发（留痕/告警/台账等副作用；自身抛错被忽略）
+     *
+     * - `error` 为 `LLMProviderError`（`instanceof LLMTimeoutError` 细分超时，
+     *   `error.status` 区分 HTTP 状态——502/504 分型等）
+     * - `info.attempts` 为实际发起的 HTTP 尝试次数（含失败尝试，≥1）
+     *
+     * 声明本钩子后框架不再重复 `console.warn`（钩子即留痕点）。
+     * 用户取消（`AgentAbortError`）不触发本钩子。
+     */
+    onFailure?: (error: Error, info: {
+        attempts: number;
+    }) => void;
+}
+/**
+ * 轻量补全通道（handler `llm` 注入参数 / `taskCtx.llm` 的类型）
+ *
+ * 由 `@faapi/agent` 插件注册到 `registries.llm`（插件未加载时注入 `undefined`）。
+ * 与 agent 循环共享 `agent.llms` 同源 providers，项目零新增配置。
+ */
+interface LlmComplete {
+    /**
+     * 一次性补全：字符串进字符串出
+     *
+     * @returns assistant 消息 content（恒字符串；轻量通道不发 tools，LLM 不会请求 tool_call）
+     * @throws {AgentError} model key 解析失败 / llms 未配置（编程/配置错误，不重试不降级）
+     * @throws {LLMProviderError} 传输失败（重试耗尽）且未声明 `fallback`
+     * @throws {AgentAbortError} 用户取消（`options.signal` 触发）
+     */
+    complete(input: string, options?: LlmCompleteOptions): Promise<string>;
 }
-declare function runTaskInWorker(options: TaskWorkerOptions): Promise<unknown>;
 
 /**
  * app 级注册表（方案 A：注册表实例化）
@@ -486,6 +594,20 @@ interface AgentHandleStore {
     get(ctx: FaapiContext): unknown;
     clear(): void;
 }
+/**
+ * 轻量 LLM 补全通道 store（由 `@faapi/agent` 插件注册）
+ *
+ * 与 AgentHandleStore 同形态（app 实例级、随 app 生命周期），差异：channel 与
+ * 请求上下文无关——存实例本身而非工厂。handler 的 `llm` 注入参数与任务执行
+ * 上下文（进程内路径）读取；插件未加载时为空（注入 `undefined`）。
+ */
+interface LlmChannelStore {
+    /** 注册 channel（null 清理）；二次注册覆盖 */
+    register(channel: LlmComplete | null): void;
+    /** channel 已注册时返回实例，未注册返回 undefined */
+    get(): LlmComplete | undefined;
+    clear(): void;
+}
 /** task 客户端工厂函数（由 createAppBase 注册，返回 TaskClient 门面） */
 type TaskHandleFactory = (ctx: FaapiContext) => unknown;
 interface TaskHandleStore {
@@ -503,6 +625,8 @@ interface AppRegistries {
     task: TaskRegistry;
     agentHandle: AgentHandleStore;
     taskHandle: TaskHandleStore;
+    /** 轻量 LLM 补全通道（`@faapi/agent` 插件注册；未加载插件时为空） */
+    llm: LlmChannelStore;
 }
 /**
  * 任务侧注册表只读视图（AppRegistries 的查询投影）
@@ -521,6 +645,960 @@ declare function createTaskRegistriesView(registries: AppRegistries): TaskRegist
 /** 创建一套 app 级注册表（`createAppBase` 每次调用创建独立实例） */
 declare function createAppRegistries(): AppRegistries;
 
+declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+type HttpMethod = (typeof HTTP_METHODS)[number];
+
+/**
+ * 注入器：按参数名匹配，提供 handler 所需的依赖
+ *
+ * 注入器是 faapi 的依赖注入扩展点，与中间件解耦：
+ * - 中间件只管请求流程（鉴权、日志、错误处理）
+ * - 注入器只管提供依赖（数据库连接、用户对象等）
+ *
+ * 注入器可以读取中间件塞进 ctx 的值（如鉴权中间件塞的 ctx.user），
+ * 也可以独立提供依赖（如数据库连接池）。
+ *
+ * 注入器按需执行：只对 handler 声明的参数执行对应的注入器，避免无谓计算。
+ *
+ * 在 middlewares.ts 中通过命名导出 `injectors` 注册：
+ * ```ts
+ * import type { InjectorMap } from '@faapi/faapi';
+ *
+ * export const injectors: InjectorMap = {
+ *   db: () => getDbConnection(),
+ *   user: (ctx) => ctx.user,  // 取中间件塞的值
+ * };
+ * ```
+ */
+type Injector = (ctx: FaapiContext) => unknown | Promise<unknown>;
+/**
+ * 注入器映射表：参数名 → 注入器函数
+ *
+ * key 必须与 handler 参数名一致，运行时按参数名匹配执行。
+ */
+type InjectorMap = Record<string, Injector>;
+
+interface RouteRecord {
+    method: HttpMethod;
+    urlPath: string;
+    filePath: string;
+    paramNames: string[];
+    isDynamic: boolean;
+    /** 是否为 catch-all 路由（[...slug]） */
+    isCatchAll?: boolean;
+    /** 中间件文件绝对路径列表（根在前，路由目录在后；按需加载用） */
+    middlewarePaths?: string[];
+    /** 路由对应的中间件集合（从根到路由目录合并，按需加载后缓存） */
+    middlewares?: FaapiMiddleware[];
+    /** 路由对应的注入器映射表（从根到路由目录合并，按需加载后缓存） */
+    injectors?: InjectorMap;
+}
+/**
+ * WebSocket 路由记录
+ *
+ * 与 HTTP RouteRecord 类似，但不绑定 HTTP 方法（WS 是协议升级，不区分 GET/POST）。
+ * 一个 handler.ts 中导出 WS 即生成一条 WS 路由记录。
+ */
+interface WsRouteRecord {
+    urlPath: string;
+    filePath: string;
+    paramNames: string[];
+    isDynamic: boolean;
+    /** 是否为 catch-all 路由（[...slug]） */
+    isCatchAll?: boolean;
+    /** 中间件文件绝对路径列表（根在前，路由目录在后；按需加载用） */
+    middlewarePaths?: string[];
+    /** 路由对应的中间件集合（握手阶段执行，复用鉴权/CORS/日志；按需加载后缓存） */
+    middlewares?: FaapiMiddleware[];
+    /** 路由对应的注入器映射表 */
+    injectors?: InjectorMap;
+}
+type RouteManifest = RouteRecord[];
+type WsRouteManifest = WsRouteRecord[];
+/**
+ * 路由单个参数的 schema 描述
+ *
+ * 供 @faapi/schema 扩展包消费，通过 MCP 暴露给 LLM。
+ */
+interface RouteParamSchema {
+    name: string;
+    type: string;
+    required: boolean;
+}
+/**
+ * 路由单个输入源的 schema 描述
+ */
+interface RouteInputSchema {
+    source: 'query' | 'body' | 'params';
+    schemaName: string | null;
+    properties: RouteParamSchema[];
+}
+/**
+ * 路由响应类型的 schema 描述
+ *
+ * 由 @faapi/schema 扩展包的 buildRouteSchemas 生成。
+ * output 为 null 表示无显式返回类型注解、void/Promise<void>、或解析失败降级。
+ */
+interface RouteOutputSchema {
+    /** 命名类型名(如 'UserResponse'),内联类型为 null */
+    schemaName: string | null;
+    /** 顶层属性列表 */
+    properties: RouteParamSchema[];
+}
+/**
+ * 路由的完整 schema 描述
+ *
+ * 由 @faapi/schema 扩展包的 buildRouteSchemas 生成。
+ * 主包只定义类型契约，逻辑实现在扩展包。
+ */
+interface RouteInfo {
+    method: string;
+    path: string;
+    filePath: string;
+    isDynamic: boolean;
+    inputs: RouteInputSchema[];
+    /** 响应类型描述(null 表示无返回类型注解/void/解析失败) */
+    output: RouteOutputSchema | null;
+}
+
+/** 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 HelmetOptions {
+    contentSecurityPolicy?: string | false;
+    xFrameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+    xContentTypeOptions?: boolean;
+    referrerPolicy?: string | false;
+    strictTransportSecurity?: string | false;
+    xDnsPrefetchControl?: boolean;
+    xDownloadOptions?: boolean;
+    xPermittedCrossDomainPolicies?: string | false;
+    crossOriginOpenerPolicy?: string | false;
+    crossOriginResourcePolicy?: string | false;
+    crossOriginEmbedderPolicy?: string | false;
+    originAgentCluster?: boolean;
+    xPoweredBy?: boolean;
+}
+declare function helmet(options?: HelmetOptions): FaapiMiddleware;
+
+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;
+}
+
+/**
+ * 隔离执行器签名（taskQueue 按任务 meta.timeoutMs 调用；测试可注入 spy）
+ */
+type TaskWorkerRunner = typeof runTaskInWorker;
+interface TaskWorkerOptions {
+    /** 任务产物模块绝对路径（`<dist>/tasks/<dir>/task.js`） */
+    taskModulePath: string;
+    payload: unknown;
+    /** signal 由执行器构造（abort/terminate 时触发），宿主只传 config 与 job 信息 */
+    taskCtx: {
+        config: unknown;
+        /**
+         * 产物 resources 目录绝对路径（纯字符串可结构化克隆）——经 workerData
+         * 传给入口在任务模块求值前播种全局读取根（内部字段，不进业务 taskCtx）
+         */
+        resourcesDir?: string;
+        job: {
+            id: string;
+            name: string;
+            attempt: number;
+        };
+    };
+    /** 单次执行超时（毫秒） */
+    timeoutMs: number;
+    /**
+     * 取消宽限期（毫秒）——两段式取消第一段发出 abort 信号后等待任务自行退出的
+     * 最长时间，超时未退出 `terminate()` 硬杀。来自 task meta `graceMs`，
+     * 未声明用 `KILL_GRACE_MS`（5s）；`0` 表示不留宽限期（判定取消即硬杀）
+     */
+    graceMs?: number;
+    /**
+     * 注册表快照（纯数据，postMessage 结构化克隆传入，worker 内重建只读视图注入
+     * taskCtx.registries）——语义层从 `TaskRegistriesView` 生成，缺省为空视图
+     */
+    registries?: TaskRegistriesSnapshot;
+    /**
+     * `agent.llms` 纯数据快照（postMessage 结构化克隆传入，worker 内动态加载
+     * `@faapi/agent` 重建轻量补全通道注入 taskCtx.llm）——缺省不传，worker 内
+     * taskCtx.llm 为 undefined
+     */
+    llms?: Record<string, LlmConfig>;
+    /**
+     * 任务日志配置（纯数据，postMessage 传入，worker 内联重建日志器注入 taskCtx.log；
+     * 缺省时 taskCtx.log 为 undefined）：scope/fields 与进程内路径一致（`task:<name>`
+     * + jobId/task/attempt），level 为宿主侧生效的全局级别（worker 侧预过滤，
+     * 宿主 writeLogEntry 再次过滤；undefined = 宿主未配置阈值——文件管道默认全量，
+     * worker 侧同样不过滤）
+     */
+    log?: {
+        level?: LogLevel;
+        scope?: string;
+        fields?: Record<string, unknown>;
+    };
+    /** 外部取消信号（驱动停机超时 abort）——abort 同样触发两段式取消 */
+    externalSignal?: AbortSignal;
+    /**
+     * 进度回调：worker 内 `taskCtx.progress(value)` 的值经 `{ type: 'progress' }`
+     * 消息回传宿主（语义层记入 `TaskJob.progress`）；不传则进度消息被忽略
+     */
+    onProgress?: (value: unknown) => void;
+    /**
+     * 日志回调：worker 内 taskCtx.log 的条目经 `{ type: 'log' }` 消息回传宿主，
+     * 由语义层接 writeLogEntry 走统一管道（自定义 sink 同样覆盖隔离任务）；
+     * 不传则日志条目被忽略。宽限期（取消判定后）到达的条目不采纳（超时判定即终局）
+     */
+    onLog?: (entry: LogEntry) => void;
+}
+declare function runTaskInWorker(options: TaskWorkerOptions): Promise<unknown>;
+
 /**
  * 任务元信息（业务方在 task.ts 中 `export const task = {...}` 声明）
  *
@@ -654,6 +1732,16 @@ interface TaskContext {
      * 隔离执行时条目经 postMessage 回传宿主输出，fields 需可结构化克隆。
      */
     log?: Logger;
+    /**
+     * 轻量 LLM 补全通道（可选字段；`@faapi/agent` 插件加载且 `agent.llms` 可解析时注入）
+     *
+     * 进程内执行为 `registries.llm` 的活引用（与 agent 循环共享 providers 单例）；
+     * 隔离执行为 worker 内按 `agent.llms` 纯数据快照重建的实例（`@faapi/agent`
+     * 不可解析时为 `undefined`，warn 留痕不中断执行）。
+     * 一次性补全（分类/蒸馏/摘要等）用此通道，不必在任务内组装 agent；
+     * 工具循环场景仍走 registries.agent 组装 Agent。详见 `@faapi/agent` 的 lightComplete.md。
+     */
+    llm?: LlmComplete;
 }
 /**
  * 任务模块形态（task.ts 编译产物中与执行相关的导出）
@@ -738,6 +1826,17 @@ interface TaskQueueDeps {
      * TaskContext.registries；缺省为空视图（直接构造队列的测试/嵌入场景）
      */
     registries?: TaskRegistriesView;
+    /**
+     * 轻量 LLM 补全通道 store（AppRegistries.llm）——进程内执行路径在任务执行时刻
+     * 惰性读取（插件晚于队列构造注册，构造期快照会漏）；缺省 taskCtx.llm 恒 undefined
+     */
+    llm?: LlmChannelStore;
+    /**
+     * `agent.llms` 纯数据快照——隔离执行路径经 postMessage 传入 worker，worker 内
+     * 动态加载 `@faapi/agent` 重建补全通道（纯数据可结构化克隆）。缺省不传入
+     * （worker 内 taskCtx.llm 为 undefined）
+     */
+    llms?: Record<string, LlmConfig>;
     /**
      * 队列驱动（必填）：`loadTaskDriver` 解析结果（pgboss/bullmq 子包驱动）
      * 或自定义 TaskDriver 实例；无任务清单时由 createAppBase 传入 idleTaskDriver
@@ -1159,4 +2258,4 @@ interface FaapiContext {
     deleteCookie(name: string): void;
 }
 
-export { type AppRegistries as A, type TaskDriverProcess as B, type CreateLoggerOptions as C, type TaskDriverRecord as D, type TaskFailedInfo as E, type FaapiContext as F, type TaskJob as G, type TaskJobStatus as H, type TaskMetadata as I, type TaskModule as J, type TaskRegistriesSnapshot as K, type LogConfig as L, type TaskRegistriesView as M, type ToolCore as N, type ToolPathMeta as O, type ToolRegistry as P, createAppRegistries as Q, createTaskRegistriesView as R, type SkillRegistry as S, type TaskClient as T, createTaskRegistry as U, type TaskFailedHandler as a, type TaskQueueDeps as b, type TaskQueue as c, type TaskDriver as d, type TaskRegistry as e, type TaskManifest as f, type ToolMetadata as g, type AgentCore as h, type AgentMetadata as i, type Logger as j, type AgentHandleFactory as k, type AgentHandleStore as l, type AgentPathMeta as m, type AgentRegistry as n, type AgentToolDescriptor as o, type FaapiContextConfig as p, type FaapiTaskMeta as q, type FailOptions as r, type LogEntry as s, type LogLevel as t, type LogSink as u, type SseEvent as v, type SseOptions as w, type SseWriter as x, type TaskContext as y, type TaskDriverJob as z };
+export { type SseWriter as $, type AgentCore as A, type LlmComplete as B, type CreateLoggerOptions as C, type LlmCompleteOptions as D, type LlmConfig as E, type FaapiMiddleware as F, type LlmModelConfig as G, type HelmetOptions as H, type Injector as I, type LogEntry as J, type LogLevel as K, type LogConfig as L, type LogSink as M, type PluginDeclaration as N, type RequestHandler as O, type PluginContext as P, type ResponseConfig as Q, type RouteManifest as R, type RouteInfo as S, type TaskQueueDeps as T, type RouteInputSchema as U, type RouteOutputSchema as V, type WsRouteManifest as W, type RouteParamSchema as X, type SkillRegistry as Y, type SseEvent as Z, type SseOptions as _, type TaskQueue as a, type TaskBullMqOptions as a0, type TaskConfig as a1, type TaskContext as a2, type TaskDriverJob as a3, type TaskDriverProcess as a4, type TaskDriverRecord as a5, type TaskFailedHandler as a6, type TaskFailedInfo as a7, type TaskJob as a8, type TaskJobStatus as a9, type TaskMetadata as aa, type TaskModule as ab, type TaskPgBossOptions as ac, type TaskRegistriesSnapshot as ad, type TaskRegistriesView as ae, type ToolCore as af, type ToolPathMeta as ag, type ToolRegistry as ah, type UpgradeHandler as ai, cors as aj, createAppRegistries as ak, createTaskRegistriesView as al, createTaskRegistry as am, helmet as an, type TaskDriver as b, type TaskRegistry as c, type TaskManifest as d, type AgentMetadata as e, type ToolMetadata as f, type FaapiContext as g, type FaapiConfig as h, type Logger as i, type AppRegistries as j, type TaskClient as k, type AgentConfig as l, type AgentHandleFactory as m, type AgentHandleStore as n, type AgentPathMeta as o, type AgentRegistry as p, type AgentToolDescriptor as q, type CorsOptions as r, type FaapiContextConfig as s, type FaapiPlugin as t, type FaapiTaskMeta as u, type FailOptions as v, type InjectorMap as w, type LifecycleContext as x, type LifecycleHooks as y, type LlmChannelStore as z };