@faapi/faapi 6.1.0 → 6.3.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 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 * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -156,6 +156,24 @@ interface LifecycleHooks {
      */
     onError?: (error: unknown, ctx: FaapiContext) => Promise<void> | void;
 }
+/**
+ * 任务子系统配置（config.task，全部字段可选）
+ *
+ * 第一版为进程内内存队列（重启丢任务、多实例不防重跑——部署职责见 task 子系统文档）。
+ */
+interface TaskConfig {
+    /** 队列驱动，当前仅 'memory'（默认） */
+    driver?: 'memory';
+    /**
+     * 是否启动任务队列（默认 true）
+     *
+     * 多实例部署时可在非 worker 节点设 `FAAPI_TASKS_DISABLED=1` 或 `task.enabled: false`，
+     * API 节点照常入队（入队能力保留），但不消费执行。
+     */
+    enabled?: boolean;
+    /** 优雅停机时等待在跑任务的最长时间（毫秒，默认 10000；超时 abort） */
+    shutdownTimeoutMs?: number;
+}
 /**
  * 生命周期上下文
  */
@@ -168,6 +186,8 @@ interface LifecycleContext {
     server: node_http.Server;
     /** app 级注册表——skill 等运行时动态注册路径（`registries.skill.upsert(...)`） */
     registries: AppRegistries;
+    /** 任务客户端——onBoot/onReady 中投递异步任务（`tasks.enqueue(name, payload)`） */
+    tasks: TaskClient;
 }
 /**
  * 统一响应包装配置
@@ -617,6 +637,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 +1081,82 @@ declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: stri
     resolversByFile: Map<string, LazyTypeResolver>;
 };
 
+/**
+ * 任务队列语义层
+ *
+ * 职责边界（driverTypes.md）：
+ * - 本层：任务存在性检查 → payload zod 校验 → 驱动入队；worker 执行包装
+ *   （模块加载 + run 调用 + 任务记录更新）；start/stop/reload 生命周期编排
+ * - 驱动层（deps.driver，默认 memoryDriver）：入队存储、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 对象 → 直接使用（编程式自定义驱动）
+ * - 其他值 → 显式抛错，不静默降级
+ *
+ * 子包 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。
+ */
+interface CronScheduler {
+    /** 建立全部 cron 定时器（幂等——重复调用先清理旧定时器） */
+    start(): void;
+    /** 停止全部定时器（幂等） */
+    stop(): void;
+}
+declare function createCronScheduler(registry: TaskRegistry, enqueue: (name: string) => Promise<unknown>): 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 +1552,8 @@ interface AppBase {
     wsRoutes: WsRouteManifest;
     /** 项目根目录 */
     rootDir: string;
+    /** 任务队列客户端（入队/查询；app 实例级，close 时随队列停机） */
+    tasks: TaskClient;
     /** 启动 HTTP server，打印路由表，执行 onReady 钩子 */
     listen(port?: number): Promise<Server>;
     /** 关闭 server，执行 onClose 钩子 */
@@ -1467,6 +1578,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 +1626,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, 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 };