@faapi/faapi 6.22.0 → 6.24.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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-CXWkRx4W.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-CXWkRx4W.js';
+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 * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -48,6 +48,14 @@ type UpgradeHandler = (req: IncomingMessage, socket: Socket, head: Buffer) => vo
 interface PluginContext {
     /** 项目根目录 */
     rootDir: string;
+    /**
+     * 产物 resources 目录绝对路径（`<rootDir>/<dist>/resources`）
+     *
+     * `src/resources/` 经 dev/build 复制进产物后的位置——插件 setup 时读静态
+     * 资源用；`@faapi/agent` 插件据此注入 AgentDeps（agent config 的
+     * systemPromptFile 相对此目录解析）。
+     */
+    resourcesDir: string;
     /** app 级注册表（tool/agent/skill/agentHandle 实例，随 app 生命周期） */
     registries: AppRegistries;
     /** 当前路由清单（setup 时的快照，reloadRoutes 后不会更新；需最新路由用 getRoutes()） */
@@ -251,6 +259,13 @@ interface TaskConfig {
 interface LifecycleContext {
     /** 项目根目录 */
     rootDir: string;
+    /**
+     * 运行时资源根目录绝对路径（<rootDir>/<dist>/resources）
+     *
+     * `src/resources/` 经 dev/build 复制进产物后的位置，onReady 中预加载
+     * prompt 模板等静态文件时定位用（`path.join(resourcesDir, 'prompts/foo.md')`）。
+     */
+    resourcesDir: string;
     /** 当前路由清单 */
     routes: RouteManifest;
     /** 服务器实例（onBoot 钩子触发时已创建但未监听，`listening === false`） */
@@ -843,6 +858,13 @@ interface WsContext {
     headers: Headers;
     /** 业务配置（来自 faapi.config.ts） */
     config: Record<string, unknown>;
+    /**
+     * 运行时资源根目录绝对路径（<rootDir>/<dist>/resources）
+     *
+     * 与 HTTP FaapiContext 同源（握手 ctx 是 FaapiContext 的结构子集），handler
+     * 的 WS 回调里读静态文件用。testing 直调未传时为 undefined。
+     */
+    resourcesDir?: string;
     /** 中间件塞入的用户信息（鉴权等） */
     user?: unknown;
     /** 允许通过 declare module 扩展 */
@@ -1244,52 +1266,6 @@ declare const TASK_PATTERNS: string[];
  */
 declare function scanTasks(rootDir: string, patterns: string[]): Promise<TaskManifest[]>;
 
-/**
- * 加载后的 agent 模块
- *
- * 与 [ToolModule](./loadToolModule.md) 对称——agent 的代码本体只有可选的 `run` 函数
- * (自定义 agent 运行逻辑,替代默认 reactLoop)。
- *
- * > `config` 字段已移除——`AgentMetadata` 已含 AST 提取的字面量字段
- * > (systemPrompt / tools / agents / model / maxTurns),`AgentModule.config`
- * > 原本用于运行时拿到完整 config 对象(含动态字段),但 `executeSubAgent`
- * > 拿到 `mod.config` 后从不读取(run 函数在自己模块内直接引用 config 变量),
- * > 属于死链路,故移除。
- *
- * `AgentMetadata`（从 `faapi-agents.js` 水合）已含字面量字段,本模块仅用于
- * 在运行时拿到 `run` 函数引用。
- */
-interface AgentModule {
-    /**
-     * 自定义 agent 运行函数（可选）
-     *
-     * `hasRun` 为 true 时一定为 function；为 false 时为 `undefined`。
-     * 调用方式由 `@faapi/agent` 子包的 Agent 类定义（Phase 3.x）。
-     */
-    run: ((...args: unknown[]) => unknown) | undefined;
-}
-/**
- * 动态 import agent handler 文件并提取 `run` 导出
- *
- * Dev 按需编译模式（Vite 风格）：先 `ensureCompiled` 确保产物存在再 import,
- * 避免 import 不存在的文件污染 Vite SSR 内部状态（详见 [loadRouteModule](./loadRouteModule.md)）。
- * Prod 模式：产物在 build 阶段已固化，直接 import，失败即报错。
- *
- * 与 [loadToolModule](./loadToolModule.md) 的差异：
- * - tool 按 `functionName` 提取单个函数（校验为 function）
- * - agent 只提取 `run`（函数，可选）——config 块字段已在 AST 阶段提取为字面量,
- *   运行时无需再加载 config 对象
- *
- * 错误传递：
- * - 编译失败 → 抛 "Failed to compile agent module"
- * - import 失败 → 抛 "Failed to load agent module"
- *
- * @param filePath agent handler 文件的绝对路径（产物形式，如 `dist/agents/researcher/handler.js`）
- * @param hasRun 是否应提取 run 导出（来自 `AgentMetadata.hasRun`）
- * @param rootDir 项目根目录（按需编译模式用，可选）
- */
-declare function loadAgentModule(filePath: string, hasRun: boolean, rootDir?: string): Promise<AgentModule>;
-
 /**
  * 加载后的 tool 模块
  *
@@ -1368,14 +1344,14 @@ declare function loadToolSchema(tool: ToolMetadata, rootDir?: string): Promise<T
 /**
  * 按名查找单个 agent 的 LLM 可见元数据（默认实例）
  *
- * 返回 [AgentCore](../ast/extractAgentMetadata.md)（不含 filePath / hasRun）。
+ * 返回 [AgentCore](../ast/extractAgentMetadata.md)（不含 filePath）。
  * 加载 handler.js 执行 `run` 函数请用 [getAgentEntry](#getAgentEntry)。
  *
  * @param name agent 名（如 `researcher`，含 `@agent` 覆盖值）
  */
 declare function getAgent(name: string): AgentCore | undefined;
 /**
- * 按名查找单个 agent 的完整元数据（默认实例，含 filePath / hasRun）
+ * 按名查找单个 agent 的完整元数据（默认实例，含 filePath）
  */
 declare function getAgentEntry(name: string): AgentMetadata | undefined;
 /**
@@ -1681,6 +1657,21 @@ interface AppBase {
     wsRoutes: WsRouteManifest;
     /** 项目根目录 */
     rootDir: string;
+    /**
+     * 产物输出目录（相对 rootDir，如 '.faapi' 或 'dist'）
+     *
+     * 与 createAppBase 内部解析一致：`options.dist ?? FAAPI_DIST ?? 'dist'`。
+     * 业务方定位任意产物文件时与 rootDir 配合使用。
+     */
+    dist: string;
+    /**
+     * 运行时资源根目录绝对路径（<rootDir>/<dist>/resources）
+     *
+     * `src/resources/` 经 dev/build 复制进产物后的位置，业务方
+     * `path.join(app.resourcesDir, 'prompts/foo.md')` 后自行读取。
+     * 源码无 `src/resources/` 目录时路径仍指向约定位置（读文件由业务方容错）。
+     */
+    resourcesDir: string;
     /** 任务队列客户端（入队/查询；app 实例级，close 时随队列停机） */
     tasks: TaskClient;
     /** 启动 HTTP server，打印路由表，执行 onReady 钩子 */
@@ -1761,4 +1752,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, 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, loadAgentModule, 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, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, upsertSkill };