@faapi/faapi 3.2.0 → 3.3.0

package/dist/index.d.ts

@@ -308,6 +308,9 @@ interface AgentConfig {
      * Phase 2.3 的 `agent` 参数注入暂返回 `undefined`，Phase 3.x 的 @faapi/agent 插件
      * 读取此值从 [agentRegistry](../injection/agentRegistry.md) 查找对应 agent 元数据，
      * 注入 `AgentHandle`（含可调用 `run`）。
+     *
+     * 可选——未设时 handler 需通过 `agent.run(input, { agent: 'name' })` 显式指定 agent 名，
+     * 否则 `agent.run` 抛 `AgentError`。
      */
     defaultAgent?: string;
     /**
@@ -323,22 +326,23 @@ interface AgentConfig {
      */
     maxAgentDepth?: number;
     /**
-     * 启用 tracing 的全局默认值（默认 true）
+     * 启用 tracing 的全局默认值（默认 false——opt-in,不开启零开销）
      *
      * 开启时 `agent.run()` / `agent.stream()` 返回的 `result.trace` /
      * `chunk.traceEvent` 填充结构化调用明细（按轮次组织的 LLM 调用、tool 调用、
      * sub-agent 嵌套调用事件,含 timing 与 token 用量）。
      *
      * 三层覆盖优先级：`AgentRunOptions.enableTracing` > agent 自身配置 >
-     * 此全局配置 > 默认 `true`。
+     * 此全局配置 > 默认 `false`。
      *
-     * 业务方在生产主路径（高 QPS 端点）显式设 `false` 关闭以零开销运行：
+     * tracing 采集每轮 LLM 消息快照与 tool 明细,有真实内存/CPU 开销——
+     * 需要观测的端点显式开启：
      *
      * ```ts
      * import type { FaapiConfig } from '@faapi/faapi';
      * export default {
      *   agent: {
-     *     enableTracing: false,
+     *     enableTracing: true, // 全局开启;单次调用可用 run(input, { enableTracing: true }) 覆盖
      *     llms: { openai: { provider: 'openai', apiKey: '...', models: { 'gpt-4o': {} } } },
      *   },
      * } satisfies FaapiConfig;
@@ -390,6 +394,15 @@ interface FaapiConfig {
     logger?: LoggerOptions | boolean;
     /** HTTP/2 配置，false 禁用（默认 http/1.1） */
     http2?: Http2Options | boolean;
+    /**
+     * 是否信任反向代理头（X-Forwarded-For），默认 false
+     *
+     * - `true`：`ctx.ip` 取 `x-forwarded-for` 第一个 IP——部署在 nginx/CDN 等受信任
+     *   反向代理之后时开启
+     * - `false`（默认）：直取 socket 地址。客户端直连时 XFF 可被任意伪造，
+     *   安全默认不信任（同时影响 HTTP 与 WS 握手的 `ctx.ip`）
+     */
+    trustedProxy?: boolean;
     /**
      * 统一响应包装配置
      *
@@ -607,20 +620,54 @@ interface WsContext {
 type WsHandler = (ctx: WsContext) => WsEventHandlers | void;
 
 /**
- * 清理所有 Program 缓存（watch 模式下文件变化时调用）
+ * 清理所有 Program 缓存 + tsconfig 解析缓存（watch 模式下文件变化时调用）
  *
  * 全量清理而非增量清理，理由：
  * - 简单可靠，无状态一致性问题
  * - 跨文件类型引用需要所有文件的 Program 同步更新
+ * - tsconfig 可能变化，需重新读取
  * - dev 模式文件量有限，全量重建在百毫秒级
  */
 declare function invalidateProgramCache(): void;
 /**
  * 为指定文件创建 TypeScript Program（带缓存）
  *
+ * 从 filePath 向上查找最近的 tsconfig.json：
+ * - 找到：用 ts.parseJsonConfigFileContent 解析，取 module / moduleResolution
+ *   覆盖默认值，同时取 parsed.fileNames 作为 program 的 rootNames（让跨文件
+ *   import 的源文件被加载进 program）
+ * - 找不到（如 os.tmpdir() 测试场景）：回退到默认 NodeNext，rootNames 仅包含 filePath
+ *
+ * 加载全部相关文件保证 `resolveTypeReference` 的兜底遍历（找同名声明）能成功，
+ * 修复业务项目用 `moduleResolution: Bundler` + 无扩展名相对导入时跨文件
+ * `import type` 解析失败的问题。
+ *
+ * 同一次生成中需要分析多个文件时用 {@link createPrograms}（按 tsconfig 分组共享
+ * 同一个 Program），避免每个文件单独创建 Program 重复解析全项目源码。
+ *
  * @param filePath 要分析的 .ts 文件绝对路径
  */
 declare function createProgram(filePath: string): ts.Program;
+/**
+ * 为多个文件创建 Program（按 tsconfig 分组共享，带缓存）
+ *
+ * 同一次批量提取（build 时生成 routes/tools/agents 产物）中，所有向上查找到
+ * 同一个 tsconfig.json 的文件共用**同一个 Program**——rootNames 为
+ * tsconfig fileNames ∪ 全部入口文件，跨文件类型解析语义与单文件 `createProgram`
+ * 完全一致，但 N 个文件只创建 1 个 Program（原来每个文件都全量解析一遍项目源码，
+ * 是 build 时间的最大单项开销）。
+ *
+ * 缓存 key 为 `shared::<tsconfigPath>::<排序后的文件列表>`：同一批次重复调用命中
+ * 缓存；不同批次（rootNames 不同）各自创建。`invalidateProgramCache()` 同时清理
+ * 共享缓存与单文件缓存。
+ *
+ * 向上查找不到 tsconfig.json 的文件（如 os.tmpdir() 测试场景）逐个回退到
+ * {@link createProgram} 单文件行为，不参与共享。
+ *
+ * @param filePaths 要分析的 .ts 文件绝对路径列表（内部去重）
+ * @returns filePath → Program 映射（包含全部请求文件）
+ */
+declare function createPrograms(filePaths: string[]): Map<string, ts.Program>;
 
 /**
  * Schema 提取错误
@@ -1181,6 +1228,16 @@ interface ToolSchemaModule {
     /** schema 导出名（如 `WeatherInputSchema`，用于日志/调试） */
     schemaName: string;
 }
+/**
+ * 计算 tool 的 zod.js 绝对路径（纯路径计算，无 fs 访问）
+ *
+ * 与 [loadToolSchema](./loadToolSchema.ts) 内部使用的路径逻辑同源（共享 `getDist()`），
+ * 供 `@faapi/agent` 的跨请求 schema 缓存用作缓存键 + mtime 校验目标。
+ *
+ * @param tool tool 元数据（含 `filePath`）
+ * @param rootDir 项目根目录（`tool.filePath` 是相对路径时拼接）
+ */
+declare function getToolSchemaPath(tool: ToolMetadata, rootDir?: string): string;
 /**
  * 动态加载 tool 的 zod.js schema 模块
  *
@@ -1509,4 +1566,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type AgentConfig, type AgentCore, type AgentHandleFactory, type AgentMetadata, type AgentModule, type AgentPathMeta, type AgentToolDescriptor, type ProdApp as App, CorsOptions, type CreateAppOptions, 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, LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type ToolCore, type ToolMetadata, type ToolModule, type ToolPathMeta, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, createProdApp as createApp, createDevApp, createProdApp, createProgram, extractTypeInfo, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadToolModule, loadToolSchema, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, upsertSkill };
+export { type AgentConfig, type AgentCore, type AgentHandleFactory, type AgentMetadata, type AgentModule, type AgentPathMeta, type AgentToolDescriptor, type ProdApp as App, CorsOptions, type CreateAppOptions, 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, LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, RouteManifest, RouteNotFoundError, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type ToolCore, type ToolMetadata, type ToolModule, type ToolPathMeta, type ToolSchemaModule, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, clearAgentHandleFactory, collectRouteSchemaSources, createProdApp as createApp, createDevApp, createProdApp, createProgram, createPrograms, extractTypeInfo, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadToolModule, loadToolSchema, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, upsertSkill };