@faapi/faapi 6.2.0 → 6.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AppRegistries, R as RouteManifest, F as FaapiContext, C as CorsOptions, H as HelmetOptions, L as LoggerOptions, a as FaapiMiddleware, I as InjectorMap, T as ToolMetadata, b as AgentCore, c as AgentMetadata, W as WsRouteManifest } from './routeTypes-Bm--uTbm.js';
-export { d as AgentHandleFactory, e as AgentHandleStore, f as AgentPathMeta, g as AgentRegistry, h as AgentToolDescriptor, i as FaapiContextConfig, j as FailOptions, k as Injector, l as RouteInfo, m as RouteInputSchema, n as RouteOutputSchema, o as RouteParamSchema, S as SkillRegistry, p as SseEvent, q as SseWriter, r as ToolCore, s as ToolPathMeta, t as ToolRegistry, u as cors, v as createAppRegistries, w as helmet, x as logger } from './routeTypes-Bm--uTbm.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';
@@ -156,6 +156,67 @@ interface LifecycleHooks {
      */
     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;
+}
 /**
  * 生命周期上下文
  */
@@ -168,6 +229,8 @@ interface LifecycleContext {
     server: node_http.Server;
     /** app 级注册表——skill 等运行时动态注册路径（`registries.skill.upsert(...)`） */
     registries: AppRegistries;
+    /** 任务客户端——onBoot/onReady 中投递异步任务（`tasks.enqueue(name, payload)`） */
+    tasks: TaskClient;
 }
 /**
  * 统一响应包装配置
@@ -617,6 +680,19 @@ interface 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）
      *
@@ -1048,6 +1124,79 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
     resolversByFile: Map<string, LazyTypeResolver>;
 };
 
+/**
+ * 任务队列语义层
+ *
+ * 职责边界（driverTypes.md）：
+ * - 本层：任务存在性检查 → payload zod 校验 → 驱动入队；worker 执行包装
+ *   （模块加载 + run 调用 + 任务记录更新）；start/stop/reload 生命周期编排
+ * - 驱动层（deps.driver，必填——持久化驱动子包或自定义 TaskDriver）：
+ *   入队存储、worker 消费、重试策略、停机 drain
+ *
+ * 任务记录（list）由本层维护：enqueue 写 pending，每次 process 写 attempts/running，
+ * 返回写 done，抛错写 failed——对任何驱动语义一致。
+ */
+declare function createTaskQueue(deps: TaskQueueDeps): TaskQueue;
+
+/**
+ * 按 config.task.driver 解析并加载任务队列驱动
+ *
+ * - `'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 同策略）。
+ * 未安装时抛出带安装指引的错误。
+ */
+declare function loadTaskDriver(driver: string | TaskDriver | undefined, driverOptions: unknown): Promise<TaskDriver>;
+
+/**
+ * cron 定时入队调度器
+ *
+ * 为注册表中声明了 `cron` 的任务建立 croner 定时器，到点调用
+ * `enqueue(name, { dedupId })` 投递空 payload——定时只是"自动投递者"，
+ * 复用队列的重试/并发/停机语义。详见 cronScheduler.md。
+ */
+interface CronScheduler {
+    /** 建立全部 cron 定时器（幂等——重复调用先清理旧定时器） */
+    start(): void;
+    /** 停止全部定时器（幂等） */
+    stop(): void;
+}
+/**
+ * cron 投递回调：opts.dedupId 为多实例防重幂等键
+ * （`cron:<任务名>:<计划触发时刻>`——各实例同一触发窗算出同键，驱动按键去重）
+ */
+type CronEnqueue = (name: string, opts: {
+    dedupId?: string;
+}) => Promise<unknown>;
+declare function createCronScheduler(registry: TaskRegistry, enqueue: CronEnqueue): CronScheduler;
+
+/**
+ * 任务扫描 patterns（框架约定，非用户可配置项）
+ *
+ * 与路由的 src/api、tool 的 src/tools 对称——任务文件约定放在
+ * `src/tasks` 下任意层级子目录的 task.ts（与 handler.ts 同构的一文件一任务约定）。
+ */
+declare const TASK_PATTERNS: string[];
+/**
+ * 扫描 tasks 目录，生成任务清单
+ *
+ * Vite 风格：只读源码 + 正则提取 meta 字面量，不 import 任务模块。
+ * 任务模块的编译与加载延后到运行时（队列派发时 import 产物路径）。
+ *
+ * 重名检测：不同文件推导出同名任务时抛错。
+ *
+ * @param rootDir 项目根目录
+ * @param patterns glob patterns（匹配 src/tasks 下的 task.ts）
+ */
+declare function scanTasks(rootDir: string, patterns: string[]): Promise<TaskManifest[]>;
+
 /**
  * 加载后的 agent 模块
  *
@@ -1443,6 +1592,8 @@ interface AppBase {
     wsRoutes: WsRouteManifest;
     /** 项目根目录 */
     rootDir: string;
+    /** 任务队列客户端（入队/查询；app 实例级，close 时随队列停机） */
+    tasks: TaskClient;
     /** 启动 HTTP server，打印路由表，执行 onReady 钩子 */
     listen(port?: number): Promise<Server>;
     /** 关闭 server，执行 onClose 钩子 */
@@ -1467,6 +1618,8 @@ interface DevApp extends AppBase {
     reloadTools(): Promise<void>;
     /** 重新扫描 agents + 重生成 faapi-agents.js + 清缓存（dev 热替换用） */
     reloadAgents(): Promise<void>;
+    /** 重新扫描 tasks + 重编译任务源码 + 重生成 faapi-tasks.js + 清队列缓存（dev 热替换用） */
+    reloadTasks(): Promise<void>;
 }
 /**
  * dev 模式应用启动 API
@@ -1513,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 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, 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, createDevApp, createProdApp, createProgram, createPrograms, extractTypeInfo, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadToolModule, loadToolSchema, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, 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 };