@faapi/faapi 6.26.0 → 6.28.0

package/dist/{contextTypes-gYf84EXF.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;
@@ -80,7 +80,7 @@ interface AgentCore {
     systemPrompt?: string;
     /**
      * 系统提示词文件路径(config 块字面量提取),相对产物 resources 目录
-     * (`<dist>/resources/`,即 `ctx.resourcesDir`),与 `systemPrompt` 互斥
+     * (`<dist>/resources/`,运行时经免传参 `readResource` 读取),与 `systemPrompt` 互斥
      * (都声明构建期抛错,二选一必填)
      *
      * 运行时每次 run 读文件内容作为 systemPrompt——dev 改 prompt 文件经 watcher
@@ -364,9 +364,8 @@ interface TaskWorkerOptions {
     taskCtx: {
         config: unknown;
         /**
-         * 产物 resources 目录绝对路径（纯字符串可结构化克隆）——两处用途：经
-         * workerData 传给入口在任务模块求值前播种全局读取根 + 挂到 worker 内的
-         * taskCtx（业务方了解/拼接资源位置）
+         * 产物 resources 目录绝对路径（纯字符串可结构化克隆）——经 workerData
+         * 传给入口在任务模块求值前播种全局读取根（内部字段，不进业务 taskCtx）
          */
         resourcesDir?: string;
         job: {
@@ -433,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[];
@@ -628,14 +627,6 @@ 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;
@@ -736,8 +727,10 @@ interface TaskQueueDeps {
     /** faapi.config.ts 全量配置，透传给 run 的 TaskContext.config */
     config?: unknown;
     /**
-     * 产物 resources 目录绝对路径——注入两条执行路径的 TaskContext.resourcesDir；
-     * 缺省不注入（直接构造队列的测试/嵌入场景）
+     * 产物 resources 目录绝对路径——**内部字段**，仅作隔离 worker 读取根播种的
+     * 数据源（经 workerData 传入 workerEntry，不进业务可见的 TaskContext——
+     * 任务读资源统一走免传参 `readResource`）；缺省不播种（直接构造队列的
+     * 测试/嵌入场景，readResource 未绑定即显式抛错）
      */
     resourcesDir?: string;
     /**
@@ -1051,15 +1044,6 @@ interface FaapiContext {
     cookies: Record<string, string>;
     /** 配置文件中的自定义业务配置（类型可通过 declare module '@faapi/faapi' 增强 FaapiContextConfig） */
     config: FaapiContextConfig;
-    /**
-     * 运行时资源根目录绝对路径（<rootDir>/<dist>/resources）
-     *
-     * `src/resources/` 经 dev/build 复制进产物后的位置。数据字段——读取统一走
-     * 免传参的 `readResource('prompts/foo.md')`（app 启动时绑定，见
-     * src/utils/readResource.md），本字段供业务方了解/拼接资源位置。
-     * HTTP/WS 请求链路恒有值；testing 直调（createTestContext）未传时为 undefined。
-     */
-    resourcesDir?: string;
     /**
      * 设置响应状态码
      */

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-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 { 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';
@@ -50,14 +50,6 @@ 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()） */
@@ -261,13 +253,6 @@ interface TaskConfig {
 interface LifecycleContext {
     /** 项目根目录 */
     rootDir: string;
-    /**
-     * 运行时资源根目录绝对路径（<rootDir>/<dist>/resources）
-     *
-     * `src/resources/` 经 dev/build 复制进产物后的位置，onReady 中预加载
-     * prompt 模板等静态文件时定位用（`path.join(resourcesDir, 'prompts/foo.md')`）。
-     */
-    resourcesDir: string;
     /** 当前路由清单 */
     routes: RouteManifest;
     /** 服务器实例（onBoot 钩子触发时已创建但未监听，`listening === false`） */
@@ -860,13 +845,6 @@ interface WsContext {
     headers: Headers;
     /** 业务配置（来自 faapi.config.ts） */
     config: Record<string, unknown>;
-    /**
-     * 运行时资源根目录绝对路径（<rootDir>/<dist>/resources）
-     *
-     * 与 HTTP FaapiContext 同源（握手 ctx 是 FaapiContext 的结构子集），handler
-     * 的 WS 回调里读静态文件用。testing 直调未传时为 undefined。
-     */
-    resourcesDir?: string;
     /** 中间件塞入的用户信息（鉴权等） */
     user?: unknown;
     /** 允许通过 declare module 扩展 */
@@ -1370,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 注册表全局访问器（默认实例便捷入口）
  *
@@ -1765,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 };