@faapi/faapi 3.2.1 → 4.0.0

package/dist/{routeTypes-FtbRkpVF.d.ts → routeTypes-DnJuuvq-.d.ts}

@@ -72,6 +72,217 @@ 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 块字面量提取),无/非字面量时为 `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;
+}
+
+/**
+ * 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;
+}
+/** 一个 app 实例持有的全套注册表 */
+interface AppRegistries {
+    tool: ToolRegistry;
+    agent: AgentRegistry;
+    skill: SkillRegistry;
+    agentHandle: AgentHandleStore;
+}
+/** 创建一套 app 级注册表（`createAppBase` 每次调用创建独立实例） */
+declare function createAppRegistries(): AppRegistries;
+
 interface CookieOptions {
     domain?: string;
     path?: string;
@@ -123,7 +334,14 @@ interface FailOptions {
  */
 interface FaapiContextConfig extends Record<string, unknown> {
 }
+
 interface FaapiContext {
+    /**
+     * app 级注册表（tool/agent/skill/agentHandle，方案 A 实例化）。
+     * 经 createContext 进入请求链路时由框架注入；编程式构造的 ctx 可不传
+     * （injectParams 等消费方回退到默认全局实例）
+     */
+    registries?: AppRegistries;
     request: Request;
     params: Record<string, string>;
     query: URLSearchParams;
@@ -488,4 +706,4 @@ interface RouteInfo {
     output: RouteOutputSchema | null;
 }
 
-export { type CorsOptions as C, type FaapiContext as F, type HelmetOptions as H, type InjectorMap as I, type LoggerOptions as L, type RouteManifest as R, type SseEvent as S, type WsRouteManifest as W, type FaapiMiddleware as a, type FaapiContextConfig as b, type FailOptions as c, type Injector as d, type RouteInfo as e, type RouteInputSchema as f, type RouteOutputSchema as g, type RouteParamSchema as h, type SseWriter as i, cors as j, helmet as k, logger as l };
+export { type AppRegistries as A, type CorsOptions as C, type FaapiContext as F, type HelmetOptions as H, type InjectorMap as I, type LoggerOptions as L, type RouteManifest as R, type SkillRegistry as S, type ToolMetadata as T, type WsRouteManifest as W, type FaapiMiddleware as a, type AgentCore as b, type AgentMetadata as c, type AgentHandleFactory as d, type AgentHandleStore as e, type AgentPathMeta as f, type AgentRegistry as g, type AgentToolDescriptor as h, type FaapiContextConfig as i, type FailOptions as j, type Injector as k, type RouteInfo as l, type RouteInputSchema as m, type RouteOutputSchema as n, type RouteParamSchema as o, type SseEvent as p, type SseWriter as q, type ToolCore as r, type ToolPathMeta as s, type ToolRegistry as t, cors as u, createAppRegistries as v, helmet as w, logger as x };

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-FtbRkpVF.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-DnJuuvq-.js';
 import { Server } from 'node:http';
 import { WebSocket } from 'ws';
 
@@ -23,6 +23,8 @@ declare function createTestContext(options: CreateTestContextOptions): FaapiCont
  * createTestContext 的选项
  */
 interface CreateTestContextOptions {
+    /** app 级注册表（测试 handler 声明 agent/agents 参数时注入用，可选） */
+    registries?: FaapiContext['registries'];
     /** 请求方法，默认 'GET' */
     method?: string;
     /** 请求路径，必填，如 '/api/user'（无需写 host） */