@faapi/faapi 6.3.0 → 6.4.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AppRegistries, R as RouteManifest, F as FaapiContext, C as CorsOptions, T as TaskClient, H as HelmetOptions, L as LoggerOptions, a as FaapiMiddleware, I as InjectorMap, b as TaskQueueDeps, c as TaskQueue, d as TaskDriver, e as TaskRegistry, f as TaskManifest, g as ToolMetadata, h as AgentCore, i as AgentMetadata, W as WsRouteManifest } from './routeTypes-CCveqSnY.js';
-export { j as AgentHandleFactory, k as AgentHandleStore, l as AgentPathMeta, m as AgentRegistry, n as AgentToolDescriptor, o as FaapiContextConfig, p as FaapiTaskMeta, q as FailOptions, r as Injector, s as RouteInfo, t as RouteInputSchema, u as RouteOutputSchema, v as RouteParamSchema, S as SkillRegistry, w as SseEvent, x as SseWriter, y as TaskContext, z as TaskDriverJob, B as TaskDriverProcess, D as TaskJob, E as TaskJobStatus, G as TaskMetadata, J as TaskModule, K as ToolCore, M as ToolPathMeta, N as ToolRegistry, O as cors, P as createAppRegistries, Q as createTaskRegistry, U as helmet, V as logger } from './routeTypes-CCveqSnY.js';
+import { A as AppRegistries, R as RouteManifest, F as FaapiContext, C as CorsOptions, T as TaskClient, H as HelmetOptions, L as LoggerOptions, a as FaapiMiddleware, I as InjectorMap, b as TaskFailedHandler, c as TaskQueueDeps, d as TaskQueue, e as TaskDriver, f as TaskRegistry, g as TaskManifest, h as ToolMetadata, i as AgentCore, j as AgentMetadata, W as WsRouteManifest } from './routeTypes-_17rXzal.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 Injector, t as RouteInfo, u as RouteInputSchema, v as RouteOutputSchema, w as RouteParamSchema, S as SkillRegistry, x as SseEvent, y as SseWriter, z as TaskContext, B as TaskDriverJob, D as TaskDriverProcess, E as TaskDriverRecord, G as TaskFailedInfo, J as TaskJob, K as TaskJobStatus, M as TaskMetadata, N as TaskModule, O as ToolCore, P as ToolPathMeta, Q as ToolRegistry, U as cors, V as createAppRegistries, X as createTaskRegistry, Y as helmet, Z as logger } from './routeTypes-_17rXzal.js';
 import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -157,13 +157,50 @@ interface LifecycleHooks {
     onError?: (error: unknown, ctx: FaapiContext) => Promise<void> | void;
 }
 /**
- * 任务子系统配置（config.task，全部字段可选）
+ * pg-boss 驱动选项（透传给 @faapi/task-pgboss）
  *
- * 第一版为进程内内存队列（重启丢任务、多实例不防重跑——部署职责见 task 子系统文档）。
+ * 主包不依赖 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 {
-    /** 队列驱动，当前仅 'memory'（默认） */
-    driver?: 'memory';
+    /**
+     * 队列驱动：'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）
      *
@@ -173,6 +210,12 @@ interface TaskConfig {
     enabled?: boolean;
     /** 优雅停机时等待在跑任务的最长时间（毫秒，默认 10000；超时 abort） */
     shutdownTimeoutMs?: number;
+    /**
+     * 任务执行失败/取消钩子——每次 process 抛错后触发（含将重试的失败），
+     * `info.willRetry` 按任务 meta.retries 推算、`info.cancelled` 标记框架终止；
+     * 用于告警/死信上报等副作用，自身抛错被忽略
+     */
+    onFailed?: TaskFailedHandler;
 }
 /**
  * 生命周期上下文
@@ -1087,47 +1130,37 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
  * 职责边界（driverTypes.md）：
  * - 本层：任务存在性检查 → payload zod 校验 → 驱动入队；worker 执行包装
  *   （模块加载 + run 调用 + 任务记录更新）；start/stop/reload 生命周期编排
- * - 驱动层（deps.driver，默认 memoryDriver）：入队存储、worker 消费、重试策略、停机 drain
+ * - 驱动层（deps.driver，必填——持久化驱动子包或自定义 TaskDriver）：
+ *   入队存储、worker 消费、重试策略、停机 drain
  *
  * 任务记录（list）由本层维护：enqueue 写 pending，每次 process 写 attempts/running，
  * 返回写 done，抛错写 failed——对任何驱动语义一致。
  */
 declare function createTaskQueue(deps: TaskQueueDeps): TaskQueue;
 
-/**
- * 进程内内存驱动（TaskDriver 默认实现，零依赖）
- *
- * 行为与第一版内存队列一致（taskQueue 重构前的原始语义）：
- * - 入队进每任务 FIFO 数组；延迟任务由 runAt 控制
- * - 每任务最多 concurrency 个并行（startWorker 注册时给定）
- * - 失败按 retries 指数退避重试（500ms * 2^(n-1)，封顶 30s）；耗尽后丢弃（失败记录由语义层在最后一次 process 抛错时写入）
- * - stop(timeoutMs)：停止出队 + 停接受新任务，等在跑任务，超时 abort；重试等待中的任务取消（视为失败）
- *
- * 取舍不变：重启即丢、多实例不防重跑（fallback.md）。
- */
-declare function createMemoryDriver(): TaskDriver;
-
 /**
  * 按 config.task.driver 解析并加载任务队列驱动
  *
- * - 未设置 / `'memory'` → 内置 memoryDriver（零依赖）
  * - `'pgboss'` → 动态加载子包 `@faapi/task-pgboss` 的 `createPgBossDriver(options)`
  * - `'bullmq'` → 动态加载子包 `@faapi/task-bullmq` 的 `createBullMQDriver(options)`
  * - TaskDriver 对象 → 直接使用（编程式自定义驱动）
- * - 其他值 → 显式抛错，不静默降级
+ * - `undefined` / `'memory'` / 其他值 → 显式抛错，不静默降级
+ *
+ * 内置 memory 驱动已移除——任务队列由持久化/外部驱动承载；未配置 driver 时
+ * createAppBase 仅在存在任务清单时报错（无任务项目用 idleTaskDriver，不调用本函数）。
  *
  * 子包 specifier 用变量拼接（`'@faapi/task-' + name`）而非字面量——主包不依赖
  * 驱动子包，运行时从业务方 node_modules 解析（与 zod peerDependency 同策略）。
- * 未安装时抛出带安装指引的错误，不静默回退 memory。
+ * 未安装时抛出带安装指引的错误。
  */
 declare function loadTaskDriver(driver: string | TaskDriver | undefined, driverOptions: unknown): Promise<TaskDriver>;
 
 /**
  * cron 定时入队调度器
  *
- * 为注册表中声明了 `cron` 的任务建立 croner 定时器，到点调用 `enqueue(name)`
- * 投递空 payload——定时只是"自动投递者"，复用队列的重试/并发/停机语义。
- * 详见 cronScheduler.md。
+ * 为注册表中声明了 `cron` 的任务建立 croner 定时器，到点调用
+ * `enqueue(name, { dedupId })` 投递空 payload——定时只是"自动投递者"，
+ * 复用队列的重试/并发/停机语义。详见 cronScheduler.md。
  */
 interface CronScheduler {
     /** 建立全部 cron 定时器（幂等——重复调用先清理旧定时器） */
@@ -1135,7 +1168,14 @@ interface CronScheduler {
     /** 停止全部定时器（幂等） */
     stop(): void;
 }
-declare function createCronScheduler(registry: TaskRegistry, enqueue: (name: string) => Promise<unknown>): CronScheduler;
+/**
+ * cron 投递回调：opts.dedupId 为多实例防重幂等键
+ * （`cron:<任务名>:<计划触发时刻>`——各实例同一触发窗算出同键，驱动按键去重）
+ */
+type CronEnqueue = (name: string, opts: {
+    dedupId?: string;
+}) => Promise<unknown>;
+declare function createCronScheduler(registry: TaskRegistry, enqueue: CronEnqueue): CronScheduler;
 
 /**
  * 任务扫描 patterns（框架约定，非用户可配置项）
@@ -1626,4 +1666,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type AgentConfig, AgentCore, AgentMetadata, type AgentModule, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, type CronScheduler, 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, TASK_PATTERNS, TaskClient, TaskDriver, TaskManifest, 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, createProdApp as createApp, createCronScheduler, createDevApp, createMemoryDriver, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, upsertSkill };
+export { type AgentConfig, AgentCore, AgentMetadata, type AgentModule, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, type CronScheduler, 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, 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, createProdApp as createApp, createCronScheduler, createDevApp, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, upsertSkill };