@faapi/faapi 5.0.0 → 5.1.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AppRegistries, R as RouteManifest, F as FaapiContext, C as CorsOptions, H as HelmetOptions, L as LoggerOptions, a as FaapiMiddleware, I as InjectorMap, T as ToolMetadata, b as AgentCore, c as AgentMetadata, W as WsRouteManifest } from './routeTypes-DnJuuvq-.js';
-export { d as AgentHandleFactory, e as AgentHandleStore, f as AgentPathMeta, g as AgentRegistry, h as AgentToolDescriptor, i as FaapiContextConfig, j as FailOptions, k as Injector, l as RouteInfo, m as RouteInputSchema, n as RouteOutputSchema, o as RouteParamSchema, S as SkillRegistry, p as SseEvent, q as SseWriter, r as ToolCore, s as ToolPathMeta, t as ToolRegistry, u as cors, v as createAppRegistries, w as helmet, x as logger } from './routeTypes-DnJuuvq-.js';
+import { A as AppRegistries, R as RouteManifest, F as FaapiContext, C as CorsOptions, H as HelmetOptions, L as LoggerOptions, a as FaapiMiddleware, I as InjectorMap, T as ToolMetadata, b as AgentCore, c as AgentMetadata, W as WsRouteManifest } from './routeTypes-DG0eL3l5.js';
+export { d as AgentHandleFactory, e as AgentHandleStore, f as AgentPathMeta, g as AgentRegistry, h as AgentToolDescriptor, i as FaapiContextConfig, j as FailOptions, k as Injector, l as RouteInfo, m as RouteInputSchema, n as RouteOutputSchema, o as RouteParamSchema, S as SkillRegistry, p as SseEvent, q as SseWriter, r as ToolCore, s as ToolPathMeta, t as ToolRegistry, u as cors, v as createAppRegistries, w as helmet, x as logger } from './routeTypes-DG0eL3l5.js';
 import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -781,8 +781,12 @@ declare class SchemaExtractionError extends Error {
      *
      * 所有抛错点应优先使用此工厂——错误无行号时，几百行的类型文件只能靠
      * 类型名肉眼定位；解析 lib.d.ts 类型别名时还会出现错误文本与文件上下文错位
+     *
+     * `sourceFile` 可选：未触达 checker 的纯语法遍历路径（binder 未运行）没有
+     * parent 指针，`node.getSourceFile()` 返回 undefined，此时调用方需显式传入
+     * `program.getSourceFile(filePath)` 的结果以携带位置。
      */
-    static at(node: ts.Node, typeText: string, reason: string): SchemaExtractionError;
+    static at(node: ts.Node, typeText: string, reason: string, sourceFile?: ts.SourceFile): SchemaExtractionError;
 }
 /**
  * 运行时类型描述

package/dist/index.js

@@ -848,15 +848,19 @@ var init_resolveTypeNode = __esm({
        *
        * 所有抛错点应优先使用此工厂——错误无行号时，几百行的类型文件只能靠
        * 类型名肉眼定位；解析 lib.d.ts 类型别名时还会出现错误文本与文件上下文错位
+       *
+       * `sourceFile` 可选：未触达 checker 的纯语法遍历路径（binder 未运行）没有
+       * parent 指针，`node.getSourceFile()` 返回 undefined，此时调用方需显式传入
+       * `program.getSourceFile(filePath)` 的结果以携带位置。
        */
-      static at(node, typeText, reason) {
-        const sourceFile = node.getSourceFile();
-        if (!sourceFile) {
+      static at(node, typeText, reason, sourceFile) {
+        const sf = sourceFile ?? node.getSourceFile();
+        if (!sf) {
           return new _SchemaExtractionError(typeText, reason);
         }
-        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
         return new _SchemaExtractionError(typeText, reason, void 0, {
-          file: sourceFile.fileName,
+          file: sf.fileName,
           line: line + 1,
           column: character + 1
         });
@@ -5085,37 +5089,35 @@ import path17 from "path";
 
 // src/ast/extractAgentMetadata.ts
 import ts9 from "typescript";
+init_resolveTypeNode();
 function extractAgentMetadata(program, filePath, pathMeta) {
   const sourceFile = program.getSourceFile(filePath);
   if (!sourceFile) return null;
   const configFound = findConfigExport(sourceFile);
-  let jsDocOwner = null;
-  let objectLiteral = null;
-  if (configFound) {
-    jsDocOwner = configFound.jsDocOwner;
-    objectLiteral = configFound.objectLiteral;
-  } else if (pathMeta.hasRun) {
-    const runNode = findRunExport(sourceFile);
-    if (runNode) {
-      jsDocOwner = runNode;
-    }
-  }
-  const jsDoc = jsDocOwner ? getJSDocFromNode(jsDocOwner) : void 0;
+  if (!configFound) {
+    throw SchemaExtractionError.at(
+      sourceFile,
+      "config.systemPrompt",
+      "agent \u5FC5\u586B\u2014\u2014\u8BF7\u5728 config \u5757\u58F0\u660E\u7CFB\u7EDF\u63D0\u793A\u8BCD\uFF08\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u6216\u65E0\u63D2\u503C\u6A21\u677F\u5B57\u7B26\u4E32\uFF09",
+      sourceFile
+    );
+  }
+  if (!configFound.objectLiteral) {
+    throw SchemaExtractionError.at(
+      configFound.jsDocOwner,
+      "config",
+      "\u4EC5\u652F\u6301\u5BF9\u8C61\u5B57\u9762\u91CF\u3001\u7BAD\u5934\u51FD\u6570\u8FD4\u56DE\u5BF9\u8C61\u5B57\u9762\u91CF\u6216\u51FD\u6570\u8FD4\u56DE\u5BF9\u8C61\u5B57\u9762\u91CF",
+      sourceFile
+    );
+  }
+  const objectLiteral = configFound.objectLiteral;
+  const jsDoc = getJSDocFromNode(configFound.jsDocOwner);
   const description = extractDescription(jsDoc);
   const agentNameOverride = extractJSDocTagValue(jsDoc, "agent");
-  let systemPrompt;
-  let tools;
-  let agents;
-  let model;
-  let maxTurns;
-  if (objectLiteral) {
-    const fields = extractConfigFields(objectLiteral);
-    systemPrompt = fields.systemPrompt;
-    tools = fields.tools;
-    agents = fields.agents;
-    model = fields.model;
-    maxTurns = fields.maxTurns;
-  }
+  const { systemPrompt, tools, agents, model, maxTurns } = extractConfigFields(
+    objectLiteral,
+    sourceFile
+  );
   return {
     name: agentNameOverride ?? pathMeta.name,
     description,
@@ -5140,8 +5142,9 @@ function findConfigExport(sourceFile) {
         if (ts9.isObjectLiteralExpression(decl.initializer)) {
           result = { jsDocOwner: node, objectLiteral: decl.initializer };
         } else if (ts9.isArrowFunction(decl.initializer)) {
-          const returnObj = getReturnObjectLiteral(decl.initializer);
-          result = { jsDocOwner: node, objectLiteral: returnObj };
+          result = { jsDocOwner: node, objectLiteral: getReturnObjectLiteral(decl.initializer) };
+        } else {
+          result = { jsDocOwner: node, objectLiteral: null };
         }
       }
     }
@@ -5152,27 +5155,6 @@ function findConfigExport(sourceFile) {
   });
   return result;
 }
-function findRunExport(sourceFile) {
-  let result = null;
-  ts9.forEachChild(sourceFile, (node) => {
-    if (result) return;
-    if (ts9.isFunctionDeclaration(node) && hasExportModifier(node) && node.name?.text === "run") {
-      result = node;
-      return;
-    }
-    if (ts9.isVariableStatement(node) && hasExportModifier(node)) {
-      for (const decl of node.declarationList.declarations) {
-        if (result) break;
-        const nameText = ts9.isIdentifier(decl.name) ? decl.name.text : "";
-        if (nameText !== "run" || !decl.initializer) continue;
-        if (ts9.isArrowFunction(decl.initializer) || ts9.isFunctionExpression(decl.initializer)) {
-          result = node;
-        }
-      }
-    }
-  });
-  return result;
-}
 function getReturnObjectLiteral(fn) {
   const body = fn.body;
   if (!body) return null;
@@ -5188,31 +5170,60 @@ function getReturnObjectLiteral(fn) {
   }
   return null;
 }
-function extractConfigFields(objLit) {
-  const result = {};
+function extractConfigFields(objLit, sourceFile) {
+  let systemPrompt;
+  let tools;
+  let agents;
+  let model;
+  let maxTurns;
   for (const prop of objLit.properties) {
-    if (!ts9.isPropertyAssignment(prop)) continue;
+    if (ts9.isSpreadAssignment(prop)) continue;
+    if (!ts9.isPropertyAssignment(prop)) {
+      throw SchemaExtractionError.at(
+        prop,
+        "config",
+        "\u4EC5\u652F\u6301 key: value \u5C5E\u6027\u5F62\u5F0F\uFF08\u4E0D\u652F\u6301 shorthand/\u65B9\u6CD5/getter\uFF09",
+        sourceFile
+      );
+    }
     const propName = getPropertyName(prop.name);
-    if (!propName) continue;
+    if (!propName) {
+      throw SchemaExtractionError.at(prop.name, "config", "\u4E0D\u652F\u6301 computed \u5C5E\u6027\u540D", sourceFile);
+    }
     switch (propName) {
       case "systemPrompt":
-        result.systemPrompt = extractStringValue(prop.initializer);
+        systemPrompt = requireStringValue(prop, "systemPrompt", sourceFile);
         break;
       case "tools":
-        result.tools = extractStringArrayValue(prop.initializer);
+        tools = requireStringArrayValue(prop, "tools", sourceFile);
         break;
       case "agents":
-        result.agents = extractStringArrayValue(prop.initializer);
+        agents = requireStringArrayValue(prop, "agents", sourceFile);
         break;
       case "model":
-        result.model = extractStringValue(prop.initializer);
+        model = requireStringValue(prop, "model", sourceFile);
         break;
       case "maxTurns":
-        result.maxTurns = extractNumberValue(prop.initializer);
+        maxTurns = requireNumberValue(prop, "maxTurns", sourceFile);
         break;
+      default:
+        throw SchemaExtractionError.at(
+          prop,
+          `config.${propName}`,
+          "\u672A\u77E5 config \u5B57\u6BB5\u2014\u2014\u4EC5\u652F\u6301 systemPrompt / tools / agents / model / maxTurns",
+          sourceFile
+        );
     }
   }
-  return result;
+  if (systemPrompt === void 0) {
+    throw SchemaExtractionError.at(
+      objLit,
+      "config.systemPrompt",
+      "agent \u5FC5\u586B\u2014\u2014\u8BF7\u5728 config \u5757\u58F0\u660E\u7CFB\u7EDF\u63D0\u793A\u8BCD\uFF08\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u6216\u65E0\u63D2\u503C\u6A21\u677F\u5B57\u7B26\u4E32\uFF09",
+      sourceFile
+    );
+  }
+  return { systemPrompt, tools, agents, model, maxTurns };
 }
 function getPropertyName(name) {
   if (ts9.isIdentifier(name)) return name.text;
@@ -5220,9 +5231,45 @@ function getPropertyName(name) {
   return null;
 }
 function extractStringValue(expr) {
-  if (ts9.isStringLiteral(expr)) return expr.text;
+  if (isStringLikeLiteral(expr)) return expr.text;
   return void 0;
 }
+function requireStringValue(prop, fieldName, sourceFile) {
+  const value = extractStringValue(prop.initializer);
+  if (value === void 0) {
+    throw SchemaExtractionError.at(
+      prop.initializer,
+      `config.${fieldName}`,
+      "\u4EC5\u652F\u6301\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u6216\u65E0\u63D2\u503C\u6A21\u677F\u5B57\u7B26\u4E32\uFF08\u542B\u63D2\u503C\u7684\u6A21\u677F\u5B57\u7B26\u4E32/\u53D8\u91CF\u5F15\u7528\u65E0\u6CD5\u9759\u6001\u6C42\u503C\uFF09",
+      sourceFile
+    );
+  }
+  return value;
+}
+function requireStringArrayValue(prop, fieldName, sourceFile) {
+  const value = extractStringArrayValue(prop.initializer);
+  if (value === void 0) {
+    throw SchemaExtractionError.at(
+      prop.initializer,
+      `config.${fieldName}`,
+      "\u4EC5\u652F\u6301\u5168\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u6570\u7EC4\uFF08\u5143\u7D20\u4E3A\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u6216\u65E0\u63D2\u503C\u6A21\u677F\u5B57\u7B26\u4E32\uFF09",
+      sourceFile
+    );
+  }
+  return value;
+}
+function requireNumberValue(prop, fieldName, sourceFile) {
+  const value = extractNumberValue(prop.initializer);
+  if (value === void 0) {
+    throw SchemaExtractionError.at(
+      prop.initializer,
+      `config.${fieldName}`,
+      "\u4EC5\u652F\u6301\u6570\u5B57\u5B57\u9762\u91CF",
+      sourceFile
+    );
+  }
+  return value;
+}
 function extractNumberValue(expr) {
   if (ts9.isNumericLiteral(expr)) {
     const num = Number(expr.text);
@@ -5230,11 +5277,14 @@ function extractNumberValue(expr) {
   }
   return void 0;
 }
+function isStringLikeLiteral(node) {
+  return ts9.isStringLiteral(node) || ts9.isNoSubstitutionTemplateLiteral(node);
+}
 function extractStringArrayValue(expr) {
   if (!ts9.isArrayLiteralExpression(expr)) return void 0;
   const values = [];
   for (const element of expr.elements) {
-    if (!ts9.isStringLiteral(element)) return void 0;
+    if (!isStringLikeLiteral(element)) return void 0;
     values.push(element.text);
   }
   return values;
@@ -5276,6 +5326,28 @@ function hydrateAgents(manifest) {
     maxTurns: a.maxTurns ?? void 0
   }));
 }
+function validateAgentList(metadata) {
+  const names = /* @__PURE__ */ new Map();
+  for (const a of metadata) {
+    const prev = names.get(a.name);
+    if (prev) {
+      throw new Error(
+        `agent \u540D\u91CD\u590D: "${a.name}"\uFF08${prev} \u4E0E ${a.filePath} \u51B2\u7A81\u2014\u2014\u76EE\u5F55\u63A8\u5BFC\u540D\u6216 @agent \u8986\u76D6\u540D\u649E\u540D\uFF09`
+      );
+    }
+    names.set(a.name, a.filePath);
+  }
+  for (const a of metadata) {
+    for (const ref of a.agents ?? []) {
+      if (!names.has(ref)) {
+        const available = [...names.keys()].join(", ") || "\u65E0";
+        throw new Error(
+          `agent "${a.name}" \u7684 agents \u5F15\u7528\u4E86\u4E0D\u5B58\u5728\u7684 agent: "${ref}"\uFF08\u6E05\u5355\u4E2D\u53EF\u7528: ${available}\uFF09`
+        );
+      }
+    }
+  }
+}
 async function generateAgentArtifacts(agents, rootDir, dist) {
   const metadata = [];
   const programByFile = createPrograms(agents.map((m) => path17.resolve(rootDir, m.filePath)));
@@ -5287,10 +5359,14 @@ async function generateAgentArtifacts(agents, rootDir, dist) {
       filePath: manifest.filePath,
       hasRun: manifest.hasRun
     });
-    if (result) {
-      metadata.push(result);
+    if (!result) {
+      throw new Error(
+        `agent "${manifest.name}" \u6E90\u6587\u4EF6\u4E0D\u5728 Program \u4E2D: ${manifest.filePath}\u2014\u2014\u65E0\u6CD5\u751F\u6210\u6E05\u5355`
+      );
     }
+    metadata.push(result);
   }
+  validateAgentList(metadata);
   const serialized = serializeAgents(metadata, dist);
   const agentsPath = path17.resolve(rootDir, dist, AGENTS_FILE);
   await writeAgentsModule(serialized, agentsPath);