@faapi/faapi 6.4.1 → 6.5.0

package/dist/{routeTypes-_17rXzal.d.ts → routeTypes-q9OXB--o.d.ts}

@@ -1,3 +1,133 @@
+/**
+ * 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 可见核心字段
+ *
+ * 描述"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 块字面量提取);文件型 agent 必填(构建期校验),DB skill 由业务方自治 */
+    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;
+}
+
 /**
  * app 实例级任务注册表（与 tool/agent/skill registry 同构，方案 A 实例化）
  *
@@ -138,6 +268,11 @@ interface TaskWorkerOptions {
     };
     /** 单次执行超时（毫秒） */
     timeoutMs: number;
+    /**
+     * 注册表快照（纯数据，postMessage 结构化克隆传入，worker 内重建只读视图注入
+     * taskCtx.registries）——语义层从 `TaskRegistriesView` 生成，缺省为空视图
+     */
+    registries?: TaskRegistriesSnapshot;
     /** 外部取消信号（驱动停机超时 abort）——abort 同样触发两段式取消 */
     externalSignal?: AbortSignal;
     /** 宽限期覆盖（默认 KILL_GRACE_MS）——测试注入短值用，业务不配置 */
@@ -145,6 +280,112 @@ interface TaskWorkerOptions {
 }
 declare function runTaskInWorker(options: TaskWorkerOptions): Promise<unknown>;
 
+/**
+ * app 级注册表（方案 A：注册表实例化）
+ *
+ * 每个应用实例（`createAppBase`）持有一套独立的注册表，随 app 创建、随
+ * `app.close()` 销毁——多 app 同进程（测试 / 嵌入 / 多租户）互不串台。
+ * 此前注册表是模块级全局单例 + hydrate 整体替换语义，后创建的 app 会覆盖
+ * 先创建的 app 的清单，任一 app close 会清空全部（详见各模块 .md）。
+ *
+ * 原四个模块（toolRegistry / agentRegistry / skillRegistry / agentHandle）
+ * 保留同名全局函数作为**默认实例的便捷访问器**（供编程式直调 / 单元测试 /
+ * 无 app 上下文的场景），内部全部路由到本模块的 `defaultRegistries`。
+ * 框架自身链路（hydrate / 请求注入 / `@faapi/agent` 插件 / lifecycle 钩子）
+ * 一律走 app 实例，不再读写全局默认实例。
+ */
+interface ToolRegistry {
+    /** 全量替换（tool 清单来自编译期产物，reload 时整体重新生成） */
+    hydrate(tools: ToolMetadata[]): void;
+    /** 按全名查找（如 `weather.getWeather`） */
+    get(name: string): ToolMetadata | undefined;
+    /** 所有已注册 tool（副本） */
+    list(): ToolMetadata[];
+    clear(): void;
+}
+/** agent 包装为 tool 的描述符（reactLoop 据此识别 sub-agent 递归） */
+interface AgentToolDescriptor {
+    kind: 'agent';
+    name: string;
+    agentName: string;
+    description?: string;
+    metadata: AgentCore;
+}
+interface AgentRegistry {
+    /** 全量替换（与 hydrateToolRegistry 同构） */
+    hydrate(agents: AgentMetadata[]): void;
+    /** LLM 可见元数据（AgentCore） */
+    getAgent(name: string): AgentCore | undefined;
+    /** 完整元数据（含 filePath / hasRun，供加载 handler.js 执行 run） */
+    getAgentEntry(name: string): AgentMetadata | undefined;
+    /** 所有已注册 agent 的 LLM 可见元数据（副本） */
+    listAgents(): AgentCore[];
+    /** 包装为 tool 描述符 */
+    asTool(name: string): AgentToolDescriptor | undefined;
+    /**
+     * 解析 agent 显式声明的 tool 集合。
+     * 跨注册表依赖：经由构造时绑定的 tool 注册表查找（同属一套 AppRegistries，
+     * 由 createAppBase 在同一启动阶段水合）
+     */
+    resolveAgentTools(name: string): ToolMetadata[];
+    /** 解析 agent 可调用的子 agent 集合 */
+    resolveSubAgents(name: string): AgentCore[];
+    clear(): void;
+}
+interface SkillRegistry {
+    /** 全量替换（DB change stream 场景也可用 upsert 增量） */
+    hydrate(skills: AgentCore[]): void;
+    /** 增量注册 / 覆盖（业务方监听 DB 单条变更） */
+    upsert(skill: AgentCore): void;
+    remove(name: string): void;
+    get(name: string): AgentCore | undefined;
+    list(): AgentCore[];
+    clear(): void;
+}
+/** agent handle 工厂函数（由 `@faapi/agent` 插件注册） */
+type AgentHandleFactory = (ctx: FaapiContext) => unknown;
+interface AgentHandleStore {
+    /** 注册工厂（null 清理）；二次注册覆盖 */
+    register(factory: AgentHandleFactory | null): void;
+    /** 工厂已注册时返回 AgentHandle 实例，未注册返回 undefined */
+    get(ctx: FaapiContext): unknown;
+    clear(): void;
+}
+/** task 客户端工厂函数（由 createAppBase 注册，返回 TaskClient 门面） */
+type TaskHandleFactory = (ctx: FaapiContext) => unknown;
+interface TaskHandleStore {
+    /** 注册工厂（null 清理）；二次注册覆盖 */
+    register(factory: TaskHandleFactory | null): void;
+    /** 工厂已注册时返回 TaskClient，未注册返回 undefined */
+    get(ctx: FaapiContext): unknown;
+    clear(): void;
+}
+/** 一个 app 实例持有的全套注册表 */
+interface AppRegistries {
+    tool: ToolRegistry;
+    agent: AgentRegistry;
+    skill: SkillRegistry;
+    task: TaskRegistry;
+    agentHandle: AgentHandleStore;
+    taskHandle: TaskHandleStore;
+}
+/**
+ * 任务侧注册表只读视图（AppRegistries 的查询投影）
+ *
+ * 注入任务执行上下文（`TaskContext.registries`）——任务执行侧不在 handler 请求链路上
+ * （拿不到 `FaapiContext.registries`），`getApp()` 在隔离 worker 线程内也不可用
+ * （globalThis 独立）。刻意不暴露 `hydrate`/`clear` 写接口：任务不是注册表的所有者。
+ */
+interface TaskRegistriesView {
+    agent: Pick<AgentRegistry, 'getAgent' | 'getAgentEntry' | 'listAgents' | 'asTool' | 'resolveAgentTools' | 'resolveSubAgents'>;
+    tool: Pick<ToolRegistry, 'get' | 'list'>;
+    skill: Pick<SkillRegistry, 'get' | 'list'>;
+}
+/** 从 AppRegistries 构造任务侧只读视图（活引用——进程内执行路径直接使用） */
+declare function createTaskRegistriesView(registries: AppRegistries): TaskRegistriesView;
+/** 创建一套 app 级注册表（`createAppBase` 每次调用创建独立实例） */
+declare function createAppRegistries(): AppRegistries;
+
 /**
  * 任务元信息（业务方在 task.ts 中 `export const task = {...}` 声明）
  *
@@ -214,6 +455,18 @@ interface TaskJob {
     /** 计划执行时间戳（重试/延迟任务与 createdAt 不同） */
     runAt?: number;
 }
+/**
+ * 隔离执行跨线程传递的注册表快照（纯数据，结构化克隆安全）
+ *
+ * 注册表对象含函数闭包不可 postMessage；元数据本身是纯数据——语义层从
+ * `TaskRegistriesView` 生成快照，worker wrapper 内重建只读视图。
+ */
+interface TaskRegistriesSnapshot {
+    /** agent 完整元数据（含 filePath/hasRun，非仅 LLM 可见字段） */
+    agents: AgentMetadata[];
+    tools: ToolMetadata[];
+    skills: AgentCore[];
+}
 /**
  * 传给任务 run 函数的第二参数
  */
@@ -227,6 +480,14 @@ interface TaskContext {
         name: string;
         attempt: number;
     };
+    /**
+     * app 注册表只读视图（agent/tool/skill 元数据查询，不含 hydrate/clear 写接口）
+     *
+     * 进程内执行为活引用；隔离执行为派发时刻的快照视图（worker 内重建）——
+     * 执行中途的 reload/DB skill 变更不影响当次执行。
+     * 任务内组装 agent 用 `registries.agent.getAgentEntry(name)`（含 filePath/hasRun）。
+     */
+    registries: TaskRegistriesView;
 }
 /**
  * 任务模块形态（task.ts 编译产物中与执行相关的导出）
@@ -299,6 +560,11 @@ interface TaskQueueDeps {
     rootDir: string;
     /** faapi.config.ts 全量配置，透传给 run 的 TaskContext.config */
     config?: unknown;
+    /**
+     * app 注册表只读视图（`createTaskRegistriesView`）——注入两条执行路径的
+     * TaskContext.registries；缺省为空视图（直接构造队列的测试/嵌入场景）
+     */
+    registries?: TaskRegistriesView;
     /**
      * 队列驱动（必填）：`loadTaskDriver` 解析结果（pgboss/bullmq 子包驱动）
      * 或自定义 TaskDriver 实例；无任务清单时由 createAppBase 传入 idleTaskDriver
@@ -409,228 +675,6 @@ interface SseWriter {
     readonly response: Response;
 }
 
-/**
- * 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 可见核心字段
- *
- * 描述"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 块字面量提取);文件型 agent 必填(构建期校验),DB skill 由业务方自治 */
-    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;
-}
-
-/**
- * app 级注册表（方案 A：注册表实例化）
- *
- * 每个应用实例（`createAppBase`）持有一套独立的注册表，随 app 创建、随
- * `app.close()` 销毁——多 app 同进程（测试 / 嵌入 / 多租户）互不串台。
- * 此前注册表是模块级全局单例 + hydrate 整体替换语义，后创建的 app 会覆盖
- * 先创建的 app 的清单，任一 app close 会清空全部（详见各模块 .md）。
- *
- * 原四个模块（toolRegistry / agentRegistry / skillRegistry / agentHandle）
- * 保留同名全局函数作为**默认实例的便捷访问器**（供编程式直调 / 单元测试 /
- * 无 app 上下文的场景），内部全部路由到本模块的 `defaultRegistries`。
- * 框架自身链路（hydrate / 请求注入 / `@faapi/agent` 插件 / lifecycle 钩子）
- * 一律走 app 实例，不再读写全局默认实例。
- */
-interface ToolRegistry {
-    /** 全量替换（tool 清单来自编译期产物，reload 时整体重新生成） */
-    hydrate(tools: ToolMetadata[]): void;
-    /** 按全名查找（如 `weather.getWeather`） */
-    get(name: string): ToolMetadata | undefined;
-    /** 所有已注册 tool（副本） */
-    list(): ToolMetadata[];
-    clear(): void;
-}
-/** agent 包装为 tool 的描述符（reactLoop 据此识别 sub-agent 递归） */
-interface AgentToolDescriptor {
-    kind: 'agent';
-    name: string;
-    agentName: string;
-    description?: string;
-    metadata: AgentCore;
-}
-interface AgentRegistry {
-    /** 全量替换（与 hydrateToolRegistry 同构） */
-    hydrate(agents: AgentMetadata[]): void;
-    /** LLM 可见元数据（AgentCore） */
-    getAgent(name: string): AgentCore | undefined;
-    /** 完整元数据（含 filePath / hasRun，供加载 handler.js 执行 run） */
-    getAgentEntry(name: string): AgentMetadata | undefined;
-    /** 所有已注册 agent 的 LLM 可见元数据（副本） */
-    listAgents(): AgentCore[];
-    /** 包装为 tool 描述符 */
-    asTool(name: string): AgentToolDescriptor | undefined;
-    /**
-     * 解析 agent 显式声明的 tool 集合。
-     * 跨注册表依赖：经由构造时绑定的 tool 注册表查找（同属一套 AppRegistries，
-     * 由 createAppBase 在同一启动阶段水合）
-     */
-    resolveAgentTools(name: string): ToolMetadata[];
-    /** 解析 agent 可调用的子 agent 集合 */
-    resolveSubAgents(name: string): AgentCore[];
-    clear(): void;
-}
-interface SkillRegistry {
-    /** 全量替换（DB change stream 场景也可用 upsert 增量） */
-    hydrate(skills: AgentCore[]): void;
-    /** 增量注册 / 覆盖（业务方监听 DB 单条变更） */
-    upsert(skill: AgentCore): void;
-    remove(name: string): void;
-    get(name: string): AgentCore | undefined;
-    list(): AgentCore[];
-    clear(): void;
-}
-/** agent handle 工厂函数（由 `@faapi/agent` 插件注册） */
-type AgentHandleFactory = (ctx: FaapiContext) => unknown;
-interface AgentHandleStore {
-    /** 注册工厂（null 清理）；二次注册覆盖 */
-    register(factory: AgentHandleFactory | null): void;
-    /** 工厂已注册时返回 AgentHandle 实例，未注册返回 undefined */
-    get(ctx: FaapiContext): unknown;
-    clear(): void;
-}
-/** task 客户端工厂函数（由 createAppBase 注册，返回 TaskClient 门面） */
-type TaskHandleFactory = (ctx: FaapiContext) => unknown;
-interface TaskHandleStore {
-    /** 注册工厂（null 清理）；二次注册覆盖 */
-    register(factory: TaskHandleFactory | null): void;
-    /** 工厂已注册时返回 TaskClient，未注册返回 undefined */
-    get(ctx: FaapiContext): unknown;
-    clear(): void;
-}
-/** 一个 app 实例持有的全套注册表 */
-interface AppRegistries {
-    tool: ToolRegistry;
-    agent: AgentRegistry;
-    skill: SkillRegistry;
-    task: TaskRegistry;
-    agentHandle: AgentHandleStore;
-    taskHandle: TaskHandleStore;
-}
-/** 创建一套 app 级注册表（`createAppBase` 每次调用创建独立实例） */
-declare function createAppRegistries(): AppRegistries;
-
 interface CookieOptions {
     domain?: string;
     path?: string;
@@ -1060,4 +1104,4 @@ interface RouteInfo {
     output: RouteOutputSchema | null;
 }
 
-export { type AppRegistries as A, type TaskDriverJob as B, type CorsOptions as C, type TaskDriverProcess as D, type TaskDriverRecord as E, type FaapiContext as F, type TaskFailedInfo as G, type HelmetOptions as H, type InjectorMap as I, type TaskJob as J, type TaskJobStatus as K, type LoggerOptions as L, type TaskMetadata as M, type TaskModule as N, type ToolCore as O, type ToolPathMeta as P, type ToolRegistry as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, cors as U, createAppRegistries as V, type WsRouteManifest as W, createTaskRegistry as X, helmet as Y, logger as Z, type FaapiMiddleware as a, type TaskFailedHandler as b, type TaskQueueDeps as c, type TaskQueue as d, type TaskDriver as e, type TaskRegistry as f, type TaskManifest as g, type ToolMetadata as h, type AgentCore as i, type AgentMetadata as j, type AgentHandleFactory as k, type AgentHandleStore as l, type AgentPathMeta as m, type AgentRegistry as n, type AgentToolDescriptor as o, type FaapiContextConfig as p, type FaapiTaskMeta as q, type FailOptions as r, type Injector as s, type RouteInfo as t, type RouteInputSchema as u, type RouteOutputSchema as v, type RouteParamSchema as w, type SseEvent as x, type SseWriter as y, type TaskContext as z };
+export { helmet as $, type AppRegistries as A, type TaskDriverJob as B, type CorsOptions as C, type TaskDriverProcess as D, type TaskDriverRecord as E, type FaapiContext as F, type TaskFailedInfo as G, type HelmetOptions as H, type InjectorMap as I, type TaskJob as J, type TaskJobStatus as K, type LoggerOptions as L, type TaskMetadata as M, type TaskModule as N, type TaskRegistriesSnapshot as O, type TaskRegistriesView as P, type ToolCore as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, type ToolPathMeta as U, type ToolRegistry as V, type WsRouteManifest as W, cors as X, createAppRegistries as Y, createTaskRegistriesView as Z, createTaskRegistry as _, type FaapiMiddleware as a, logger as a0, type TaskFailedHandler as b, type TaskQueueDeps as c, type TaskQueue as d, type TaskDriver as e, type TaskRegistry as f, type TaskManifest as g, type ToolMetadata as h, type AgentCore as i, type AgentMetadata as j, type AgentHandleFactory as k, type AgentHandleStore as l, type AgentPathMeta as m, type AgentRegistry as n, type AgentToolDescriptor as o, type FaapiContextConfig as p, type FaapiTaskMeta as q, type FailOptions as r, type Injector as s, type RouteInfo as t, type RouteInputSchema as u, type RouteOutputSchema as v, type RouteParamSchema as w, type SseEvent as x, type SseWriter as y, type TaskContext as z };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { F as FaapiContext, a as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-_17rXzal.js';
+import { F as FaapiContext, a as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-q9OXB--o.js';
 import { Server } from 'node:http';
 import { WebSocket } from 'ws';