@lark-apaas/nestjs-capability 0.0.1-alpha.3 → 0.0.1-alpha.6

package/dist/index.d.ts

@@ -13,6 +13,143 @@ interface PluginActionContext {
     userContext: UserContext;
 }
 
+interface JSONSchema {
+    type?: string;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    items?: JSONSchema;
+    [key: string]: unknown;
+}
+interface CapabilityConfig {
+    id: string;
+    pluginKey: string;
+    pluginVersion: string;
+    name: string;
+    description: string;
+    paramsSchema: JSONSchema;
+    formValue: Record<string, unknown>;
+    createdAt: number;
+    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: {
+            content: 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);
@@ -30,8 +167,10 @@ interface PluginInstance {
     getOutputSchema(actionName: string, input: unknown, config?: unknown): ZodSchema | undefined;
     /** 列出所有 action */
     listActions(): string[];
-    /** 流式执行指定 action */
+    /** 流式执行指定 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;
     /** 聚合流式结果（可选，插件自定义聚合逻辑） */
@@ -41,24 +180,24 @@ interface PluginPackage {
     create(): PluginInstance;
 }
 
-interface JSONSchema {
-    type?: string;
-    properties?: Record<string, JSONSchema>;
-    required?: string[];
-    items?: JSONSchema;
-    [key: string]: unknown;
-}
-interface CapabilityConfig {
-    id: string;
-    pluginID: string;
-    pluginVersion: string;
-    name: string;
-    description: string;
-    paramsSchema: JSONSchema;
-    formValue: Record<string, unknown>;
-    createdAt: number;
-    updatedAt: number;
-}
+/**
+ * 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];
 
 /**
  * 模板引擎服务
@@ -88,24 +227,24 @@ 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): Promise<PluginInstance>;
-    isPluginInstalled(pluginID: string): boolean;
-    clearCache(pluginID?: string): void;
+    loadPlugin(pluginKey: string): Promise<PluginInstance>;
+    isPluginInstalled(pluginKey: string): boolean;
+    clearCache(pluginKey?: string): void;
 }
 
 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 {
     /**
@@ -115,11 +254,18 @@ interface CapabilityExecutor {
      */
     call(actionName: string, input: unknown, context?: Partial<PluginActionContext>): Promise<unknown>;
     /**
-     * 流式调用 capability
+     * 流式调用 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 是否为流式
      */
@@ -165,6 +311,12 @@ declare class CapabilityService implements OnModuleInit {
      * - unary action: 包装为单次 yield
      */
     private executeCallStream;
+    /**
+     * 流式执行 capability，返回带事件协议的流
+     * - 优先使用 pluginInstance.runStreamWithEvents
+     * - 如果插件不支持，则包装 runStream/run 为 StreamEvent
+     */
+    private executeCallStreamWithEvents;
     private buildActionContext;
     private getUserContext;
 }
@@ -174,34 +326,12 @@ interface DebugRequestBody {
     params?: Record<string, unknown>;
     capability?: CapabilityConfig;
 }
-interface DebugResponse {
-    code: number;
-    message: string;
-    data: unknown;
-    debug?: {
-        capabilityConfig: unknown;
-        resolvedParams: unknown;
-        duration: number;
-        pluginID: string;
-        action: string;
-    };
-}
-interface ListResponse$1 {
-    code: number;
-    message: string;
-    data: Array<{
-        id: string;
-        name: string;
-        pluginID: string;
-        pluginVersion: string;
-    }>;
-}
 declare class DebugController {
     private readonly capabilityService;
     private readonly pluginLoaderService;
     private readonly templateEngineService;
     constructor(capabilityService: CapabilityService, pluginLoaderService: PluginLoaderService, templateEngineService: TemplateEngineService);
-    list(): ListResponse$1;
+    list(): SuccessResponse<ListResponseData>;
     /**
      * 获取 capability 配置
      * 优先使用 body.capability，否则从服务获取
@@ -212,7 +342,7 @@ declare class DebugController {
      * 优先使用传入的 action，否则使用插件第一个 action
      */
     private getActionName;
-    debug(capabilityId: string, body: DebugRequestBody): Promise<DebugResponse>;
+    debug(capabilityId: string, body: DebugRequestBody): Promise<SuccessResponse<DebugExecuteResponseData> | ErrorResponse>;
     debugStream(capabilityId: string, body: DebugRequestBody, res: Response): Promise<void>;
 }
 
@@ -220,28 +350,11 @@ interface ExecuteRequestBody {
     action: string;
     params: Record<string, unknown>;
 }
-interface ExecuteResponse {
-    code: number;
-    message: string;
-    data: unknown;
-}
-interface CapabilityInfo {
-    id: string;
-    name: string;
-    description: string;
-    pluginID: string;
-    pluginVersion: string;
-}
-interface ListResponse {
-    code: number;
-    message: string;
-    data: CapabilityInfo[];
-}
 declare class WebhookController {
     private readonly capabilityService;
     constructor(capabilityService: CapabilityService);
-    list(): ListResponse;
-    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>;
 }
 
@@ -249,4 +362,4 @@ 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 };