@lark-apaas/nestjs-capability 0.0.1-alpha.0 → 0.0.1-alpha.10

package/dist/index.d.ts

@@ -1,31 +1,19 @@
-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';
 
 interface UserContext {
     userId: string;
     tenantId: string;
+    appId: string;
 }
 interface PluginActionContext {
     logger: Logger;
-    httpClient: PlatformHttpClient;
+    platformHttpClient: PlatformHttpClient;
     userContext: UserContext;
-}
-
-interface ActionSchema {
-    input: ZodSchema | ((config: unknown) => ZodSchema);
-    output?: ZodSchema | ((input: unknown, config: unknown) => ZodSchema);
-}
-interface PluginInstance {
-    run(actionName: string, context: PluginActionContext, input: unknown): Promise<unknown>;
-    hasAction(actionName: string): boolean;
-    getActionSchema(actionName: string): ActionSchema | null;
-    getInputSchema(actionName: string, config?: unknown): ZodSchema | undefined;
-    getOutputSchema(actionName: string, input: unknown, config?: unknown): ZodSchema | undefined;
-    listActions(): string[];
-}
-interface PluginPackage {
-    create(): PluginInstance;
+    /** 是否为调试模式（来自 debug controller 的调用） */
+    isDebug: boolean;
 }
 
 interface JSONSchema {
@@ -37,7 +25,7 @@ interface JSONSchema {
 }
 interface CapabilityConfig {
     id: string;
-    pluginID: string;
+    pluginKey: string;
     pluginVersion: string;
     name: string;
     description: string;
@@ -47,8 +35,192 @@ interface CapabilityConfig {
     updatedAt: number;
 }
 
+/**
+ * 成功响应基础结构
+ */
+interface SuccessResponse<T> {
+    status_code: '0';
+    data: T;
+}
+/**
+ * 错误响应结构
+ */
+interface ErrorResponse {
+    status_code: string;
+    error_msg: string;
+}
+/**
+ * Debug 信息
+ */
+interface DebugInfo {
+    capabilityConfig: CapabilityConfig;
+    resolvedParams: unknown;
+    duration: number;
+    pluginID: string;
+    action: string;
+}
+/**
+ * 执行接口响应 data 结构
+ */
+interface ExecuteResponseData {
+    output: unknown;
+}
+/**
+ * Debug 执行接口响应 data 结构
+ */
+interface DebugExecuteResponseData {
+    output: unknown;
+    debug: DebugInfo;
+}
+/**
+ * 能力列表项
+ */
+interface CapabilityListItem {
+    id: string;
+    name: string;
+    pluginID: string;
+    pluginVersion: string;
+}
+/**
+ * 列表接口响应 data 结构
+ */
+interface ListResponseData {
+    capabilities: CapabilityListItem[];
+}
+/**
+ * 流式内容响应
+ */
+interface StreamContentResponse {
+    status_code: '0';
+    data: {
+        type: 'content';
+        delta: unknown;
+        finished?: boolean;
+    };
+}
+/**
+ * 流式错误响应
+ */
+interface StreamErrorResponse {
+    status_code: '0';
+    data: {
+        type: 'error';
+        error: {
+            code: number;
+            message: string;
+        };
+    };
+}
+/**
+ * 流式响应类型
+ */
+type StreamResponse = StreamContentResponse | StreamErrorResponse;
+/**
+ * 流完成元数据
+ */
+interface StreamDoneMetadata {
+    /** chunk 总数 */
+    chunks: number;
+    /** 流持续时间 (ms) */
+    duration: number;
+    /** 聚合结果（可选） */
+    aggregated?: unknown;
+}
+/**
+ * 流错误信息
+ */
+interface StreamError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/**
+ * 流事件类型
+ * - data: 数据事件，包含单个 chunk
+ * - done: 完成事件，包含元数据
+ * - error: 错误事件，包含错误信息
+ */
+type StreamEvent<T> = {
+    type: 'data';
+    data: T;
+} | {
+    type: 'done';
+    metadata: StreamDoneMetadata;
+} | {
+    type: 'error';
+    error: StreamError;
+};
+
+interface ActionSchema {
+    input: ZodSchema | ((config: unknown) => ZodSchema);
+    output?: ZodSchema | ((input: unknown, config: unknown) => ZodSchema);
+}
+interface PluginInstance {
+    /** 执行指定 action（unary） */
+    run(actionName: string, context: PluginActionContext, input: unknown): Promise<unknown>;
+    /** 检查 action 是否存在 */
+    hasAction(actionName: string): boolean;
+    /** 获取 action 的 schema */
+    getActionSchema(actionName: string): ActionSchema | null;
+    /** 获取解析后的 input schema */
+    getInputSchema(actionName: string, config?: unknown): ZodSchema | undefined;
+    /** 获取解析后的 output schema */
+    getOutputSchema(actionName: string, input: unknown, config?: unknown): ZodSchema | undefined;
+    /** 列出所有 action */
+    listActions(): string[];
+    /** 流式执行指定 action，返回原始流 */
+    runStream?(actionName: string, context: PluginActionContext, input: unknown): AsyncIterable<unknown>;
+    /** 流式执行指定 action，返回带事件协议的流（推荐） */
+    runStreamWithEvents?(actionName: string, context: PluginActionContext, input: unknown): AsyncIterable<StreamEvent<unknown>>;
+    /** 检查 action 是否为流式 */
+    isStreamAction?(actionName: string): boolean;
+    /** 聚合流式结果（可选，插件自定义聚合逻辑） */
+    aggregate?(actionName: string, chunks: unknown[]): unknown;
+}
+interface PluginPackage {
+    create(): PluginInstance;
+}
+
+/**
+ * Capability 模块错误码
+ */
+declare const ErrorCodes: {
+    /** 成功 */
+    readonly SUCCESS: "0";
+    /** 能力不存在 */
+    readonly CAPABILITY_NOT_FOUND: "k_ec_cap_001";
+    /** 插件不存在 */
+    readonly PLUGIN_NOT_FOUND: "k_ec_cap_002";
+    /** Action 不存在 */
+    readonly ACTION_NOT_FOUND: "k_ec_cap_003";
+    /** 参数验证失败 */
+    readonly PARAMS_VALIDATION_ERROR: "k_ec_cap_004";
+    /** 执行失败 */
+    readonly EXECUTION_ERROR: "k_ec_cap_005";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+/**
+ * 模板引擎服务
+ *
+ * 支持语法：
+ * - expr: '{{' + selector + '}}'
+ * - selector: 'input.' + ident | selector.ident
+ * - ident: [a-zA-Z_]([a-zA-Z_0-9])*
+ *
+ * 示例：
+ * - {{input.a}}
+ * - {{input.a.b}}
+ * - "this is {{input.a.b}}"
+ *
+ * 求值规则：
+ * - 如果整个字符串是单个表达式，保留原始类型
+ * - 如果是字符串插值（多个表达式或混合内容），返回字符串
+ * - 如果变量不存在，返回原始表达式
+ */
 declare class TemplateEngineService {
-    private readonly TEMPLATE_REGEX;
+    private readonly EXPR_REGEX;
+    private readonly WHOLE_STRING_EXPR_REGEX;
     resolve(template: unknown, input: Record<string, unknown>): unknown;
     private resolveString;
     private resolveObject;
@@ -56,101 +228,201 @@ declare class TemplateEngineService {
 }
 
 declare class PluginNotFoundError extends Error {
-    constructor(pluginID: string);
+    constructor(pluginKey: string);
 }
 declare class PluginLoadError extends Error {
-    constructor(pluginID: string, reason: string);
+    constructor(pluginKey: string, reason: string);
 }
 declare class PluginLoaderService {
     private readonly logger;
     private readonly pluginInstances;
-    loadPlugin(pluginID: string): PluginInstance;
-    isPluginInstalled(pluginID: string): boolean;
-    clearCache(pluginID?: string): void;
+    /** 记录每个插件的加载版本（时间戳），用于 ESM 缓存绕过 */
+    private readonly pluginVersions;
+    loadPlugin(pluginKey: string): Promise<PluginInstance>;
+    isPluginInstalled(pluginKey: string): boolean;
+    /**
+     * 清除插件缓存（包括 Node.js 模块缓存）
+     * @param pluginKey - 插件标识，不传则清除所有
+     */
+    clearCache(pluginKey?: string): void;
+    /**
+     * 清除 CJS 模块缓存
+     */
+    private clearNodeModuleCache;
+    /**
+     * 递归清除子模块缓存
+     */
+    private clearModuleAndChildren;
+    /**
+     * 强制重新加载插件
+     * @param pluginKey - 插件标识
+     */
+    reloadPlugin(pluginKey: string): Promise<PluginInstance>;
 }
 
 declare class CapabilityNotFoundError extends Error {
     constructor(capabilityId: string);
 }
 declare class ActionNotFoundError extends Error {
-    constructor(pluginID: string, actionName: string);
+    constructor(pluginKey: string, actionName: string);
 }
 interface CapabilityExecutor {
+    /**
+     * 调用 capability（始终返回 Promise）
+     * - unary action: 直接返回结果
+     * - stream action: 内部聚合所有 chunk 后返回
+     */
     call(actionName: string, input: unknown, context?: Partial<PluginActionContext>): Promise<unknown>;
+    /**
+     * 流式调用 capability，返回原始流
+     * - 返回原始 AsyncIterable
+     * - 如果 action 是 unary，包装为单次 yield
+     */
+    callStream(actionName: string, input: unknown, context?: Partial<PluginActionContext>): AsyncIterable<unknown>;
+    /**
+     * 流式调用 capability，返回带事件协议的流（推荐）
+     * - 返回 StreamEvent 类型的 AsyncIterable
+     * - 支持 data/done/error 三种事件类型
+     * - Controller 层应优先使用此方法实现边收边发
+     */
+    callStreamWithEvents(actionName: string, input: unknown, context?: Partial<PluginActionContext>): AsyncIterable<StreamEvent<unknown>>;
+    /**
+     * 检查 action 是否为流式
+     */
+    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 httpClient;
+    private readonly platformHttpClient;
     private readonly pluginLoaderService;
     private readonly templateEngineService;
     private readonly logger;
     private readonly capabilities;
+    /** 文件路径到 capability id 的映射，用于文件删除时查找 */
+    private readonly filePathToId;
     private capabilitiesDir;
-    constructor(requestContextService: RequestContextService, httpClient: PlatformHttpClient, pluginLoaderService: PluginLoaderService, templateEngineService: TemplateEngineService);
+    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;
     load(capabilityId: string): CapabilityExecutor;
-    private execute;
+    /**
+     * 使用传入的配置加载能力执行器
+     * 用于 debug 场景，支持用户传入自定义配置
+     */
+    loadWithConfig(config: CapabilityConfig): CapabilityExecutor;
+    private createExecutor;
+    /**
+     * 检查 action 是否为流式
+     */
+    private checkIsStream;
+    /**
+     * 执行 capability（始终返回 Promise）
+     * - unary action: 直接返回结果
+     * - stream action: 内部聚合所有 chunk 后返回
+     */
+    private executeCall;
+    /**
+     * 流式执行 capability
+     * - stream action: 返回原始 AsyncIterable
+     * - unary action: 包装为单次 yield
+     */
+    private executeCallStream;
+    /**
+     * 流式执行 capability，返回带事件协议的流
+     * - 优先使用 pluginInstance.runStreamWithEvents
+     * - 如果插件不支持，则包装 runStream/run 为 StreamEvent
+     */
+    private executeCallStreamWithEvents;
     private buildActionContext;
     private getUserContext;
 }
 
-interface ExecuteRequestBody$1 {
-    action: string;
-    params: Record<string, unknown>;
-}
-interface DebugResponse {
-    code: number;
-    message: string;
-    data: unknown;
-    debug?: {
-        capabilityConfig: unknown;
-        resolvedParams: unknown;
-        duration: number;
-        pluginID: string;
-    };
-}
-interface ListResponse {
-    code: number;
-    message: string;
-    data: Array<{
-        id: string;
-        name: string;
-        pluginID: string;
-        pluginVersion: string;
-    }>;
+interface DebugRequestBody {
+    action?: string;
+    params?: Record<string, unknown>;
+    capability?: CapabilityConfig;
 }
 declare class DebugController {
     private readonly capabilityService;
+    private readonly pluginLoaderService;
     private readonly templateEngineService;
-    constructor(capabilityService: CapabilityService, templateEngineService: TemplateEngineService);
-    list(): ListResponse;
-    debug(capabilityId: string, body: ExecuteRequestBody$1): Promise<DebugResponse>;
+    private readonly logger;
+    constructor(capabilityService: CapabilityService, pluginLoaderService: PluginLoaderService, templateEngineService: TemplateEngineService);
+    list(): SuccessResponse<ListResponseData>;
+    /**
+     * 获取 capability 配置
+     * 优先使用 body.capability，否则从服务获取
+     */
+    private getCapabilityConfig;
+    /**
+     * 获取 action 名称
+     * 优先使用传入的 action，否则使用插件第一个 action
+     */
+    private getActionName;
+    debug(capabilityId: string, body: DebugRequestBody): Promise<SuccessResponse<DebugExecuteResponseData> | ErrorResponse>;
+    debugStream(capabilityId: string, body: DebugRequestBody, res: Response): Promise<void>;
 }
 
 interface ExecuteRequestBody {
     action: string;
     params: Record<string, unknown>;
 }
-interface ExecuteResponse {
-    code: number;
-    message: string;
-    data: unknown;
-}
 declare class WebhookController {
     private readonly capabilityService;
+    private readonly logger;
     constructor(capabilityService: CapabilityService);
-    execute(capabilityId: string, body: ExecuteRequestBody): Promise<ExecuteResponse>;
+    list(): SuccessResponse<ListResponseData>;
+    execute(capabilityId: string, body: ExecuteRequestBody): Promise<SuccessResponse<ExecuteResponseData> | ErrorResponse>;
+    executeStream(capabilityId: string, body: ExecuteRequestBody, res: Response): Promise<void>;
 }
 
 declare class CapabilityModule {
     static forRoot(options?: CapabilityModuleOptions): DynamicModule;
 }
 
-export { ActionNotFoundError, type ActionSchema, type CapabilityConfig, type CapabilityExecutor, CapabilityModule, type CapabilityModuleOptions, CapabilityNotFoundError, CapabilityService, DebugController, type JSONSchema, type PluginActionContext, type PluginInstance, PluginLoadError, PluginLoaderService, PluginNotFoundError, type PluginPackage, TemplateEngineService, type UserContext, WebhookController };
+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 };