@faapi/faapi 6.2.0 → 6.3.0

package/dist/{routeTypes-Bm--uTbm.d.ts → routeTypes-CCveqSnY.d.ts}

@@ -1,3 +1,199 @@
+/**
+ * app 实例级任务注册表（与 tool/agent/skill registry 同构，方案 A 实例化）
+ *
+ * 任务清单来自编译期产物（faapi-tasks.js），reload 时整体替换（hydrate 语义）。
+ * 每个 app 持有独立实例，多 app 同进程互不串台；详见 taskRegistry.md。
+ */
+interface TaskRegistry {
+    /** 全量替换（任务清单来自编译期产物，reload 时整体重新生成） */
+    hydrate(tasks: TaskMetadata[]): void;
+    /** 按任务名查找 */
+    get(name: string): TaskMetadata | undefined;
+    /** 所有已注册任务（副本） */
+    list(): TaskMetadata[];
+    clear(): void;
+}
+declare function createTaskRegistry(): TaskRegistry;
+
+/**
+ * 任务队列驱动抽象（语义层与存储/调度实现分离的边界）
+ *
+ * 语义层（taskQueue）负责：任务存在性检查、payload zod 校验、任务模块加载、
+ * run 执行包装、任务记录（list）；驱动层负责：入队存储、worker 消费、
+ * 失败重试、停机 drain。换驱动 = 换存储，业务方写法不变。
+ *
+ * 内置 memory 驱动（memoryDriver.ts，进程内数组，零依赖）；
+ * 外部驱动由独立子包提供：`@faapi/task-pgboss`（Postgres）、`@faapi/task-bullmq`（Redis），
+ * 主包不依赖它们——按 config.task.driver 动态加载（loadTaskDriver.ts）。
+ */
+
+/** 驱动层交付给语义层执行的单个任务 */
+interface TaskDriverJob {
+    /** 队列系统侧任务 id（memory 为 uuid；pg-boss/bullmq 为其自身 id） */
+    id: string;
+    name: string;
+    payload: unknown;
+    /** 第几次执行（从 1 起，含重试） */
+    attempt: number;
+    /** 停机/取消信号；驱动不支持取消时为永不 abort 的信号 */
+    signal: AbortSignal;
+}
+/** 语义层交给驱动层的执行函数（抛错 = 失败，由驱动按入队时的 retries 重试） */
+type TaskDriverProcess = (job: TaskDriverJob) => Promise<unknown>;
+/**
+ * 任务队列驱动接口
+ */
+interface TaskDriver {
+    /**
+     * 入队一个任务，返回驱动侧任务 id
+     *
+     * @param opts.retries 失败重试次数（语义层从任务 meta 取，驱动负责执行重试策略）
+     * @throws 驱动已停止 / 连接失败等
+     */
+    enqueue(name: string, payload: unknown, opts?: {
+        delayMs?: number;
+        retries?: number;
+    }): Promise<string>;
+    /**
+     * 注册某任务的消费 worker（幂等覆盖）。process 抛错 = 本次失败，驱动决定重试。
+     * 调用时机：queue.start() 为注册表中每个任务注册一次。
+     */
+    startWorker(name: string, opts: {
+        concurrency: number;
+        process: TaskDriverProcess;
+    }): Promise<void> | void;
+    /** 停止消费并等待 in-flight 任务（timeoutMs 超时后驱动自行处置），幂等 */
+    stop(timeoutMs?: number): Promise<void>;
+    /** 仅停止 worker 消费（不断开驱动连接），供 dev reloadTasks 重注册用；可选 */
+    stopWorkers?(): Promise<void>;
+}
+
+/**
+ * 任务元信息（业务方在 task.ts 中 `export const task = {...}` 声明）
+ *
+ * 所有字段可选；未声明时由运行时使用默认值（concurrency=1、retries=0、无 cron）。
+ */
+interface FaapiTaskMeta {
+    /** 同名任务的最大并行执行数（默认 1） */
+    concurrency?: number;
+    /** 失败重试次数（默认 0——失败即 failed，不重试） */
+    retries?: number;
+    /** cron 表达式（croner 语法，支持秒级）——到点自动入队空 payload */
+    cron?: string;
+}
+/**
+ * 构建期扫描清单记录（scanTasks 产出，源码路径形式）
+ */
+interface TaskManifest {
+    /** 任务名：tasks/ 后目录路径段用 . 连接（如 `send-email`、`a.b`） */
+    name: string;
+    /** 源码相对路径（`src/tasks/<dir>/task.ts`） */
+    filePath: string;
+    cron?: string;
+    concurrency?: number;
+    retries?: number;
+}
+/**
+ * 运行时任务元数据（faapi-tasks.js 水合到 TaskRegistry 后的形态，产物路径形式）
+ */
+interface TaskMetadata {
+    name: string;
+    /** 产物路径（`<dist>/tasks/<dir>/task.js`），运行时 import 任务模块 */
+    filePath: string;
+    cron?: string;
+    concurrency?: number;
+    retries?: number;
+}
+/** 任务记录状态 */
+type TaskJobStatus = 'pending' | 'running' | 'retry' | 'done' | 'failed';
+/**
+ * 任务执行记录（内存快照）
+ */
+interface TaskJob {
+    id: string;
+    name: string;
+    payload: unknown;
+    status: TaskJobStatus;
+    /** 已执行次数（含当前正在执行的一次） */
+    attempts: number;
+    /** run 的返回值（done 时） */
+    result?: unknown;
+    /** 错误消息（failed 时） */
+    error?: string;
+    createdAt: number;
+    /** 计划执行时间戳（重试/延迟任务与 createdAt 不同） */
+    runAt?: number;
+}
+/**
+ * 传给任务 run 函数的第二参数
+ */
+interface TaskContext {
+    /** 优雅停机时对在跑任务 abort 的信号 */
+    signal: AbortSignal;
+    /** faapi.config.ts 全量配置（含自定义业务配置） */
+    config: unknown;
+    job: {
+        id: string;
+        name: string;
+        attempt: number;
+    };
+}
+/**
+ * 任务模块形态（task.ts 编译产物中与执行相关的导出）
+ */
+interface TaskModule {
+    run?: (payload: unknown, taskCtx: TaskContext) => unknown;
+}
+/**
+ * 任务触发客户端（`tasks` 注入参数 / `ctx.tasks` / `app.tasks` 共用）
+ */
+interface TaskClient {
+    /**
+     * 入队一个任务
+     *
+     * @returns 任务 id
+     * @throws 任务不存在 / 队列已停止 / payload 校验失败（ValidationError）
+     */
+    enqueue(name: string, payload?: unknown, opts?: {
+        delayMs?: number;
+    }): Promise<{
+        id: string;
+    }>;
+    /** 任务记录快照（可按任务名过滤） */
+    list(name?: string): TaskJob[];
+}
+/**
+ * 任务队列（TaskClient + 生命周期控制，createAppBase 内部使用）
+ */
+interface TaskQueue extends TaskClient {
+    /** 开始派发（幂等） */
+    start(): void;
+    /** 停止接受新任务并等待在跑任务完成（超时 abort），幂等 */
+    stop(timeoutMs?: number): Promise<void>;
+    /** 重注册 worker（dev reloadTasks 用——驱动连接保持，仅按最新注册表重建消费） */
+    reload(): Promise<void>;
+    /** 清空任务模块缓存（dev reloadTasks 用） */
+    invalidateModules(): void;
+    /** 清空 payload schema 缓存（dev reloadTasks 用） */
+    invalidateSchemas(): void;
+}
+/** 队列依赖（测试可注入自定义加载器/驱动） */
+interface TaskQueueDeps {
+    registry: TaskRegistry;
+    rootDir: string;
+    /** faapi.config.ts 全量配置，透传给 run 的 TaskContext.config */
+    config?: unknown;
+    /**
+     * 队列驱动（默认 memoryDriver——进程内数组，重启丢任务）
+     * 外部驱动：`@faapi/task-pgboss` / `@faapi/task-bullmq` 或自定义 TaskDriver 实例
+     */
+    driver?: TaskDriver;
+    /** 任务模块加载器（默认：import 产物路径） */
+    loadTaskModule?: (filePath: string) => Promise<TaskModule>;
+    /** payload schema 加载器（默认：import 任务目录 zod.js，取首个 `*Schema` 导出） */
+    loadPayloadSchema?: (filePath: string) => Promise<unknown>;
+}
+
 /**
  * SSE（Server-Sent Events）支持
  *
@@ -273,12 +469,23 @@ interface AgentHandleStore {
     get(ctx: FaapiContext): unknown;
     clear(): void;
 }
+/** task 客户端工厂函数（由 createAppBase 注册，返回 TaskClient 门面） */
+type TaskHandleFactory = (ctx: FaapiContext) => unknown;
+interface TaskHandleStore {
+    /** 注册工厂（null 清理）；二次注册覆盖 */
+    register(factory: TaskHandleFactory | null): void;
+    /** 工厂已注册时返回 TaskClient，未注册返回 undefined */
+    get(ctx: FaapiContext): unknown;
+    clear(): void;
+}
 /** 一个 app 实例持有的全套注册表 */
 interface AppRegistries {
     tool: ToolRegistry;
     agent: AgentRegistry;
     skill: SkillRegistry;
+    task: TaskRegistry;
     agentHandle: AgentHandleStore;
+    taskHandle: TaskHandleStore;
 }
 /** 创建一套 app 级注册表（`createAppBase` 每次调用创建独立实例） */
 declare function createAppRegistries(): AppRegistries;
@@ -342,6 +549,12 @@ interface FaapiContext {
      * （injectParams 等消费方回退到默认全局实例）
      */
     registries?: AppRegistries;
+    /**
+     * 任务队列客户端（TaskClient：enqueue/list）。
+     * 经 createContext 进入请求链路时由框架从 `registries.taskHandle` 工厂注入；
+     * 无 app 编排（编程式直调 ctx）时为 undefined
+     */
+    tasks?: TaskClient;
     request: Request;
     params: Record<string, string>;
     query: URLSearchParams;
@@ -706,4 +919,4 @@ interface RouteInfo {
     output: RouteOutputSchema | null;
 }
 
-export { type AppRegistries as A, type CorsOptions as C, type FaapiContext as F, type HelmetOptions as H, type InjectorMap as I, type LoggerOptions as L, type RouteManifest as R, type SkillRegistry as S, type ToolMetadata as T, type WsRouteManifest as W, type FaapiMiddleware as a, type AgentCore as b, type AgentMetadata as c, type AgentHandleFactory as d, type AgentHandleStore as e, type AgentPathMeta as f, type AgentRegistry as g, type AgentToolDescriptor as h, type FaapiContextConfig as i, type FailOptions as j, type Injector as k, type RouteInfo as l, type RouteInputSchema as m, type RouteOutputSchema as n, type RouteParamSchema as o, type SseEvent as p, type SseWriter as q, type ToolCore as r, type ToolPathMeta as s, type ToolRegistry as t, cors as u, createAppRegistries as v, helmet as w, logger as x };
+export { type AppRegistries as A, type TaskDriverProcess as B, type CorsOptions as C, type TaskJob as D, type TaskJobStatus as E, type FaapiContext as F, type TaskMetadata as G, type HelmetOptions as H, type InjectorMap as I, type TaskModule as J, type ToolCore as K, type LoggerOptions as L, type ToolPathMeta as M, type ToolRegistry as N, cors as O, createAppRegistries as P, createTaskRegistry as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, helmet as U, logger as V, type WsRouteManifest as W, type FaapiMiddleware 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 AgentHandleFactory as j, type AgentHandleStore as k, type AgentPathMeta as l, type AgentRegistry as m, type AgentToolDescriptor as n, type FaapiContextConfig as o, type FaapiTaskMeta as p, type FailOptions as q, type Injector as r, type RouteInfo as s, type RouteInputSchema as t, type RouteOutputSchema as u, type RouteParamSchema as v, type SseEvent as w, type SseWriter as x, type TaskContext as y, type TaskDriverJob as z };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { F as FaapiContext, a as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-Bm--uTbm.js';
+import { F as FaapiContext, a as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-CCveqSnY.js';
 import { Server } from 'node:http';
 import { WebSocket } from 'ws';
 

package/dist/testing.js

@@ -371,6 +371,7 @@ function createContextFromUrl(request, url, params, config = {}, ip = "", regist
   };
   if (registries) {
     ctx.registries = registries;
+    ctx.tasks = registries.taskHandle.get(ctx);
   }
   const extend = config?.extendContext;
   if (typeof extend === "function") {
@@ -550,8 +551,10 @@ var PARAM_TYPE_MAP = {
   fields: "fields",
   agent: "agent",
   // Phase 2.3
-  agents: "agents"
+  agents: "agents",
   // Phase 2.3
+  tasks: "tasks"
+  // 任务子系统：TaskClient（入队/查询）
 };
 var injectionCache = /* @__PURE__ */ new WeakMap();
 function resolveInjection(fn) {
@@ -645,6 +648,29 @@ function queryToObject(params) {
   return result;
 }
 
+// src/task/taskRegistry.ts
+function createTaskRegistry() {
+  let registry = /* @__PURE__ */ new Map();
+  return {
+    hydrate(tasks) {
+      const next = /* @__PURE__ */ new Map();
+      for (const task of tasks) {
+        next.set(task.name, task);
+      }
+      registry = next;
+    },
+    get(name) {
+      return registry.get(name);
+    },
+    list() {
+      return Array.from(registry.values());
+    },
+    clear() {
+      registry = /* @__PURE__ */ new Map();
+    }
+  };
+}
+
 // src/injection/registries.ts
 function createToolRegistry() {
   let registry = /* @__PURE__ */ new Map();
@@ -767,12 +793,29 @@ function createAgentHandleStore() {
     }
   };
 }
+function createTaskHandleStore() {
+  let currentFactory = null;
+  return {
+    register(factory) {
+      currentFactory = factory;
+    },
+    get(ctx) {
+      if (currentFactory === null) return void 0;
+      return currentFactory(ctx);
+    },
+    clear() {
+      currentFactory = null;
+    }
+  };
+}
 function createAppRegistries() {
   const tool = createToolRegistry();
   const agent = createAgentRegistry(tool);
   const skill = createSkillRegistry();
+  const task = createTaskRegistry();
   const agentHandle = createAgentHandleStore();
-  return { tool, agent, skill, agentHandle };
+  const taskHandle = createTaskHandleStore();
+  return { tool, agent, skill, task, agentHandle, taskHandle };
 }
 var defaultRegistries = createAppRegistries();
 
@@ -826,6 +869,9 @@ function getBuiltinInjectionValue(type, ctx, body) {
     // Phase 3.5：调 @faapi/agent 插件注册的工厂获取 AgentHandle
     case "agent":
       return ctx.registries ? ctx.registries.agentHandle.get(ctx) : getAgentHandle(ctx);
+    // 任务子系统：注入 TaskClient（入队/查询）；未注册工厂（无 app 编排）时 undefined
+    case "tasks":
+      return ctx.registries ? ctx.registries.taskHandle.get(ctx) : void 0;
     default:
       return void 0;
   }