@faapi/faapi 6.23.0 → 6.25.0

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

@@ -60,13 +60,13 @@ interface ToolPathMeta {
 /**
  * Agent 的 LLM 可见核心字段
  *
- * 描述"agent 是什么"——LLM 真正需要消费的字段,**不含**代码本体加载细节
- * (filePath / hasRun)。文件型 agent 与 DB-driven skill 都实现此接口。
+ * 描述"agent 是什么"——LLM 真正需要消费的字段,**不含**声明文件定位信息
+ * (filePath)。文件型 agent 与 DB-driven skill 都实现此接口。
  *
  * - 文件型 agent:由 [AgentMetadata](./extractAgentMetadata.md) 继承扩展,
- *   额外含 `filePath` / `hasRun`(代码本体加载用)
+ *   额外含 `filePath`(声明文件定位用)
  * - DB-driven skill:业务方 plugin 从 DB 字段映射到本接口即可,无需填占位值
- *   (skill 无源文件,不走 `loadAgentModule`,自然不读 filePath / hasRun)
+ *   (skill 无源文件,自然不读 filePath)
  *
  * `@faapi/agent` 子包的 `Agent` 类、`agentRegistry` 查询入口、`asTool` 包装
  * 都消费 `AgentCore`,实现"agent 与 skill 走同一运行时链路"。
@@ -78,6 +78,16 @@ interface AgentCore {
     description?: string;
     /** 系统提示词(config 块字面量提取);文件型 agent 必填(构建期校验),DB skill 由业务方自治 */
     systemPrompt?: string;
+    /**
+     * 系统提示词文件路径(config 块字面量提取),相对产物 resources 目录
+     * (`<dist>/resources/`,即 `ctx.resourcesDir`),与 `systemPrompt` 互斥
+     * (都声明构建期抛错,二选一必填)
+     *
+     * 运行时每次 run 读文件内容作为 systemPrompt——dev 改 prompt 文件经 watcher
+     * 增量复制后立即生效,无需 reload;`deps.resourcesDir` 未注入或文件读取失败
+     * 时抛 `AgentError`(不静默降级)
+     */
+    systemPromptFile?: string;
     /** agent 显式声明可用的 tool 引用列表(config 块字面量提取),未声明时为 `undefined`;声明了但含无法静态求值的元素在构建期抛错 */
     tools?: string[];
     /** 可调用的其他 agent 名列表(config 块字面量提取),未声明时为 `undefined`;声明了但含无法静态求值的元素在构建期抛错 */
@@ -99,12 +109,13 @@ interface AgentCore {
 /**
  * Agent 完整元数据(文件型 agent)
  *
- * 继承 [AgentCore](./extractAgentMetadata.md) 的 LLM 字段,额外扩展**代码本体加载细节**:
- * - `filePath` — `loadAgentModule` 加载 `handler.js` 产物提取 `run` 函数用
- * - `hasRun` — 是否导出 `run` 函数(`Agent.executeSubAgent` 据此决定走自定义 run
- *   还是默认 reactLoop)
+ * 继承 [AgentCore](./extractAgentMetadata.md) 的 LLM 字段,额外扩展声明文件定位:
+ * - `filePath` — 声明文件源码相对路径(启动日志 / 清单可观测性用)
  *
- * DB-driven skill 不实现此接口(无源文件,无需加载),只实现 `AgentCore`。
+ * agent 统一为声明式执行(config + 默认 reactLoop)——自定义 `run` 导出已移除,
+ * 检测到 run 导出在提取阶段抛迁移错误(编排场景注册 tool)。
+ *
+ * DB-driven skill 不实现此接口(无源文件),只实现 `AgentCore`。
  *
  * 由 [extractAgentMetadata](./extractAgentMetadata.md) 产出,合并路径推导字段
  * (来自 [scanAgents](../agents/scanAgents.md) 的 `AgentManifest`)与 AST 提取字段
@@ -112,15 +123,13 @@ interface AgentCore {
  *
  * 字段来源：
  * - `name` — `@agent` JSDoc 覆盖值,或 `pathMeta.name`(目录推导)
- * - `filePath` / `hasRun` — 由 `pathMeta` 透传
+ * - `filePath` — 由 `pathMeta` 透传
  * - `description` — JSDoc 注释块自由文本(对 LLM 可见)
- * - `systemPrompt` / `tools` / `agents` / `model` / `maxTurns` / `inputDescription` — config 块字面量提取
+ * - `systemPrompt` / `systemPromptFile` / `tools` / `agents` / `model` / `maxTurns` / `inputDescription` — config 块字面量提取
  */
 interface AgentMetadata extends AgentCore {
-    /** 源码相对路径(从 `pathMeta` 透传),`loadAgentModule` 据此加载 `handler.js` 提取 `run` */
+    /** 源码相对路径(从 `pathMeta` 透传)——声明文件定位与清单可观测性用 */
     filePath: string;
-    /** 是否导出 `run` 函数(从 `pathMeta` 透传),`Agent.executeSubAgent` 据此选择自定义 run / 默认 reactLoop */
-    hasRun: boolean;
 }
 /**
  * 路径推导的 agent 元数据(由 [scanAgents](../agents/scanAgents.ts) 计算)
@@ -133,8 +142,6 @@ interface AgentPathMeta {
     name: string;
     /** 源码相对路径(如 `src/agents/researcher/handler.ts`) */
     filePath: string;
-    /** 是否导出 `run` 函数(scanAgents 正则检测) */
-    hasRun: boolean;
 }
 
 /**
@@ -356,6 +363,12 @@ interface TaskWorkerOptions {
     /** signal 由执行器构造（abort/terminate 时触发），宿主只传 config 与 job 信息 */
     taskCtx: {
         config: unknown;
+        /**
+         * 产物 resources 目录绝对路径（纯字符串可结构化克隆）——两处用途：经
+         * workerData 传给入口在任务模块求值前播种全局读取根 + 挂到 worker 内的
+         * taskCtx（业务方了解/拼接资源位置）
+         */
+        resourcesDir?: string;
         job: {
             id: string;
             name: string;
@@ -439,7 +452,7 @@ interface AgentRegistry {
     hydrate(agents: AgentMetadata[]): void;
     /** LLM 可见元数据（AgentCore） */
     getAgent(name: string): AgentCore | undefined;
-    /** 完整元数据（含 filePath / hasRun，供加载 handler.js 执行 run） */
+    /** 完整元数据（含 filePath，声明文件定位） */
     getAgentEntry(name: string): AgentMetadata | undefined;
     /** 所有已注册 agent 的 LLM 可见元数据（副本） */
     listAgents(): AgentCore[];
@@ -602,7 +615,7 @@ interface TaskJob {
  * `TaskRegistriesView` 生成快照，worker wrapper 内重建只读视图。
  */
 interface TaskRegistriesSnapshot {
-    /** agent 完整元数据（含 filePath/hasRun，非仅 LLM 可见字段） */
+    /** agent 完整元数据（含 filePath，非仅 LLM 可见字段） */
     agents: AgentMetadata[];
     tools: ToolMetadata[];
     skills: AgentCore[];
@@ -615,6 +628,14 @@ interface TaskContext {
     signal: AbortSignal;
     /** faapi.config.ts 全量配置（含自定义业务配置） */
     config: unknown;
+    /**
+     * 产物 resources 目录绝对路径（`<rootDir>/<dist>/resources`）
+     *
+     * 任务读静态文件（prompt 模板等）用：`fs.readFile(path.join(taskCtx.resourcesDir, 'x.md'))`。
+     * 进程内与隔离执行两条路径均注入（隔离为纯字符串，可结构化克隆）；
+     * 直接构造 TaskContext 的测试/自定义执行器可不传。
+     */
+    resourcesDir?: string;
     job: {
         id: string;
         name: string;
@@ -625,7 +646,7 @@ interface TaskContext {
      *
      * 进程内执行为活引用；隔离执行为派发时刻的快照视图（worker 内重建）——
      * 执行中途的 reload/DB skill 变更不影响当次执行。
-     * 任务内组装 agent 用 `registries.agent.getAgentEntry(name)`（含 filePath/hasRun）。
+     * 任务内组装 agent 用 `registries.agent.getAgentEntry(name)`（含 filePath）。
      */
     registries: TaskRegistriesView;
     /**
@@ -714,6 +735,11 @@ interface TaskQueueDeps {
     rootDir: string;
     /** faapi.config.ts 全量配置，透传给 run 的 TaskContext.config */
     config?: unknown;
+    /**
+     * 产物 resources 目录绝对路径——注入两条执行路径的 TaskContext.resourcesDir；
+     * 缺省不注入（直接构造队列的测试/嵌入场景）
+     */
+    resourcesDir?: string;
     /**
      * app 注册表只读视图（`createTaskRegistriesView`）——注入两条执行路径的
      * TaskContext.registries；缺省为空视图（直接构造队列的测试/嵌入场景）
@@ -1028,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;
@@ -1148,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-CJV5M90s.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-CJV5M90s.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';
@@ -48,6 +50,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()） */
@@ -1258,52 +1268,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 模块
  *
@@ -1382,14 +1346,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;
 /**
@@ -1527,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` 调用）
  *
@@ -1790,4 +1765,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, readResource, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, scanTasks, upsertSkill };