@faapi/faapi 6.23.0 → 6.24.0

package/dist/{routeTypes-CJV5M90s.d.ts → routeTypes-D1swYDVC.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,8 @@ interface TaskWorkerOptions {
     /** signal 由执行器构造（abort/terminate 时触发），宿主只传 config 与 job 信息 */
     taskCtx: {
         config: unknown;
+        /** 产物 resources 目录绝对路径（纯字符串可结构化克隆，worker 内挂到 taskCtx） */
+        resourcesDir?: string;
         job: {
             id: string;
             name: string;
@@ -439,7 +448,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 +611,7 @@ interface TaskJob {
  * `TaskRegistriesView` 生成快照，worker wrapper 内重建只读视图。
  */
 interface TaskRegistriesSnapshot {
-    /** agent 完整元数据（含 filePath/hasRun，非仅 LLM 可见字段） */
+    /** agent 完整元数据（含 filePath，非仅 LLM 可见字段） */
     agents: AgentMetadata[];
     tools: ToolMetadata[];
     skills: AgentCore[];
@@ -615,6 +624,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 +642,7 @@ interface TaskContext {
      *
      * 进程内执行为活引用；隔离执行为派发时刻的快照视图（worker 内重建）——
      * 执行中途的 reload/DB skill 变更不影响当次执行。
-     * 任务内组装 agent 用 `registries.agent.getAgentEntry(name)`（含 filePath/hasRun）。
+     * 任务内组装 agent 用 `registries.agent.getAgentEntry(name)`（含 filePath）。
      */
     registries: TaskRegistriesView;
     /**
@@ -714,6 +731,11 @@ interface TaskQueueDeps {
     rootDir: string;
     /** faapi.config.ts 全量配置，透传给 run 的 TaskContext.config */
     config?: unknown;
+    /**
+     * 产物 resources 目录绝对路径——注入两条执行路径的 TaskContext.resourcesDir；
+     * 缺省不注入（直接构造队列的测试/嵌入场景）
+     */
+    resourcesDir?: string;
     /**
      * app 注册表只读视图（`createTaskRegistriesView`）——注入两条执行路径的
      * TaskContext.registries；缺省为空视图（直接构造队列的测试/嵌入场景）

package/dist/testing.d.ts

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