@faapi/faapi 6.24.0 → 6.26.0

package/dist/{routeTypes-D1swYDVC.d.ts → contextTypes-gYf84EXF.d.ts}

@@ -363,7 +363,11 @@ interface TaskWorkerOptions {
     /** signal 由执行器构造（abort/terminate 时触发），宿主只传 config 与 job 信息 */
     taskCtx: {
         config: unknown;
-        /** 产物 resources 目录绝对路径（纯字符串可结构化克隆，worker 内挂到 taskCtx） */
+        /**
+         * 产物 resources 目录绝对路径（纯字符串可结构化克隆）——两处用途：经
+         * workerData 传给入口在任务模块求值前播种全局读取根 + 挂到 worker 内的
+         * taskCtx（业务方了解/拼接资源位置）
+         */
         resourcesDir?: string;
         job: {
             id: string;
@@ -1050,8 +1054,9 @@ interface FaapiContext {
     /**
      * 运行时资源根目录绝对路径（<rootDir>/<dist>/resources）
      *
-     * `src/resources/` 经 dev/build 复制进产物后的位置，handler 读静态文件用：
-     * `await fs.readFile(path.join(ctx.resourcesDir, 'prompts/foo.md'))`。
+     * `src/resources/` 经 dev/build 复制进产物后的位置。数据字段——读取统一走
+     * 免传参的 `readResource('prompts/foo.md')`（app 启动时绑定，见
+     * src/utils/readResource.md），本字段供业务方了解/拼接资源位置。
      * HTTP/WS 请求链路恒有值；testing 直调（createTestContext）未传时为 undefined。
      */
     resourcesDir?: string;
@@ -1170,205 +1175,4 @@ interface FaapiContext {
     deleteCookie(name: string): void;
 }
 
-/**
- * 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 FaapiMiddleware = (ctx: FaapiContext, next: () => Promise<Response>) => Promise<void | Response>;
-
-/**
- * 注入器：按参数名匹配，提供 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 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;
-
-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;
-
-declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
-type HttpMethod = (typeof HTTP_METHODS)[number];
-
-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;
-}
-
-export { type ToolPathMeta as $, type AppRegistries as A, type RouteOutputSchema as B, type CorsOptions as C, type RouteParamSchema as D, type SseEvent as E, type FaapiMiddleware as F, type SseOptions as G, type HelmetOptions as H, type InjectorMap as I, type SseWriter as J, type TaskContext as K, type LogConfig as L, type TaskDriverJob as M, type TaskDriverProcess as N, type TaskDriverRecord as O, type TaskFailedInfo as P, type TaskJob as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, type TaskJobStatus as U, type TaskMetadata as V, type WsRouteManifest as W, type TaskModule as X, type TaskRegistriesSnapshot as Y, type TaskRegistriesView as Z, type ToolCore as _, type FaapiContext as a, type ToolRegistry as a0, cors as a1, createAppRegistries as a2, createTaskRegistriesView as a3, createTaskRegistry as a4, helmet as a5, type TaskFailedHandler as b, type TaskQueueDeps as c, type TaskQueue as d, type TaskDriver as e, type TaskRegistry as f, type TaskManifest as g, type ToolMetadata as h, type AgentCore as i, type AgentMetadata as j, type CreateLoggerOptions as k, type Logger as l, type AgentHandleFactory as m, type AgentHandleStore as n, type AgentPathMeta as o, type AgentRegistry as p, type AgentToolDescriptor as q, type FaapiContextConfig as r, type FaapiTaskMeta as s, type FailOptions as t, type Injector as u, type LogEntry as v, type LogLevel as w, type LogSink as x, type RouteInfo as y, type RouteInputSchema as z };
+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 };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import { F as FaapiMiddleware, A as AppRegistries, R as RouteManifest, a as FaapiContext, C as CorsOptions, T as TaskClient, H as HelmetOptions, L as LogConfig, I as InjectorMap, b as TaskFailedHandler, W as WsRouteManifest, c as TaskQueueDeps, d as TaskQueue, e as TaskDriver, f as TaskRegistry, g as TaskManifest, h as ToolMetadata, i as AgentCore, j as AgentMetadata, k as CreateLoggerOptions, l as Logger } from './routeTypes-D1swYDVC.js';
-export { m as AgentHandleFactory, n as AgentHandleStore, o as AgentPathMeta, p as AgentRegistry, q as AgentToolDescriptor, r as FaapiContextConfig, s as FaapiTaskMeta, t as FailOptions, u as Injector, v as LogEntry, w as LogLevel, x as LogSink, y as RouteInfo, z as RouteInputSchema, B as RouteOutputSchema, D as RouteParamSchema, S as SkillRegistry, E as SseEvent, G as SseOptions, J as SseWriter, K as TaskContext, M as TaskDriverJob, N as TaskDriverProcess, O as TaskDriverRecord, P as TaskFailedInfo, Q as TaskJob, U as TaskJobStatus, V as TaskMetadata, X as TaskModule, Y as TaskRegistriesSnapshot, Z as TaskRegistriesView, _ as ToolCore, $ as ToolPathMeta, a0 as ToolRegistry, a1 as cors, a2 as createAppRegistries, a3 as createTaskRegistriesView, a4 as createTaskRegistry, a5 as helmet } from './routeTypes-D1swYDVC.js';
+import { A as AppRegistries, F as FaapiContext, T as TaskClient, L as LogConfig, a as TaskFailedHandler, b as TaskQueueDeps, c as TaskQueue, d as TaskDriver, e as TaskRegistry, f as TaskManifest, g as ToolMetadata, h as AgentCore, i as AgentMetadata, C as CreateLoggerOptions, j as Logger } from './contextTypes-gYf84EXF.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 LogEntry, t as LogLevel, u as LogSink, S as SkillRegistry, v as SseEvent, w as SseOptions, x as SseWriter, y as TaskContext, z as TaskDriverJob, B as TaskDriverProcess, D as TaskDriverRecord, E as TaskFailedInfo, G as TaskJob, H as TaskJobStatus, I as TaskMetadata, J as TaskModule, K as TaskRegistriesSnapshot, M as TaskRegistriesView, N as ToolCore, O as ToolPathMeta, P as ToolRegistry, Q as createAppRegistries, R as createTaskRegistriesView, U as createTaskRegistry } from './contextTypes-gYf84EXF.js';
+import { F as FaapiMiddleware, R as RouteManifest, C as CorsOptions, H as HelmetOptions, I as InjectorMap, W as WsRouteManifest } from './routeTypes-DlD6nnbT.js';
+export { a as Injector, b as RouteInfo, c as RouteInputSchema, d as RouteOutputSchema, e as RouteParamSchema, f as cors, h as helmet } from './routeTypes-DlD6nnbT.js';
 import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -1489,6 +1491,17 @@ declare function loadConfig(rootDir: string, dist: string): Promise<Partial<Faap
  */
 declare function loadEnv(rootDir: string): void;
 
+/**
+ * 读取当前 app 的运行时资源内容（参数为相对路径，只能读 resources 内的文件）
+ *
+ * 唯一读取入口：HTTP/WS handler、任务、插件、lifecycle 钩子、编程式调用全部用
+ * 本函数——resources 目录在 app 启动时绑定（createAppBase），调用方不传路径根。
+ * 越界校验见 resolveResourceTarget——绝对路径、`..` 穿越、符号链接逃逸均显式抛错，
+ * resources 内部的合法软链不误伤。
+ */
+declare function readResource(relativePath: string): Promise<Buffer>;
+declare function readResource(relativePath: string, encoding: BufferEncoding): Promise<string>;
+
 /**
  * 设置全局日志配置（进程级，`createAppBase` 启动时以 `config.log` 调用）
  *
@@ -1752,4 +1765,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type AgentConfig, AgentCore, AgentMetadata, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, CreateLoggerOptions, 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, LogConfig, Logger, type 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, configureLogging, createProdApp as createApp, createCronScheduler, createDevApp, createLogger, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, flushLogging, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, logger, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, upsertSkill };
+export { type AgentConfig, AgentCore, AgentMetadata, type ProdApp as App, AppRegistries, CorsOptions, type CreateAppOptions, CreateLoggerOptions, 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, LogConfig, Logger, type 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, configureLogging, createProdApp as createApp, createCronScheduler, createDevApp, createLogger, createProdApp, createProgram, createPrograms, createTaskQueue, extractTypeInfo, flushLogging, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadConfig, loadEnv, loadTaskDriver, loadToolModule, loadToolSchema, logger, readResource, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, upsertSkill };