@faapi/faapi 6.30.0 → 6.31.0

package/dist/{contextTypes-DhagvRH_.d.ts → contextTypes-BKQsSVMv.d.ts}

@@ -130,6 +130,15 @@ interface AgentCore {
 interface AgentMetadata extends AgentCore {
     /** 源码相对路径(从 `pathMeta` 透传)——声明文件定位与清单可观测性用 */
     filePath: string;
+    /**
+     * 派发入参 schema 声明(handler.ts 顶层 `interface Input` / `type Input` 检测)
+     *
+     * 声明时为 `'Input'`——[generateAgentArtifacts](../cli/generateAgentArtifacts.md)
+     * 据此生成 agent 的 zod.js,`@faapi/agent` 派发该 agent 时用富 JSON Schema 替代
+     * 默认单字段 `input` 交接单并在执行前校验;未声明为 `undefined`,派发行为不变
+     * (完全向后兼容)。DB-driven skill 无源文件,恒为 `undefined`。
+     */
+    inputTypeName?: string;
 }
 /**
  * 路径推导的 agent 元数据(由 [scanAgents](../agents/scanAgents.ts) 计算)
@@ -1159,4 +1168,4 @@ interface FaapiContext {
     deleteCookie(name: string): void;
 }
 
-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 };
+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 AgentCore as g, type AgentMetadata as h, type ToolMetadata 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,7 +1,7 @@
-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-DhagvRH_.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-DhagvRH_.js';
-import { F as FaapiMiddleware, R as RouteManifest, C as CorsOptions, H as HelmetOptions, I as InjectorMap, W as WsRouteManifest } from './routeTypes-0rwuIws-.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-0rwuIws-.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 AgentCore, h as AgentMetadata, i as ToolMetadata, C as CreateLoggerOptions, j as Logger } from './contextTypes-BKQsSVMv.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-BKQsSVMv.js';
+import { F as FaapiMiddleware, R as RouteManifest, C as CorsOptions, H as HelmetOptions, I as InjectorMap, W as WsRouteManifest } from './routeTypes-Cc0P3CcU.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-Cc0P3CcU.js';
 import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -1299,31 +1299,44 @@ interface ToolSchemaModule {
  * 计算 tool 的 zod.js 绝对路径（纯路径计算，无 fs 访问）
  *
  * 与 [loadToolSchema](./loadToolSchema.ts) 内部使用的路径逻辑同源（共享 `getDist()`），
+/**
+ * zod.js 定位的最小来源结构——`ToolMetadata` 与 `AgentMetadata`（派发入参 schema
+ * 声明场景）均满足，加载器无需感知来源差异
+ */
+interface SchemaSourceRef {
+    /** 源码/产物相对路径（与 zod.js 同级，推导 zod.js 路径用） */
+    filePath: string;
+    /** schema 类型名（`undefined` = 无 schema 声明） */
+    inputTypeName?: string;
+}
+/**
+ * 计算 zod.js 的绝对路径（纯路径计算，无 fs 访问）
+ *
+ * 与 [loadToolSchema](./loadToolSchema.ts) 内部使用的路径逻辑同源（共享 `getDist()`），
  * 供 `@faapi/agent` 的跨请求 schema 缓存用作缓存键 + mtime 校验目标。
  *
- * @param tool tool 元数据（含 `filePath`）
- * @param rootDir 项目根目录（`tool.filePath` 是相对路径时拼接）
+ * @param ref schema 来源元数据（tool / agent 均可，含 `filePath`）
+ * @param rootDir 项目根目录（`ref.filePath` 是相对路径时拼接）
  */
-declare function getToolSchemaPath(tool: ToolMetadata, rootDir?: string): string;
+declare function getToolSchemaPath(ref: SchemaSourceRef, rootDir?: string): string;
 /**
- * 动态加载 tool 的 zod.js schema 模块
+ * 动态加载 zod.js schema 模块（tool input 与 agent 派发入参共用）
  *
  * 与 [loadToolModule](./loadToolModule.md) 对称——一个加载 handler.js（tool 函数），
- * 一个加载 zod.js（tool schema）。
+ * 一个加载 zod.js（schema 模块）。tool 的 zod.js 与 handler.js 同级；agent 声明
+ * `Input` 时同样生成同级 zod.js（见 generateAgentArtifacts），同一加载器服务两类来源。
  *
  * 行为：
- * - `tool.inputTypeName` 为 `undefined` → 返回 `undefined`（无 schema，用自由 schema）
- * - zod.js 文件不存在 → 返回 `undefined`（schema 可选，缺失用自由 schema）
+ * - `ref.inputTypeName` 为 `undefined` → 返回 `undefined`（无 schema 声明）
+ * - zod.js 文件不存在 → 返回 `undefined`（schema 缺失，调用方按各自语义处理——
+ *   tool 用自由 schema `{ type: 'object' }`；agent 派发入参在声明了 `inputTypeName`
+ *   时视为产物异常，由 `@faapi/agent` 侧显式抛错）
  * - import 失败 / 导出名不匹配 → 返回 `undefined`
  *
- * 与 route schema 不同（route schema 缺失抛 `InternalError`），tool schema 是可选的——
- * `@faapi/agent` 的 `resolveToolSchema` 未提供时用自由 schema `{ type: 'object' }`，
- * LLM 自由传参，handler 内部自行处理参数合法性。
- *
- * @param tool tool 元数据（含 `filePath` + `inputTypeName`）
- * @param rootDir 项目根目录（用于计算 zod.js 绝对路径，`tool.filePath` 是相对路径时拼接）
+ * @param ref schema 来源元数据（tool / agent 均可，含 `filePath` + `inputTypeName`）
+ * @param rootDir 项目根目录（用于计算 zod.js 绝对路径，`ref.filePath` 是相对路径时拼接）
  */
-declare function loadToolSchema(tool: ToolMetadata, rootDir?: string): Promise<ToolSchemaModule | undefined>;
+declare function loadToolSchema(ref: SchemaSourceRef, rootDir?: string): Promise<ToolSchemaModule | undefined>;
 
 /**
  * 按名查找单个 agent 的 LLM 可见元数据（默认实例）
@@ -1768,4 +1781,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, LLM_TOOL_NAME_PATTERN, 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, SUB_AGENT_TOOL_PREFIX, 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, subAgentToolName, 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, LLM_TOOL_NAME_PATTERN, 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, SUB_AGENT_TOOL_PREFIX, SchemaExtractionError, type SchemaSourceRef, 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, subAgentToolName, upsertSkill };

package/dist/index.js

@@ -3926,18 +3926,18 @@ function getDist() {
   }
   return process.env.FAAPI_DIST ?? "dist";
 }
-function getToolSchemaPath(tool, rootDir) {
+function getToolSchemaPath(ref, rootDir) {
   const dist = getDist();
-  return getRuntimeSchemaPath(tool.filePath, dist, rootDir ?? process.cwd());
+  return getRuntimeSchemaPath(ref.filePath, dist, rootDir ?? process.cwd());
 }
-async function loadToolSchema(tool, rootDir) {
-  if (!tool.inputTypeName) return void 0;
-  const schemaName = `${tool.inputTypeName}Schema`;
-  const zodPath = getToolSchemaPath(tool, rootDir);
+async function loadToolSchema(ref, rootDir) {
+  if (!ref.inputTypeName) return void 0;
+  const schemaName = `${ref.inputTypeName}Schema`;
+  const zodPath = getToolSchemaPath(ref, rootDir);
   if (!existsSync3(zodPath)) return void 0;
   try {
     const mod = await importWithCacheBust(zodPath, isDevOnDemandEnabled());
-    const schema = mod[`${tool.inputTypeName}Schema`];
+    const schema = mod[`${ref.inputTypeName}Schema`];
     if (!schema) return void 0;
     return { schema, schemaName };
   } catch {
@@ -6902,9 +6902,20 @@ function extractAgentMetadata(program, filePath, pathMeta) {
     agents,
     model,
     maxTurns,
-    inputDescription
+    inputDescription,
+    inputTypeName: findInputDeclaration(sourceFile) ? "Input" : void 0
   };
 }
+function findInputDeclaration(sourceFile) {
+  let found = false;
+  ts11.forEachChild(sourceFile, (node) => {
+    if (found) return;
+    if ((ts11.isInterfaceDeclaration(node) || ts11.isTypeAliasDeclaration(node)) && node.name.text === "Input") {
+      found = true;
+    }
+  });
+  return found;
+}
 function findRunExportOwner(sourceFile) {
   let result = null;
   ts11.forEachChild(sourceFile, (node) => {
@@ -7111,6 +7122,9 @@ function extractStringArrayValue(expr) {
 // src/cli/generateAgentArtifacts.ts
 init_createProgram();
 init_atomicWrite();
+init_extractHandlerTypes();
+init_generateZodSchema();
+init_generateZodArtifacts();
 var AGENTS_FILE = "faapi-agents.js";
 function serializeAgents(agents, dist = "dist") {
   return agents.map((a) => ({
@@ -7123,6 +7137,7 @@ function serializeAgents(agents, dist = "dist") {
     model: a.model,
     maxTurns: a.maxTurns,
     inputDescription: a.inputDescription,
+    inputTypeName: a.inputTypeName,
     filePath: toProdFilePath(a.filePath, dist)
   }));
 }
@@ -7143,7 +7158,8 @@ function hydrateAgents(manifest) {
     agents: a.agents ?? void 0,
     model: a.model ?? void 0,
     maxTurns: a.maxTurns ?? void 0,
-    inputDescription: a.inputDescription ?? void 0
+    inputDescription: a.inputDescription ?? void 0,
+    inputTypeName: a.inputTypeName ?? void 0
   }));
 }
 function validateAgentList(metadata) {
@@ -7189,8 +7205,66 @@ async function generateAgentArtifacts(agents, rootDir, dist) {
   const serialized = serializeAgents(metadata, dist);
   const agentsPath = path24.resolve(rootDir, dist, AGENTS_FILE);
   await writeAgentsModule(serialized, agentsPath);
+  await generateAgentZodArtifacts(metadata, programByFile, rootDir, dist);
   return metadata;
 }
+async function generateAgentZodArtifacts(metadata, programByFile, rootDir, dist) {
+  const declared = metadata.filter((a) => a.inputTypeName);
+  if (declared.length === 0) return;
+  const resolversByFile = /* @__PURE__ */ new Map();
+  const sources = [];
+  for (const agent of declared) {
+    const absPath = path24.resolve(rootDir, agent.filePath);
+    const program = programByFile.get(absPath);
+    if (!program) {
+      throw new Error(
+        `agent "${agent.name}" \u6E90\u6587\u4EF6\u4E0D\u5728 Program \u4E2D: ${agent.filePath}\u2014\u2014\u65E0\u6CD5\u751F\u6210\u5165\u53C2 schema`
+      );
+    }
+    if (!resolversByFile.has(absPath)) {
+      resolversByFile.set(absPath, createLazyTypeResolver(program, absPath));
+    }
+    const typeInfo = extractTypeInfo(program, absPath, agent.inputTypeName);
+    sources.push({
+      name: agent.name,
+      filePath: absPath,
+      schemaName: agent.inputTypeName,
+      typeInfo
+    });
+  }
+  await generateZodArtifacts(sources, {
+    generateFileSource: generateAgentSchemaFileSource,
+    resolversByFile,
+    rootDir,
+    dist
+  });
+}
+function generateAgentSchemaFileSource(sources, resolveType, helpersImportPath) {
+  const lines = ["import { z } from 'zod';"];
+  const schemaBlocks = [];
+  for (const source of sources) {
+    if (!source.typeInfo) continue;
+    const block = [`// agent ${source.name} \u2192 ${source.schemaName}`];
+    const schemaCode = generateZodSchemaSource(
+      source.typeInfo,
+      resolveType,
+      source.schemaName,
+      false
+    ).replace(/^import \{ z \} from 'zod';\s*\n\s*\n/, "");
+    block.push(schemaCode);
+    block.push("");
+    schemaBlocks.push(block.join("\n"));
+  }
+  const allSchemaCode = schemaBlocks.join("\n");
+  if (helpersImportPath && usesCoerceHelpers(allSchemaCode)) {
+    lines.push(
+      `import { coerceNumber, coerceBoolean, coerceMap, coerceSet } from '${helpersImportPath}';`
+    );
+  }
+  lines.push("");
+  lines.push(...schemaBlocks);
+  return lines.join("\n").replace(/\n+$/, "\n");
+}
 
 // src/cli/generateTaskArtifacts.ts
 init_generateZodArtifacts();