@faapi/faapi 6.27.0 → 6.28.0

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

@@ -51,7 +51,7 @@ interface ToolMetadata extends ToolCore {
  * 透传到 [ToolMetadata](./extractToolMetadata.ts) 输出,与 AST 提取字段合并。
  */
 interface ToolPathMeta {
-    /** 路径推导的 tool 名(如 `weather.getWeather`) */
+    /** 路径推导的 tool 名(如 `weather_getWeather`) */
     name: string;
     /** 源码相对路径(如 `src/tools/weather/handler.ts`) */
     filePath: string;
@@ -432,7 +432,7 @@ declare function runTaskInWorker(options: TaskWorkerOptions): Promise<unknown>;
 interface ToolRegistry {
     /** 全量替换（tool 清单来自编译期产物，reload 时整体重新生成） */
     hydrate(tools: ToolMetadata[]): void;
-    /** 按全名查找（如 `weather.getWeather`） */
+    /** 按全名查找（如 `weather_getWeather`） */
     get(name: string): ToolMetadata | undefined;
     /** 所有已注册 tool（副本） */
     list(): ToolMetadata[];

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-CBE86AO2.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-CBE86AO2.js';
-import { F as FaapiMiddleware, R as RouteManifest, C as CorsOptions, H as HelmetOptions, I as InjectorMap, W as WsRouteManifest } from './routeTypes-DVSnH0jk.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-DVSnH0jk.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-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 * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -1348,11 +1348,40 @@ declare function resolveSubAgents(name: string): AgentCore[];
  *
  * 框架路径（`@faapi/agent` 插件 / 请求注入）从 app 实例查找。
  *
- * @param tool 全名（如 `weather.getWeather`）
+ * @param tool 全名（如 `weather_getWeather`）
  * @returns `ToolMetadata` 或 `undefined`（未注册）
  */
 declare function getTool(name: string): ToolMetadata | undefined;
 
+/**
+ * sub-agent 派发工具名生成（唯一入口）
+ *
+ * agent-as-tool 把 sub-agent 包装成 tool 发给 LLM，`function.name` 受 OpenAI 兼容协议
+ * 硬约束 `^[a-zA-Z0-9_-]+$`——DeepSeek / OpenAI 等强校验上游对非法字符整单 400。
+ * 历史上派发名是 `agent.<agentName>`（点号前缀 + 嵌套 agent 名的点号分隔），在强校验
+ * 上游完全不可用（业务方反馈 TODO-faapi-gaps #1）。
+ *
+ * 命名规则：`agent-` 前缀 + agent 名直拼。agent 名的合法性由上游保证——文件型 agent
+ * 在 scanAgents 目录段校验（段内 `[a-zA-Z0-9-]`，`_` 为 `/` 规范化后的嵌套分隔符）、
+ * `@agent` 覆盖名在 extractAgentMetadata 校验（整体 `^[a-zA-Z0-9_-]+$`）；本模块对组合
+ * 结果做最后一道运行时闸门（程序化 hydrate 的 agent 名不经构建期扫描），违例显式抛错
+ * ——不静默净化（掩盖配置错误），不降级放行（强校验上游 400）。
+ *
+ * 详见 [subAgentToolName.md](./subAgentToolName.md)。
+ */
+/** OpenAI 兼容协议对 LLM 工具名（function.name）的字符集约束 */
+declare const LLM_TOOL_NAME_PATTERN: RegExp;
+/** sub-agent 派发工具名前缀（旧版 `agent.` 点号前缀违反上述字符集，已废弃） */
+declare const SUB_AGENT_TOOL_PREFIX = "agent-";
+/**
+ * 生成 sub-agent 派发工具名：`agent-<agentName>`
+ *
+ * @param agentName agent 注册名（scanAgents 目录推导或 `@agent` 覆盖名）
+ * @returns 满足 {@link LLM_TOOL_NAME_PATTERN} 的派发工具名
+ * @throws agent 名含工具名字符集之外的字符时抛错（含原名与改名指引）
+ */
+declare function subAgentToolName(agentName: string): string;
+
 /**
  * skill 注册表全局访问器（默认实例便捷入口）
  *
@@ -1743,4 +1772,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, 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 };
+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 };

package/dist/index.js

@@ -1835,6 +1835,19 @@ function createTaskRegistry() {
   };
 }
 
+// src/injection/subAgentToolName.ts
+var LLM_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+var SUB_AGENT_TOOL_PREFIX = "agent-";
+function subAgentToolName(agentName) {
+  const toolName = SUB_AGENT_TOOL_PREFIX + agentName;
+  if (!LLM_TOOL_NAME_PATTERN.test(toolName)) {
+    throw new Error(
+      `Sub-agent tool name "${toolName}" (from agent name "${agentName}") violates the LLM tool name pattern ${LLM_TOOL_NAME_PATTERN} \u2014 rename the agent (allowed: a-z A-Z 0-9 '-' '_'; file-based agent directory segments allow a-z A-Z 0-9 '-' only, '_' is the nesting separator)`
+    );
+  }
+  return toolName;
+}
+
 // src/injection/registries.ts
 function createToolRegistry() {
   let registry = /* @__PURE__ */ new Map();
@@ -1882,7 +1895,7 @@ function createAgentRegistry(tool) {
       if (!agent) return void 0;
       return {
         kind: "agent",
-        name: `agent.${agent.name}`,
+        name: subAgentToolName(agent.name),
         agentName: agent.name,
         description: agent.description,
         metadata: agent
@@ -3685,6 +3698,7 @@ function extractJSDocTagValue(jsDoc, tagName) {
 }
 
 // src/ast/extractToolMetadata.ts
+init_resolveTypeNode();
 function extractToolMetadata(program, filePath, functionName, pathMeta) {
   const sourceFile = program.getSourceFile(filePath);
   if (!sourceFile) return null;
@@ -3694,6 +3708,14 @@ function extractToolMetadata(program, filePath, functionName, pathMeta) {
   const jsDoc = getJSDocFromNode(jsDocOwner);
   const description = extractDescription(jsDoc);
   const toolNameOverride = extractJSDocTagValue(jsDoc, "tool");
+  if (toolNameOverride !== void 0 && !LLM_TOOL_NAME_PATTERN.test(toolNameOverride)) {
+    throw SchemaExtractionError.at(
+      jsDocOwner,
+      "@tool",
+      `\u8986\u76D6\u540D "${toolNameOverride}" \u542B\u975E\u6CD5\u5B57\u7B26\u2014\u2014\u987B\u6EE1\u8DB3 ${LLM_TOOL_NAME_PATTERN}\uFF08tool \u540D\u76F4\u63A5\u4F5C\u4E3A LLM function.name\uFF0C\u5F3A\u6821\u9A8C\u4E0A\u6E38\u5BF9\u975E\u6CD5\u5B57\u7B26\u6574\u5355 400\uFF09`,
+      sourceFile
+    );
+  }
   const inputTypeName = getFirstParamTypeName(fn, sourceFile);
   return {
     name: toolNameOverride ?? pathMeta.name,
@@ -6825,6 +6847,14 @@ function extractAgentMetadata(program, filePath, pathMeta) {
   const jsDoc = getJSDocFromNode(configFound.jsDocOwner);
   const description = extractDescription(jsDoc);
   const agentNameOverride = extractJSDocTagValue(jsDoc, "agent");
+  if (agentNameOverride !== void 0 && !LLM_TOOL_NAME_PATTERN.test(agentNameOverride)) {
+    throw SchemaExtractionError.at(
+      configFound.jsDocOwner,
+      "@agent",
+      `\u8986\u76D6\u540D "${agentNameOverride}" \u542B\u975E\u6CD5\u5B57\u7B26\u2014\u2014\u987B\u6EE1\u8DB3 ${LLM_TOOL_NAME_PATTERN}\uFF08\u8986\u76D6\u540D\u6210\u4E3A LLM \u5DE5\u5177\u540D "agent-<\u8986\u76D6\u540D>"\uFF0C\u5F3A\u6821\u9A8C\u4E0A\u6E38\u5BF9\u975E\u6CD5\u5B57\u7B26\u6574\u5355 400\uFF09`,
+      sourceFile
+    );
+  }
   const { systemPrompt, systemPromptFile, tools, agents, model, maxTurns, inputDescription } = extractConfigFields(objectLiteral, sourceFile);
   return {
     name: agentNameOverride ?? pathMeta.name,
@@ -7897,11 +7927,20 @@ function extractToolExportsFromSource(source) {
   }
   return names;
 }
+var TOOL_DIR_SEGMENT_PATTERN = /^[a-zA-Z0-9-]+$/;
 function extractNamespaceFromRelPath(relPath) {
   const lastSlash = relPath.lastIndexOf("/");
   const dirPath = lastSlash === -1 ? "" : relPath.slice(0, lastSlash);
   if (!dirPath) return "";
-  return dirPath.split("/").join(".");
+  const segments = dirPath.split("/");
+  for (const segment of segments) {
+    if (!TOOL_DIR_SEGMENT_PATTERN.test(segment)) {
+      throw new Error(
+        `Invalid tool directory segment "${segment}" in "tools/${relPath}": tool directory names allow a-z A-Z 0-9 '-' only ('_' is reserved as the nesting separator, '.' is not allowed \u2014 tool names are sent to LLMs as function.name) \u2014 rename the directory`
+      );
+    }
+  }
+  return segments.join("_");
 }
 function filePathToToolNamespace(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
@@ -7912,7 +7951,13 @@ function filePathToToolNamespace(filePath) {
   return "";
 }
 function buildToolName(namespace, functionName) {
-  return namespace ? `${namespace}.${functionName}` : functionName;
+  const name = namespace ? `${namespace}_${functionName}` : functionName;
+  if (!LLM_TOOL_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Tool name "${name}" (function "${functionName}"${namespace ? ` in namespace "${namespace}"` : ""}) violates the LLM tool name pattern ${LLM_TOOL_NAME_PATTERN} \u2014 rename the function or use a @tool JSDoc override (allowed: a-z A-Z 0-9 '-' '_')`
+    );
+  }
+  return name;
 }
 async function scanTools(rootDir, patterns) {
   const files = await fg4(patterns, {
@@ -7954,6 +7999,7 @@ async function scanTools(rootDir, patterns) {
 // src/agents/scanAgents.ts
 import fg5 from "fast-glob";
 var DEFAULT_AGENT_PATTERNS = ["src/agents/**/handler.ts"];
+var AGENT_DIR_SEGMENT_PATTERN = /^[a-zA-Z0-9-]+$/;
 function extractAgentNameFromPath(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
   const match = normalized.match(/(?:^|\/)agents\/(.+)\/handler\.ts$/);
@@ -7962,7 +8008,15 @@ function extractAgentNameFromPath(filePath) {
       `Not an agent path: "${filePath}". Expected pattern: src/agents/<name>/handler.ts`
     );
   }
-  return match[1].replace(/\//g, ".");
+  const segments = match[1].split("/");
+  for (const segment of segments) {
+    if (!AGENT_DIR_SEGMENT_PATTERN.test(segment)) {
+      throw new Error(
+        `Invalid agent directory segment "${segment}" in "${filePath}": agent directory names allow a-z A-Z 0-9 '-' only ('_' is reserved as the nesting separator, '.' is not allowed \u2014 agent names become LLM tool names "agent-<name>") \u2014 rename the directory`
+      );
+    }
+  }
+  return segments.join("_");
 }
 async function scanAgents(rootDir, patterns) {
   const files = await fg5(patterns, {
@@ -8078,9 +8132,11 @@ async function createProdApp(options) {
 export {
   FaapiError,
   InternalError,
+  LLM_TOOL_NAME_PATTERN,
   MethodNotAllowedError,
   ModuleLoadError,
   RouteNotFoundError,
+  SUB_AGENT_TOOL_PREFIX,
   SchemaExtractionError,
   TASK_PATTERNS,
   ValidationError,
@@ -8125,6 +8181,7 @@ export {
   resolveSubAgents,
   resolveTypeNode,
   scanTasks,
+  subAgentToolName,
   upsertSkill
 };
 //# sourceMappingURL=index.js.map