@faapi/faapi 3.3.0 → 4.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as RouteManifest, C as CorsOptions, F as FaapiContext, H as HelmetOptions, L as LoggerOptions, a as FaapiMiddleware, I as InjectorMap, W as WsRouteManifest } from './routeTypes-FtbRkpVF.js';
-export { b as FaapiContextConfig, c as FailOptions, d as Injector, e as RouteInfo, f as RouteInputSchema, g as RouteOutputSchema, h as RouteParamSchema, S as SseEvent, i as SseWriter, j as cors, k as helmet, l as logger } from './routeTypes-FtbRkpVF.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-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 * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
@@ -20,6 +20,8 @@ type UpgradeHandler = (req: IncomingMessage, socket: Socket, head: Buffer) => vo
 interface PluginContext {
     /** 项目根目录 */
     rootDir: string;
+    /** app 级注册表（tool/agent/skill/agentHandle 实例，随 app 生命周期） */
+    registries: AppRegistries;
     /** 当前路由清单（setup 时的快照，reloadRoutes 后不会更新；需最新路由用 getRoutes()） */
     routes: RouteManifest;
     /** 获取最新路由清单（reloadRoutes 后返回更新后的数组） */
@@ -94,6 +96,23 @@ type PluginDeclaration = string | [string, unknown] | {
     options?: unknown;
 };
 
+interface CompressionOptions {
+    /**
+     * 最小压缩字节数，body 低于该值不压缩（小 payload 压缩后反而变大）
+     * @default 1024
+     */
+    threshold?: number;
+}
+
+interface EtagOptions {
+    /**
+     * 生成弱 ETag（`W/"<hash>"`）。弱校验器允许压缩等表示差异下的 304 协商，
+     * 与 compression 中间件配合正确；强 ETag 需对每个表示（编码）单独生成
+     * @default true
+     */
+    weak?: boolean;
+}
+
 interface Http2Options {
     key?: string;
     cert?: string;
@@ -132,6 +151,8 @@ interface LifecycleContext {
     routes: RouteManifest;
     /** 服务器实例 */
     server: node_http.Server;
+    /** app 级注册表——skill 等运行时动态注册路径（`registries.skill.upsert(...)`） */
+    registries: AppRegistries;
 }
 /**
  * 统一响应包装配置
@@ -249,6 +270,21 @@ interface LlmConfig {
      * model 级字段（如 `temperature`）覆盖 provider 级同名字段。
      */
     models: Record<string, LlmModelConfig>;
+    /**
+     * LLM 请求超时（毫秒，可选——未设置时无超时）
+     *
+     * provider 层用 `AbortSignal.timeout` 实现，与 run-level 的 `signal` 组合生效。
+     * 超时触发抛 `LLMProviderError`（message 含 timed out），计入重试（429/5xx/网络错误同策略）。
+     */
+    timeoutMs?: number;
+    /**
+     * 429 / 5xx / 网络错误的最大重试次数（默认 2，设 0 关闭重试）
+     *
+     * 退避策略：优先尊重响应的 `Retry-After` 头（秒，封顶 30s），否则指数退避
+     * 500ms * 2^attempt。4xx 其他状态（400/401 等）是确定性错误，不重试。
+     * 流式请求仅在「连接建立前」重试，流开始输出后中断不重试。
+     */
+    maxRetries?: number;
     /**
      * 其他透传参数（provider 级，如 temperature / top_p / max_tokens）
      *
@@ -351,6 +387,48 @@ interface AgentConfig {
      * 详见 `@faapi/agent` 的 [trace](../../agent/src/trace.md) 文档。
      */
     enableTracing?: boolean;
+    /**
+     * 执行守卫（authHooks，见 @faapi/agent 的 authHooks 文档）
+     *
+     * 每次 tool / sub-agent 执行前调用（`agent.x` 名称为 sub-agent 递归）。
+     * 三种返回：`void` 放行；`{ error }` 拒绝（不执行，error 回传 LLM 调整策略）；
+     * `{ args }` 改写后放行（多租户场景强制注入可信值，不信 LLM 传入的标识参数）。
+     *
+     * 典型用法：中间件解析 `ctx.workspace` 后在此校验/强制改写 `args.workspaceId`。
+     */
+    /**
+     * 发送给 LLM 的历史 token 预算（近似估算，未设置 = 不裁剪）
+     *
+     * 多轮 tool 循环中对话历史只增不减，大 tool 结果会撑爆模型上下文窗口导致
+     * 下一轮 400。超预算时从最旧的轮组开始裁剪（system 与初始 user 保留、
+     * tool 配对不拆散），只作用于发给 LLM 的消息副本。详见 @faapi/agent 的
+     * reactLoop 文档历史裁剪章节。
+     */
+    maxHistoryTokens?: number;
+    beforeToolCall?: (name: string, args: Record<string, unknown>, ctx: FaapiContext | undefined) => void | {
+        error: string;
+    } | {
+        args: Record<string, unknown>;
+    };
+    /**
+     * 审计钩子（authHooks）：tool / sub-agent 成功返回后调用，返回值忽略。
+     * 用于日志/审计/计量；异常路径不调用。
+     */
+    afterToolCall?: (name: string, args: Record<string, unknown>, result: unknown, ctx: FaapiContext | undefined) => void;
+    /**
+     * 可见性过滤（authHooks）：LLM 可见 tools 清单组装完成后调用，
+     * 返回过滤后的数组（含 agent-as-tool 项）。每次 agent.run / stream 生效——
+     * 无权 tool 不进 LLM 视野，比执行时拒绝省一轮 LLM 调用。
+     */
+    filterTools?: (tools: Array<{
+        name: string;
+        description?: string;
+        input: Record<string, unknown>;
+    }>, ctx: FaapiContext | undefined) => Array<{
+        name: string;
+        description?: string;
+        input: Record<string, unknown>;
+    }>;
 }
 /**
  * faapi 配置文件类型
@@ -388,6 +466,16 @@ interface FaapiConfig {
     lifecycle?: LifecycleHooks;
     /** 安全头配置，false 禁用 */
     helmet?: HelmetOptions | boolean;
+    /**
+     * 响应压缩（gzip/deflate/br 协商），默认关闭。
+     * Vary: Accept-Encoding 自动附加；SSE/流式响应跳过，详见 middleware/compression.md
+     */
+    compression?: CompressionOptions | boolean;
+    /**
+     * ETag/304 条件请求协商（GET/HEAD 2xx 弱 ETag），默认关闭。
+     * handler 显式 ctx.setETag() 时不覆盖，详见 middleware/etag.md
+     */
+    etag?: EtagOptions | boolean;
     /** 请求体大小限制（字节），默认 10MB（10 * 1024 * 1024） */
     bodyLimit?: number;
     /** 日志中间件配置 */
@@ -657,9 +745,11 @@ declare function createProgram(filePath: string): ts.Program;
  * 完全一致，但 N 个文件只创建 1 个 Program（原来每个文件都全量解析一遍项目源码，
  * 是 build 时间的最大单项开销）。
  *
- * 缓存 key 为 `shared::<tsconfigPath>::<排序后的文件列表>`：同一批次重复调用命中
- * 缓存；不同批次（rootNames 不同）各自创建。`invalidateProgramCache()` 同时清理
- * 共享缓存与单文件缓存。
+ * 缓存 key 为 `shared::<tsconfigPath>`（同一 tsconfig 一份 Program）：同一批次重复
+ * 调用命中缓存；不同批次通过 `program.getSourceFile` 校验缓存已覆盖本次全部入口文件，
+ * 未覆盖（入口在 tsconfig include 之外）时重建。若把文件列表纳入 key，dev 按需模式下
+ * 每个路由文件会各自持有一份全项目 Program（内存 O(路由数 × 项目大小)）。
+ * `invalidateProgramCache()` 同时清理共享缓存与单文件缓存。
  *
  * 向上查找不到 tsconfig.json 的文件（如 os.tmpdir() 测试场景）逐个回退到
  * {@link createProgram} 单文件行为，不参与共享。
@@ -675,10 +765,24 @@ declare function createPrograms(filePaths: string[]): Map<string, ts.Program>;
  * 遇到无法解析或不支持运行时校验的类型时抛出，
  * 避免静默降级为 any 导致用户不知情。
  */
+/** 错误在源文件中的位置（file:line:column，便于在几百行类型文件中定位） */
+interface SchemaErrorLocation {
+    file: string;
+    line: number;
+    column: number;
+}
 declare class SchemaExtractionError extends Error {
     readonly typeText: string;
     readonly reason: string;
-    constructor(typeText: string, reason: string, options?: ErrorOptions);
+    readonly location?: SchemaErrorLocation | undefined;
+    constructor(typeText: string, reason: string, options?: ErrorOptions, location?: SchemaErrorLocation | undefined);
+    /**
+     * 从 AST 节点构造错误（自动携带 file:line:column）
+     *
+     * 所有抛错点应优先使用此工厂——错误无行号时，几百行的类型文件只能靠
+     * 类型名肉眼定位；解析 lib.d.ts 类型别名时还会出现错误文本与文件上下文错位
+     */
+    static at(node: ts.Node, typeText: string, reason: string): SchemaExtractionError;
 }
 /**
  * 运行时类型描述
@@ -714,6 +818,7 @@ type RuntimeType = {
 } | {
     kind: 'object';
     properties: PropertyType[];
+    catchall?: RuntimeType;
 } | {
     kind: 'union';
     members: RuntimeType[];
@@ -820,8 +925,11 @@ type TypeConstraint = {
  * @param typeNode TypeScript 类型节点
  * @param checker  类型 checker（用于解析引用类型）
  * @param visited  防止递归循环
+ * @param bindings 泛型形参绑定（形参名 → 已解析的实参类型），解析泛型声明的
+ *                 类型体时传入；形参名在 resolveTypeReference 入口优先命中，
+ *                 遮蔽同名的真实类型声明
  */
-declare function resolveTypeNode(typeNode: ts.TypeNode, checker?: ts.TypeChecker, visited?: Set<string>): RuntimeType;
+declare function resolveTypeNode(typeNode: ts.TypeNode, checker?: ts.TypeChecker, visited?: Set<string>, bindings?: Map<string, RuntimeType>): RuntimeType;
 
 interface HandlerTypeInfo {
     name: string;
@@ -835,6 +943,14 @@ interface HandlerTypeInfo {
  * 支持的类型声明：
  * - interface 声明（含继承）
  * - type 别名（type Query = { ... }）
+ * - enum 声明（跨文件回退路径支持）
+ *
+ * 自身文件找不到目标声明时，回退到 program 的其他源文件查找同名顶层声明
+ * （跳过 node_modules / TypeScript lib，首个匹配生效，与 resolveImportAlias
+ * 兜底路径语义一致）。该回退服务于入口类型中第二次出现的跨文件引用：首次引用
+ * 已由 checker 内联，二次引用被标记为 ref，代码生成阶段经
+ * createLazyTypeResolver → extractTypeInfo 解析，若无回退会静默生成
+ * z.unknown()，违背「不降级放行」约定。
  *
  * 遇到不支持的类型时抛 `SchemaExtractionError`，错误信息包含文件路径和类型名。
  *
@@ -843,6 +959,23 @@ interface HandlerTypeInfo {
  * @param typeName 类型名，如 'GETQuery'
  */
 declare function extractTypeInfo(program: ts.Program, filePath: string, typeName: string): HandlerTypeInfo | null;
+/**
+ * 惰性类型解析器
+ *
+ * 按名称解析类型并缓存。与 extractAllTypes 的差异：extractAllTypes 提前解析
+ * 文件中全部顶层类型——与路由无关的类型也会被解析，其中任何类型含不支持语法
+ * 都会拖垮整个 build/reload；惰性解析器只在类型真正被需要时（入口类型或
+ * ref 引用）才解析，无关类型零开销。
+ */
+interface LazyTypeResolver {
+    /**
+     * 按名称解析类型
+     *
+     * @returns 类型信息；文件中无该名称的声明时返回 null
+     * @throws SchemaExtractionError 类型声明含不支持语法时（与 extractTypeInfo 一致，不降级）
+     */
+    resolve(name: string): HandlerTypeInfo | null;
+}
 
 /**
  * 根据 HTTP 方法判断主输入类型
@@ -887,256 +1020,21 @@ interface RouteSchemaSource {
  *
  * dev 和 prd 共享的核心提取流程：
  * 1. 按文件分组遍历路由
- * 2. 对每个文件 createProgram + extractAllTypes 收集所有类型
- * 3. 用 analyzeInjection + extractTypeInfo 提取每个路由的 schema 类型
- * 4. 同时返回按文件分组的 allTypesMap 和合并后的全局 allTypes
- *
- * 调用方基于返回的 sources 和 allTypes 各自做最终转换：
- * - dev：生成 JS 模块文件 → import 加载（用 allTypesByFile）
- * - prd：生成 JS 模块代码 → SchemaModuleEntry[]（用 allTypesByFile）
+ * 2. 批量共享 Program（同一次提取只按文件组创建少量 Program）
+ * 3. 对每个路由用 analyzeInjectionInSourceFile 定位入口参数类型，
+ *    extractTypeInfo 解析入口类型（入口类型必须严格解析，失败抛 SchemaExtractionError）
+ * 4. 返回按文件分组的惰性类型解析器——generateSchemaFiles 生成 zod.js 时
+ *    遇到 ref（同文件循环引用）按需解析并缓存
+ *
+ * 惰性语义：与路由无关的类型（未被任何入口类型引用）不会被解析——文件里
+ * 存在一个含不支持语法的无关类型不再拖垮整个 build/reload。
  */
 declare function collectRouteSchemaSources(routes: RouteManifest, rootDir?: string): {
     sources: RouteSchemaSource[];
-    /** 按文件分组的类型映射（prd writeSchemaModule 用） */
-    allTypesByFile: Map<string, Map<string, HandlerTypeInfo>>;
-    /** 合并后的全局类型映射（兼容旧调用方保留，新路径使用 allTypesByFile） */
-    mergedAllTypes: Map<string, HandlerTypeInfo>;
+    /** 按文件分组的惰性类型解析器（generateSchemaFiles 解析 ref 用） */
+    resolversByFile: Map<string, LazyTypeResolver>;
 };
 
-/**
- * Agent 的 LLM 可见核心字段
- *
- * 描述"agent 是什么"——LLM 真正需要消费的字段,**不含**代码本体加载细节
- * (filePath / hasRun)。文件型 agent 与 DB-driven skill 都实现此接口。
- *
- * - 文件型 agent:由 [AgentMetadata](./extractAgentMetadata.md) 继承扩展,
- *   额外含 `filePath` / `hasRun`(代码本体加载用)
- * - DB-driven skill:业务方 plugin 从 DB 字段映射到本接口即可,无需填占位值
- *   (skill 无源文件,不走 `loadAgentModule`,自然不读 filePath / hasRun)
- *
- * `@faapi/agent` 子包的 `Agent` 类、`agentRegistry` 查询入口、`asTool` 包装
- * 都消费 `AgentCore`,实现"agent 与 skill 走同一运行时链路"。
- */
-interface AgentCore {
-    /** agent 名(`@agent` JSDoc 覆盖值 或 目录推导值) */
-    name: string;
-    /** JSDoc 描述(agent 描述,对 LLM 可见),无 JSDoc 或 JSDoc 无自由文本时为 `undefined` */
-    description?: string;
-    /** 系统提示词(config 块字面量提取),无/非字面量时为 `undefined` */
-    systemPrompt?: string;
-    /** agent 显式声明可用的 tool 引用列表(config 块字面量提取),无/含非字面量元素时为 `undefined` */
-    tools?: string[];
-    /** 可调用的其他 agent 名列表(config 块字面量提取),无/含非字面量元素时为 `undefined` */
-    agents?: string[];
-    /** LLM 模型名(config 块字面量提取),无/非字面量时为 `undefined` */
-    model?: string;
-    /** 最大对话轮数(config 块字面量提取),无/非字面量时为 `undefined` */
-    maxTurns?: number;
-}
-/**
- * Agent 完整元数据(文件型 agent)
- *
- * 继承 [AgentCore](./extractAgentMetadata.md) 的 LLM 字段,额外扩展**代码本体加载细节**:
- * - `filePath` — `loadAgentModule` 加载 `handler.js` 产物提取 `run` 函数用
- * - `hasRun` — 是否导出 `run` 函数(`Agent.executeSubAgent` 据此决定走自定义 run
- *   还是默认 reactLoop)
- *
- * DB-driven skill 不实现此接口(无源文件,无需加载),只实现 `AgentCore`。
- *
- * 由 [extractAgentMetadata](./extractAgentMetadata.md) 产出,合并路径推导字段
- * (来自 [scanAgents](../agents/scanAgents.md) 的 `AgentManifest`)与 AST 提取字段
- * (JSDoc 描述、`@agent` 覆盖名、config 块字段)。
- *
- * 字段来源：
- * - `name` — `@agent` JSDoc 覆盖值,或 `pathMeta.name`(目录推导)
- * - `filePath` / `hasRun` — 由 `pathMeta` 透传
- * - `description` — JSDoc 注释块自由文本(对 LLM 可见)
- * - `systemPrompt` / `tools` / `agents` / `model` / `maxTurns` — config 块字面量提取
- */
-interface AgentMetadata extends AgentCore {
-    /** 源码相对路径(从 `pathMeta` 透传),`loadAgentModule` 据此加载 `handler.js` 提取 `run` */
-    filePath: string;
-    /** 是否导出 `run` 函数(从 `pathMeta` 透传),`Agent.executeSubAgent` 据此选择自定义 run / 默认 reactLoop */
-    hasRun: boolean;
-}
-/**
- * 路径推导的 agent 元数据(由 [scanAgents](../agents/scanAgents.ts) 计算)
- *
- * 透传到 [AgentMetadata](./extractAgentMetadata.ts) 输出,与 AST 提取字段合并。
- * 与 [ToolPathMeta](./extractToolMetadata.md) 对称。
- */
-interface AgentPathMeta {
-    /** 目录推导的 agent 名(如 `researcher`) */
-    name: string;
-    /** 源码相对路径(如 `src/agents/researcher/handler.ts`) */
-    filePath: string;
-    /** 是否导出 `run` 函数(scanAgents 正则检测) */
-    hasRun: boolean;
-}
-
-/**
- * Tool 的 LLM 可见核心字段
- *
- * 描述"tool 是什么"——LLM 真正需要消费的字段(发往 LLM 的 tool 定义只含
- * `name` / `description` / input schema),**不含**代码本体加载细节
- * (`filePath` / `functionName` / `inputTypeName`)。
- *
- * 与 [AgentCore](./extractAgentMetadata.md) 对称——LLM-facing 字段与代码加载
- * 细节分离,便于未来扩展(如 DB-driven tool 只实现 `ToolCore` 即可)。
- *
- * `toolRegistry` 查询入口 / `@faapi/agent` 子包的 `buildToolDefinitions`
- * 都消费 `ToolCore` 字段组装 LLM tool 列表。
- */
-interface ToolCore {
-    /** tool 名(`@tool` JSDoc 覆盖值 或 路径推导值) */
-    name: string;
-    /** JSDoc 描述(tool 描述,对 LLM 可见),无 JSDoc 或 JSDoc 无自由文本时为 `undefined` */
-    description?: string;
-}
-/**
- * Tool 完整元数据(文件型 tool)
- *
- * 继承 [ToolCore](./extractToolMetadata.md) 的 LLM 字段,额外扩展**代码本体加载细节**:
- * - `filePath` — `loadToolModule` 加载 `handler.js` 产物定位函数用
- * - `functionName` — 源码导出函数名(不受 `@tool` 覆盖影响,AST 定位 + 运行时 resolveExport 用)
- * - `inputTypeName` — 第一个参数的 TypeReference 名(供 [extractTypeInfo](./extractHandlerTypes.md)
- *   生成 zod schema;运行时 `resolveToolSchema` 据此定位 `zod.js`)
- *
- * 由 [extractToolMetadata](./extractToolMetadata.md) 产出,合并路径推导字段
- * (来自 [scanTools](../tools/scanTools.md) 的 `ToolManifest`)与 AST 提取字段
- * (JSDoc 描述、`@tool` 覆盖名、第一个参数 interface 名)。
- *
- * 字段来源:
- * - `name` — `@tool` JSDoc 覆盖值,或 `pathMeta.name`(路径推导)
- * - `description` — JSDoc 注释块自由文本(对 LLM 可见)
- * - `filePath` / `functionName` — 由 `pathMeta` 透传
- * - `inputTypeName` — 第一个参数的 TypeReference 名(供 [extractTypeInfo](./extractHandlerTypes.md) 生成 zod schema)
- */
-interface ToolMetadata extends ToolCore {
-    /** 第一个参数的 interface/type 名(用于生成 zod schema),
-     *  无参数/参数无类型标注/参数为内联类型字面量时为 `undefined` */
-    inputTypeName?: string;
-    /** 源码相对路径(从 `pathMeta` 透传) */
-    filePath: string;
-    /** 源码中的导出函数名(从 `pathMeta` 透传,AST 定位用,不受 `@tool` 覆盖影响) */
-    functionName: string;
-}
-/**
- * 路径推导的 tool 元数据(由 [scanTools](../tools/scanTools.ts) 计算)
- *
- * 透传到 [ToolMetadata](./extractToolMetadata.ts) 输出,与 AST 提取字段合并。
- */
-interface ToolPathMeta {
-    /** 路径推导的 tool 名(如 `weather.getWeather`) */
-    name: string;
-    /** 源码相对路径(如 `src/tools/weather/handler.ts`) */
-    filePath: string;
-}
-
-/**
- * 按名查找单个 agent 的 LLM 可见元数据
- *
- * 返回 [AgentCore](../ast/extractAgentMetadata.md) 字段(name / description /
- * systemPrompt / tools / agents / model / maxTurns),**不含** `filePath` / `hasRun`。
- *
- * 仅查文件 registry（编译期 `faapi-agents.js` 产物来源）。**不 fallback 到
- * [skillRegistry](./skillRegistry.ts)**——skill 与 agent 职责正交不耦合,
- * skill 由业务方 plugin 内部使用,不参与 agent 查询链路。
- *
- * 用于 LLM-facing 场景(`agents` 参数注入、`asTool` 描述、
- * `resolveAgentTools` / `resolveSubAgents` 解析)。
- * 加载 handler.js 执行 `run` 函数请用 [getAgentEntry](#getAgentEntry)。
- *
- * @param name agent 名（如 `researcher`，含 `@agent` 覆盖值）
- * @returns `AgentCore` 或 `undefined`（未注册）
- */
-declare function getAgent(name: string): AgentCore | undefined;
-/**
- * 按名查找单个 agent 的完整元数据(含代码加载细节)
- *
- * 返回 [AgentMetadata](../ast/extractAgentMetadata.md) —— 继承 AgentCore
- * 额外含 `filePath` / `hasRun`,供 `@faapi/agent` 子包 `loadAgentModule`
- * 加载 handler.js 执行自定义 `run` 函数。
- *
- * 调用方需先判断 `entry?.hasRun` 再决定是否加载 handler.js。
- *
- * @param name agent 名
- * @returns `AgentMetadata` 或 `undefined`（未注册）
- */
-declare function getAgentEntry(name: string): AgentMetadata | undefined;
-/**
- * agent 包装为 tool 的描述符
- *
- * 与 [ToolMetadata](../ast/extractToolMetadata.md) 平行结构，供 reactLoop 把
- * agent 当作 tool 发给 LLM。reactLoop 按 `kind` 字段路由执行：
- * - `'tool'` → `loadToolModule` 加载 handler 函数
- * - `'agent'` → `loadAgentModule` 加载 agent handler + 递归 reactLoop
- *
- * `name` 加 `agent.` 前缀避免与常规 tool 冲突，reactLoop 据此识别 sub-agent 递归。
- * 不含 input schema——agent `run` 函数参数为开放式（任意 JSON），无类型约束。
- *
- * `metadata` 为 [AgentCore](../ast/extractAgentMetadata.md) 类型——reactLoop 只消费
- * LLM-facing 字段(systemPrompt / model / maxTurns);加载 handler.js 执行 `run`
- * 函数由 `@faapi/agent` 子包通过 [getAgentEntry](#getAgentEntry) 单独获取。
- */
-interface AgentToolDescriptor {
-    /** 标识此 tool 实际是 agent（reactLoop 据此走 sub-agent 递归） */
-    kind: 'agent';
-    /** tool 名（默认 `agent.<agentName>`，避免与常规 tool 冲突） */
-    name: string;
-    /** agent 名（不含前缀，用于按名查找 agent 元数据） */
-    agentName: string;
-    /** 描述（对 LLM 可见，来自 `agent.description`），无 JSDoc 描述时为 `undefined` */
-    description?: string;
-    /** agent LLM 可见元数据引用（reactLoop 取 `systemPrompt` / `model` / `maxTurns`） */
-    metadata: AgentCore;
-}
-/**
- * 解析 agent 可用 tool 集合
- *
- * 只返回 agent 显式声明的 tool（agent config 块的 `tools` 字段）。
- * `resolveAgentTools` 只关心 agent 自身显式声明的部分，职责单一。
- * sub-agent 的合并由 `@faapi/agent` 的 `Agent.buildToolDefinitions` 在更上层完成（按 `name` 去重）。
- *
- * agent 必须显式声明用哪些 tool，显式优于隐式。
- *
- * 通过 [getAgent](#getAgent) 查询文件型 agent,不 fallback 到 skillRegistry。
- *
- * `tools` 中未在 toolRegistry 找到的 tool 名静默跳过（tool 可选可用，不强制存在）。
- *
- * 跨注册表依赖 [toolRegistry](./toolRegistry.ts) 的 `getTool`，
- * 两个注册表由 `createAppBase` 在同一启动阶段水合。
- *
- * @param name agent 名
- * @returns `ToolMetadata[]`（agent 未注册返回空数组）
- */
-declare function resolveAgentTools(name: string): ToolMetadata[];
-/**
- * 解析 agent 可调用的子 agent 集合
- *
- * 读 `agent.agents` 字段（[extractAgentMetadata](../ast/extractAgentMetadata.md)
- * 提取的 `config.agents` 字面量列表），按名查找已注册文件型 agent。
- *
- * 不 fallback 到 skillRegistry——skill 不参与 sub-agent 递归,
- * 父 agent 的 `agents` 列表只能引用文件型 agent 名。
- *
- * 返回 `AgentCore[]`(LLM-facing 字段,供 `@faapi/agent` 子包包装为
- * `AgentToolDescriptor` 发给 LLM)。加载 sub-agent handler.js 执行 `run` 函数
- * 由 `@faapi/agent` 子包通过 [getAgentEntry](#getAgentEntry) 单独获取。
- *
- * reactLoop 组装 LLM tool 列表：
- * ```ts
- * const tools = [
- *   ...resolveAgentTools(name),                                    // 常规 tool
- *   ...resolveSubAgents(name).map((a) => asTool(a.name)!),        // agent-as-tool
- * ];
- * ```
- *
- * @param name agent 名
- * @returns `AgentCore[]`（`agents` 未设置 / agent 未注册返回空数组）
- */
-declare function resolveSubAgents(name: string): AgentCore[];
-
 /**
  * 加载后的 agent 模块
  *
@@ -1259,7 +1157,31 @@ declare function getToolSchemaPath(tool: ToolMetadata, rootDir?: string): string
 declare function loadToolSchema(tool: ToolMetadata, rootDir?: string): Promise<ToolSchemaModule | undefined>;
 
 /**
- * 按全名查找单个 tool
+ * 按名查找单个 agent 的 LLM 可见元数据（默认实例）
+ *
+ * 返回 [AgentCore](../ast/extractAgentMetadata.md)（不含 filePath / hasRun）。
+ * 加载 handler.js 执行 `run` 函数请用 [getAgentEntry](#getAgentEntry)。
+ *
+ * @param name agent 名（如 `researcher`，含 `@agent` 覆盖值）
+ */
+declare function getAgent(name: string): AgentCore | undefined;
+/**
+ * 按名查找单个 agent 的完整元数据（默认实例，含 filePath / hasRun）
+ */
+declare function getAgentEntry(name: string): AgentMetadata | undefined;
+/**
+ * 解析 agent 显式声明的 tool 集合（默认实例，跨查默认 tool 注册表）
+ */
+declare function resolveAgentTools(name: string): ToolMetadata[];
+/**
+ * 解析 agent 可调用的子 agent 集合（默认实例，按声明顺序）
+ */
+declare function resolveSubAgents(name: string): AgentCore[];
+
+/**
+ * 按全名查找单个 tool（默认实例）
+ *
+ * 框架路径（`@faapi/agent` 插件 / 请求注入）从 app 实例查找。
  *
  * @param tool 全名（如 `weather.getWeather`）
  * @returns `ToolMetadata` 或 `undefined`（未注册）
@@ -1267,48 +1189,41 @@ declare function loadToolSchema(tool: ToolMetadata, rootDir?: string): Promise<T
 declare function getTool(name: string): ToolMetadata | undefined;
 
 /**
- * 水合 skill 注册表(全量替换)
+ * skill 注册表全局访问器（默认实例便捷入口）
  *
- * 业务方 plugin `lifecycle.onReady` 启动期调用:全量查 DB → 转 `AgentCore[]`
- * → 调本函数灌入。与 `hydrateAgentRegistry` 同构,全量替换而非增量。
+ * 框架推荐路径已改为 **app 实例级注册表**：业务方 plugin 在
+ * `lifecycle.onReady(ctx)` 中通过 `ctx.registries.skill` 灌入 DB skill——
+ * 这样 skill 与该 app 的生命周期绑定，多 app 同进程互不串台，且 app close
+ * 时随实例销毁。
  *
- * 运行时增量更新场景(DB change stream)用 [upsertSkill](#upsertSkill) /
- * [removeSkill](#removeSkill),不走本函数。
+ * 本模块的同名函数保留为**默认实例**的便捷访问器（向后兼容），但注意：
+ * 默认实例与 app 实例相互独立——经全局函数灌入的 skill 不会出现在
+ * 该 app 的请求链路中。
  *
- * @param skills 从 DB / 外部源加载并转好的 `AgentCore[]`
+ * 详见 [skillRegistry.md](./skillRegistry.md) 与 [registries.md](./registries.md)。
  */
-declare function hydrateSkillRegistry(skills: AgentCore[]): void;
 /**
- * 单条增改 skill(运行时增量)
- *
- * 监听 DB change stream 的 `insert` / `update` 事件时调用。
- * `Map.set` 原子操作,并发安全(多请求同时 upsert 最后一次 wins)。
+ * 水合默认实例的 skill 注册表（全量替换）
  *
- * 同名 skill 覆盖(更新),不重复累积。
+ * 框架推荐路径：`lifecycle.onReady(ctx)` 中 `ctx.registries.skill.hydrate(skills)`。
+ */
+declare function hydrateSkillRegistry(skills: AgentCore[]): void;
+/**
+ * 单条增改默认实例的 skill（运行时增量）
  *
- * @param core skill 的 LLM 可见元数据
+ * 框架推荐路径：`ctx.registries.skill.upsert(skill)`。
  */
 declare function upsertSkill(core: AgentCore): void;
 /**
- * 单条删除 skill(运行时增量)
- *
- * 监听 DB change stream 的 `delete` 事件时调用。
- * 幂等:删除不存在的 name 静默无操作,不抛错。
- *
- * @param name skill 名
+ * 单条删除默认实例的 skill（幂等）
  */
 declare function removeSkill(name: string): void;
 /**
- * 按名查单个 skill
- *
- * @param name skill 名
- * @returns `AgentCore` 或 `undefined`(未注册)
+ * 按名查默认实例的单个 skill
  */
 declare function getSkill(name: string): AgentCore | undefined;
 /**
- * 返回所有已注册 skill
- *
- * 返回副本,调用方修改不影响内部状态(与 `listAgents` / `listTools` 同构)。
+ * 返回默认实例所有已注册 skill（副本）
  */
 declare function listSkills(): AgentCore[];
 
@@ -1326,20 +1241,26 @@ declare function listSkills(): AgentCore[];
 /** agent handle 工厂函数（由 `@faapi/agent` 插件注册） */
 type AgentHandleFactory = (ctx: FaapiContext) => unknown;
 /**
- * 注册 agent handle 工厂
+ * agent handle 工厂全局访问器（默认实例便捷入口）
  *
- * 由 `@faapi/agent` 插件在 `setup()` 时调用，传入创建 `AgentHandle` 的工厂函数。
- * 二次注册覆盖第一次（与 `hydrateAgentRegistry` 全量替换同构）。
+ * 框架路径已改为 app 实例：`@faapi/agent` 插件在 setup 时经
+ * `ctx.registries.agentHandle.register(factory)` 注册到**当前 app 的实例**，
+ * 请求注入经 `ctx.registries.agentHandle.get(ctx)` 读取——多 app 同进程互不覆盖。
+ * 此前模块级单值会让第二个 app 的插件注册覆盖第一个。
  *
- * 传入 `null` 等效于 [clearAgentHandleFactory](#clearAgentHandleFactory)。
+ * 本模块的同名函数保留为默认实例便捷访问器（向后兼容）。
  *
- * @param factory 工厂函数或 `null`（清理）
+ * 详见 [agentHandle.md](./agentHandle.md) 与 [registries.md](./registries.md)。
  */
-declare function registerAgentHandleFactory(factory: AgentHandleFactory | null): void;
 /**
- * 清空工厂注册（app close / 测试清理时调用）
+ * 注册默认实例的 agent handle 工厂
  *
- * 与 `clearAgentRegistry` / `clearToolRegistry` 对称，避免测试间状态泄漏。
+ * 框架路径请使用 `ctx.registries.agentHandle.register(factory)`（PluginContext 提供）。
+ * 传入 `null` 等效于清理。
+ */
+declare function registerAgentHandleFactory(factory: AgentHandleFactory | null): void;
+/**
+ * 清空默认实例的工厂注册
  */
 declare function clearAgentHandleFactory(): void;
 
@@ -1490,6 +1411,8 @@ interface CreateAppOptions {
 interface AppBase {
     /** Node.js Server 实例（listen 后可用，close 后置 null） */
     server: Server | null;
+    /** app 级注册表（tool/agent/skill/agentHandle 实例，close 时清理） */
+    registries: AppRegistries;
     /** 排序后的路由清单 */
     routes: RouteManifest;
     /** WebSocket 路由清单 */
@@ -1566,4 +1489,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, createPrograms, extractTypeInfo, getAgent, getAgentEntry, getApp, getInputTypeForMethod, getSkill, getTool, getToolSchemaPath, hydrateSkillRegistry, invalidateProgramCache, listSkills, loadAgentModule, loadConfig, loadEnv, loadToolModule, loadToolSchema, registerAgentHandleFactory, removeSkill, resolveAgentTools, resolveSubAgents, resolveTypeNode, upsertSkill };
+export { type AgentConfig, AgentCore, AgentMetadata, type AgentModule, type ProdApp as App, AppRegistries, 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, ToolMetadata, type ToolModule, 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 };