@lark-apaas/nestjs-capability 0.0.1-alpha.9 → 0.1.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Logger, OnModuleInit, DynamicModule } from '@nestjs/common';
+import { Logger, OnModuleInit, OnModuleDestroy, DynamicModule } from '@nestjs/common';
 import { PlatformHttpClient, RequestContextService } from '@lark-apaas/nestjs-common';
 import { ZodSchema } from 'zod';
 import { Response } from 'express';
@@ -94,9 +94,7 @@ interface StreamContentResponse {
     status_code: '0';
     data: {
         type: 'content';
-        delta: {
-            content: unknown;
-        };
+        delta: unknown;
         finished?: boolean;
     };
 }
@@ -230,6 +228,7 @@ declare class TemplateEngineService {
 }
 
 declare class PluginNotFoundError extends Error {
+    readonly pluginKey: string;
     constructor(pluginKey: string);
 }
 declare class PluginLoadError extends Error {
@@ -238,15 +237,40 @@ declare class PluginLoadError extends Error {
 declare class PluginLoaderService {
     private readonly logger;
     private readonly pluginInstances;
+    /** 记录每个插件的加载版本（时间戳），用于 ESM 缓存绕过 */
+    private readonly pluginVersions;
     loadPlugin(pluginKey: string): Promise<PluginInstance>;
     isPluginInstalled(pluginKey: string): boolean;
+    /**
+     * 清除插件缓存
+     * - 清除应用层 pluginInstances 缓存
+     * - 清除 Node.js CJS 模块缓存（require.cache）
+     * - 更新版本号，下次 import 时绕过 ESM 缓存
+     * @param pluginKey - 插件标识，不传则清除所有
+     */
     clearCache(pluginKey?: string): void;
+    /**
+     * 清除 CJS 模块缓存
+     */
+    private clearNodeModuleCache;
+    /**
+     * 递归清除子模块缓存
+     */
+    private clearModuleAndChildren;
+    /**
+     * 强制重新加载插件
+     * @param pluginKey - 插件标识
+     */
+    reloadPlugin(pluginKey: string): Promise<PluginInstance>;
 }
 
 declare class CapabilityNotFoundError extends Error {
+    readonly capabilityId: string;
     constructor(capabilityId: string);
 }
 declare class ActionNotFoundError extends Error {
+    readonly pluginKey: string;
+    readonly actionName: string;
     constructor(pluginKey: string, actionName: string);
 }
 interface CapabilityExecutor {
@@ -275,19 +299,60 @@ interface CapabilityExecutor {
     isStream(actionName: string): Promise<boolean>;
 }
 interface CapabilityModuleOptions {
+    /** 能力配置目录路径，默认 server/capabilities */
     capabilitiesDir?: string;
+    /** 是否启用文件监听（热更新），默认 false */
+    enableWatching?: boolean;
+    /** 文件变更防抖时间（ms），默认 300 */
+    watchDebounce?: number;
 }
-declare class CapabilityService implements OnModuleInit {
+declare class CapabilityService implements OnModuleInit, OnModuleDestroy {
     private readonly requestContextService;
     private readonly platformHttpClient;
     private readonly pluginLoaderService;
     private readonly templateEngineService;
     private readonly logger;
     private readonly capabilities;
+    /** 文件路径到 capability id 的映射，用于文件删除时查找 */
+    private readonly filePathToId;
     private capabilitiesDir;
+    private fileWatcher;
+    private options;
     constructor(requestContextService: RequestContextService, platformHttpClient: PlatformHttpClient, pluginLoaderService: PluginLoaderService, templateEngineService: TemplateEngineService);
+    /**
+     * 设置模块配置
+     */
+    setOptions(options: CapabilityModuleOptions): void;
     setCapabilitiesDir(dir: string): void;
     onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    /**
+     * 启动文件监听（沙箱环境自动调用）
+     */
+    startWatching(): void;
+    /**
+     * 停止文件监听
+     */
+    stopWatching(): void;
+    /**
+     * 重新加载所有能力配置
+     */
+    reloadAllCapabilities(): Promise<void>;
+    private handleFileAdd;
+    private handleFileChange;
+    private handleFileUnlink;
+    /**
+     * 从文件加载单个能力配置
+     */
+    private loadCapabilityFromFile;
+    /**
+     * 重新加载单个能力配置
+     */
+    private reloadCapabilityFromFile;
+    /**
+     * 根据文件路径移除能力配置
+     */
+    private removeCapabilityByFile;
     private loadCapabilities;
     listCapabilities(): CapabilityConfig[];
     getCapability(capabilityId: string): CapabilityConfig | null;
@@ -335,7 +400,7 @@ declare class DebugController {
     private readonly templateEngineService;
     private readonly logger;
     constructor(capabilityService: CapabilityService, pluginLoaderService: PluginLoaderService, templateEngineService: TemplateEngineService);
-    list(): SuccessResponse<ListResponseData>;
+    list(res: Response): void;
     /**
      * 获取 capability 配置
      * 优先使用 body.capability，否则从服务获取
@@ -346,7 +411,11 @@ declare class DebugController {
      * 优先使用传入的 action，否则使用插件第一个 action
      */
     private getActionName;
-    debug(capabilityId: string, body: DebugRequestBody): Promise<SuccessResponse<DebugExecuteResponseData> | ErrorResponse>;
+    debug(capabilityId: string, body: DebugRequestBody, res: Response): Promise<void>;
+    /**
+     * 构建错误响应
+     */
+    private buildErrorResponse;
     debugStream(capabilityId: string, body: DebugRequestBody, res: Response): Promise<void>;
 }
 
@@ -358,8 +427,12 @@ declare class WebhookController {
     private readonly capabilityService;
     private readonly logger;
     constructor(capabilityService: CapabilityService);
-    list(): SuccessResponse<ListResponseData>;
-    execute(capabilityId: string, body: ExecuteRequestBody): Promise<SuccessResponse<ExecuteResponseData> | ErrorResponse>;
+    list(res: Response): void;
+    execute(capabilityId: string, body: ExecuteRequestBody, res: Response): Promise<void>;
+    /**
+     * 构建错误响应
+     */
+    private buildErrorResponse;
     executeStream(capabilityId: string, body: ExecuteRequestBody, res: Response): Promise<void>;
 }
 
@@ -367,4 +440,68 @@ declare class CapabilityModule {
     static forRoot(options?: CapabilityModuleOptions): DynamicModule;
 }
 
-export { ActionNotFoundError, type ActionSchema, type CapabilityConfig, type CapabilityExecutor, type CapabilityListItem, CapabilityModule, type CapabilityModuleOptions, CapabilityNotFoundError, CapabilityService, DebugController, type DebugExecuteResponseData, type DebugInfo, type ErrorCode, ErrorCodes, type ErrorResponse, type ExecuteResponseData, type JSONSchema, type ListResponseData, type PluginActionContext, type PluginInstance, PluginLoadError, PluginLoaderService, PluginNotFoundError, type PluginPackage, type StreamContentResponse, type StreamDoneMetadata, type StreamError, type StreamErrorResponse, type StreamEvent, type StreamResponse, type SuccessResponse, TemplateEngineService, type UserContext, WebhookController };
+/**
+ * Migration Adaptor
+ *
+ * 用于迁移老版本 capability 调用代码，将新版本的返回结果包装为老版本的 Response 结构
+ */
+/**
+ * 失败输出结构
+ */
+interface FailureOutput {
+    response: {
+        status: {
+            /** 协议层返回码（如 HTTP 状态码） */
+            protocolStatusCode: string;
+            /** 业务应用状态码 */
+            appStatusCode: string;
+        };
+        /** 返回体（JSON 字符串形式） */
+        body: string;
+    };
+}
+/**
+ * 老版本 capability 调用的 Response 结构
+ *
+ * 注意：output 使用 any 类型以简化迁移代码，避免类型断言
+ */
+interface MigrationResponse {
+    /** 当 code=0 时表示执行成功，当 code!=0 时表示执行失败 */
+    code: number;
+    data?: {
+        /** 执行成功时的输出结果（any 类型，兼容迁移场景） */
+        output?: any;
+        /** 执行结果，'success' 或 'error' */
+        outcome?: 'success' | 'error';
+        /** 执行失败时的输出结果 */
+        failureOutput?: FailureOutput;
+    };
+    /** 发生错误时的错误信息 */
+    message?: string;
+}
+/**
+ * 迁移适配器
+ *
+ * 将 CapabilityService.load().call() 的返回结果包装为老版本的 Response 结构
+ *
+ * @example
+ * // 老代码
+ * const result = await generateTaskDescription(params);
+ *
+ * // 新代码
+ * const result = await migrationAdaptor(
+ *   this.capabilityService.load('ai_generate_task_description').call('run', params)
+ * );
+ *
+ * // result 结构
+ * // {
+ * //   code: 0,
+ * //   data: {
+ * //     output: { ... },  // 能力执行结果
+ * //     outcome: 'success'
+ * //   }
+ * // }
+ */
+declare function migrationAdaptor(promise: Promise<unknown>): Promise<MigrationResponse>;
+
+export { ActionNotFoundError, type ActionSchema, type CapabilityConfig, type CapabilityExecutor, type CapabilityListItem, CapabilityModule, type CapabilityModuleOptions, CapabilityNotFoundError, CapabilityService, DebugController, type DebugExecuteResponseData, type DebugInfo, type ErrorCode, ErrorCodes, type ErrorResponse, type ExecuteResponseData, type FailureOutput, type JSONSchema, type ListResponseData, type MigrationResponse, type PluginActionContext, type PluginInstance, PluginLoadError, PluginLoaderService, PluginNotFoundError, type PluginPackage, type StreamContentResponse, type StreamDoneMetadata, type StreamError, type StreamErrorResponse, type StreamEvent, type StreamResponse, type SuccessResponse, TemplateEngineService, type UserContext, WebhookController, migrationAdaptor };